🎸 Florent + The Machine

Node.js Streams For Fun And Profit

2020-04-16T00:00:00+00:00

I joined the riff team at Pivotal a year and a half ago. I have been working for more than a year on riff invokers.

This probably deserves a blog post on its own, but invokers, in short, have the responsibility of invoking user-defined functions and exposing a way to send inputs and receive outputs. The riff invocation protocol formally defines the scope of such invokers.

Part of my job has been to update the existing invokers (especially the Node.js one) so that they comply with this spec. As the invocation protocol is a streaming-first protocol, I had to really brush up my knowledge about Node.js streams (narrator’s voice: well, learn from zero).

I learnt a lot by trial and error, probably more than I care to admit. This blog post serves as an introduction to Node.js streams. Hopefully, it also outlines some good practices, and some annoying pitfalls to avoid.

Thanks, Dear (Proof)Readers

I would like to thank:

for the various suggestions to make this better. Thanks ❤️

Harder, Better, Mapper, Zipper

Let’s create a tiny Node.js library that works with streams and provide familiar functional operators such as map and zip.

First, what is a stream?

Loosely defined, a stream conveys (possibly indefinitely) chunks of data, to which specific operations can be applied.

How does that translate to Node.js exactly?

Streams in Node.js

Node.js streams come in two flavors: Readable and Writable.

Readable streams can be read from
Writable streams can be written to

Readable#pipe allows to create a pipeline, where the inputs come from the Readable stream and are written to the destination Writable stream.

const { Readable, Writable } = require("stream");

const myReadableStream /* = instantiate Readable stream */;
const myWritableStream /* = instantiate Writable stream */;

myReadableStream.pipe(myWritableStream);

What happens here is that the source Readable stream goes from a paused state to a flowing state after pipe is called.

You can manually manage such state transitions with functions like Readable#pause or Readable#resume but we are only going to rely on automatic flowing mode from now on.

A Node.js stream can also encapsulate a Readable side and a Writable side, such streams are called Duplex streams. If outputs of the duplex stream depend on inputs, then a Transform stream is the way to go (it is a specialization of the Duplex type).

Outputs are read, hence they come from the Readable side of the Duplex stream.

Inputs are written, hence they go to the Writable side of the Duplex stream.

Transform streams automatically expose chunks from the Writable side to a user-defined transformation function. The function results are automatically forwarded to the Readable side of the Transform stream.

Note: unfortunately, Duplex streams do not differentiate Readable errors from Writable ones.

These compound streams are interesting for any kind of pipeline beyond basic ones. They encode intermediate transformations before chunks reach the final destination Writable stream.

const { Readable, Transform, Writable } = require("stream");

const myReadableStream /* = instantiate Readable stream */;
const myTransformStream1  /* = instantiate Transform stream */;
const myTransformStream2  /* = instantiate Transform stream */;
const myTransformStream3  /* = instantiate Transform stream */;
const myWritableStream /* = instantiate Writable stream */;

myReadableStream
    .pipe(myTransformStream1)
    .pipe(myTransformStream2)
    .pipe(myTransformStream3)
    .pipe(myWritableStream);

The above “fluent” example works because Readable#pipe returns the reference to the destination stream. Transform (or more generally, Duplex) streams have two sides, so they can be piped to (Writable side) and then from (Readable side) via a new pipe call.

However, this is not necessarily the best way to define a linear pipeline though. One important limitation is that pipe does not offer any particular assistance when it comes to error handling.

Emphasis on linear here. Streams can be piped from and to several times, so you can end up with graph-shaped pipelines.

A more robust alternative in case of linear pipelines is to use the built-in pipeline function. It must be called with:

1 Readable stream (a.k.a. the source)
0..n Duplex stream (a.k.a. intermediates)
1 Writable stream (a.k.a. the destination)

const { pipeline, Readable, Transform, Writable } = require("stream");

const myReadableStream /* = instantiate Readable stream */;
const myTransformStream1  /* = instantiate Transform stream */;
const myTransformStream2  /* = instantiate Transform stream */;
const myTransformStream3  /* = instantiate Transform stream */;
const myWritableStream /* = instantiate Writable stream */;

pipeline(
    myReadableStream,
    myTransformStream1,
    myTransformStream2,
    myTransformStream3,
    myWritableStream,
    (err) => { /* ... */ }
);

You can also provide a callback that will be invoked when the pipeline completes, abnormally (i.e. when an error occurs) or not.

pipeline invokes the completion callback even if any of the streams’ setting autoDestroy is set to false.

pipeline actually supports more than streams but that’s out of scope for this article. Feel free to check the documentation to learn about other usages.

Now that the general pipeline model is understood, let’s dive into the details of how map works, learning how custom streams are implemented in the process.

You Can’t `map` This

Credit where credit is due, I am going to reuse the awesome diagrams of project Reactor.

The top of the diagram depicts chunks as they initially come to the stream, as well as the stream completion signal (marked by the bold vertical line at the end of the sequence).

The map operation here is in the middle, applying a transformation from circles to squares.

The bottom part of the diagram shows the resulting chunks and how the completion signal is propagated as-is.

In other terms, map applies a transformation function to each element of the stream, in the order they arrive.

Let’s start with a Jasmine test:

const { PassThrough, pipeline, Readable } = require("stream");

describe("map operator =>", () => {
 
    it("applies transformations to chunks", (done) => {
        const source = Readable.from([1, 2, 3], { objectMode: true }); // (1)
        const transformation = new MapTransform((number) => number ** 2); // (2)
        const destination = new PassThrough({ objectMode: true }); // (3)
        const result = [];

        // ??? (4)

        pipeline(
            source,
            transformation,
            destination,
            (err) => { // (5)
                expect(err).toBeFalsy('pipeline should successfully complete');
                expect(result).toEqual([1, 4, 9]);
                done();
            }
        );
    });
})

A few things of note:

You can create a Readable from an iterable source such as an array, or a generator function. Here, the stream will emit each array element in succession. The objectMode option configures the stream to receive any kind of chunk. The default chunk data type is textual or binary (i.e. strings, Buffer or Uint8Array). Quite surprisingly, the default mode when specifically using Readable#from is the object mode, contrary to stream constructors. However redundant, the object mode is set here just for consistency’s sake.
MapTransform does not exist yet, we will have to figure out its implementation next but we can assume its constructor accepts a transformation function (here: the square function). We could pass the objectMode setting, but let’s assume it always operates this way.
PassThrough is a special implementation of Transform stream which directly forwards inputs as outputs (it applies the identity function in other words).
we need to somehow accumulate the observed outputs to result, more on that soon
we leverage the completion callback of pipeline to verify a few things:
1. the pipeline completes successfully
2. the observed results are consistent with the transformation we intend to apply on the initial chunks
3. done is a Jasmine utility to notify the test runner of the (asynchronous) test completion

For people familiar with the given-when-then test structure, this test may look a bit strange. Indeed, the order is changed here to given-then-when. This has to do with the asynchronous nature of streams. We have to set up the expectations (the “then” block) before data starts flowing in, i.e. before pipeline is called.

How can we be sure the test completes? After all, streams can be infinite. In that case, Readable#from reads a finite array and will send a completion signal once the array is fully consumed. This completion signal will be forwarded to all the other (downstream) streams, we can therefore be confident the pipeline completion callback is going to be called. In the worst case, the test will hang for a while until the Jasmine timeout is reached, causing a test failure.

We now need to figure out how to complete the test.

Node.js streams extend EventEmitter. They emit specific events that can be listened to via functions such as EventEmitter#on(eventType, callback). Event listeners are synchronously executed in the order they are added (you can tweak the order via alternative functions such as EventEmitter#prependListener(eventType, callback)).

Our test needs to observe chunks written to the destination stream. Technically, the destination could just be a Writable stream as this is the only requirement of pipe and pipeline. However, we need to read the chunks that have been written to, so using a Transform stream such as PassThrough definitely helps as it exposes a Readable side.

In particular, Readable streams emit a data event with the associated chunk of data. That is exactly what we need to accumulate the results!

Our test now becomes:

const { PassThrough, pipeline, Readable } = require("stream");

describe("map operator =>", () => {
 
    it("applies transformations to chunks", (done) => {
        const source = Readable.from([1, 2, 3], { objectMode: true });
        const transformation = new MapTransform((number) => number ** 2);
        const destination = new PassThrough({ objectMode: true });
        const result = [];

        destination.on('data', (chunk) => {
            result.push(chunk);
        });

        pipeline(
            source,
            transformation,
            destination,
            (err) => {
                expect(err).toBeFalsy('pipeline should successfully complete');
                expect(result).toEqual([1, 4, 9]);
                done();
            }
        );
    });
})

The test seems ready. If I execute it, I get:

 $ npm test
Failures:
1) map operator => applies transformations to chunks
  Message:
    ReferenceError: MapTransform is not defined

Just to make sure the pipeline is properly set up, let’s temporarily replace MapTransform with PassThrough in object mode. In that case, the test should fail because result will be equal to [1, 2, 3] and not [1, 4, 9]. Let’s see:

 $ npm test
1) map operator => applies transformations to chunks
  Message:
    Expected $[1] = 2 to equal 4.
    Expected $[2] = 3 to equal 9.

The test fails as expected, let’s focus on the implementation now.

map is an intermediate transformation, directly correlating outputs to inputs. Hence, Transform is the ideal choice.

