Julien Blanchard

Setting up a 9front CPU server on a Raspberry Pi 4

Fri, 01 Mar 2024 17:52:00 +0200

Some notes setting up a pi4 as a 9front cpu server

Smolmail

Tue, 14 Jul 2022 14:18:00 +0200

An experiment with email

C styles

Tue, 01 Jun 2021 14:18:00 +0200

A collection of interesting C style guides found here and there. If you know other style guides please let me know!

Journaling my life at work using Github

Tue, 25 Jul 2017 19:18:00 +0200

Following this post on lobste.rs and the interest that some manifested after I mentioned it on twitter, I wanted to write about something I’m doing for about 6 months now which is journaling my days at work.

It started while chatting with my friend Flavien who was asking how he could have a TODO list with reccuring tasks.

Half-jockingly I said use Github issues with a template. Thinking more about it I thought it could be a great idea and I should try this in practice.

My daily routine

Regarding my daily tasks, I’ve mostly been a low-tech person with pen and paper crossing out what I had done. But this process is quite inefficient regarding reccuring tasks. Also keeping up with what was left to do from the other days is not really optimal. Tried some TODO/GTD apps too but it didn’t catch.

These days I try to keep a journal of what I do at work using Github issues. I chose Github since I use it everyday so I figured this would be a great place to store this “me vs. work” stuff.

Every morning I open a new issue in a private repo with the date as the title. The repository is not public, perhaps one day it will. I’ve got mixed feelings with opening it, it’s my private life but journaling in the open could be an interesting experiment too.

There is an ISSUE_TEMPLATE file in the repository. It contains my daily routine tasks and a placeholder for what I intend to do today and another one for tasks I did that were not planned.

The template looks like this:

Today here are the tasks I'd like to complete:

- [ ] Check Slack for urgencies
- [ ] Check X status
- [ ] Check New Relic
- [ ] Check Sentry
- [ ] Check Y

I also did:

- [ ]

So every morning with my coffee I make a quick standup with myself and it ends up with something like:

Today here are the tasks I'd like to complete:

- [ ] Check Slack for urgencies
- [ ] Check X status
- [ ] Check New Relic
- [ ] Check Sentry
- [ ] Check Y
- [ ] Project 42
    - [ ] a sub task
    - [ ] another subtask
    - [ ] and another subtask
- [ ] Fix bug #66

I also did:

- [ ]

I then add a label with my current mood and if I’m working remotely or not.

During the day I check every task I completed and eventually add un-planned tasks. At the end of the day I’m left with:

Today here are the tasks I'd like to complete:

- [x] Check Slack for urgencies
- [x] Check X status
- [x] Check New Relic
- [x] Check Sentry
- [x] Check Y
- [ ] Project 42
    - [x] a sub task
    - [x] another subtask
    - [ ] and another subtask
- [x] Fix bug #66

I also did:

- [x] Free-up space on Jenkins
- [x] Some Open source stuff
- [x] Fixed a bug for a customer

When the day is over it’s time for a bit of reflection over it and I’ll tag the issue with some labels to rate it. So far I have 12 of them:

The productivity labels are purely subjective, it’s just how I feel at the end of the day not how much I accomplished quantitatively. The mood I set in the morning can be adjusted if I feel like it was not the right one too.

I usually close the issue but leave the tab open so that I can copy paste the unfinished tasks for the next issue.

What’s next?

The closed issues list is pretty nice with all the labels and the progress bar

but I haven’t found a real use for them yet except a sense of completion (or not) at the end of the day.

Since I have an API with pre-formatted data at hand using Github, I’m thinking about making a visualisation interface with some graphs and try to get some insights. It would be a nice side-project to play with some new front-end tools too (Purescript I’m looking at you).

The idea would be not only to have a fancy TODO list but also to try to self-quantitize my life as a worker. Trying to extract tendencies from this data would be great. For example if it’s been 20 days I’ve been setting my Mood to Bad and my Productivity to Bad then perhaps it’s time for a deeper reflection and a big change, this kind of stuff. It could also help for the 1-to-1s with my manager perhaps.

I also thought about some elisp or a script I could write to automate my process a bit but I’m not sure it would really add value. My issue routine is a moment of reflection, I’m not sure I want to speed it up right now.

That’s it for my daily routine. If you have thoughts, comments or ideas of improvement don’t hesitate to open an issue here.

Getting started with F# and .NET Core

