limerun

About

limerun is the reference implementation for OWIN-JS, a lightweight REST framework for Node.js.

It is an open-source, standards-based, drop-in replacement for Connect, Express, and Koa, with built-in seamless bridging to Node's built-in HTTP server, COAP servers such as node-coap, and native OWIN servers such as nodekit.io

The OWIN-JS specification defines a standard interface between Node.js REST servers and application/device logic. These include HTTP servers for web applications and COAP servers for Internet of Things (IOT) devices.

In fact, OWIN-JS is a direct port of the OWIN specification to expand the reach to Node.js servers as well as keep the reference .NET spec intact.

Published as open-source standards without dependence on any implementation or platform , the OWIN-JS specs allow applications to be developed independently of the actual server (nGinX, IIS, Node.js, Katana, node-coap, etc.)

In contrast to the OWIN-JS specification, this repository contains an actual OWIN-JS server implementation for node.js Javascript.

A broad ecosystem of servers and middleware, such as routers and view engines, exist in the the [OwinJS Organization](https://github.com/OwinJS] on GitHub.

Summary

A limerun middleware/application is simply a function(next) that provides a single REST-server owin context for each request, where it is easy to access all the HTTP/COAP parameters (this.request.path, this.response.body etc.). "Tasks" (promises) are returned for full async programming without callbacks nor use of limited ES6 features.

Middleware can be chained with app.use(middleware1).use(middleware2) etc.

limerun servers can also call regular Node HTTP middleware in the same chain with app.use( function(req,res){ ... } ).

limerun middleware and legacy middleware can be used with a COAP server such as node-coap with app.buildCoap() and can be used directly with Node's built-in http server with app.buildHttp(). It can even be used in embedded webkit applications such as nodekit.io.

For Humans and Things

limerun powers limedesktop, an open-source cross-platform OWIN-JS certified user interface framework for Mac, Windows, iOS, Android, Node.js, etc. Anything that can be written as a web application or REST application can be run on a single device with no coding changes, in javascript. As such limerun is for communicating with humans.

limerun also powers limedevice, a cross-platform OWIN-D connected IoT framework for any device that runs Node.js (including Raspberry Pi, BeagleBone, etc. ). As such limerun is for communicating things.

NPM Package Contents

This repository contains a Node Package Manager (NPM) package with helper functions for:

• AppBuilder for chaining middleware and applications, with automatic bridging to async-based Tasks (Promises conforming to Promise/A specification), use of this for owinContext instead of separate argument, and next argument for middleware chaining
• Connect app bridge: An OWIN-JS -> Connect/Express application bridge
• HTTP server bridge: A Node.js Http Server --> OWIN application bridge
• COAP server bridge: A node-coap Server --> OWIN application bridge
• Promise: Includes a dependency to the bluebird implementation which can be used by all other OWIN-JS applications and middleware

This package is intended for use in Node.js applications that either run on a web server that conform to the OWIN-JS specifications (such as the embedded webserver inside nodekit.io) or run using the included owinCoap and owinHttp bridge for node-coap and node Http servers respectively.

Middleware/Application Pipeline Builder: AppBuilder

app.use(middleware)

Adds a middleware node to the OWIN-JS function pipeline. The middleware are invoked in the order they are added: the first middleware passed to app.use will be the outermost function, and the last middleware passed to Use will be the innermost.

middleware

The middleware parameter determines which behavior is being chained into the pipeline.

• If the middleware given to use is a function that takes one argument, then it will be invoked with the next component in the chain as its parameter, and with the this context set to the OWIN-JS context. It MUST return a promise that conforms to the Promise/A specification.

• If the middleware given to use is a function that takes two arguments, then it will be invoked with the next component in the chain as its parameter, with a Node-based callback (function(err, result){})as its second parameter, and with the this context set to the OWIN-JS context. This type of middleware should return void.

• Legacy middleware can also be invoked with app.use( function(req,res){ ... } ), app.use( function(req, res, next){ ... } ) or app.use( function(err, req, res, next){ ... } ). The AppBuilder is smart enough to detect the two argument function with parameters named req and res in this case (use of different naming conventions need to be wrapped in a function(req,res){}), and assumes three and four argument functions are legacy.

returns app

The AppBuilder app itself is returned. This enables you to chain your use statements together.

build pipeline when all middleware added:

app.build()

returns an OWIN-JS AppFunc (promise) function(owin) that can be inserted into any OWIN-JS server.

Bridges

Three simple functions owin.connect(), owin.COAP() and owin.REST() are provided to bridge between OWIN-JS context applications/middleware and Node.js COAP and HTTP REST-style function(req,res) based applications/middleware. Often these are not used directly as the AppBuilder functionality automatically wraps legacy middleware and can even return a node.js-ready pipeline with .buildREST()

Note: The bridges are low overhead functions, binding by reference not by value wherever possible, so middleware can be interwoven throughout the pipeline, and open up the OWIN-JS world to the entire Connect/Express based ecosystem and vice versa.

We have not ported to Koa, Mach, Kraken or other similar frameworks but it would be relatively straightforward to do so.

• owin.connect() consumes a Connect-based application function (one that would normally be passed to the http.CreateServer method) and returns an OWIN-JS AppFunc.
• owin.http() consumes an OWIN-JS AppFunc and returns a function (that takes http.requestMessage and http.requestMessage as arguments) and one that can be passed directly to the http.createServer method
• app.buildHttp() is syntactic sugar to build the pipleine and returns a node.js-ready function (that takes http.requestMessage and http.requestMessage as arguments) and one that can be passed directly to the http.createServer method
• owin.coap() consumes an OWIN-JS AppFunc and returns a function (that takes http.requestMessage and http.requestMessage as arguments) and one that can be passed directly to the http.createServer method
• app.buildCoap() is syntactic sugar to build the pipleine and returns a node-coap-ready function (that takes req and res as arguments) and one that can be passed directly as server.on('request', ____) event handler

Example Usage

Installation

npm install limerun

To run HTTP and COAP demo:

git clone https://github.com/limerun/limerun.git
cd limerun
npm install
npm install coap
node demo.js

Hello World Example

const lime = require('limerun')
    , http = require('http');
var app = new lime.app();
app.use(function(next){
       this["owin.WriteHead"](200, {'Content-Type': 'text/html'});
    this["owin.ResponseBody"].end("<html><head></head><body>Hello World from HTTP Server</body>");
     return next();
    });
http.createServer(app.build()).listen(); 

Hello World with callbacks instead of Async Promises

const lime = require('limerun')
    , http = require('http');
var app = new lime.app();
app.use(function(next, callback){
     this["owin.WriteHead"](200, {'Content-Type': 'text/html'});
    this["owin.ResponseBody"].end("<html><head></head><body>Hello World from HTTP Server</body>");
   next(this, function(err, result){callback(err,result)});
    });
http.createServer(app.build()).listen(); 

Automatic OwinConnect Bridge to Legacy Connect/Express Middleware

var lime = require('limerun')
  , http = require('http');
var app = new owin.app();  
app.use(function(req, res) {
    response.writeHead(200, {"Content-Type": "text/html"});
    response.end("<html><head></head><body>Hello World</body>");
});
http.createServer(app.build()).listen(); 

OWIN - HTTP Bridge

var lime = require('limerun')
  , http = require('http'); 
var http = require('http');
var app = new owin.app();
app.use(function(next){
    this.response.writeHead(200, {'Content-Type': 'text/html'});
    this.response.end("<html><head></head><body>Hello World</body>");
return next();
});
http.createServer(app.buildHttp()).listen();

Definitions

• appFunc = (Promise) function() with this = owin
• app.use = (app)function(middleware)
• middleware = (Promise) function(next) with this = owin, next=appFunc
• OR middleware = (void) function(next, callback) with this = owin, next=(void) function(callback) for compatibility with traditional node Callback-style OWIN-JS middelware
• OR middleware = fn(req, res, next) for compatibility with Connect/ExpressJS middleware
• OR middleware = fn(err, req, res, next) for compatibility with Connect/ExpressJS middleware
• app.build = (appFunc) function() // builds middleware
• app.buildHttp = (function(req, res)) function() // builds middleware for compatibility with Connect/ExpressJS hosts
• owin = limerun owin context

API Reference Specification

OWIN-JS/owin-js-spec