Let’s subclass Transform, then:

const { Transform } = require("stream");

class MapTransform extends Transform {
    
    constructor(mapFunction) {
        super({ objectMode: true });
        this.mapFunction = mapFunction;
    }

    // ???
}

Transform streams need to implement the _transform method. The first parameter is the chunk of data coming to the Writable side, the second is the encoding (which is irrelevant in object mode) and the third one is a callback that must be called exactly once to notify either an error or null (first argument) or pass on the result to the Readable side (second argument).

const { Transform } = require("stream");

class MapTransform extends Transform {
    
    constructor(mapFunction) {
        super({ objectMode: true });
        this.mapFunction = mapFunction;
    }

    _transform(chunk, encoding, callback) {
        callback(null, this.mapFunction(chunk));
    }
}

Let’s see if the test passes now:

 $ npm test

> jasmine

Randomized with seed 30817
Started
.


1 spec, 0 failures
Finished in 0.014 seconds

🍾 It does!

We could improve a few things, such as accepting asynchronous functions and handling throwing functions. This is left as an exercise to the readers 😉 (hint: Promise.resolve bridges synchronous and asynchronous functions)

Zip it!

zip is slightly more complex than map as it operates on (at least) two streams. Let’s see it in action (thanks again to project Reactor for the diagrams):

zip pairs up chunks by order of arrival. Once the pair is formed, a transformation function is applied to it. zip completes when the last stream completes.

For simplicity’s sake, our zip implementation will only pair elements together but not apply any transformation.

Time to express our intent with a test:

const { PassThrough, pipeline, Readable } = require("stream");

describe("zip operator =>", () => {

    it("pairs chunks from upstream streams", (done) => {
        const upstream1 = Readable.from([1, 2, 3], { objectMode: true }); // (1)
        const upstream2 = Readable.from(["Un", "Deux", "Trois"], { objectMode: true }); // (1)
        const zipSource = new ZipReadable(upstream1, upstream2); // (2)
        const destination = new PassThrough({ objectMode: true }); // (3)
        const result = []; // (4)

        destination.on('data', (chunk) => { // (4)
            result.push(chunk);
        });

        pipeline(
            zipSource,
            destination,
            (err) => { // (5)
                expect(err).toBeFalsy('pipeline should successfully complete');
                expect(result).toEqual([
                    [1, "Un"],
                    [2, "Deux"],
                    [3, "Trois"]
                ]);
                done();
            }
        );
    })
})

This is very similar to the previous map test:

we need two streams to read from, hence the creation of two Readable streams from different arrays. Note we could (and should for a production implementation) spice up the test a bit by introducing latency, thus making sure we properly wait for chunks to be paired in order. This could be done with generator functions and setTimeout.
the next step will be to figure out how to implement ZipReadable. We can safely assume it accepts two Readable streams to read chunks from.
same as before, we rely on PassThrough to receive the resulting chunks. We will use its Readable side to observe and accumulate the results.
we accumulate the observed resulting chunks in result, based on the data event emitted by the Readable side of the PassThrough stream
finally, we rely on the completion callback to make sure, as before, that the pipeline successfully completes, the resulting chunks are as we expect and notify Jasmine of the test completion

Let’s run the test:

 $ npm test
Failures:
1) zip operator => pairs chunks from upstream streams
  Message:
    ReferenceError: ZipReadable is not defined

Let’s create an implementation that works with two streams for now. First, what kind of stream our ZipReadable should be? Let’s go with Readable, as ZipReadable acts as a source built upon two upstream streams.

const { Readable } = require("stream");

class ZipReadable extends Readable {
    
    constructor(stream1, stream2) {
        super({ objectMode : true });
        this.stream1 = stream1;
        this.stream2 = stream2;
    }
    
    // ??? (2)

    _startReading() {
        this.stream1.on('data', (chunk1) => {
            // ??? (1)
        });
        this.stream2.on('data', (chunk2) => {
            // ??? (1)
        });
    }
}

we need to get data from both the upstream streams. We chose here not to call _startReading in the constructor. The goal is to start reading only when a first consumer wants to read data.
we somehow need to emit data whenever ZipReadable is read from

Let’s first worry about buffering the incoming data:

const { Readable } = require("stream");

class ZipReadable extends Readable {

    constructor(stream1, stream2) {
        super({ objectMode : true });
        this.chunks1 = [];
        this.chunks2 = [];
        this.stream1 = stream1;
        this.stream2 = stream2;
    }

    // ???

    _startReading() {
        this.stream1.on('data', (chunk1) => {
            this.chunks1.push(chunk1);
        });
        this.stream2.on('data', (chunk2) => {
            this.chunks2.push(chunk2);
        });
    }

}

Nothing too fancy here, chunks are pushed to the corresponding array. Custom Readable need to implement Readable#_read. Results are pushed to consumers via Readable#push.

Let’s have a crack at it:

// DO NOT USE IN PRODUCTION - SEE BELOW FOR DETAILS
const { Readable } = require("stream");

class ZipReadable extends Readable {

    constructor(stream1, stream2) {
        super({ objectMode : true });
        this.initialized = false;
        this.stream1 = stream1;
        this.stream2 = stream2;
        this.chunks1 = [];
        this.chunks2 = [];
    }

    _read(size) {
        if (!this.initialized) {
            this._startReading(); // (1)
            this.initialized = true;
        }
        const bound = Math.min(size, this.chunks1.length, this.chunks2.length); // (2)
        if (bound === 0) {
            return;
        }
        const readyChunks1 = this.chunks1.splice(0, bound); // (3)
        const readyChunks2 = this.chunks2.splice(0, bound); // (3)
        for (let i = 0; i < bound; i++) {
            const pair = [readyChunks1[i], readyChunks2[i]]; // (4)
            this.push(pair); // (5)
        }
    }

    _startReading() {
        this.stream1.on('data', (chunk1) => {
            this.chunks1.push(chunk1);
        });
        this.stream2.on('data', (chunk2) => {
            this.chunks2.push(chunk2);
        });
    }
}

upon the first call to Readable#_read (when pipeline is called in the test), we start reading data from the upstream sources. As we do not want to subscribe to the 'data' event multiple times, we guard this initialization with the this.initialized flag.
size is advisory, so we could just ignore it but it does not cost much to include in the bound computation. More on that towards the end of this article.
splice is used here to remove and return the bound first elements of each array as well as shift the remaining ones. That way, we do not keep consumed chunks around.
the core logic of zip is here, we create a pair (an array) of chunks accumulated from two streams
finally, we publish that pair

Let’s see if our test is happy:

Failures:
1) zip operator => pairs chunks from upstream streams
  Message:
    Error: Timeout - Async function did not complete within 5000ms (set by jasmine.DEFAULT_TIMEOUT_INTERVAL)

Oh no! The test fails. Looking at the above implementation, this actually makes sense. When _read is called the first time, there is no guarantee at all that data has been buffered yet from the upstream sources.

Looking a bit more closely to Readable#_read documentation, we can read:

Once the readable._read() method has been called, it will not be called again until more data is pushed through the readable.push() method.

Ahah! That’s exactly the issue we hit! _read is called a first time when the pipeline is set up, but no data has come yet so nothing to push. Then, we are stuck forever as no further Readable#push calls can occur because _read will not be called anymore.

Lucky for us, nothing prevents Readable#push, or even Readable#_read from being called from elsewhere in the Readable implementation.

Let’s try again (and add a few temporary logs while we’re at it):

// DO NOT USE IN PRODUCTION - SEE BELOW FOR DETAILS
const { Readable } = require("stream");

class ZipReadable extends Readable {

    constructor(stream1, stream2) {
        super({ objectMode : true });
        this.initialized = false;
        this.waitingForData = false;
        this.stream1 = stream1;
        this.stream2 = stream2;
        this.chunks1 = [];
        this.chunks2 = [];
    }

    _read(size) {
        if (!this.initialized) {
            console.log('Initializing pipeline');
            this._startReading();
            this.initialized = true;
        }
        const bound = Math.min(size, this.chunks1.length, this.chunks2.length);
        if (bound === 0) {
            console.log(`Waiting for data, nothing to do for now...`);
            this.waitingForData = true;
            return;
        }
        console.log(`Data flowing: ${bound} element(s) from each source to zip!`);
        this.waitingForData = false;
        const readyChunks1 = this.chunks1.splice(0, bound);
        const readyChunks2 = this.chunks2.splice(0, bound);
        for (let i = 0; i < bound; i++) {
            const pair = [readyChunks1[i], readyChunks2[i]];
            this.push(pair);
        }
    }

    _startReading() {
        this.stream1.on('data', (chunk1) => {
            console.log(`Chunk 1 received: ${chunk1}`);
            this.chunks1.push(chunk1);
            if (this.waitingForData) {
                console.log(`Waiting for data, calling with ${this.chunks1.length} element(s) from first upstream`);
                this._read(this.chunks1.length);
            }
        });
        this.stream2.on('data', (chunk2) => {
            console.log(`Chunk 2 received: ${chunk2}`);
            this.chunks2.push(chunk2);
            if (this.waitingForData) {
                console.log(`Waiting for data, calling with ${this.chunks2.length} element(s) from second upstream`);
                this._read(this.chunks2.length);
            }
        });
    }
}

Let’s re-run the test:

 $ npm test