Mon, 24 Jul 2017 23:10:00 +0200

TLDR: F# and .NET Core are really cool, you should give them a try.

I recently got interested in the .NET world thanks to my colleagues who are doing C# at $WORK. My last experience with Microsoft technologies was during my school years doing ASP Classic and it was not a great one but .NET Core is now a multi-platform, open-source .NET and it has a functional language: F#.

F# was designed by Don Syme. It’s open-source and maintained by the F# Software Foundation and individual contributors with some working at Microsoft.

I’m really fond of functional languages like Haskell or OCaml so I took F# for a test-drive to see what I could benefit from it.

Core vs Mono vs Standard

A bit of terminology first.

.NET Framework is Windows-only and is what you usually think about what .NET is.

Mono is a cross-platform implementation of .NET Framework from Xamarin (which Microsoft bought).

Microsoft chose to rewrite .NET to be truly cross-platform and stripped some APIs that were not considered core. The new product is .NET Core. So .NET Core is a smaller cross-platform .NET Framework.

.NET Standard aims to unify a set of APIs that all .NETs (Framework, Mono and Core) must implement.

.NET Native is a new initiative to compile code to native CPU instructions instead of using the CLR to compile to intermediate language.

Unfortunately resources for using F# with .NET Core are still very sparse, most examples are tailored for the .NET Framework or Mono so here are some notes on what I learned so far. Hope it helps.

Installation

First get .Net Core from here and follow installation instructions.

The basics

.NET Core provides a great command line tool: dotnet.

Creating a new project:

λ mkdir project
λ cd project
λ dotnet new console -lang f#

Adding a package:

λ dotnet add package Newtonsoft.Json

Restoring (installing) packages:

λ dotnet restore

Building the app:

λ dotnet build

Running the app:

λ dotnet run

Publishing an app:

λ dotnet publish

Publishing with a specific framework and runtime:

λ dotnet publish --framework netcoreapp1.1 --runtime osx.10.11-x64

.NET Core projects used to have a project.json configuration file but it’s been replaced by an XML file with a .fsproj extension in order to gain better compatibility with MsBuild.

Moving to this new format allows to build and restore multiple projects simultaneously thanks to solution files. A solution file is useful when you want to link projects together. When using dotnet restore at the solution file level, all packages in that solution will be restored instead of having to do it for every one of them.

Adding a project to a solution:

λ dotnet sln todo.sln add todo-app/todo-app.fsproj

Tooling

There are a few additional tools you can use besides dotnet CLI.

Paket

Paket is a dependency manager for .NET projects. It works with NuGet packages (like dotnet add packages) and also Git repositories references or HTTP resources. It seems to better solve dependency issues than the standard NuGet way.

It’s quite simple to add to your Core project. Download it for your platorm then paket init will generate a paket.dependecies file. paket install will install those dependencies.

Fake

Fake is F# Make. Similar to Rake in the Ruby world it’s a DSL you can use for all your build or deploy needs for example.

Ionide

Ionide is a Visual Studio Code/Atom package for F# development with everything you’d find in a modern IDE like syntax highlighting, autocompletion, type at point… Really an awesome package if you’re using these editors.

Omnisharp

For Emacs users like me, OmniSharp is a cross-platform tool that brings Intellisense for a lot of editors (Emacs, Vim, Sublime…). Combined with fsharp-mode this makes a pretty nice development environment.

Forge

Forge is a project/solution management tool. It’s useful for creating a project without an IDE but it seems it’s not needed for .NET Core projects. If you’re working on a Mono project this is a nice addition to your toolbelt.

Web stuff

In C# you would usually use ASP.NET Core (aka Rails.NET) or eventually Nancy a Sinatra-like framework for your web services needs. It’s possible to use them with F# but a better alternative exists: Suave.

Tamizh Vendan has written a good book on Suave: F# Applied.

F# the language

F# looks a lot like OCaml with a few goodies. I’m not going to detail the syntax, just highlight some features of the language that I really like.

Go check F# syntax in 60 seconds for a quick overview of the syntax.

Use C# libs

One of the best benefits of using F# is the amount of quality .NET libraries available. Most of these are written in C# but you can use them in F# quite easily.

Since it’s my first attempt to learn .NET programming, I found that learning a bit of C# can be helpful to understand how to use libraries and stuff. The C# 7 and .NET Core: Modern Cross-Platform Development book was an easy read and simple enough approach to learn more about the ecosystem.

