marufsiddiqui / feathers Goto Github PK

Introduction

Feathers is a light weight web application framework that rides on top of Express, one of the most popular web frameworks for NodeJS. It makes it easy to create RESTful web services and real-time applications using SocketIO and several other NodeJS real-time libraries.

If you are not familiar with Express head over to the Express Guides to get an idea. Feathers works the exact same way except that var app = require('express')(); is replaced with var app = require('feathers')(). The most important concept that Feathers adds to Express middleware is data oriented Services. How services work and the API additional to the available Express API is outlined in the following documentation.

Configuration

REST

In almost every case you want to exposes your services through a RESTful JSON interface. This can be achieved by calling app.configure(feathers.rest()).

To set service parameters in a middleware, just attach it to the req.feathers object which will become the params for any resulting service call:

app.configure(feathers.rest()).use(function(req, res) {
  req.feathers.data = 'Hello world';
});

app.use('/todos', {
  get: function(name, params, callback) {
    console.log(params.data); // -> 'Hello world'
    callback(null, {
      id: name,
      params: params,
      description: "You have to do " + name + "!"
    });
  }
});

The default REST handler is a middleware that formats the data retrieved by the service as JSON. If you would like to configure your own handler middleware just pass it to feathers.rest(handler). For example a middleware that just renders plain text with the todo description (res.data contains the data returned by the service):

app.configure(feathers.rest(function restFormatter(req, res) {
    res.format({
      'text/plain': function() {
        res.end('The todo is: ' + res.data.description);
      }
    });
  }))
  .use('/todo', {
    get: function (id, params, callback) {
      callback(null, { description: 'You have to do ' + id });
    }
  });

If you want to add other middleware before the REST handler, simply call app.use(middleware) before configuring the handler.

SocketIO

To expose services via SocketIO call app.configure(feathers.socketio()). It is also possible pass a function(io) {} when initializing the provider where io is the main SocketIO object. Since Feathers is only using the SocketIO default configuration, this is a good spot to initialize the recommended production settings:

app.configure(feathers.socketio(function(io) {
  io.enable('browser client minification');  // send minified client
  io.enable('browser client etag');          // apply etag caching logic based on version number
  io.enable('browser client gzip');          // gzip the file
  io.set('log level', 1);                    // reduce logging

  // enable all transports (optional if you want flashsocket support, please note that some hosting
  // providers do not allow you to create servers that listen on a port different than 80 or their
  // default port)
  io.set('transports', [
      'websocket'
    , 'flashsocket'
    , 'htmlfile'
    , 'xhr-polling'
    , 'jsonp-polling'
  ]);
}));

This is also the place to listen to custom events or add authorization:

app.configure(feathers.socketio(function(io) {
  io.on('connection', function(socket) {
    socket.emit('news', { hello: 'world' });
    socket.on('my other event', function (data) {
      console.log(data);
    });
  });

  io.set('authorization', function (handshakeData, callback) {
    // Authorize using the /users service
    app.lookup('users').find({
      username: handshakeData.username,
      password: handshakeData.password
    }, callback);
  });
}));

Similar than the REST middleware, the SocketIO handshakes feathers property will be extended for service parameters:

app.configure(feathers.socketio(function(io) {
  io.set('authorization', function (handshake, callback) {
    handshake.feathers.user = { name: 'David' };
  });
}));

app.use('todos', {
  create: function(data, params, callback) {
    // When called via SocketIO:
    params.user // -> { name: 'David' }
  }
});

Once the server has been started with app.listen() the SocketIO object is available as app.io.

Primus

Primus is a universal wrapper for real-time frameworks and allows you to transparently use Engine.IO, WebSockets, BrowserChannel, SockJS and Socket.IO. Set it up with feathers.primus(configuration [, fn]) where configuration is the Primus server configuration and fn an optional callback with the Primus server instance that can e.g. be used for setting up authorization:

// Set up Primus with SockJS
app.configure(feathers.primus({
  transformer: 'sockjs'
}, function(primus) {
  // Set up Primus authorization here
  primus.authorize(function (req, done) {
    var auth;

    try { auth = authParser(req.headers['authorization']) }
    catch (ex) { return done(ex) }

    // Do some async auth check
    authCheck(auth, done);
  });
}));

In the Browser you can connect like this:

<script type="text/javascript" src="primus/primus.js"></script>
<script type="text/javascript">
  var primus = new Primus(url);

  primus.on('todos created', function(todo) {
    console.log('Someone created a Todo', todo);
  });

  primus.send('todos::create', { description: 'Do something' }, {}, function() {
    primus.send('todos::find', {}, function(error, todos) {
      console.log(todos);
    });
  });
</script>

Just like REST and SocketIO, the Primus request object can be extended with a feathers parameter during authorization which will extend the params for any service request:

app.configure(feathers.primus({
  transformer: 'sockjs'
}, function(primus) {
  // Set up Primus authorization here
  primus.authorize(function (req, done) {
    req.feathers = {
      user: { name: 'David' }
    }

    done();
  });
}));

Services

As mentioned, the basic Feathers functionality is fully compatible with Express. The key concept added to that of middleware is *service objects. A service can be any JavaScript object that offers one or more of the find, get, create, update, remove and setup service methods with the following signatures:

var myService = {
  find: function(params, callback) {},
  get: function(id, params, callback) {},
  create: function(data, params, callback) {},
  update: function(id, data, params, callback) {},
  patch: function(id, data, params, callback) {},
  remove: function(id, params, callback) {},
  setup: function(app) {}
}

And can be used like any other Express middleware app.use('/my-service', myService).

All service callbacks follow the function(error, data) NodeJS convention. params can contain any additional parameters, for example the currently authenticated user. REST service calls set params.query with the query parameters (e.g. a query string like ?status=active&type=user becomes { query: { status: "active", type: "user" } }).

It is also possible to return a Promise object from a service instead of using the callback, for example using Q:

var Q = require('q');

var todos = {
  get: function(id) {
    var dfd = Q.defer();

    setTimeout(function() {
      dfd.resolve({
        id: id,
        description: 'You have to do ' + id
      });
    }, 500);

    return dfd.promise;
  }
}

find

find(params, callback) retrieves a list of all resources from the service. Ideally use params.query for things like filtering and paging so that REST calls like todo?status=completed&user=10 work right out of the box.

REST

GET todo?status=completed&user=10

SocketIO

socket.emit('todo::find', {
  query: {
    status: 'completed'
    user: 10
  }
}, function(error, data) {
});

get

get(id, params, callback) retrieves a single resource with the given id from the service.

REST

GET todo/1

SocketIO

socket.emit('todo::get', 1, {}, function(error, data) {

});

create

create(data, params, callback) creates a new resource with data. The callback should be called with the newly created resource data.

REST

POST todo
{ "description": "I really have to iron" }

By default the body can be eihter JSON or form encoded as long as the content type is set accordingly.

SocketIO

socket.emit('todo::create', {
  description: 'I really have to iron'
}, {}, function(error, data) {
});

update

update(id, data, params, callback) updates the resource identified by id using data. The callback should be called with the updated resource data.

REST

PUT todo/2
{ "description": "I really have to do laundry" }

SocketIO

socket.emit('todo::update', 2, {
  description: 'I really have to do laundry'
}, {}, function(error, data) {
  // data -> { id: 2, description: "I really have to do laundry" }
});

patch

patch(id, data, params, callback) patches the resource identified by id using data. The callback should be called with the updated resource data. Implement patch additionally to update if you want to separate between partial and full updates and support the PATCH HTTP method.

REST

PATCH todo/2
{ "description": "I really have to do laundry" }

SocketIO

socket.emit('todo::patch', 2, {
  description: 'I really have to do laundry'
}, {}, function(error, data) {
  // data -> { id: 2, description: "I really have to do laundry" }
});

remove

remove(id, params, callback) removes the resource with id. The callback should be called with the removed resource.

REST

DELETE todo/2

SocketIO

socket.emit('todo::remove', 2, {}, function(error, data) {
});

setup

setup(app, path) initializes the service passing an instance of the Feathers application and the path it has been registered on. The SocketIO server is available via app.io. setup is a great way to connect services:

var todoService = {
  get: function(name, params, callback) {
    callback(null, {
      id: name,
      description: 'You have to ' + name + '!'
    });
  }
};

var myService = {
  setup: function(app) {
    this.todo = app.lookup('todo');
  },

  get: function(name, params, callback) {
    this.todo.get('take out trash', {}, function(error, todo) {
      callback(error, {
        name: name,
        todo: todo
      });
    });
  }
}

feathers()
	.use('todo', todoService)
	.use('my', myService)
	.listen(8000);

You can see the combination when going to http://localhost:8000/my/test.