Initializing pipeline
Waiting for data, nothing to do for now...
Chunk 1 received: 1
Waiting for data, calling with 1 element(s) from first upstream
Waiting for data, nothing to do for now...
Chunk 2 received: Un
Waiting for data, calling with 1 element(s) from second upstream
Data flowing: 1 element(s) from each source to zip!
Chunk 1 received: 2
Chunk 2 received: Deux
Chunk 1 received: 3
Chunk 2 received: Trois
Data flowing: 2 element(s) from each source to zip!
Waiting for data, nothing to do for now...

Failures:
1) zip operator => pairs chunks from upstream streams
  Message:
    Error: Timeout - Async function did not complete within 5000ms (set by jasmine.DEFAULT_TIMEOUT_INTERVAL)

Hmm, the test still fails, but the implementation seems to behave correctly. What actually happens is that our ZipReadable implementation never completes. Looking again at the Readable#push documentation, we can see pushing that null notifies downstream consumers that the stream is done emitting data.

Now, when should we do that? If we look at the Reactor diagram of zip again:

… we can see that the completion should be sent when the last stream completes. Readable streams notify consumers with the end event when they are done. Now that we have got everything figured out, let’s get rid of the logs and fix our implementation:

// DO NOT USE IN PRODUCTION - SEE BELOW FOR DETAILS
const { Readable } = require("stream");

class ZipReadable extends Readable {

    constructor(stream1, stream2) {
        super({ objectMode : true });
        this.initialized = false;
        this.waitingForData = false;
        this.endedUpstreamCount = 0; // (1)
        this.stream1 = stream1;
        this.stream2 = stream2;
        this.chunks1 = [];
        this.chunks2 = [];
    }

    _read(size) {
        if (!this.initialized) {
            this._startReading();
            this.initialized = true;
        }
        const bound = Math.min(size, this.chunks1.length, this.chunks2.length);
        if (bound === 0) {
            this.waitingForData = true;
            return;
        }
        this.waitingForData = false;
        const readyChunks1 = this.chunks1.splice(0, bound);
        const readyChunks2 = this.chunks2.splice(0, bound);
        for (let i = 0; i < bound; i++) {
            const pair = [readyChunks1[i], readyChunks2[i]];
            this.push(pair);
        }
    }

    _startReading() {
        this.stream1.on('end', () => { // (2)
            this.endedUpstreamCount++;
            if (this.endedUpstreamCount === 2) { // (3)
                this.push(null);
            }
        });
        this.stream2.on('end', () => { // (2)
            this.endedUpstreamCount++;
            if (this.endedUpstreamCount === 2) { // (3)
                this.push(null);
            }
        });
        this.stream1.on('data', (chunk1) => {
            this.chunks1.push(chunk1);
            if (this.waitingForData) {
                this._read(this.chunks1.length);
            }
        });
        this.stream2.on('data', (chunk2) => {
            this.chunks2.push(chunk2);
            if (this.waitingForData) {
                this._read(this.chunks2.length);
            }
        });
    }
}

we introduce a counter to keep track of upstream stream completion.
we observe each upstream stream completion and increment the counter when than occurs.
we notify the zip stream completion when all upstream streams are done.

Let’s run the tests:

 $ npm test

2 specs, 0 failures

Yay, it passes 🥳

However, the implementation could definitely be refactored as there is a lot of duplicated behaviors. It could even be generalized to n upstream sources (the corresponding test is very similar to the one with 2 sources)!

And here we go:

// DO NOT USE IN PRODUCTION - SEE BELOW FOR DETAILS
const { Readable } = require("stream");

class ZipReadable extends Readable {

    constructor(...upstreams) { // (1)
        super({ objectMode : true });
        this.initialized = false;
        this.waitingForData = false;
        this.endedUpstreamCount = 0;
        this.streams = upstreams;
        this.chunks = upstreams.map(() => []); // (2)
    }

    _read(size) {
        if (!this.initialized) {
            this._startReading();
            this.initialized = true;
        }
        const bound = Math.min(size, ...this.chunks.map(array => array.length));  // (3)
        if (bound === 0) {
            this.waitingForData = true;
            return;
        }
        this.waitingForData = false;
        this.chunks
            .map(a => a.splice(0, bound))
            .reduce((prev, curr) => {  // (4)
                const result = [];
                for (let i = 0; i < bound; i++) {
                    const previous = (Array.isArray(prev[i])) ? prev[i] : [prev[i]];
                    result.push([...previous, curr[i]]);
                }
                return result
            })
            .forEach((pair) => {
                this.push(pair);
            })
    }

    _startReading() {
        this.streams.forEach((stream, index) => {
            stream.on('end', () => {
                this.endedUpstreamCount++;
                if (this.endedUpstreamCount === this.streams.length) { // (5)
                    this.push(null);
                }
            });
            stream.on('data', (chunk) => {
                const streamChunks = this.chunks[index];
                streamChunks.push(chunk);
                if (this.waitingForData) {
                    this._read(streamChunks.length);
                }
            });
        });
    }
}

we use now the “rest parameter” syntax to accept any number of streams. We could arguably improve the signature further by having two mandatory streams and an optional rest ones for extra streams.
we just have to create an initial empty array of chunks for every stream
we compute the current length of each chunk array and use the “spread syntax” to fit these lengths into separate arguments of Math.min.
finally, after Array#splice extract the bound first parameter of each chunk array, these arrays are reduced into pairs and then published via Readable#push
the counter now need to reflect the dynamic number of upstream sources instead of the hardcoded 2 of the previous version

Does the existing test still pass?

 $ npm test

2 specs, 0 failures

Yes!

One More Thing

There is one (albeit very important) aspect of streams I deliberately did not mention here: backpressure. Backpressure happens when downstream streams cannot keep up with upstream streams. Basically, the latter conveys data too fast for the first.

The good news is that Readable#pipe handles backpressure “for free” (and I assume pipeline as well).

That being said, do our custom implementations of zip and map handle backpressure correctly?

Spoiler alert: I’m afraid not.

However, there will be a dedicated blog post about this, with updates to the initial implementations 😉

Going further

If you notice improvements (other than backpressure-related ones), please send a Pull Request and/or reach out to me on Twitter. Here are a few references that helped me in my stream learning journey that are worth sharing:

https://nodejs.org/api/stream.html: the official documentation of Node.js streams, including implementation guides
https://github.com/nodejs/help/: stuck with something? Open an issue in this repository and Node.js maintainers will help you!
https://www.w3.org/TR/streams-api/ W3C/WhatWG stream spec (it slightly differs from Node.js stream API, but many concepts overlap)
https://v8.dev/blog: not directly related to streams, but this blog authored by v8 maintainers is a goldmine of information w.r.t. how v8 works and new Javascript features

Hello Jekyll!

2019-05-19T00:00:00+00:00

After a few issues with Hubpress.io (is it even maintained now?), I decided to migrate my blog again and move to Jekyll.

The process was a mix of automatic (Pandoc), semi-manual (helped with some good old Bash commands) and purely manual transformations. I even fixed old quirks from the previous Dotclear->Hubpress migration in the process.

The theme is used is well… minimal but I do not really need a fancy blog. I got rid of the analytics. I also added a mystery page.

Anyway, my blog is now live and usable again.

Stay tuned for an announcement I have been wanting to make for a while!

In the meantime, long live Jekyll!

hack.commit.push

2019-05-19T00:00:00+00:00

hack.commit.push est un nouvel événement gratuit autour des projets libres / open-source qui débarque bientôt à Paris !

Avant d’entrer dans les détails, je voulais revenir sur les motivations qui m’ont poussé à le co-créer.

TL;DR

Pas envie de tout lire ? Vous pouvez aller droit à l’essentiel avec les infos à retenir.

La source : Hackergarten Paris

Le meetup Hackergarten Paris réunit contributeur·trice·s de projets libres/open-source et personnes désireuses de s’y mettre sans nécessairement savoir par où commencer.

Comme expliqué dans une publication précédente, l’avantage est multiple.

Les nouveaux·elles venu·e·s sont accompagné·e·s en direct par une personne familière avec le code à changer. Elles peuvent donc contribuer efficacement, prendre confiance et aussi démystifier le travail accompli : vous aussi êtes capable de contribuer !

Côté project leads, une récente enquête (en anglais) de l’excellente initiative Open Collective résume bien mieux que moi l’un des besoins que les meetups Hackergarten ont pour ambition de satisfaire.

One of the core reasons why the @hackcommitpush conference and the @hackergarten meetups exist is perfectly summed up in this @opencollect survey: https://t.co/qmOEIkKAdr. Worth reading and sharing!
Looking forward to welcoming contributors on June 15: https://t.co/skQvuterrd! pic.twitter.com/yYDiHtRHBO
— hack.commit.push (@hackcommitpush) May 17, 2019

En effet, la plupart des projets libres/open-source sont maintenus par des personnes distribuées sur toute la planète et la communication s’effectue habituellement par écrans interposés.

Le meetup Hackergarten Paris (comme ceux d’autres villes) permet donc de co-localiser les personnes motivées par un sujet commun et de les faire avancer dans un cadre détendu et bienveillant. En bref, retisser un lien social qui se perd entre contributeur·rice·s.

hack.commit.push dans tout ça ?

J’ai d’excellents souvenirs de mes premières participations au Hackergarten autour de 2011-2012. Il avait lieu régulièrement à Xebia et était organisé par Mathilde, Brice et Éric.