Smooth Operators

The pipe operator |> (that Elixir borrowed from F#) lets you pass the result of the function on the left onto the other function as its first argument.

Note: the F# REPL is launched with fsharpi, ;; are needed to end statements in the REPL.

> [1..10] |> List.filter (fun n -> n % 2 = 0);;
val it : int list = [2; 4; 6; 8; 10]

<| takes the function on the left and applies it to the value on the right.

> let double n = n * 2;;
val double : n:int -> int

> printfn "The double of 16 is %d" <| double 16;;
The double of 16 is 32
val it : unit = ()

The composition operator >> lets you ‘compose’ functions together.

Let’s define two functions triple and square:

> let triple n = n * 3;;
val double : n:int -> int

> let square n = n * n;;
val square : n:int -> int

We can compose the two functions like:

> let tripleSquare = triple >> square;;
val tripleSquare : (int -> int)

> tripleSquare 2;;
val it : int = 36

The << operator takes two functions and applies the function on the right before the one the left of the operator.

> let isOdd n = n % 2 = 1;;
val isOdd : n:int -> bool

> [1..10] |> List.filter (not << isOdd);;
val it : int list = [2; 4; 6; 8; 10]

Async and Parallel

Asynchronous workflows can be easily constructed using async { ... }. It’s also possible to have some computations composed in parallel using the fork-join combinator Async.Parallel.

let task1 = async {
        do! Async.Sleep 1000
        printfn "task1 finished!"
        return 5
    }

let task2 = async {
        do! Async.Sleep 500
        printfn "task2 finished!"
        return 2
    }

[task1; task2]
|> Async.Parallel
|> Async.RunSynchronously
|> printfn "%A"

outputs:

task2 finished!
task1 finished!
[|5; 2|]
val task1 : Async<int>
val task2 : Async<int>
val it : unit = ()

This example executes both async tasks task1 and task2 concurrently and wait for both to finish before printing the results.

Mailboxes

Another concurrency primitive available in F# is mailboxes. F# can natively handle message-based concurrency thanks to its mailbox processors. It somewhat brings Erlang’s actor model to F#.

Basically actors are lightweight constructs that have a queue and can send messages to other actors and process incoming messages sent to them from the queue.

This great article by Rachel Reese explores the subject if you want to dig deeper.

Some additional resources

It’s quite hard to find good resources updated for .NET Core with examples so I’ve setup a Github Repository with some basic tasks I needed to do like using a database or parsing JSON. I’ll try to update it whenever I manage to do something that was difficult to find existing resources for.

There is a really friendly Slack that you should join.

F# for fun and profit is a superb collection of resources on F#. There is an ebook compiling all the posts too.

This Awesome dotnet core repo lists some libs, tools and resources for development with .NET Core but not specifically F#.

Regarding books Expert F# is great and assumes no prior .NET knowledge.

Ody Mbegbu has made a nice intro video to getting started with .NET Core using F#.

Conclusion

F# is a nicely designed functional language (that can do OOP too but I didn’t try it yet). Most of the resources are newbie friendly and avoid words like functors and monads. In general I find them more geared toward practical usage which is pretty nice sometimes.

The main issue with .NET Core at the moment (1.x) is that there are still a lot of missing APIs which lead to incompatible libraries like FSharp.Data but the good news is that the upcoming .NET Core release later this year (2.x) will bring something like 20000 more APIs and most of the libs should be compatible or easily adaptable then.

For me F# is a great language with a robust eco-system. It has all the FP features that matters the most to me: a strong type system, pattern-matching and good concurrency primitives. Its interoperability with C# could be a gateway to more functional programming in my company. I’m currently rewriting some of our slow Ruby services with it and I wish this will demonstrate its value to my co-workers.

Hope this article helped clearing up a bit how to work with F# and .NET Core. Don’t hesitate to post your questions or remarks here.

Fancy Rust development with Emacs

Sat, 14 May 2016 17:10:00 +0200

Rustup beta was released this week. As a member of the Church of Emacs I needed to update my config a bit. This inspired me to write this post on how to setup your Emacs as a great Rust IDE.

Installing Rust

Thanks to rustup installing Rust on your system is now even easier. First do:

λ curl https://sh.rustup.rs -sSf | sh

When prompted choose 1) Proceed with installation (default) unless you have some special requirements.

