Vinculum

Participants
Skills
Status	Production
Niche	Software
Purpose	Infrastructure
Tool	No
Location
Cost
Tool category

vinculum-sketch-0.png {{#if:No | [[Tool Owner::{{{ProjectParticipants}}} | }} {{#if:No | [[Tool Cost:: | }}

Description

Tool to consolidate data like sensor data, spaceapi data and mpd. https://github.com/Petraea/vinculum

Concept

Vinculum is a stateless, language-agnostic multidirectional message translating and redirecting engine built with the idea of using the minimal possible user-defined input to allow for maximum benefit. This translates into the Vinculum process opening arbitrary ports or making arbitrary connections on vinculum.nurdspace.lan as requested of it by any user capable of writing lines into its rules file.

The Rules File

The rule file is the core of vinculum and is read, top-to-bottom, on receipt of each line of data. Each line defines:

A regex that is run against the body of the message
The origin of the message (e.g. TCP:slab.nurdspace.lan:2003, meaning that vinculum will open a TCP connection to slab.nurdspace.lan on port 2003, then match INCOMING messages from this source. Local source sockets e.g. TCP-LISTEN:0.0.0.0:5555 can be defined, both opening said socket, and subsequently matching messages against the regex)
The destination of the message (Same rules as above, may be sent to anyone connected to a socket with e.g. TCP-LISTEN, or sent through a connection to a destination)
A regex to match for substitutions in the message
A regex to substitute (see https://docs.python.org/2/library/re.html#re.sub for format)
A continue flag (True or False) that decrees whether the engine should continue to perform matches in subsequent lines or halt here.

Each piece of data is on one line, comma separated (commas can be \'d out if needed in actual lines) and is executed in the order of the vinculum.rules file. The file itself is checked regularly, and upon update the process will attempt to restart itself according to the new configuration (although this is currently a touch buggy).

Protocols available:

TCP SEND and LISTEN
UDP LISTEN (SEND is a bit more complex...)
SSL SEND and LISTEN
UNIX file socket SEND and LISTEN

Practical Example

From the vinculum.rules file:

   #Send out espeak messages (and terminate)
   .*,TCP-LISTEN:*:16016,TCP:slab:16016,,,True
   .*,TCP-LISTEN:*:16016,TCP:smokescreen:16016,,,True
   .*,TCP-LISTEN:*:16016,TCP:spacenanny:55555,^.*?([^\t]+)\t?([^\t]+)$,\1: \2,False

These three lines control where the messages from !espeak go. Let's focus on the initial part:

 .*,TCP-LISTEN:*:16016

A s you can see, this is the same for all three. What this does is instruct vinculum to create a TCP listener port on port 16016, and then match every string (.*) from every IP (*) going into it. Next, the rules about where it goes:

 TCP:<host>:<port>

In the top two we see that the message is being redirected out via TCP to port 16016 on the two espeak-servers. The last one pushes the line towards spacenanny port 55555, where the bigledpanel listener is. We can make some modifications to the message as it travels, too:

 ^.*?([^\t]+)\t?([^\t]+)$,\1: \2

In the two espeak-server exits, we want the string completely unmolested so that all the options get parsed by the end listener. But for the bigledpanel, we only want the username and the message, which happen to be the penultimate and last tab-separated fields. So, to get these, we match on the regex ^.*?([^\t]+)\t?([^\t]+)$ and then output it as \1: \2 (i.e. the first matching group then the second).

Lastly, we see this:

 False

This controls whether the string that matched this line ought to continue through the rules. Because we know that there are no more rules below the bigledpanel one that ought to get matched, in order to save processing power we instruct vinculum to terminate matching after the last rule.

Where does it run?

It is running on a VM with the name vinculum.nurdspace.lan. Code in /opt/vinculum

Additional Functions

I'm currently building a JSON-RPC 2.0 compatible line-based receiver on vinculum to allow for more intuitive control of the LanBox. (Source: https://github.com/Petraea/LanBox-JSONRPC ) It's currently running on port 4444. Code is in /opt/LanBox-JSONRPC/