Néanmoins, faute de temps, le meetup ne fut plus organisé que pendant les grandes conférences (Devoxx etc). Avec la permission des trois organisateurs cités ci-dessus, j’ai alors repris le meetup (fin 2015, de mémoire) et relancé sa version mensuelle (qui continue aujourd’hui : tous les derniers mardis du mois à Paris).

J’ai même essayé deux ou trois fois de tenir le Hackergarten pendant Devoxx France, après sa migration au Palais des Congrès. Pour des raisons diverses, cela n’a simplement pas fonctionné : quasiment personne n’a rejoint la session.

Au delà des améliorations d’organisation potentielles de Devoxx pour le Hackergarten (les orgas abattent déjà un travail considérable), j’ai fini par me demander s’il était vraiment pertinent de proposer un Hackergarten à des personnes venues avant tout pour assister à des conférences et pour réseauter.

C’est de ce constat qu’est né l’idée du hack.commit.push est né : un événement 100% dédié aux contributions de projets libres / open-source, à la manière des Hackergartens existants !

Save the date

Organisée par Andres, Hervé, Michael et votre serviteur, soutenue par des contributeur·trice·s tel·le·s que Jessica, Dilek et Daniel, la première édition est GRATUITE, aura lieu le 15 Juin à Paris dans les très beaux locaux de Tech & Code Factory et s’inscrit dans la droite lignée des Hackergartens :

tou·te·s les participant·e·s sont bienvenu·e·s, quel que soit leur niveau en développement logiciel et leur expérience avec des projets libres / open-source
que ce soit de l’amélioration de documentation, de design, de correction de bugs ou de l’ajout de fonctionnalité, chaque contribution compte !

Pour les débutant·e·s, nous avons pour volonté d’organiser des ateliers d’introduction la matinée (par exemple : introduction à Git / Github) afin de les aider à contribuer pendant l’après-midi.

Nous avons d’ores et déjà de beaux projets à vous proposer :

Apache Maven
Neo4j
Gradle
riff
Kubernetes FR docs <- un grand merci à Rémy Leone de Scaleway au passage
et bien d’autres !

N’hésitez plus, inscrivez-vous et faites passer le mot !

Vous souhaitez vous impliquer davantage ? Lisez ce qui suit ↓

Je veux m’impliquer !

Je veux proposer un projet

Votre mission, si vous l’acceptez, est d’accompagner de façon bienveillante des personnes au niveau varié sur leurs premières contributions à votre projet libre/open-source.

Votre challenge sera d’équilibrer le temps d’explication nécessaire pour commencer à contribuer (vous voulez maximiser la participation des contributeur·trice·s) et le temps effectif de contribution (vous pouvez définir des pré-requis pour être plus efficace, mais c’est au risque d’exclure d’emblée trop de participant·e·s).

Toujours tenté·e·s ? Alors, n’hésitez pas à nous envoyer, de préférence en anglais, une description de votre projet et les contributions possibles en une journée (avec d’éventuels pré-requis pour les participant·e·s) : organization AT hack-commit-pu.sh.

Ma société veut sponsoriser

Nous avons en effet divers frais à couvrir, tels que le buffet de la journée, le cocktail de clôture et pourquoi pas encore d’autres services si le budget le permet.

Pour information, nous sommes structurés en association.

N’hésitez pas à nous contacter, de préférence en anglais, à organization AT hack-commit-pu.sh pour que nous vous envoyions notre prospectus.

Je veux animer un atelier d’introduction

Nous avons à coeur que les profils moins expérimentés puissent également participer. Le but des ateliers d’introduction est d’adresser, en deux heures, les fondamenteux de technologies utiles aux différents projets représentés pendant l’événement.

Le candidat le plus évident est Git / Github.

N’hésitez pas à nous contacter, de préférence en anglais, à organization AT hack-commit-pu.sh si cette opportunité vous intéresse.

Je veux être bénévole

Si vous voulez rejoindre l’aventure, n’hésitez pas à nous contacter, de préférence en anglais, à organization AT hack-commit-pu.sh.

Si vous ne voulez aider “que” pendant le jour J, voici un aperçu de ce qu’il est possible de faire :

accueil des sponsors / project leads
inscription des participant·e·s
annonce des pauses
aide au ménage en fin de journée

Ce qui n’est pas incompatible avec une participation à l’événement en lui-même (vous aurez juste un temps de participation un peu plus réduit) !

Pourquoi Venir Au Hackergarten

2016-09-20T00:00:00+00:00

Qu’on se le dise, les logiciels Open Source sont partout. Il y a fort à parier que vous les utilisiez directement voire en développiez dans votre activité professionnelle. Il demeure indéniable que vous en bénéficiez dans votre vie quotidienne, même indirectement.

Hackers: we need you!

Il vous est peut-être même arrivé de renseigner un bug, voire de soumettre un correctif à un logiciel open-source que vous utilisez dans le cadre professionnel. Mais en dehors de ces rares occasions, vous n’avez jamais trouvé le temps de contribuer de façon plus pérenne.

Pourtant, en voilà un objectif qui peut rendre fier|fière ! Devenir l’un des committers principaux d’un projet visible (ou en passe de le devenir) peut faire une belle différence sur le CV et dans votre carrière.

Cela ne se fait évidemment pas en un jour, mais chaque première contribution est importante. Il peut être assez difficile de se plonger dans une base de code inconnue sans aide extérieure, ni objectif précis.

Paris Hackergarten est là pour vous !

Il vise à regrouper, dans une même pièce, le temps d’une soirée (1 fois par mois), committers confirmés (a.k.a. mentors) et contributeurs motivés (a.k.a. hackers) !

Chacun y retrouve son compte :

le mentor voit son projet avancer grâce aux contributions
le hacker se familiarise avec la base de code, avec l’aide du mentor et envoie ses premières contributions en quelques heures, et non pas en quelques jours

Lors de la dernière soirée, un binôme a réussi à soumettre une pull request au projet Apache Maven ! Ils ont pourtant commencé la soirée sans connaissances préalables de la base de code. Merci à Hervé pour le mentoring au passage !

Tous les hackers sont bienvenus ! Ne vous auto-censurez pas en pensant que vous n’avez pas le niveau, ça n’est pas vrai ! ;-)

Appel aux mentors

Vous souhaitez présenter votre projet et attirer de nouvelles contributions ?

Pour se faire, deux règles sont en vigueur :

préparer une présentation deux minutes afin de familiariser et "vendre" votre projet aux participants
avoir un ensemble de tâches bien définies, idéalement réalisables en une soirée

Concernant la technologie employée : aucune contrainte !

Je tiens à insister sur ce point. On pourrait croire actuellement que le meetup est réservé aux développeurs Java, ça n’est pas le cas !

Il se peut même qu’une session du Paris Hackergarten soit prochainement dédiée au développement iOS, stay tuned! ;-)

À vos calendriers !

Nous nous efforçons d’organiser le Paris Hackergarten tous les derniers mardis du mois, dans les locaux de Xebia.

Le prochain aura donc lieu le 27 Septembre, j’espère donc vous y voir !

Rant: The Teletubbies “Documentation” Pitfall

2016-09-19T00:00:00+00:00

Disclaimer

I am not Uncle Bob’s nephew, but if you already have read Clean Code, chances are you will not learn much from this post.

Typical example

Let me talk about a coding practice that I find profoundly disturbing. Get this code for instance:

public SomeResult computeResult(SomeParameter parameter) {
    // call nice service to fetch foo
    Foo foo = niceService.fetchFoo(parameter);
    return new SomeResult(foo);
}

Basically, we have got some trivial calls to a service and use it for instanciating the result we are interested in.

Do we need the comment, though? Obviously, we don’t!

We are just adding noise!

That’s why I call it a Teletubbies documentation.

Teletu-what?

Teletubbies, as you probably already know, is a TV show for very young children, created by the BBC.

If you know the show, you know also that whenever a Teletubbies character does something, the following happens:

the character announces what it intends to do
the voice-over paraphrases what the character just said
the character does it
optionally back to step 1

This makes sense for very young children, part of education is based on repetition.

Back to our example

So whenever I encounter a snippet of code like above, I immediately hear this annoying voice-over that just repeats something we already know.

It is annoying because, well, we are not very young children.

What’s the big deal, you might object?

Well, comments like these can easily get out of sync. In the worst-case scenario, they become misleading.

It leads to situations where you have to confront the current code and the outdated comment and you cannot really be sure which one describes what the behavior should be.

Comments don’t run, they are just an informal bunch of text and cannot be changed automatically (at least, not in a 100% reliable way). Their risk of becoming obsolete is therefore higher.

To rephrase it, comments like this are part of the problem, not the solution.

Inline comments are just a liability.

The worst part is that they often appear as a whole bunch:

public SomeResult computeResult(SomeParameter parameter) {
    // call nice service to fetch foo
    Foo foo = niceService.fetchFoo(parameter);

    // [...] 200 lines with comments+code like that
    // hilarity ensues... not
    return new SomeResult(foo, ...);
}

Indeed, the bad side effect of this kind of brain-dead comments is that it prevents the original authors to ask themselves: is the code readable enough this way? Am I thinking this through? How can I make the code more self-explanatory?

If you get used to this kind of comments, you will most likely focus your reading on them and live in the illusion that the method is readable and well-documented.

I have got some bad news for you: 200 lines of code for a method are NOT readable at all, no matter how much obsolete poetry you stick in there.