rustup was previously named multirust. It will create a ~/.multirust directory to store rust toolchains.

The binaries and tools will be installed in ~/.cargo. Make sure that you have ~/.cargo/bin in your PATH otherwise add it with:

export PATH="$HOME/.cargo/bin:$PATH"

By default your projects will use the stable toolchain (Rust 1.8 at the time of this writing).

rustup has a lot of functionalities which you can find more about on the github page.

Crates and packages you’ll need

For this part I assume you already have a working emacs and that you know how to install packages and organize your configuration.

rust-mode

rust-mode handles syntax highlighting, indentation and various settings for you.

Just M-x package-install rust-mode.

cargo.el

Cargo is Rust package manager. cargo.el is a minor mode which allows us to run cargo commands from emacs like:

C-c C-c C-b to run cargo build
C-c C-c C-r to run cargo run
C-c C-c C-t to run cargo test

and many others.

As for installation, nothing fancy just M-x package-install cargo and add:

(add-hook 'rust-mode-hook 'cargo-minor-mode)

rustfmt

rustfmt formats your code according to community style guidelines just like gofmt in the Go language world. It’s automatically handled by rust-mode.

First install the rustfmt crate:

λ cargo install rustfmt

I use C-c <tab> a lot in my emacs to automatically indent the current buffer so it would be nice if the same key combination would run rustfmt which also fixes indentation. So I simply added:

