Background #

Deployd modules are 100% compatible with regular node modules. This means you can use any of the 17,000+ node modules when building your Deployd app.

Hello World #

Any module in your app's node_modules folder will be loaded when the Deployd server starts.

You don't have to require() or load anything to instantiate your module. The following will log 'hello world' when you run dpd.

// /my-app/node_modules/hello.js
console.log('hello world');

Accessing the Server #

In order to do anything interesting you need a reference to the current Deployd server object. The server is always available at process.server. This means you don't need to require anything to use most of the internal APIs.

One Off Modules #

The simplest kind of module is a one-off module. These are easy to create but hard to reuse. Typically any behavior that is specific to just your app that can't be implemented using an existing module can be built with a simple one-off module.

Here's an example one off module that maintains a count of requests to the url /hits and writes it to a file every minute.

// /my-app/node_modules/hits.js
var fs = require('fs');
process.server.hits = 0;

process.server.on('request', function(req) {
  if(req.url === '/hits') {
    process.server.hits++;
  }
});

// write a file every minute
setInterval(function() {
  fs.writeFile('hits.json', JSON.stringify({hits: process.server.hits}));
}, 60000);

Reusable Modules #

Modules can also expose useful APIs of their own. The simplest way to create reusable modules is to define a Resource Type. Resource Types are exposed in the dashboard and are much easier to reuse, and you can share them with other Deployd developers. See the custom resource type guide for more info.

Debugging #

Deployd uses debug to log requests and show other internal debug info. To activate it you need to set the DEBUG env variable to *, for example:

process.env['DEBUG'] = '*';

Example Resource Type #

The most basic Custom Resource Type that is useful is the Event Resource, which will simply execute an On GET event when it receives a GET request and an On POST event when it receives a POST request.

This is the source for that module:

var Resource = require('deployd/lib/resource')
    , util = require('util');

function EventResource() {
    Resource.apply(this, arguments);
}
util.inherits(EventResource, Resource);

EventResource.label = "Event";
EventResource.events = ["get", "post"];

module.exports = EventResource;

EventResource.prototype.clientGeneration = true;

EventResource.prototype.handle = function (ctx, next) {
    var parts = ctx.url.split('/').filter(function(p) { return p; });

    var result = {};

    var domain = {
            url: ctx.url
        , parts: parts
        , query: ctx.query
        , body: ctx.body
        , 'this': result
        , setResult: function(val) {
            result = val;
        }
    };

    if (ctx.method === "POST" && this.events.post) {
        this.events.post.run(ctx, domain, function(err) {
            ctx.done(err, result);
        });
    } else if (ctx.method === "GET" && this.events.get) {
        this.events.get.run(ctx, domain, function(err) {
            ctx.done(err, domain.result);
        });
    } else {
        next();
    }
};

Let's look at it line-by-line:

var Resource = require('deployd/lib/resource')
    , util = require('util');

To create a Resource, you'll need the Resource module and Node's util module.

function EventResource() {
    Resource.apply(this, arguments);
}

Creates the constructor for the EventResource, also applying the base Resource constructor.

util.inherits(EventResource, Resource);

Causes EventResource to inherit its prototype from Resource using Node's util.inherits() function.

EventResource.label = "Event";

Changes the Resource.label property to set how the EventResource appears in the "Add Resource" menu in the Dashboard. Without this setting, it would appear using the constructor name, EventResource.

EventResource.events = ["get", "post"];

Configures two events for the Resource type: get and post. These will appear on the "Events" page in the Dashboard with no extra configuration.

Note: The Dashboard provides the "On" prefix, e.g. "On Get"

module.exports = EventResource;

Exports the EventResource constructor. This is how Deployd finds and loads the resource type.

EventResource.prototype.clientGeneration = true;

Sets the clientGeneration flag, which ensures that resources created with this resource type will be generated into dpd.js.

EventResource.prototype.handle = function (ctx, next) {

Defines a handle() function. This function will be called whenever a request is routed to this resource. The ctx object is a Context, which includes useful properties (body, query, etc.) and functions (particularly done()) to simplify working with HTTP.

The next function gives control back to the router.

var parts = ctx.url.split('/').filter(function(p) { return p; });

var result = {};

Set up some local variables; parts is an array of the /-separated parts in the URL.

var domain = {
        url: ctx.url
    , parts: parts
    , query: ctx.query
    , body: ctx.body
    , 'this': result
    , setResult: function(val) {
        result = val;
    }
};

Create a domain for the events. These are objects and functions that will be accessible from the event. Notice that the setResult function is a closure that assigns its argument to the local result variable.

if (ctx.method === "POST" && this.events.post) {
    this.events.post.run(ctx, domain, function(err) {
        ctx.done(err, result);
    });
}

Run the POST event using the Script.run() function if applicable, passing it the current context and domain.

The this.events object contains all of the available events; if the user has not written a POST event, though, this.events.post might be null.

The callback for Script.run returns an error err if something went wrong in the script (or if the script writer called cancel())

Finally, call ctx.done() with both the error and result (result is the local variable we set up earlier which the scriptwriter can change using setResult(). The response body is always the second parameter, but it is ignored if an error is passed.

} else if (ctx.method === "GET" && this.events.get) {
    this.events.get.run(ctx, domain, function(err) {
        ctx.done(err, domain.result);
    });
}

Do the same thing for the GET event.

} else {
    next();
}

