circuits
====

A simple socket-io framework for client and server communcation around CRUD operations

Usage

install using npm

npm install circuits

Basic client server example source

``coffee


port to listen to

client.on 'connect', ->
client.emit Operation, 'echo', CRUD.read, 'any bats in here?',(err, data)->
if (data == 'any bats in here?')
console.log 'No bats here I guess..'
process.exit()
`

ToDo:
Example using Circuits with a Backbone model
Example using Circuits with a Backbone collection
Example using Circuits with Express framework

Whats in the box?

#### create Circuits server instance

new circuits.Server( httpServer, controllerResolver, [acl, redisHost, redisDB, redis, redisPort, circuitChannel] )

- httpServer instance of require('http').Server
- controllerResolver function that returns an object with mapping to CRUD operation for provided controller name
- acl the ACL object, if none provided it allowes everything
- redisHost IP address of your redis (default is "127.0.0.1")
- redisDB redis db to use (default is 10 )
- redisPort redis port (deault is 6379)
- circuitChannel name space for communication between Circuits instances

#### messages

circuits.Messages
is a map of String => String of supported Circuits messages

the Operation message is a request for a message to be dispatched to respective controller on the server

arguments

name | type | description
-----|------|------------
controller name | String | the controller to dispatch this message to
crudOp | circuits.CRUD.{create,read..} | the crud operation
params | Object | parameters to be passed
operation params | Object* | depending on the CRUD operation, a set of required fields

required operation params for the different CRUD operations

CRUD.create

name | type | description
-----|------|------------
data | Object | the object to be created

CRUD.read

name | type | description
-----|------|------------
id | String | resource id

CRUD.update

name | type | description
-----|------|------------
id | String | resource id
data | Object | the object to update with

CRUD.delete

name | type | description
-----|------|------------
id | String | resource id

#### CRUD operations

circuits.CRUD

is simply a map of String => String of
create, read, update, delete and patch

#### ACL

circuits.ACL constructor arguments

name | type | description
-----|------|------------
rules | Object | mapping of controllers to allowed crud operations and respective user groups
controller+crud groups | function(userID, callback = function(err, groups)) | function that returns groups for a given user ID
optional check | function(userID, model, modelId, crudOp, callback = function(message,boolean) | an optional check for special cases were you want to enforce a finer grained ACL, for example for when only a creater of a resource is only allowed to do a write operation on that model..

example of a controller+crud group rules

`javascript
{
"MyModel" : {
"create" : ["public"],
"read" : ["public"],
"update" : ["users"],
"delete" : []
},
"SecretModel" : {
"create" : ["users"],
"read" : ["users"],
"update" : ["users"],
"delete" : ["users"]
}
}
``

is simply an object mapping controllers to respective allowed crud operations

High Level Design