Distro, helper module to create UPD clients and servers.

This new package “Distro” encapsulates the work needed to create UDP datagram servers and clients.

This is a very early version and the API may change but I like what I have so far.

As part of the package I included a message factory as well to try to formalize an early interface for these messages that the servers and clients can agree upon and provide some other layers on top of the basic UDP protocol (see below “Working with verbs”).

Install

Simple do npm install distro

Creating a server

Creating a server is as simple as:

	var distro = require("distro");

	var server = distro.create()
		.udp4Server({port: 41234})
		.receive(cb);

	function cb(err, msg) {
		console.log("Handling message: " + msg.id);
	}

You can register multiple handlers per server, just call receive again.

	var distro = require("../src/client_server");

	var server = distro.create()
		.udp4Server({port: 41234});

	server.receive(handler1);
	server.receive(handler2)

A server is nothing without a client

	var distro = require("distro");
	var client = distro.create()
		.udp4Client({port: 41234})
		.send(obj);

The send method takes a distro Message that you can easily create using the library.

The Messages

Messages need at least two parameteres, a headers object and a payload.
The headers needs at least one property (uri).

	var distro = require("distro");
	var header = {uri: "/object/main" };
	var msg = distro.create().message(headers, payload);

If you want to receive confirmation once the message is received you can add the server information to the headers object.

	var distro = require("distro");
	var header = {
		uri: "/object/main",
		address: "localhost",
		port: 42234
	};
	var msg = distro.create().message(headers, payload);

The server(s) that receives a message with origin information will send back a RECEIVED message to such origin.
The payload of a RECEIVED message is the id of the message.

Messages Id are autogenerated UUID, the payload of a message can be any serializable object. This is a very important consideration since recursive objects will not work properly.

Working with “verbs”

This is not supported by users datagrams but have been added to standardize interfaces with a future project that I have in mind.

The headers object can have a verb property that maps to some of the http verbs. At the moment the supported verbs are HEAD, GET, POST, PUT, DELETE and PATCH.

What do I mean with supported verbs, you may ask?

The server object can register different handlers for each of those verbs. Instead of registering handlers with the receive method you can use specific verbs methods.

	var distro = require("distro");

	var server = distro.create()
		.udp4Server({port: 41234})

	server.head(handleHeadVerb);
	server.get(handleGetVerb);
	server.post(handlePostVerb);
	server.put(handlePutVerb);
	server.del(handleDeleteVerb);
	server.patch(handlePathVerb);

You don’t need to specify the get verb for messages. If you registered handlers with the get method and your messages don’t have a verb, this handler(s) will be used.

You can still add handlers to receive that will be called no matter the verb of the messages, this can be helpful for audit, logging or error handlers purposes.