If no event applies, call next(). This tells the router that this resource cannot handle the current request, and the router will allow other resources to handle it. If every resource calls next(), then Deployd will return a 404 status code.

Useful files #

• index.js

Useful files #

• index.js

Useful files #

• index.js

Class: Collection #

A Collection inherits from Resource. Any constructor that inherits from Collection must include its own Collection.external prototype object.

Example inheriting from Collection:

var Collection = require('deployd/lib/resources/collection');
var util = require('util');

function MyCollection(name, options) {
  Collection.apply(this, arguments);
}
MyCollection.external = Collection.external;

util.inherits(MyCollection, Collection);

Mock Contexts #

Contexts may be created without a real request and response such as during an internal request using the dpd object. See Internal Client for more info.

Class: Context #

var Context = require('deployd/lib/context');
var ctx = new Context(resource, req, res, server);

fs.readFile('bar.txt', ctx.done);

Async Mode #

Scripts can be run in an async mode. This mode is triggered when a Script is run(ctx, domain, fn) with a callback (fn). When run in this mode a Script will try scrub all functions in the domain for operations that require a callback. If a callback is required, the function is re-written to count the callbacks completion and notify the script. When all pending callbacks are complete the script is considered finished.

Async Errors #

If a script is run with a callback (in async mode), any error will emit an internal error event. This will stop the execution of the script and pass the error to the script's callback.

Class: Script #

var Script = require('deployd/lib/script');
var script = new Script('hello()', 'hello.js');

A Script's source is compiled when its constructor is called. It can be run() many times with independent Contexts and domains.

Default Domain #

Scripts are executed with a default sandbox and set of domain functions. These are functions that every Script usually needs, and are available to every Script. These can be overridden by passing a value such as {cancel: ...} in a domain. See Event API for Custom Resources for documentation on this default domain.

internalClient.build(server, [session], [stack]) #

var internalClient = require('deployd/lib/internal-client');

process.server.on('listening', function() {
  var dpd = internalClient.build(process.server);
  dpd.todos.get(function(data, err) {
    // Do something
  });  
});

• server {Server}

The Deployd server to build a client for.

• session {Session} (optional)

The Session object on the current request.

• stack {Array} (optional)

Used internally to prevent recursive calls to resources.

Mock context #

In order to make requests on resources within the Deployd server, internal-client creates mock req and res objects. These objects are not Streams and cannot be treated exactly like the standard http.ServerRequest and http.ServerResponse objects in Node, but they imitate their interfaces with the following properties:

Events / Scripts #

A Resource can execute Scripts during the handling of an http request when certain events occur. This allows users of the resource to inject logic during specific events during an http request without having to extend the resource or create their own.

For example, the Collection resource executes the get.js event script when it retrieves each object from its store. If a get.js file exists in the instance folder of a resource (eg. /my-project/resources/my-collection/get.js), it will be pulled in by the resource and exposed as myResource.scripts.get.

Overriding Behavior #

Certain methods on a Resource prototype are called by the runtime. Their default behavior should be overridden to define an inherited Resources behavior.

Class: Server #

Servers are created when calling the Deployd exported function.

var deployd = require('deployd')
  , options = {port: 3000}
  , server = deployd(options);

• options {Object}

  • port {Number} - the port to listen on
  • db {Object} - the database to connect to
  • db.connectionString {String} - The URI of the mongoDB using standard Connection String. If db.connectionString is set, the other db options are ignored.
  • port {Number} - the port of the database server
  • host {String} - the ip or domain of the database server
  • name {String} - the name of the database
  • credentials {Object} - credentials for the server
    • username {String}
    • password {String}
  • env {String} - the environment to run in.

Note: If options.env is "development", the dashboard will not require authentication and configuration will not be cached. Make sure to change this to "production" or something similar when deploying.

deployd.attach #

deployd.attach can attach Server Class functions into a regular http server. It also provide handleRequest function to act as express middleware.

var deployd = require('deployd')
  , options = {}
  , server = require('http').createServer(app)
  , server = deployd.attach(server, options);

• options {Object}

  • socketIo {Object} - socket.io instance
  • db {Object} - the database to connect to
  • port {Number} - the port of the database server
  • host {String} - the ip or domain of the database server
  • name {String} - the name of the database
  • credentials {Object} - credentials for the server
    • username {String}
    • password {String}
  • env {String} - the environment to run in.

Note: If options.env is "development", the dashboard will not require authentication and configuration will not be cached. Make sure to change this to "production" or something similar when deploying.

Class: Session #

A store for persisting sessions in-between connection and disconnection. Automatically creates session IDs on inserted objects.

var session = new Session({id: 'my-sid', new SessionStore('sessions', db)});
session.set({uid: 'my-uid'}).save();

• data {Object}

The data used to construct the session.

• store {SessionStore}

The store used to persist the session.

• sockets {Socket.IO.sockets}

The Socket.IO sockets object used to attach an existing socket.

Class: SessionStore #

A store for persisting sessions in-between connection and disconnection. Automatically creates session IDs on inserted objects.

var db = process.server.db;
var sockets = process.server.sockets;
var name = 'sessions';
var store = new SessionStore(name, db, sockets);

• name {String}

The name of the db store.

• db {Db}

The server db instance

• sockets {Socket.IO.sockets}

The socket.io sockets object.

Class: Store #

You shouldn't construct Stores directly. Instead use the process.server.createStore() method.