Pro tip:

Bind the apps lookup method to your service to always look your services up dynamically:

var myService = {
  setup: function(app) {
    this.lookup = app.lookup.bind(app);
  },

  get: function(name, params, callback) {
    this.lookup('todos').get('take out trash', {}, function(error, todo) {
      callback(null, {
        name: name,
        todo: todo
      });
    });
  }
}

Events

Any registered service will be automatically turned into an event emitter that emits events when a resource has changed, that is a create, update or remove service call returned successfully. It is therefore possible to bind to the below events via app.lookup(servicename).on() and, if enabled, all events will also broadcast to all connected SocketIO clients in the form of <servicepath> <eventname>. Note that the service path will always be stripped of leading and trailing slashes regardless of how it has been registered (e.g. /my/service/ will become my/service).

created

The created event will be published with the callback data when a service create calls back successfully.

app.use('/todos', {
  create: function(data, params, callback) {
    callback(null, data);
  }
});

app.lookup('/todos').on('created', function(todo) {
  console.log('Created todo', todo);
});

app.lookup('/todos').create({
  description: 'We have to do something!'
}, {}, function(error, callback) {
  // ...
});

app.listen(8000);

SocketIO

<script src="http://localhost:8000/socket.io/socket.io.js"></script>
<script>
  var socket = io.connect('http://localhost:8000/');

  socket.on('todos created', function(todo) {
    console.log('Got a new Todo!', todo);
  });
</script>

updated, patched

The updated and patched events will be published with the callback data when a service update or patch method calls back successfully.

app.use('/my/todos/', {
  update: function(id, data, params, callback) {
    callback(null, data);
  }
});

app.listen(8000);

SocketIO

<script src="http://localhost:8000/socket.io/socket.io.js"></script>
<script>
  var socket = io.connect('http://localhost:8000/');

  socket.on('my/todos updated', function(todo) {
    console.log('Got an updated Todo!', todo);
  });

  socket.emit('my/todos::update', 1, {
    description: 'Updated description'
  }, {}, function(error, callback) {
   // Do something here
  });
</script>

removed

The removed event will be published with the callback data when a service remove calls back successfully.

app.use('/todos', {
  remove: function(id, params, callback) {
    callback(null, { id: id });
  }
});

app.lookup('/todos').remove(1, {}, function(error, callback) {
  // ...
});

app.listen(8000);

SocketIO

<script src="http://localhost:8000/socket.io/socket.io.js"></script>
<script>
  var socket = io.connect('http://localhost:8000/');

  socket.on('todos removed', function(todo) {
    // Remove element showing the Todo from the page
    $('#todo-' + todo.id).remove();
  });
</script>

Event filtering

By default all service events will be dispatched to all connected clients. In many cases you probably want to be able to only dispatch events for certain clients. This can be done by implementing the created, updated, patched and removed methods as function(data, params, callback) {} with params being the parameters set when the client connected, in SocketIO when authorizing and setting handshake.feathers and Primus with req.feathers.

var myService = {
  created: function(data, params, callback) {},
  updated: function(data, params, callback) {},
  patched: function(data, params, callback) {},
  removed: function(data, params, callback) {}
}

The event dispatching service methods will be run for every connected client. Calling the callback with data (that you also may modify) will dispatch the according event. Callling back with a falsy value will prevent the event being dispatched to this client.

The following example only dispatches the Todo updated event if the authorized user belongs to the same company:

app.configure(feathers.socketio(function(io) {
  io.set('authorization', function (handshake, callback) {
    // Authorize using the /users service
    app.lookup('users').find({
      username: handshake.username,
      password: handshake.password
    }, function(error, user) {
      if(!error || !user) {
        return callback(error, false);
      }

      handshake.feathers = {
        user: user
      };

      callback(null, true);
    });
  });
}));

app.use('todos', {
  update: function(id, data, params, callback) {
    // Update
    callback(null, data);
  },

  updated: function(todo, params, callback) {
    // params === handshake.feathers
    if(todo.companyId === params.user.companyId) {
      // Dispatch the todo data to this client
      return callback(null, todo);
    }

    // Call back with a falsy value to prevent dispatching
    callback(null, false);
  }
});

On the client:

socket.on('todo updated', function(data) {
  // The client will only get this event
  // if authorized and in the same company
});

API

listen

app.listen([port]) starts the application on the given port. It will first call the original Express app.listen([port]), then run app.setup(server) (see below) with the server object and then return the server object.

