What is this?

Plubus is an agnostic micro-service router.

Features

• Bring your archaic HTTP api into the micro-service age without modifying the API
• Any language, any networking or queuing library
• Distributed by design, even session information
• Everything is a stream/push. Even HTTP (just a very short stream session!)
• Mix & Match - Daisy-chainable
• Everything's a stream™ - Low latency, low memory overhead, and processing before things 'complete transfer' for large things

Example scenerio

Let's take the case where you have an aging HTTP web-service API and you want to write all future API endpoints in the micro-service fashion. Additionally, you wish to add support for sockio.

In this example, here's our driver configuration: we're using an HTTP driver (plumbus_http) and a SockIO Driver (plumbus_sockio) on the request side.

• Request Side
  • plumbus_http
  • plumbus_sockio
• Response Side
  • plumbus_http_backend_shim
  • plumbus_redis

Each driver may support request, response, or request and response; request and response are known as sides. The protocol & conventions (e.g. client-server) that a driver links to typically determine which side(s) the driver supports. E.g. plumbus_http only supports the request side, but plumbus_redis supports both request and response.

Routing schemes

Every request and response that comes through plumbus (i.e. from a request driver or back through a response driver), contains the following. The transfer format of the message is driver-dependent, as these messages are passed via raw ruby calls.

{
  :sid => "a1a062f25f4e94c2762886069",
  :mid => "8b43601a1a062f25f4e94c2762886069,
  :path => '/x/y/z',
  :payload => <user defined data>
}

• sid - The session-identifier. Each request has a unique sid. When a response driver 'replies', it sends the sid back to plumbus which then forwards it to the correct request driver
• mid - The message identifier. In the event a message fails to route, the message-identifier is used to signal the sender (which could be the request or response side, w.r.t to plumbus), with the mid of the failed send (signal undeliverable)
• path - The path is used to route requests. We recommend you use unix style paths for all your requests as it makes doing things like HTTP shims easier. Else, if your HTTP requests, assuming you used a sane http request driver, would end up looking something like myserver.io/admin_dashboard_user_new instead of myserver.io/admin/dashboard/user/new.
• payload - The payload is arbitrary.

Signals

Under certain circumstances, signals are propogated to request drivers & response-drivers.

• undeliverable - For any undeliverable message, a response-driver gets an undeliverable response; this may or may not be important to the driver. For example, HTTP request drivers would probably return a 404 under these circumstances.
• hangup - Both a client request and all associated responses are able to hang-up (or not, for stream based responses). In the event a response hangs-up, if there are no remaining responsees, the client will not receive a hangup signal. In the event the request hangs-up, all responses associated with the original request (that have not themselves hung-up) will receive the hangup signal. For drivers like a typical HTTP request driver, this can utilized to determine that the HTTP request has received all the information and it should finish sending the client the HTTP stream and close the connection. For stream-based drivers, this provieds a useful way to watch resources or enable push notifications.
• panic - In the event a bonified un-recoverabl exception occurrs, and not user-based exceptions like authorization failures, missing parameters, etc, a response may reply with panic. Typically, a panic would be followed by a hangup. Sane HTTP request drivers may use this to return a 500 type excption.

Streaming

All connections in plumbus are streams. HTTP, as it is stateless, is just treated as a degenerate stream that closes it's session after a response is given. One of the neat-things about plumbus is that streams are able to hit multiple responses (by virtue of a request stream has sent multiple action requests and those were routed to seperate responses). This provides you with load-balancing on traditionally single-server streams (like sock.io).

Configuration

Configure is handled through a ruby file. This file contains a listing of ports which are just driver instances that are declared on either the request or response side.

port(:request, 'plumbus-http') do
  #Driver specific config
end

port(:request, 'plumbus-sockio') do
  #Driver specific config
end

port(:response, 'plumbus-http') do
  #Driver specific config
end

port(:response, 'plumbus-redis-queue') do
  #Driver specific config
end

Setup

#Setup
gem install plumbus

Usage

SYNOPSIS

plumbus config

DESCRIPTION

config is a ruby file that declares backends & frontends (called ports).

Requirements

• Modern nix (FreeBSD, Mac, or Linux)
• Ruby 2.2.1 or Higher (Very important)

Communication

♥ This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

• If you found a bug, open an issue.
• If you have a feature request, open an issue.
• If you want to contribute, submit a pull request.

Installation

RVM users: Run gem install plumbus

System ruby installation? Run sudo gem install plumbus

---

FAQ

When should I use plumbus?

Todo

Creator

• Seo Townsend (@seotownsend)

License

plumbus is released under the MIT license. See LICENSE for details.