(add-hook 'rust-mode-hook
          (lambda ()
            (local-set-key (kbd "C-c <tab>") #'rust-format-buffer)))

The ìndent-buffer function I mentioned if you ever need it:

(defun indent-buffer ()
  "Indent current buffer according to major mode."
  (interactive)
  (indent-region (point-min) (point-max)))

racer

Racer is a code completion and source code navigation tool for Rust.

Install the racer crate:

λ cargo install racer

Rust source code is needed for auto-completion so clone it somewhere:

λ git clone git@github.com:rust-lang/rust.git

To use racer within emacs, do a M-x package-install racer and set it up like:

(setq racer-cmd "~/.cargo/bin/racer") ;; Rustup binaries PATH
(setq racer-rust-src-path "/Users/julien/Code/rust/src") ;; Rust source code PATH

(add-hook 'rust-mode-hook #'racer-mode)
(add-hook 'racer-mode-hook #'eldoc-mode)
(add-hook 'racer-mode-hook #'company-mode)

Note that racer relies on company-mode so install it if you haven’t.

flycheck-rust

flycheck is my prefered solution for on the fly syntax checking. It will compile your code in background and highlight the problematic parts.

Let’s M-x package-install flycheck-rust and then set it up like:

(add-hook 'flycheck-mode-hook #'flycheck-rust-setup)

Wrapping up

That’s all, you now have some great Rust support in your emacs with syntax highlighting, cargo handling, code formatting, errors highlighting, code-completion and source navigation. Happy Rust hacking!

Rust on AWS Lambda

Tue, 17 Nov 2015 16:10:00 +0100

AWS Lambda is an amazing event-based compute service capable of running a function without worrying about the underlying infrastructure. Currently it supports Node.js, Java (and JVM based langs) & Python. It’s a brilliant tool for micro-services.

In this article I’ll show you how to run some Rust code on AWS Lambda even if Rust is not officially supported.

Our micro-service

We will create a simple service that will determine if a string is a valid email address.

Let’s start a new cargo project:

λ cargo new email-checker --bin

We will need the regex crate. In Cargo.toml:

[dependencies]
regex = "0.1.41"

Then our service implementation in src/main.rs:

extern crate regex;
use regex::Regex;
use std::env;

fn main() {
    println!("Starting email-checker...");

    // Create an email regular expression
    let re = Regex::new(r"^\w+([-+.']\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*$").unwrap();

    // Match the first argument against the regular expression
    match env::args().nth(1) {
        // We have an argument
        Some(email) => {
            if re.is_match(&email) {
                println!("{} is a valid email.", email);
            } else {
                println!("{} is NOT a valid email.", email);
            }
        }
        // No argument provided
        None => {
            println!("Please provide a string to test.");
            return;
        }
    };
};

Generate a Rust binary

My machine is running OS X, AWS Lambda runs Linux. I tried to cross-compile a Linux binary on Darwin but that was too much of a hassle. In order to get the same environment as my lambda function will run on, I simply created an EC2 t2.micro instance to compile my code.

Create an Amazon Linux EC2 instance, ssh onto it and run:

λ sudo yum install git
λ sudo yum groupinstall "Development Tools"

to get a working development environment. Then clone your email-checker repo and run:

λ cargo build --release
λ cp target/release/email-checker ./email-checker-linux

We now have a working Linux binary w00t! Commit and push the binary to your repo, you can terminate the instance.

The Node.js wrapper

Since Rust is not supported by AWS Lambda, we will write a simple Javascript module that will spawn a child process with our Rust binary. That’s the main trick of this article :). Note that we could ship a Haskell, Go, OCaml or whatever binary the same way.

Let’s create a main.js at the root of our project:

var child_process = require('child_process');

exports.handler = function(event, context) {
    // event is the JSON we provide to our lambda function. More on this later.
    console.log(event["email"]);

    // spawn a child process with our email-checker-linux binary and the event["email"] value for our argument.
    var proc = child_process.spawn('./email-checker-linux', [ event["email"] ], { stdio: 'inherit' });

    proc.on('close', function(code) {
        if(code !== 0) {
            return context.done(new Error("Process exited with non-zero status code"));
        }

        context.done(null);
    });
}

Packaging our service

In order to upload our code to AWS lambda, we just have to create a zip file containing our main.js and our email-checker-linux binary.

Creating a lambda function

Log in to the AWS console, click on Lambda in the Compute section and click Get started now. We are then shown a list of lambda functions blueprints. We will not use a blueprint for our example so click Skip. Next we need to configure our lambda function.

Fill in the name of the function, its description and choose the Node.js runtime.

In the Lambda function code section, choose Upload a .ZIP file and upload the file we created previously.

In Lambda function handler and role, use main.handler for the handler and choose the Basic execution role. This will open a popup prompting you to create a new IAM Role, just allow with the default settings.

Back on our function setup, leave the Advanced settings as is and click Next.

Finally, we can review and create the function. Congratulations you created your first AWS Lambda function.

Testing our lambda function

On the lambda function screen click Actions then Configure test event. Here we can write some JSON that will be received by our Node.js handler as the event parameter.

{
  "email": "karl@marx.com"
}

Click Save and test. This will execute our lambda function. If you click Monitoring, you can see that we ran our function once.

To view the result, click View logs in CloudWatch. We’re presented with a list of log lines.

Click the first line and boom karl@marx.com is indeed a valid email.

What can we do from here?

Our email checking micro-service is still lacking an interface, we could use Amazon API gateway to create a simple endpoint where we could POST the string we want to check and return a proper response for example.

That’s it! We successfully ran some Rust code on AWS Lambda. Have fun Rustaceans :)

You can find the full code and the Linux binary here.

Using Resque with Rust

Thu, 29 Oct 2015 15:30:00 +0100

Disclaimer: I’m not a Rust expert by any means so please tell me if there is something I can improve in the examples below. I’m not going to explain how Rust works. If you’re not familiar with it I highly encourage you to read the Rust Book

Resque is a popular solution in the Ruby world to process background jobs. The great thing with it is the fact it uses Redis as a backend, making it easy to share jobs with workers written in other languages.

In this article we’ll see how we can write a fully functional Resque worker in Rust. This will allow us to either use Resque entirely with Rust, enqueue a job in Ruby and perform it with Rust or vice versa.

The full code for the following examples can be found here.

How does Resque work?

Resque jobs are enqueued in a Redis list using the RPUSH command. A Resque job is represented internally with a JSON string containing two keys, one for the job class name and one for its arguments (or payload in Resque terms).

{
    'class': 'JobClass',
    'args': [ arg1, arg2 ]
}

Available queues are defined in a resque:queues Redis SET whose entries are the queue name like some_queue_name.

Enqueueing a job is done by issueing a RPUSH command with a payload to some queue.

Knowing that let’s enqueue our first job from Rust.

Enqueing a Resque job

Let’s pretend we need to enqueue a Resque job in order to send a confirmation email.

First we need to start a new project with:

λ cargo new rust-worker --bin

First we will need to add some crates. In your Cargo.toml add:

[dependencies]
rustc-serialize = "0.3.16"

[dependencies.redis]
git = "https://github.com/mitsuhiko/redis-rs.git"
tag = "0.5.1"

Next let’s use those crates. In our main.rs:

extern crate redis;
extern crate rustc_serialize;

use redis::Commands;
use rustc_serialize::Encodable;
use rustc_serialize::json;

For our example we need to define a Job struct with with two fields: a class that will be a String and args that will be a vector of Strings.

#[derive(RustcEncodable, Debug)]
pub struct Job {
    class: String,
    args: Vec<String>
}

This struct needs the RustcEncodable trait so that we can encode it in JSON and the Debug trait for printing purposes so we’ll derive them.

Next, we will define an enqueue function that will take a Job as input and return a Redis Result:

fn enqueue(job: Job) -> redis::RedisResult<Job> {
    // Connect to a local Redis
    let client = try!(redis::Client::open("redis://127.0.0.1/"));
    let conn = try!(client.get_connection());

    // Encode our Job in JSON
    let json_job = json::encode(&job).unwrap();

    // Add our queue in resque:queues Set
    try!(conn.sadd("resque:queues", "rust_test_queue"));
    // Push our job in the resque:queue:rust_test_queue list
    try!(conn.rpush("resque:queue:rust_test_queue", json_job));

    println!("Enqueued job: {:?}", job);

    Ok(job)
}

Finally we create and enqueue a job in our main function:

fn main() {
    // Create a Job
    let job: Job = Job { class: "SignupEmail".to_owned(),
                         args: vec!["user@example.com".to_owned()] };

    // Enqueue our job
    match enqueue(job) {
        Ok(job) => println!("Enqueued job: {:?}", job),
        Err(_) => { /* handle failure here */ }
    }
}

Great! We successfully enqueued a job that can be performed through Resque.

Now onto the perform part.

Performing a Resque job

A Resque worker will try to reserve a job by polling a queue with the LPOP command until it gets something to perform.

Let’s implement that.

We need a reserve function that will check if a job is present in a queue:

fn reserve() -> redis::RedisResult<()> {
    println!("--: Checking rust_test_queue");

    // Connect to a local Redis
    let client = try!(redis::Client::open("redis://127.0.0.1/"));
    let conn = try!(client.get_connection());

    // Check if a job is present in the queue
    let res = conn.lpop("resque:queue:rust_test_queue").unwrap();

    // Perform the job or return
    match res {
        Some(job) => perform(job),
        None => return Ok(()),
    }
}

We also need to have a function that waits a few seconds to mimic Resque behaviour:

fn wait_a_bit() {
    println!("--: Sleeping for 5.0 seconds");
    std::thread::sleep_ms(5000);
}

In order to perform our job, we need to decode the JSON String retrieved from the Resque queue and then do something useful like sending an email in our case.

fn perform(json_job: String) -> redis::RedisResult<()> {
    println!("Found job: {:?}", json_job);

    // Decode JSON
    let job: Job = json::decode(&*json_job).unwrap();

    // Send our email with something like:
    // send_email(job.args.first());
    // not implemented here.

    Ok(())
}

Our Job struct must derive the RustcDecodable trait to be decodable. I’m decoding &*json_job since json::decode expects a &str and not a String.

Now let’s update our main() function to enqueue a job, perform it and wait for other jobs to come.

fn main() {
    let job: Job = Job { class: "SignupEmail".to_owned(),
                         args: vec!["user@example.com".to_owned()] };

    enqueue(job).unwrap();

    loop {
        reserve().unwrap();
        wait_a_bit();
    }
}

Time to try our worker.

λ cargo build
   Compiling rust-resque-example v0.1.0 (file:///Users/julien/Code/rust-resque-example)

λ cargo run
     Running `target/debug/rust-resque-example`
Enqueued job: Job { class: "SignupEmail", args: ["user@example.com"] }
--: Checking rust_test_queue
Found job: Job { class: "SignupEmail", args: ["user@example.com"] }
--: Checking rust_test_queue
--: Sleeping for 5.0 seconds
--: Checking rust_test_queue
--: Sleeping for 5.0 seconds

And it works! We successfully enqueued and performed a job in Resque from Rust.

What’s missing?

Our implementation still needs to be Resque web compatible (display workers, failed jobs…). It also needs to be deployed alongside our Ruby workers but that’s for another article :)

Thanks a lot to the reviewers: Flavien, Marc, Steve & Yohan.

How I upgraded my Ruby with Contracts

Mon, 13 Jul 2015 19:18:00 +0200

Toying with many languages made me discover new approaches and techniques. For example, Haskell taught me about Types and Erlang/Elixir enlightened me on Pattern-matching.

Professionally I mainly code with Ruby and I dreamed of having an advanced type system and some pattern-matching. I discovered this brilliant gem Contracts.ruby by Aditya Bhargava and in this article I will try to present Design by Contracts through the use of this gem.

What is a contract?

A contract ensures what kind of input a method expects (pre-condition), what it outputs (post-condition). It will define how our method behaves but also check its behavior.

The gem Contracts.ruby allows us to decorate our methods with code that will check that the inputs and outputs correspond to what the contract specifies. Of course, one is not obliged to annotate each method but I think that specifying a contract for your public API can only be beneficial.

A first example

Contract Num, Num => Num
def add(a, b)
  a + b
end

The contract of my method is Contract Num Num => Num, meaning that the add method takes two numbers as input and returns a number. Simple, right?

You will object that ok, it’s documentation, I could just add a comment. But since this is a contract, the Contracts.ruby gem will help ensure that it is respected.

require 'contracts'

class Foo
  include Contracts

  Contract Num, Num => Num
  def self.add(a, b)
    a + b
  end
end

Foo.add(1, 2) obviously returns 3 but Foo.add(1, ‘2’) will return:

ParamContractError: Contract violation for argument 2 of 2:
        Expected: Num,
        Actual: "2"
        Value guarded in: Foo::add
        With Contract: Num, Num => Num

The error highlights that the contract of the method add wasn’t respected because the second parameter we sent, ‘2’, isn’t of the type Num.

Note that you must always specify the type of the value returned even if the method does not return anything:

Contract String => nil
def hello(name)
  puts "hello, #{name}!"
end

If our method returns many values, its signature will be

Contract Num => [Num, Num]

Types at our disposal

Besides the classics Num, String, Bool, we can use more interesting types like:

Any when we have no type constraint
None when you need no argument
Or if our argument can be of different types, for example Or[Fixnum, Float]
Not if our argument can’t be of a certain type, like Not[nil]
Maybe if our argument is optionnal, example Maybe[String]

And many others that you will discover in the documentation.

Advanced Types Contracts

We can use contracts with advanced types like lists:

Contract ArrayOf[Num] => Num
def multiply(vals)
  vals.reduce(:*)
end

The contract of multiply method indicates that it wants a list of values of the type Num. Therefore multiply([2, 4, 16]) is valid but multiply([2, 4, ‘foo’]) is not.

Hashes:

Contract ({ nom: String, age: Num, ville: String }) => nil

Methods:

Contract ArrayOf[Any], Proc => ArrayOf[Any]

If you use Ruby 2.x keyword arguments, the contract will look like:

Contract KeywordArgs[foo: String, bar: Num] => String

We can also define our own contracts with synonyms:

Token = String
Client = Or[Hash, nil]

Contract Token => Client
def authenticate(token)

Our authenticate method is thus more clear as to what it expects and what it does. A Token of type String is desired as input and it returns a Client which can be a Hash or nothing (nil).

Pattern-matching

Pattern-matching will, for a given value, test if it matches a pattern or not. If this is the case an action is triggered. It’s a bit like Java method overloading. One could imagine it as a giant switch case but much more elegant.

A simple example with calculation (not effective at all) of the Fibonacci sequence:

Contract 0 => 0
def fib(n)
  0
end

Contract 1 => 1
def fib(n)
  1
end

Contract Num => Num
def fib(n)
  fib(n-1) + fib(n-2)
end

For a given argument, each method will be tried in order. The first method that does not generate an error will be used.

A little more real-world™ example, the management of an HTTP response based on its status code:

Contract 200, JsonString => JsonString
def handle_response(status, response)
  transform_response(response)
end

Contract Num, JsonString => JsonString
def handle_response(status, response)
  response
end

If the HTTP response code is 200 it will transform the answer, otherwise we will simply return the response.

Conclusion

There are many benefits. Contracts allow us to have greater consistency in our inputs and outputs. The flow of data in our system is clearer. And most the type errors of our system can be detected and fixed quickly. Additionally it’s easier to understand what a method does, needs and returns. It also provides some kind of documentation that would always be up to date :p.

I think we can thus save a lot of unit tests on the type of the argument(s) received by a method and focus on what it produces with this contract system. Refactoring also becomes a lot easier with this kind of safety.

I hope this article has convinced you of the value of contracts and pattern-matching in your daily Ruby and also gave you the urge to explore other languages with other paradigms.