coju

Coju

A name from some random website that generated random names. No meaning. Not going to use any buzz-words like "Opinionated" or "super ballsy framework to make your cat sing showtunes"...

Problem

The problem with existing frameworks is they do a lot more than the average developer uses, this is part of the industry standard for some reason. Everything needs to do everything. bullshit

More importantly, there aren't many frameworks that strive to use the best of the available technology and developers happily settle for living in an umma-gumma land of dreams.

Most modules aren't even strict compliant which is a ball-ache for developers who want to use a strict environment.

Solution - Wrap the Http object in a strict smoking jacket

Just a simple wrapper for the http object, a bit like connect but strict compatible and using Harmony (ES6) features as they become available for the type of developer that might say "Yolo" (even sarcastically)

Getting started

To create a server you must first know how to run Node with strict mode enabled. This breaks a LOT of modules. a LOT of modules, actually most modules. I can't stress that enough, shame on JS devs.

Also; unfortunately, due to the harmony-ess of this project, this is also not compatible with Node JS versions < 0.11.7; although I recommend 0.11.9 since the 0.11.7 release has a few bugs from what I can see on 26/2/2014.

This version requirement will increase as more Harmony features are added to V8 and decrease as they stabalise but development of these futuristic strains will happen on new branches specifically for people living on the edge. YOLO.

Please don't report a bug if you're getting errors and can trace it to a module that isn't strict compliant or just has a bug in it. Use your noggin and node debug --harmony --use_strict yourapp.js to find your culprit and then report bugs.

To run Coju you must run node with two flags:

NODE_ENV=development node --harmony --use_strict yourapp.js

Otherwise you're going to get a lot of errors around the new syntax.

To get started you'll need to create a server, this is pretty simple to be honest as this is just a wrapper for dealing with some normal http stuff in Node JS.

{
  require('coju').listen(1811);
}

Much like Connect (which, by the way is awesome) Coju has a "middleware" philosophy with slightly less verbosity/guesswork.

• No need for a configure block, although one is available for options/optimisation.
• None of this set/get string stuff. Annoying. This isn't PHP.
• Doesn't come "packaged" with any other gumph besides core code.
• Doesn't care what order middleware is loaded in. Http.Server is an EventEmitter and will work that way.

###Building your project on coju

Building a site on coju is like building any other node/Connect project, the concept of modules, servers and all that other stuff is the same. All coju offers is a neatly gift-wrapped http service for capturing requests and modifying responses via a series of middleware.

Your main entry point will look something like this, for a simple hello world example

index.js

{
  let coju = require('coju');
		
  coju.on('request', function(req, res) {
  res.writeHead(200, {'Content-Type': 'text/html'});
  res.end("<h1>Hello World.</h1>");
});
		
  coju.listen(1811);
}

While the notion of a built in router seems clever and helpful, any modules that aren't core to the http service should be external and thus managed so. All extra functionality will be handled this way going forwards.

coju has a simple api and a very small number of "types" to keep shit simple, frameworks these days all seem convoluted and voodoo. Not coju.

##coju-core API

See here for documentation on coju core.

####coju()

type Function
access Public
return Function
stability 6: Testing

coju is a class (in the loosest possible usage of the word until we get classes/modules in Harmony) and simply interjects a very lightweight system in the middle for using middleware easily.

---

{
  require('coju').listen(1811);
}

####coju.configure(json options)

type Function
access Public
return void
stability 6: Testing

The default configuration of coju should keep most people happy but there are some bottleneck features that might not be necessary that can be switched off easily inside of this function. The below example shows all currently configurable options.

Debug will be true if your NODE_ENV is set to development and false if it is equal to anything else.

---

coju.configure({
  "debug"  : true,
  "events" : {
    "request"       : true,
    "close"         : true,
    "checkContinue" : true,
    "continue"      : true,
    "connect"       : true,
    "upgrade"       : true,
    "clientError"   : true
  }
});

####coju.on|off(string eventName, Function callback)

type Function
access Public
return Void
stability 6: Testing

coju uses Nodes default list of events from the http.Server object, to view all the available event subscriptions please read the documentation.

Coercly, all the above events can be unsubscribed from by using the coju.off method with a similar syntax.

To use this most efficiently, USE NAMED FUNCTIONS otherwise it has to index and check indexes and blah blah. Named functions simply win.

####Subscription

{
	let coju = require('coju');
		
	coju.on('request', function myFirstCojuMiddleware(req, res) {
  res.writeHead(200, {'Content-Type': 'text/plain'});
  res.end("Hello World.");
});
		
	coju.listen(1811);
}

####Unsubscribing from events

{
	let coju = require('coju');
	
	coju.on('request', function myFirstCojuMiddleware(req, res) {
  res.writeHead(200, {'Content-Type': 'text/plain'});
  res.end("Hello World.");
});
		
	coju.off('request', function myFirstCojuMiddleware(req, res) {
  res.writeHead(200, {'Content-Type': 'text/plain'});
  res.end("Hello World.");
});
		
	coju.listen(1811);
}

Writing Middleware

Unlike with Express/Connect middleware is not registered via a use call, if we're writing a module we imply it's usage by subscribing to our varying events (yes, if you configure coju to not fire these events all of your middleware will stop working) see this example, a simple IP blocker.

#####index.js

{
  let
    coju = require('coju'),
    ipban = require('./middleware/ip-ban');
    
  // On all requests, check for banned IP addresses.
  ipban(coju);
  
  // Create server
  coju.listen(1811);
}

#####middleware/ipban.js

{
  
  function getRemoteIPAddress(req) {
    return (req.headers['x-forwarded-for'] || '').split(',')[0] 
          || req.connection.remoteAddress; 
  }
  
  function ipban(req, res) {
    let banned = ['8.8.8.8', '127.0.0.1'];
    if (banned.indexOf(getRemoteIPAddress(req))) {
      res.writeHead(403, {'Content-Type': 'text/plain'});
    res.end("Nope. No access, banned IP.");
    }
  }
  
  module.exports = function(coju) {
    coju('request', ipban);
  };
}