graft

Warning: This library is under active development, and should not be considered production ready

The Graft project explores what the web could become, if we extended microservice architectures into the client.

• Motivation
• API
• About LibChan
• Contributors
• License

Interested in Graft and jsChan? Watch @mcollina presentation at NodeConf.eu 2014, "Full Stack Through Microservices"

Motivation

When you graft something, it involves joining together parts to create a new whole. One that is hopefully more adaptable, resilient and ultimately interesting.

"Instead of pretending everything is a local function even over the network ..., what if we did it the other way around? Pretend your components are communicating over a network even when they aren't?" -- Docker's Solomon Hykes on LibChan - [link]

Explore our concepts and influences

---

Our Projects

• graft: the library that ties everything together.
• jschan: our 'standard carrier'. A port of libchan.
• aetherboard: our 'hello world' demo. A collaborative whiteboard.

Our Process

• discover how to connect tools through microservices.
• explore the tools that are already available.
• adapt those that could be integrated.
• innovate to build those that don't exist yet.

Our Principles

• favor small tools that serve only one purpose, but do so well.
• eschew state, because it only leads to trouble.
• focus on javascript, because it is universal.
• evaluate and document, not prescribe.
• educate.

Our Goals

• be the premier javascript implementation of libchan.
• be completely supported for node.js as soon as possible.
• use Node.JS streams to replicate the semantics of Go Channels.
• be functional and usable on the browser as we test the waters.
• use virtual stream objects to provide an api similar to Gulp.
• attempt control flow abstractions similar to HighlandJS.
• experiment, document and learn.

---

API

• graft()
• graft.ReadChannel()
• graft.WriteChanel()
• graft.branch()
• graft.where()
• Request Interface
• spdy.client()
• spdy.server()
• ws.client()
• ws.server()

---

graft()

The main object of this library. A Graft instance is a Transform stream with objectMode: true. The objects on the output of a Graft instance are Requests. On the input side, you can write just normal JS objects, and everything else you can write to a jsChan channel. These objects will be automatically wrapped up in a Request.

Internally, each Graft instance is backed by jschan.memorySession()`.

In order to process the requests, you can just:

var graft = require('graft')();
var through = require('through2');

graft.pipe(through.obj(function(msg, enc, cb) {
  console.log(msg); // prints { hello: 'world' }
  // process your request
  cb();
}));

graft.write({ hello: 'world' });

graft.ReadChannel()

Returns a nested read channel, this channel will wait for data from the other party.

graft.WriteChannel()

Returns a nested write channel, this channel will buffer data up until is received by the other party.

graft.branch(function(req), stream)

Passes the request to the first argument, and if that returns a truthy value, it calls write(req) on the associated stream. It respect backpressure.

graft.where(obj, stream)

Shortcut for the most common usage of graft.branch(), it allows to rewrite:

graft.branch(function(msg) {
  return msg.hello === 'world'
}, stream)

into:

graft.where({ hello: 'world' }, stream)

---

Request Interface

Each Graft request is the first message sent on a top-level channel, and it is composed of:

• all the properties of the message
• _channel, the associated channel
• _session, the associated session

Each request will have its own channel, but the session is generic for every client.

The _channel and _session properties will not be enumerable.

---

spdy.client()

Creates a new spdy client to pipe to:

var graft = require('graft')();
var spdy = require('graft/spdy');

graft.pipe(spdy.client({ port: 12345 }));

graft.write({ hello: 'world' });

---

spdy.server()

Creates a new spdy server that you can pipe to a graft instance:

var graft = require('graft')();
var spdy = require('graft/spdy');
var through = require('through2');

spdy
  .server({ port: 12345 })
  .pipe(graft)
  .pipe(through.obj(function(msg, enc, cb) {
    console.log(msg); // prints { hello: 'world' }
    // process your request
    cb();
  }));

---

ws.client()

Creates a new ws client to pipe to:

var graft = require('graft')();
var ws = require('graft/ws');

graft.pipe(ws.client({ port: 12345 }));

graft.write({ hello: 'world' });

It works even from a Browser, using WebPack or Browserify.

---

ws.server()

Creates a new ws server that you can pipe to a graft instance:

var graft = require('graft')();
var ws = require('graft/ws');
var through = require('through2');

ws
  .server({ port: 12345 })
  .pipe(graft)
  .pipe(through.obj(function(msg, enc, cb) {
    console.log(msg); // prints { hello: 'world' }
    // process your request
    cb();
  }));

You can even pass an existing http server that will be hooked up, like so:

var graft   = require('graft');
var ws      = require('graft/ws');
var http    = require('http');
var server  = http.createServer();

ws
  .server({ server: server })
  .pipe(graft())

About LibChan

Libchan is the connective tissue to all our endeavours. It is a microservices library announced by the Docker project, and it is going to form the basis of all of the tools they build in the future.

It's most unique characteristic is that it replicates the semantics of go channels across network connections, while allowing for nested channels to be transferred in messages. This would let you to do things like attach a reference to a remote file on an HTTP response, that could be opened on the remote end for reading or writing.

The protocol uses SPDY as it's default transport with MSGPACK as it's default serialization format. Both are able to be switched out, with http1+websockets and protobuf fallbacks planned.

While the RequestResponse pattern is the primary focus, Asynchronous Message Passing is still possible, due to the low level nature of the protocol.

Contributors

Adrian Rossouw

• CTO of Wayfinder
• Co-Founder of Graft project.
• Founder of Aegir project.
• Founder of Waif project.
• Former Drupal Core Developer

Peter Elgers

• VP of Engineering at Nearform.
• Co-Founder of Graft project.

Matteo Collina

• Co-Founder of Graft
• Founder of Mosca project.
• Founder of Levelgraph project.
• Founder of Ponte project.

License

MIT