As a general rule of thumb, is it worth writing something down if that only took you 10 seconds to come up with?

A not-so-noisy example

Let’s move on to a more interesting example.

It’s not that the first example does not happen frequently, but there are some situations like the following that involves a bit more than pure noise.

public SomeResult computeResult(SomeParameter parameter) {
    /*
     * call nice service to fetch foo because
     * some contextual reasons
     *
     * fetchFoo may throw in theory but will not
     * because the parameter is always valid in
     * this particular usecase [...], so no try-catch,
     * YOLO
     */
    Foo foo = niceService.fetchFoo(parameter);
    return new SomeResult(foo);
}

"Ah! This comment is useful! It explains the implementation rationale!”, you may say.

While there is some value in these pieces of information, they just do not belong there.

Let me elaborate.

Small detour: back to basics

As you already know, in many programming languages, method signatures look like:

public SomeResult computeResult(SomeParameter parameter)

Ideally, the signature should be explicit enough (especially with well-defined types, parametricity FTW) to know what the method does. How the method does it should be relevant only if you have to change something there.

Everything that follows between curly braces is about implementation details.

Back to the example again

However, I would argue that the two information encoded as a inline comment above are NOT implementation details, yet they live in the implementation section.

What are these comment sections about?

the first part describe the intent behind the implementation (or at least part of it)
the second and last part describe (part of) the observable behavior of the method

Intent documentation

Intents are very contextual and temporal.

Decisions, no matter how small, are taken every day and guide the way we implement things.

These decisions are influenced by temporal factors mostly: the assumptions made at the time may not hold at all anymore in 6 months, 1 year…

Temporal documentation.

TEMPORAL documentation.

It rings a bell, somehow.

S-C-M! Source Control Management tools like Git, Mercurial and friends.

They play an important part in documentation. Not only do they intrinsically describe what has changed and when, they should describe why the changes were made.

That’s what commit messages are for!

And if you start thinking this way, there will be an additional benefit: you will keep your commits as small and focused as possible. If the commit is too big, there is no way you can explain all the important changes you made ;-)

And if you start to care enough about your changelog, you will get nice readable releases notes for free!

Observable behavior documentation

If what you describe is part of the observable behavior of the scope you are modifying, then it is clearly about the contract you implicitly sign between the code you are implementing and its callers.

The documentation is about the API. API is just a clever name for a set of accessible signatures. It is not an implementation detail at all, it should be near the method signature itself:

/**
 * *describes the nominal observable behaviour here [...]*
 *
 * fetchFoo may throw in theory but will not
 * because the parameter is always valid in this
 * particular usecase [...], so no try-catch, YOLO
 */
public SomeResult computeResult(SomeParameter parameter) {
    Foo foo = niceService.fetchFoo(parameter);
    return new SomeResult(foo);
}

Going further

You could even rewrite the method like this:

/**
 * *describes the nominal observable behaviour here [...]*
 */
public SomeResult computeResult(SomeParameter parameter) {
    try {
        Foo foo = niceService.fetchFoo(parameter);
        return new SomeResult(foo);
    }
    catch (MyNiceServiceException e) {
        throw new AssertionError("Should not happen", e);
    }
}

Now the assumptions are even more explicit. That opens even an interesting discussion about the virtues of failing fast :-)

One could argue we could do even better. Ideally, method signatures should be sufficient to tell what the method is doing: parametricity FTW! Hoogle.com is probably one of the best illustrations for this.

That requires discipline (especially with languages such as Java, C# et al), but is not impossible to achieve: try to minimize and contain side effects, forego nulls… and then types could convery a lot more useful information!

Yet another interesting discussion!

The end

As you can see, caring about documentation is a gateway drug to better software, clearer releases and happier collaborators.

I personally write comments less than 1% of the time I write code. This happens where there is a tiny local expression that may seem obscure and there is not simple way around it.

For the 99+%, there are almost always better places to write the information you want to convey:

the code itself, it should answer WHAT it does, without ambiguity, else just refactor it (extract meaningful methods, rename, split expressions… the IDE is your friend). This is the material that decays the least, rely on this as much as you can!
the *-doc (e.g. Javadoc, Csharpdoc): the information is about the observable behavior of the section you are altering
the intent: that should justify the commit you are about to push

Inline comments are (99+%) dead! Long live inline comments!

Compilers Hate Him! Discover This One Weird Trick with Neo4j Stored Procedures

2016-07-12T00:00:00+00:00

As you probably already know, Neo4j 3.0 finally comes with stored procedures (let’s call them sprocs from now on).

The cool thing about this is you can directly interact with sprocs in Cypher, as Michael Hunger explains in this blog post.

Writing stored procedures

During the preparation of my Neo4j introduction talk in the latest Criteo summit (we’re hiring!), I started playing around with sprocs.

The process is quite simple:

You write some code, annotate it
test it with the test harness
package the JAR and deploy it to your Neo4j instance (plugins/)!

Actually, step 3 may repeat itself quite a few times, Neo4j sprocs must comply to a few rules before your Neo4j server accepts to deploy it.

Sproc rules

The rules are detailed in @org.neo4j.procedure.Procedure javadoc, but we can summarize them as follows:

a sproc is a method annotated with @org.neo4j.procedure.Procedure
it must return a java.util.stream.Stream<T> where T is a user-defined record type
the record type must define public fields
these can only be of restricted types
if the sproc accepts parameters, they all must be annotated with @org.neo4j.procedure.Name
parameters can only be of specific types
the procedure name must be unique (name = package name+method name)
injectable types (GraphDatabaseService et al) must target public non-static, non-final, @Context-annotated fields

Fortunately, folks at Neo Technology have done a wonderful job at error reporting. Neo4j fails fast if any of the rules is violated and gives a detailed error message.

Here is an example with Neo4j 3.0.3 and the following failing attempt to deploy the following sproc:

@Procedure
public Stream<MyRecord> doSomething(Map<String, Integer> value) {
    // [...]
}

The following error will be prompted (see logs/neo4j.log):

Caused by: org.neo4j.kernel.api.exceptions.ProcedureException: Argument at position 0 in method `doSomething` is missing an `@Name` annotation.
Please add the annotation, recompile the class and try again.

Nice error message! Just add the missing @Name on the only parameter, re-compile, package and deploy the JAR again, restart Neo4j and you’re done!

Can we do better?

The previous example is quite trivial, but this back-and-forth could be potentially repeated many times, especially when one is not much familiar with sprocs.

Fortunately for us, most of the errors can be caught at compile time.

@Eureka("annotation processing FTW!”)

Annotations have been around in Java since end of 2004 (v1.5) and have come together with apt (now built in javac), the annotation processing tool.

What the latter does in brief (in long, read the spec) is to allow user-defined code to introspect a Java program at compile-time (original paper here) and possibly:

issue compilation notices/warnings/errors
generate static, source and/or bytecode files

(By the way, this means exceptions can be raised at compile-time too!)

Based on this, I decided to write a little annotation processor on my way back from Criteo summit (did I mention we are hiring?).

neo4j-sproc-compiler is born. And it’s used!

If Michael is happy, I am happy:

(I swear it’s not photoshopped, see #apoc channel, 1st of July 2016 in Neo4j-Users Slack).

neo4j-sproc-compiler in action

While the following screencast features Maven, the annotation processor is actually agnostic of any build tool. You can use any build tool you want or directly javac if that floats your boat!

Conclusion

Be cautious, most but not all checks can be performed at compile time. You’ll still need to write some tests and monitor your deploys!

Hopefully, this little utility that I wrote will shorten your development feedback loop and get your stored procedures harder, better, stronger and faster.

New Blog!

2015-05-03T00:00:00+00:00

Getting rid of Dotclear was long overdue. Impractical at best, I wasted way too much time polishing the contents so that it would not render too bad.

What’s next?

I need to automate the migration to HubPress, so it will take some more time before all my blog posts show up here. For now, http://florent.biville.net is still serving my old blog.

It’s just a matter of time before everything is fully set up ;)

Transfert Estival

2014-10-05T00:00:00+00:00

Mais pourquoi ?!

Pour avoir un dictionnaire chaque année, bien sûr ! (Désolé, mes talents GIMPiens sont encore limités).

Plus sérieusement, le fait de partir de Lateral Thoughts, société à laquelle j’étais associé et où je disposais d’une grande autonomie, peut poser question. Lateral Thoughts, pour toute personne souhaitant devenir freelance, est un endroit idéal. On peut même y être salarié en ayant les mêmes avantages (rémunérations nets moindres, évidemment). Oui, mais voilà, alors que le freelancing fait rage depuis plusieurs années dans notre "industrie", ma voie actuelle s’en écarte.

Le déclencheur

Il y a quelques mois, j’ai été contacté par un recruteur Google. De l’agréable surprise s’ensuivit un stress énorme et des préparations d’entretien jusqu’à la dernière marche courant Juin : la journée d’entretiens à Paris. Finalement non retenu à l’ultime jury de sélection de cette ultime étape, je n’en retiens que du positif. Petite parenthèse, quand je vois certains critiquer les entretiens où il est demandé de coder, je rigole doucement. Tentez le marathon Google et on en reparle :) Revenons à nos moutons. Comme je le disais, cette expérience intense m’a énormément appris : la lecture des publications de Google, entr’apercevoir l’entreprise pendant quelques heures, parler avec quelques ingénieurs… ont renforcé ma conviction sur un point : je veux être développeur, et rien d’autre. C’est un peu l’essence de notre métier, tel que je le conçois, qui m’est revenu en pleine figure : la technique au service du besoin. Et quand je dis technique, je ne parle pas du dernier framework à la mode ou du dernier langage soi-disant révolutionnaire. Je pense plutôt à de l’algorithmie, du design (pas celui de l’Architecte Omniscient, hein). Les ingés de Google n’ont pas créé Google FileSystem pour le fun ou pour en parler en conférence, mais bien parce que le besoin était criant. Revenir aux fondamentaux a donc redynamisé mon intérêt pour le développement et m’a fait prendre conscience de la distance entre mon quotidien, le microcosme dans lequel j’évolue et le quotidien présenté dans une entreprise d’une telle ampleur.

Et pourquoi pas freelance ?

Le fait d’évoluer en quasi-freelance m’a appris beaucoup de choses. Ça pourrait en fait se résumer en une phrase : on n’obtient que ce que l’on va chercher. Une bonne mission ? Trouve-la toi-même (ou fais en sorte que celle où tu es le devienne). Pas content de telle ou telle situation ? Agis ou accepte. Tout n’est pas rose non plus. Au sein d’un regroupement de freelances ou simili-freelances comme à Lateral Thoughts, chacun, et c’est bien normal, trace son bonhomme de chemin et fait émerger les projets qu’il a envie de développer. Là où cela se complique, c’est quand il s’agit de mutualiser les efforts. Pas de magie : si tu as besoin de plus de cerveaux pour co-réaliser ton idée, il faut convaincre. C’est un procédé juste, mais usant voire parfois démotivant. Pour qui me donne-je du mal ? Pour ma personne ? Pour Lateral Thoughts ? Une des réponses est : “en t’exposant au public, tu bénéficies de plus de visibilité et c’est aussi tout bénef’ pour LT”. J’ai d’ailleurs suivi ce précepte pendant 2 ans, autour de Neo4j, notamment : de Paris à Istanbul en passant par Genève. Enrichissant, mais fatigant aussi. Finalement, ces entretiens pour Google m’ont redonné un objectif qui dépasse mon nombril. J’ai touché de près à l’un des géants du Web, une boîte qui (me) fait rêver et à laquelle j’ai envie de contribuer. (J’assume mon côté bisounours). Bref, Google m’a juste aiguillé sur le bon chemin. Et ce chemin ne passe pas par le freelancing.

L’arrivée à Vidal

J’étais déjà intervenu à Vidal et j’y connaissais ses challenges techniques. L’environnement de travail de notre équipe auto-organisée est propice à l’amélioration continue et je compte bien l’utiliser à bon escient. Ce qui m’a motivé pour les rejoindre en tant qu’interne : c’est la perspective de pouvoir se focaliser sur ce que l’on fait de mieux et devenir irréprochables (par ordre d’importance) :

s’approprier nos softs, de leur création au suivi de prod en passant par les tests
devenir de plus en plus véloces sur la maintenance de ces produits
oser tenter des choix à contre-courant

Ce ne sont pas les idées qui manquent, ni la motivation générale. J’ai vraiment à coeur que notre équipe "Software" s’améliore collectivement. Nicolas Martignole parlait de l’équipe "Software" de Vidal en 2010, vivement 2015 !

Créer une application java avec Neo4j embarqué

2014-06-17T00:00:00+00:00

Un long discours ?

Après vous avoir assommé avec mon article précédent sur le stockage interne de Neo4j et sa scalabilité, je vais aujourd’hui me contenter d’assez peu. En effet, plutôt que de consacrer un effort important à expliquer des bonnes pratiques autour de la mise en oeuvre de Neo4j dans des projets Java, pourquoi ne pas créer l’archetype Maven qui fait le boulot ?

Archetype… Maven ?

Alors oui, je sais, certains d’entre vous ne peuvent pas voir Maven en couleurs.

Je sais qu’il existe quelques archetypes bien particuliers autour de Neo4j pour d’autres outils de build tels que celui de Stefan Armbruster pour Gradle. Néanmoins, je n’ai pas croisé d’archetypes équivalents à celui que je vais vous présenter.

Si vous pensez en avoir trouvé un, n’hésitez pas à me contacter que je le liste ici.

Physiologie

Penchons-nous maintenant sur l’archetype créé pour l’occasion.

Il génère des projets embarquant :

neo4j
neo4j-kernel (classifier test-jar) pour les tests d’intégration
junit
assertj-core

assertj-neo4j n’est pas encore assez mature, je vais tâcher de le faire évoluer avant de le proposer via l’archetype.

Contenu

Si vous suivez les instructions, vous vous retrouverez avec un projet tout simple : * qui insère des données avec Cypher :

qui lit des données via le framework de traversée Java
qui utilise EmbeddedDatabaseRule pour les tests JUnit (cette règle JUnit encapsule l’utilisation de Neo4j pour les tests d’intégration via son implémentation spécifique)

Conclusion

Un autre archetype Maven devrait suivre pour l’interfaçage REST de Neo4j. L’archetype décrit ici sera bientôt releasé sur Maven Central. En attendant, vous pouvez déjà l’utiliser et démarrer avec Neo4j sur des bases saines !

Neo4j Sous Le Capot

2014-06-09T00:00:00+00:00

3615-ma-vie

Tout ce qui va suivre n’est qu’un tissu de mauvaises excuses, me
direz-vous, mais j’ai tout de même quelques circonstances atténuantes
quant à l’inactivité de mon blog (et mon absence de la scène parisienne: je n’y ai pas fait de talks depuis 6 mois).

Sur un plan personnel d’abord, je suis heureux de vous annoncer qu’une jolie alliance orne désormais l’annulaire de ma main gauche :-)