setup

app.setup(server) is used initialize all services by calling each services .setup(app, path) method (if available). It will also use the server instance passed (e.g. through http.createServer) to set up SocketIO (if enabled) and any other provider that might require the server instance.

Normally app.setup will be called automatically when starting the application via app.listen([port]) but there are cases when you need to initialize the server separately:

HTTPS

With your Feathers application initialized it is easy to set up an HTTPS REST and SocketIO server:

app.configure(feathers.socketio()).use('/todos', todoService);

var https = require('https');
var server = https.createServer({
  key: fs.readFileSync('privatekey.pem'),
  cert: fs.readFileSync('certificate.pem')
}, app).listen(443);

// Call app.setup to initialize all services and SocketIO
app.setup(server);

Virtual Hosts

You can use feathers.vhost (which is the same as Express and Connect .vhost) to run your Feathers app on a virtual host:

app.use('/todos', todoService);

var host = feathers().use(feathers.vhost('foo.com', app));
var server = host.listen(8080);

// Here we need to call app.setup because .listen on our virtal hosted
// app is never called
app.setup(server);

lookup

app.lookup(path) returns the wrapped service object for the given path. Note that Feathers internally creates a new object from each registered service. This means that the object returned by lookup will provide the same methods and functionality as the original service but also functionality added by Feathers (most notably it is possible to listen to service events). path can be the service name with or without leading and trailing slashes.

app.use('/my/todos', {
  create: function(data, params, callback) {
    callback(null, data);
  }
});

var todoService = app.lookup('my/todos');
// todoService is an event emitter
todoService.on('created', function(todo) {
  console.log('Created todo', todo);
});

use

app.use([path], service) works just like Express app.use([path], middleware) but additionally allows to register a service object (an object which at least provides one of the service methods as outlined in the Services section) instead of the middleware function. Note that REST services are registered in the same order as any other middleware so the below example will allow the /todos service only to Passport authenticated users.

// Serve public folder for everybody
app.use(feathers.static(__dirname + '/public');
// Make sure that everything else only works with authentication
app.use(function(req,res,next){
  if(req.isAuthenticated()){
    next();
  } else {
    // 401 Not Authorized
    next(new Error(401));
  }
});
// Add a service.
app.use('/todos', {
  get: function(name, params, callback) {
    callback(null, {
      id: name,
      description: "You have to do " + name + "!"
    });
  }
});

service

app.service([path], service) is what is called internally by app.use([path], service) if a service object is being passed. Use it instead of app.use([path], service) if you want to be more explicit that you are registering a service. app.service does not provide the Express app.use functionality and doesn't check the service object for valid methods.

Why?

We know! Oh God another NodeJS framework! We really didn't want to add another name to the long list of NodeJS web frameworks but also wanted to explore a different approach than any other framework we have seen. We strongly believe that data is the core of the web and should be the focus of web applications.

We also think that your data resources can and should be encapsulated in such a way that they can be scalable, easily testable and self contained. The classic web MVC pattern used to work well but is becoming antiquated in today's web.

With that being said there are some amazing frameworks already out there and we wanted to leverage the ideas that have been put into them, which is why Feathers is built on top of Express and is inspired in part by Sails, Flatiron and Derby.

Changelog

0.4.0

• Allow socket provider event filtering and params passthrough (#49, #50, #51)
• Added patch support (#47)
• Allow to configure REST handler manually (#40, #52)

0.3.2

• Allows Feathers to use other Express apps (#46)
• Updated dependencies and switched to Lodash (#42)

0.3.1

• REST provider refactoring (#35) to make it easier to develop plugins
• HTTP requests now return 405 (Method not allowed) when trying to access unavailable service methods (#35)

0.3.0

• Added Primus provider (#34)
• app.setup(server) to support HTTPS (and other functionality that requires a custom server) (#33)
• Removed bad SocketIO configuration (#19)
• Add .npmignore to not publish .idea folder (#30)
• Remove middleware: connect.bodyParser() (#27)

0.2.0

• Pre-initialize req.feathers in REST provider to set service parameters
• Allowing to initialize services with or without slashes to be more express-compatible

0.1.0

• First beta release
• Directly extends Express
• Removed built in services and moved to Legs
• Created example repository

0.0.x

• Initial test alpha releases

License

Copyright (C) 2013 David Luecke [email protected] Copyright (C) 2013 Eric Kryski [email protected]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.