dualapi
v1.3.1
Published
Framework for distributed javascript applications
Downloads
32
Maintainers
Readme
DualAPI
A lightweight and extensible framework for distributed isomorphic javascript applications. DualAPI extends dual-protocol, adding convenience functions and default behaviors for common messaging patterns.
For a simple example distributed example, see the dual-engine.io example.
Constructing domains
The dualapi
module is the constructor for dualapi
domains.
var d = require('dualapi')();
The most common use case for dualapi
domains is to provide
a listener function for processing dual-protocol
messages. Hosts
are attached to the domain by using the
dual-protocol mount
method:
d.mount(['unresponsive'], function (body, ctxt) {
// do some processing
});
Request and Return
Often, a dualapi
host will emit a response after processing
input. dualapi
provides a convienent extension to dual-protocol
by providing the ctxt.return
method.
d.mount(['simpledb', 'get'], function (body, ctxt) {
ctxt.return('the processed response');
});
By default, return
sets the returned options.statusCode
to 200
.
Then, any method having access to a connected domain may request data
from this address. The
request
method returns a spreadable promise which will be resolved when the
source host replies:
d.request(['simpledb', 'get'])
.spread(function (body, options) {
console.log(options.statusCode + ' ' + body);
});
// prints:
// "200 the processed response"
A smarter database can override the response statusCode
by providing
explicit options.
var db = {};
d.mount(['smarterdb', 'set', ':key'], function (body, ctxt) {
if (db.hasOwnProperty(ctxt.params.key)) {
ctxt.return('Conflict', { statusCode: 409 });
} else {
db[ctxt.params.key] = body;
ctxt.return('OK', { statusCode: 201 });
}
});
d.mount(['smarterdb', 'get', ':key'], function (body, ctxt) {
if (db.hasOwnProperty(ctxt.params.key)) {
ctxt.return(db[ctxt.params.key]);
} else {
ctxt.return('Not Found', { statusCode: 404 });
}
});
A client can use the enhanced status codes to modify its own response:
d.request(['smarterdb', 'get', 'bucket'])
.spread(function (body, options) {
if (options.statusCode == 200) {
console.log('' + options.statusCode + ' Request returned: ' + body);
} else {
console.log('' + options.statusCode + ' Failed to retrieve from bucket.');
}
});
d.request(['smarterdb', 'set', 'bucket'], 'an egg')
.spread(function (body, options) {
if (options.statusCode == 201) {
console.log('' + options.statusCode + ' Wrote to bucket');
} else {
console.log('' + options.statusCode + ' Failed to write to bucket.');
}
});
d.request(['smarterdb', 'get', 'bucket'])
.spread(function (body, options) {
if (options.statusCode == 200) {
console.log('' + options.statusCode + ' Second request got: ' + body);
} else {
console.log('' + options.statusCode + ' Second request failed to retrieve bucket.');
}
});
// Running this the first time would print:
// 404 Failed to retrieve from bucket
// 201 Wrote to bucket
// 200 Second request got: an egg
// Running a second time would print:
// 200 Request returned: an egg
// 409 Failed to write to bucket.
// 200 Second request got: an egg
On the other hand, if no host is listening at the requested address,
request will return with a status code of 503
. The request may also
provide a timeout option, in which case the status code will be 504
.
d.request(['nowhere'])
.spread(function (body, options) {
console.log('"nowhere" request returned status code ' + options.statusCode);
});
// would print
// "nowhere" request returned status code 503
d.request(['unresponsive'], null, { timeout: 1 })
.spread(function (body, options) {
console.log('"unresponsive" request returned status code ' + options.statusCode);
});
// would print (after 1 second delay)
// "unresponsive" request returned status code 504
Forward
To be written.
Proxy
To be written.
Error
To be written.