Sur un plan professionnel, bien qu’absent “publiquement”, beaucoup de choses se sont passées : ma première formation sur Neo4j a eu lieu, j’ai eu l’occasion d’intervenir chez plus de clients et certains projets autour de Neo4j s’esquissent encore (stay tuned!).

D’ailleurs, si vous voulez que je vienne parler de Neo4j dans votre User Group, n’hésitez pas à me contacter (sur Twitter par exemple).

Back to business : parlons de Neo

Base de données orientée graphe ?

Neo4j, vous l’aurez compris, est une base de données orientée graphe. Mais qu’est-ce qu’“orientée graphe” signifie exactement ?

Si l’on cite Wikipedia, une base de données orientée graphe (graph database) est donc une base de données mettant en oeuvre des noeuds, relations et propriétés pour représenter et stocker de la donnée.

Cette définition peut vous paraître anodine, mais notez bien la présence de deux verbes (et non pas d’un seul) :

représenter
stocker

En termes plus techniques, une base de données orientée graphe offre donc une API (“représenter”) exposant un vocabulaire propre au graphe. Ses enregistrements sur disque (“stocker”) doivent eux aussi être formatés selon les structures d’un graphe.

Ce deuxième point est fondamental.

Prenons l’exemple d’un concurrent de Neo4j : Titan.

Dès la page d’accueil, on peut lire :

Titan is a scalable graph database […]

Support for various storage backends:

Apache Cassandra

Apache HBase

Oracle BerkeleyDB

Akiban Persistit

Cela contredit la définition que je vous ai donnée plus haut.

Si Titan était une base de données graphe, cela impliquerait que Cassandra, HBase, BerkeleyDB et Persistit le soient. Or, jusqu’à preuve du contraire, cela n’est pas le cas :)

Titan propose une surcouche d’API orientée graphe, déléguant la persistance à des stores distribuées. Cela n’en fait pas pour autant une base de données orientée graphe, tout comme Apache Giraph n’est “qu’une” API de calcul orientée graphe.

“Quelle importance ?”, me direz-vous ?

Hé bien, une base de données graphe, bien qu’elle offre des nombreux avantages, est intrinsèquement difficile à distribuer comme nous allons le voir au travers de cet article. C’est en regardant les couches les plus basses d’une base typiquement orientée graphe comme Neo4j que vous allez comprendre ce qu’être une base de données graphe implique en termes de partis pris.

Des liens et des chaînes

Neo4j, selon le modèle du Property Graph, structure les données par des noeuds liés par des relations.

Chacune de ces entités peut se voir attribuer un ensemble de propriétés (une clef [String], une valeur [entier, String, tableau de primitifs]).
Chaque relation porte obligatoirement une notion de type (exemple : une relation “FOLLOWS” ou “IS_FRIEND_WITH”).
Chaque noeud porte, depuis la version 2.0, une notion optionnelle (mais fortement recommandée) appelée “label” (un noeud a de 0 à n labels).

Évidemment, toutes ces informations sont persistées sur disque.

Un simple ls /path/to/neo/data/graph.db vous permettra de constater, outre les fichiers d’indexes Lucene (legacy: répertoire index, nouveau: répertoire schema) et les journaux de transactions, les différents fichiers .db :

neostore.labeltokenstore.db
neostore.nodestore.db
neostore.propertystore.db
neostore.relationshipstore.db
neostore.schemastore.db

Ils représentent tous un “store” dédié à un type de données particulier. Passons-les en revue individuellement, en commençant par les nouveautés.

Notez que les informations à venir sont sujettes à caution : les récents travaux autour des noeuds denses ont sans doute influencé le format des fichiers décrits.

`LabelTokenStore`

On s’en douterait presque, ce(s) fichier(s) contien(nen)t les enregistrements de labels. Il(s) n’existai(en)t donc pas avant la sortie de la 2.0.

Ces enregistrements comprennent :

un ID interne (typé int en Java, donc jusqu’à 2³¹ - 1 [sauf Java 8 où on peut avoir des int de 0 à 232 - 1 mais je diverge]). chacun de ces IDs est référencé dans le fichier neostore.labeltokenstore.db.id.
et un nom (c’est justement la valeur que vous assignez au label : “Personne” pour le label Personne) lui-même uniquement identifié (neostore.labeltokenstore.db.names.id) et stocké dans (neostore.labeltokenstore.db.names)

Ainsi le fichier neostore.labeltokenstore.db ne comporte en fait que des références vers les IDs internes et noms, stockés “à côté”. Notez que cette division en fichier neostore.db.* se retrouve pour tous les autres stores.

`SchemaStore`

Avec l’émergence des labels est apparu la notion de schema. Ne vous emballez pas : Neo4j n’est pas devenue une base de données normalisée. On parle plutôt d’une base de données schema-optional.

Les labels permettent de grouper des noeuds sémantiquement similaires (cela est donc complètement dépendant du domaine métier) mais rien n’empêche lesdits noeuds d’être complètement hétérogènes. Par exemple, deux noeuds peuvent partager le label Personne tout en comportant des propriétés différentes, disons, la couleur des cheveux pour l’un, la pointure pour l’autre.

Maintenant que nous avons des labels à disposition, nous pouvons même définir des contraintes sur ceux-ci : des contraintes d’unicité par exemple. Ces contraintes sont en fait appelées rules et l’ensemble de celles-ci forment le fameux schema dont je vous parlais. Ce support est assez récent et la structuration sous-jacente est encore toute simple. En effet, une rule comprend :

un ID interne (neostore.schemastore.db.id)
sa description à proprement parler (neostore.schemastore.db)

Jusqu’ici, j’ai couvert les additions récentes de Neo4j.

Bien entendu, Neo n’a pas attendu sa version 2.0 pour être une base de données orientée graphe à part entière. Regardons ses composants centraux.

PropertyStore

À quoi servirait une base de données orientée graphe sans propriétés sur nos noeuds et relations ? Pas grand chose :-)

Ces propriétés (rappel : propriété = clef/valeur) néanmoins ne sont pas enregistrées exactement au même endroit selon certains critères :

neostore.propertystore.db.index stocke la partie “clef” des propriétés
neostore.propertystore.db.arrays, comme son nom l’indique, est dédié aux propriétés dont la valeur est un tableau de primitives ou String
neostore.propertystore.db.strings quant à lui se charge de répertorier les propriétés dont la valeur est une chaîne de caractères
les autres propriétés (booléen, entier) sont stockés directement dans neostore.propertystore.db

Chaque jeu de propriétés est propre à la relation/le noeud le contenant, les propriétés sont représentées comme des listes simplement chaînées.

NodeStore et RelationshipStore

Le voilà, le nerf de la guerre !

Commençons par les noeuds. Chaque noeud est composé d’un :

ID “interne” (neostore.nodestore.db.id)
des références à ses labels (neostore.nodestore.db.labels{,.id})
une référence vers sa première propriété (l’ID interne de la propriété) et le premier noeud parmi tous ceux qui lui sont liés (le tout dans neostore.nodestore.db)

Conceptuellement, cela pourrait se représenter ainsi (slide outrageusement et à de nombreuses reprises emprunté à Neo Technology) :

Tout repose sur la structuration des enregistrements de relations. Cela est plutôt intuitif : les relations sont l’épine dorsale du graphe.

Cet élément central se décompose de la façon suivante :

un ID “interne” (comme d’hab’ : neostore.relationshipstore.db.id)
son type (neostore.relationshiptypestore.db.names)

Pour l’instant, ça n’explique pas ce qui en fait une base orientée graphe.

Pour cela, regardons plutôt le code Java (eh oui, c’est ça qui est cool avec les projets open source dans les langages qu’on connaît bien) :

public class RelationshipRecord extends PrimitiveRecord

{

    private long firstNode;

    private long secondNode;

    private int type;

    private long firstPrevRel = 1;

    private long firstNextRel = Record.NO_NEXT_RELATIONSHIP.intValue();

    private long secondPrevRel = 1;

    private long secondNextRel = Record.NO_NEXT_RELATIONSHIP.intValue();

    // [...]

Passons sur le formatage digne des codeurs C les plus chevronnés (qui pour une Pull Request pour remettre les accolades en fin de ligne ? :P).

Ce qui est vraiment intéressant ici, c’est cette notion de first et second. En réalité, il s’agit des références internes (tout est référence à ce niveau) aux enregistrements correspondant aux noeuds de départ et d’arrivée. Seulement, la notion de direction n’ayant de sens qu’au moment du requêtage et non à la création de la relation, on ne peut pas savoir, à ce niveau, qui du first ou du second est le noeud de départ d’où cette nomenclature.

Ce que vous devez comprendre de ce petit bout de code, c’est qu’une relation porte en réalité, outre les informations précédemment mentionnées :

une référence vers ses noeuds de départ et d’arrivée
une référence vers la précédente relation des noeuds de départ / d’arrivée
une référence vers la relation suivante des noeuds de départ / d’arrivée

Une illustration vaut mieux qu’un long discours :

Il s’agit exactement de ce que j’ai tenté d’expliquer : les flèches rouges symbolisent les liens portés par les enregistrements de relations. Chacune de ces relations pointe vers les relations précédentes/suivantes de ses noeuds de départ et d’arrivée.

Autrement dit, chaque noeud référence (flèche verte) un élément d’une liste doublement chaînée de relations.

Et c’est là la nature même du graphe !

C’est par cette structure que Neo4j peut se targuer d’être une base de données graphe.

Comment requêter de la donnée dans un graphe ? Par une traversée.
Comment traverser dans Neo4j ? En trouvant les points de départ les plus pertinents possible et en naviguant dans listes de relations/noeuds.

Vous commencez à comprendre pourquoi ce genre de base de données s’adapte très bien aux données fortement connectées ?

Quid des noeuds denses ?

Ahah, je vois que j’ai affaire à des lecteurs initiés ;)

Resituons le contexte au travers de deux situations légèrement différentes.

Situation n°1

Un noeud dense est un noeud qui est fortement connecté. De nombreux exemples se retrouvent d’ailleurs dans la vie courante. Par exemple, Justin Bieber a 52 millions de followers sur Twitter (tiens, je ne savais pas que la surdité était devenu un phénomène de masse).

Rappelez-vous, le noeud Justin Bieber pointe vers sa première relation. Si par manque de chance, vous avez besoin d’accéder à son 52 millionième noeud-fan, vous allez devoir traverser, dans le pire des cas, l’intégralité de la liste doublement chaînée des relations avant de le retrouver : bref, du O(n)… vraiment pas terrible.

Ceci dit, ce cas reste relativement rare. Modifions légèrement l’exemple.

Situation n°2

Justin Bieber a certes 52 millions de followers mais il a bien moins de personnes dans sa famille.

Si par hasard, parmi cette gigantesque quantité de relations, seules les relations familiales vous intéressent, vous faites face exactement au même problème que décrit ci-dessus… si vous utilisez une version de Neo4j antérieure à la version 2.1 de Neo4j.

Depuis cette version, les relations sont aussi discriminées par type, permettant ainsi de ne pas tomber dans cet écueuil. Un noeud est d’ailleurs considéré dense à partir de 50 relations par défaut (cf. “http://docs.neo4j.org/chunked/stable/kernel-configuration.html[dense node threshold]”).

Help! Je suis dans la situation n°1!

Si par malheur, et après exploration de toutes les alternatives (échantillonnage statistique etc), vous en concluez que vous ne pouvez faire autrement : rassurez-vous !

Tout d’abord, les équipes de Neo continuent de plancher et d’apporter des améliorations à ce sujet. Nous devrions donc voir quelques améliorations avec la v2.2.

De plus, une approche simple est déjà codée pour vous par l’excellent Max de Marzi.

L’idée de son extension est simple : elle va simplement ventiler les noeuds par niveau lors de chaque nouvelle insertion et les lire de façon transparente.

Voici donc un exemple de structure automatiquement créée par son extension :

Tout comme Justin Bieber, Lady Gaga et Madonna ont également de nombreux fans (chaque fan “LIKES” l’artiste). Un noeud factice va donc se substituer aux noeuds que l’on aurait directement lié aux artistes et introduire des couches, par le biais de noeuds intermédiaires regroupant eux aussi un nombre limité de fans, relié alors par une “DENSE_LIKES”. Les relations sont maintenant réparties et l’on pourra paginer nos requêtes de lecture de cette façon :

MATCH (fan:Fan)-[:DENSE_LIKES*0..5]->()-[:LIKES]->(loved:Artist {name:
“Madonna”})
RETURN fan

Cette requête signifie (en lisant le pattern de bas en haut, de droite à gauche) :

retourne tous les noeuds au label “Artist” et au nom “Madonna” +
qui sont “LIKÉS“ par un noeud quelconque (appelons-le META) +
et 0 à 5 relations DENSE_LIKE séparent META des noeuds

Étant donné que la requête recherche les nombreux fans d’un artiste, sans aucune ventilation du graphe, nous serions en plein dans la situation n°1 décrite préalablement. Néanmoins, cette approche simple couplée à l’usage astucieux des variable-length paths permet de ne récupérer qu’une fraction des fans sans pour autant traverser toutes les relations dont l’artiste dépend.

Neo4j et scalabilité

Maintenant que le format physique des fichiers est un peu plus clair, regardons un peu les couches supérieures.

Architecture

Les accès disques sont bien évidemment limités autant que possible. Deux niveaux de cache interviennent.

Le file buffer cache

Vous vous en doutez, le file buffer cache sert de tampon aux écritures/lectures des enregistrements physiques (cf. les fichiers décrits précédemment). Les entrées les moins récemment accédées sont évincées du buffer (LRU). Si possible, ce buffer est directement mappé au fichier store sous-jacent (“memory-mapping”). Ce comportement dépend du système de fichiers et de l’OS. Quoi qu’il en soit, cette couche a pour seul but de réduire au maximum les accès disque mais n’introduit aucune forme d’abstraction sur les données manipulées.

L’object cache

Lui aussi cache LRU, c’est à partir de ce moment-là que les données manipulées commencent à prendre la forme du graphe que vous requêtez par traversée ou par Cypher. Notez que l’allocation mémoire à ce niveau est prise sur la heap de la JVM hôte et non plus directement de l’OS hôte sous-jacent. C’est pourquoi il est souvent préférable de déployer Neo4j de façon isolée, afin que votre application ne vienne pas perturber (comme par exemple : ) les cycles GC de votre instance Neo et vise-versa.

et le reste

À partir de là, les APIs unitaires Java prennent le relais, suivies des APIs de traversées, Cypher et les APIs REST !

Gestion de la concurrence

Bien que faisant partie de cette (non-)famille qu’est NoSQL, Neo4j fait un peu figure d’exception, en se conformant à ACID. En effet, vous retrouverez avec Neo4j les transactions en 2 phases que vous connaissez bien. N’étant pas un spécialiste des systèmes distribués, je vous invite à lire la multitude d’articles existants sur les limites d’ACID, les limites du locking et les alternatives existantes (“lock-free concurrency”, BASE vs ACID) : Google est votre ami. J’en profite donc pour passer à la partie qui m’intéresse le plus : le sharding :)

Sharding d’un graphe dynamique

Expliquons brièvement le terme sharding. Le sharding consiste simplement à répartir ses données entre différentes instances d’un système de persistence distribué. Par exemple : je peux décider de stocker toutes les adresses postales américaines sur mes serveurs aux États-Unis et mes adresses australiennes à Sydney. Une instance donnée ne contient donc pas l’intégralité des données, mais le domaine métier auquel appartient mon application appartient comporte des notions qui se répartissent naturellement. Eh oui ! Le sharding est une solution technique, certes, mais hautement dépendante du métier (comme toute solution technique devrait l’être, mais je digresse).

Graphe statique

Un graphe statique est plutôt facile à sharder (dans la mesure où le domaine métier modélisé le permet), ses fragmentations sont faciles à détecter (on parle de “graph clustering” ou de “community detection”) : elles ne sont pas amenées à évoluer du tout. Certains algorithmes sont même relativement faciles à implémenter.

Graphe dynamique

Pour les graphes dynamiques, en revanche, c’est une autre paire de manche. De nombreuses opérations d’insertion et suppression interviennent en permanence et elles impactent nécessairement la topologie du graphe. Le but du jeu est donc de déterminer un découpage du graphe en shards de telle sorte, qu’à tout instant, le nombre de relations inter-shards soit minimisé. Cela est d’autant plus critique que les shards sont distants (imaginez la latence réseau induite par une traversée qui commence par un shard hébergé à Los Angeles pour finir dans un shard à Pékin).

C’est un sujet de recherche à part entière et Neo Technology travaille depuis plusieurs années sur un système shardable. Comprenez bien le terrible dilemne : par son orientation graphe dès les couches physiques, Neo4j est à la fois idéal pour stocker et requêter des données sous forme de graphe mais également très difficile à sharder !

Une lueur d’espoir ?

Il est pour l’instant nécessaire de miser sur du [*scaling
vertical*](http://fr.wikipedia.org/wiki/Scalability) : dimensionnez
suffisamment vos machines et tout se passera très bien. Laissez-moi vous
rassurer davantage : * jusqu’à présent, une infime minorité de clients
a été confrontée à une volumétrie telle ([capacité nomimale de
Neo4j](http://docs.neo4j.org/chunked/stable/capabilities-capacity.html): 34 millards de noeuds et de relations) qu’une répartition des données était nécessaire * il se trouve que certains domaines métiers permettent naturellement de ségréguer ses données * il existe un début de solution de répartition !

Le cache sharding !

Le titre peut faire peur, mais rassurez-vous, l’idée est toute simple. Tout d’abord, cette idée s’applique à Neo4j en mode High Availability. En d’autres termes, cela ne s’applique qu’à une instance Neo4j au sein d’un cluster.

Non seulement vous bénéficiez d’une réplication master/replica, mais vous pouvez également bénéficier de sharding. Oui, oui, j’ai bien dit sharding. Malheureusement, pour les raisons évoquées plus haut, il ne s’agit pas de sharding sur les données à proprement parler. Comme le titre l’évoque, il s’agit de sharding sur le cache.

Comment est-ce possible ? C’est tout simple !

Les caches de Neo4j sont des caches LRU, ils ne conservent que les entrées les plus récentes en leur sein. S’il existait un moyen de répartir les requêtes de façon persistante entre chaque instance de mon cluster, le tour serait joué. En effet, la requête X serait toujours exécutée sur l’instance A, la requête Y sur l’instance B… Le résultat X serait de facto dans les caches A, celui d’Y dans les caches B. Mes données seraient donc effectivement réparties par cache. Le problème se réduit donc à : comment répartir de façon consistante les requêtes à exécuter entre les instances de mon cluster Neo4j ? Je vous le donne en mille. La solution existe depuis des lustres : un simple load balancer comme HAProxy saura faire l’affaire. On parle de consistent routing (plus généralement de consistent hashing). Il suffit de configurer sa façon de router selon un des arguments présents dans le corps ou un quelconque entête des appels HTTP envoyés à Neo (rappelez-vous : toute communication distante est définie par une API REST) et le load balancer se chargera d’exécuter vos ordres là où vous l’avez configuré ! Astucieux, non ? Un simple load balancer, un cluster Neo4j (l’édition High Availability vous fournit tous les outils qu’il vous fait) et vous êtes prêts à affronter une forte volumétrie de données !

Conclusion

Une des leçons de NOSQL est que toute solution se restreint à un certain champ d’application et s’applique sous certaines conditions. J’espère que cet article vous aura permis de comprendre les faiblesses mais surtout les forces des bases de données graphe et, qui sait, vous donnera envie d’approfondir le sujet.

Je ne prétends pas à l’exhaustivité, donc si vous souhaitez que je détaille d’autres parties (exemple : Cypher), je peux éventuellement y consacrer d’autres articles.

<shameless_plug>Si cet article vous a plu, je peux aussi venir en parler dans un User Group de votre ville et je donne des formations customisables sur Neo4j et en français ! </shameless_plug>

🎸 Florent + The Machine

Node.js Streams For Fun And Profit

Thanks, Dear (Proof)Readers

Harder, Better, Mapper, Zipper

Streams in Node.js

You Can’t map This

Zip it!

One More Thing

Going further

Hello Jekyll!

hack.commit.push

TL;DR

La source : Hackergarten Paris

hack.commit.push dans tout ça ?

Save the date

Je veux m’impliquer !

Je veux proposer un projet

Ma société veut sponsoriser

Je veux animer un atelier d’introduction

Je veux être bénévole

Pourquoi Venir Au Hackergarten

Hackers: we need you!

Appel aux mentors

À vos calendriers !

Rant: The Teletubbies “Documentation” Pitfall

Disclaimer

Typical example

Teletu-what?

Back to our example

A not-so-noisy example

Small detour: back to basics

Back to the example again

Intent documentation

Observable behavior documentation

Going further

The end

Compilers Hate Him! Discover This One Weird Trick with Neo4j Stored Procedures

Writing stored procedures

Sproc rules

Can we do better?

@Eureka("annotation processing FTW!”)

neo4j-sproc-compiler in action

Conclusion

New Blog!

What’s next?

Transfert Estival

Mais pourquoi ?!

Le déclencheur

Et pourquoi pas freelance ?

L’arrivée à Vidal

Créer une application java avec Neo4j embarqué

Un long discours ?

Archetype…​ Maven ?

Physiologie

Contenu

Conclusion

Neo4j Sous Le Capot

3615-ma-vie

Back to business : parlons de Neo

Base de données orientée graphe ?

Des liens et des chaînes

LabelTokenStore

SchemaStore

PropertyStore

NodeStore et RelationshipStore

Quid des noeuds denses ?

Situation n°1

Situation n°2

Help! Je suis dans la situation n°1!

Neo4j et scalabilité

Architecture

Le file buffer cache

L’object cache

et le reste

Gestion de la concurrence

Sharding d’un graphe dynamique

Graphe statique

Graphe dynamique

Une lueur d’espoir ?

Le cache sharding !

You Can’t `map` This

Archetype… Maven ?

`LabelTokenStore`

`SchemaStore`