Fetchr augments Flux applications by allowing Flux stores to be used on server and client to fetch data.
On the server, stores can call the database directly to fetch some data.
On the client, however, stores can NOT call the database in the same way. Instead, xhr requests need to be made to the server( then to the database) and then the response can be parsed client side.
Fetchr provides an appropriate abstraction so that you can fetch (CRUD) your data in your stores using the same exact syntax on server and client side.
npm install fetchr
Fetchr needs delicate set up to work properly.
On the server side, add the fetchr middleware into your express app at a custom API endpoint.
Fetcher middleware expects that you're using the body-parser middleware (or an alternative middleware that populates req.body) before you use fetcher middleware.
//...
var express = require('express'),
Fetcher = require('fetchr'),
bodyParser = require('body-parser'),
app = express();
// you need to use body-parser middleware before fetcher middleware
app.use(bodyParser.json());
app.use('/myCustomAPIEndpoint', Fetcher.middleware());
//...xhrPath config option when instantiating the Fetchr class is optional. Defaults to /api.
On the clientside, the xhrPath will be used for XHR requests.
On the serverside, the xhrPath isn't needed and is ignored.
Note: Even though this config is optional, it is necessary for xhrPath on the clientside fetcher to match the path where the middleware was mounted on in the previous step.
//...
var Fetcher = require('fetchr'),
fetcher = new Fetcher({
xhrPath: '/myCustomAPIEndpoint'
})
//...You can pass the full origin host into corsPath and potentially overwrite constructGetUri. For example:
var qs = require('qs');
function constructGetUri (uri, resource, params, config) {
// this refers to the Fetcher object itself that this function
// is invoked with.
if (config.cors) {
return uri + '/' + resource + '?' + qs.stringify(this.context);
}
// Return `falsy` value will result in `fetcher` using its internal
// path construction instead.
}
var Fetcher = require('fetchr');
var fetcher = new Fetcher({
corsPath: 'http://www.google.com',
xhrPath: '/googleProxy'
});
fetcher.read('service', { foo: 1 }, {
cors: true,
constructGetUri: constructGetUri
}, callbackFn);//app.js
//...
var Fetcher = require('fetchr'),
myDataFetcher = require('./dataFetcher');
Fetcher.registerFetcher(myDataFetcher);
//...//dataFetcher.js
module.exports = {
//Name is required
name: 'data_api_fetcher',
//At least one of the CRUD methods is Required
read: function(req, resource, params, config, callback) {
//...
},
//other methods
//create: function(req, resource, params, body, config, callback) {},
//update: function(req, resource, params, body, config, callback) {},
//delete: function(req, resource, params, config, callback) {}
}Data fetchers might need access to each individual request, for example, to get the current logged in user's session. For this reason, Fetcher will have to be instantiated once per request.
On the serverside, this requires fetcher to be instantiated per request, in express middleware.
On the clientside, this only needs to happen on page load.
//app.js - server
//...
var express = require('express'),
Fetcher = require('fetchr'),
app = express(),
myDataFetcher = require('./dataFetcher');
Fetcher.registerFetcher(myDataFetcher);
app.use('/myCustomAPIEndpoint', Fetcher.middleware());
app.use(function(req, res, next) {
//instantiated fetcher with access to req object
var fetcher = new Fetcher({
xhrPath: '/myCustomAPIEndpoint', //xhrPath will be ignored on the serverside fetcher instantiation
req: req
});
fetcher.read('data_api_fetcher', {id: ###}, {}, function (err, data, meta) {
//handle err and/or data returned from data fetcher in this callback
})
});
//...//app.js - client
//...
var Fetcher = require('fetchr'),
fetcher = new Fetcher({
xhrPath: '/myCustomAPIEndpoint', //xhrPath is REQUIRED on the clientside fetcher instantiation
context: { // These context values are persisted with XHR calls as query params
_csrf: 'Ax89D94j'
}
});
fetcher.read('data_api_fetcher', {id: ###}, {}, function (err, data, meta) {
//handle err and/or data returned from data fetcher in this callback
})
//...See the simple example
You can protect your XHR paths from CSRF attacks by adding a middleware in front of the fetchr middleware:
app.use('/myCustomAPIEndpoint', csrf(), Fetcher.middleware());
You could use https://github.com/expressjs/csurf for this as an example.
Next you need to make sure that the CSRF token is being sent with our XHR requests so that they can be validated. To do this, pass the token in as a key in the options.context object on the client:
new Fetcher({
xhrPath: '/myCustomAPIEndpoint', //xhrPath is REQUIRED on the clientside fetcher instantiation
context: { // These context values are persisted with XHR calls as query params
_csrf: 'Ax89D94j'
}
})This _csrf will be sent in all XHR requests as a query parameter so that it can be validated on the server.
When calling a Fetcher service you can pass an optional config object.
When this call is made from the client the config object is used to define XHR request options and can be used to override default options:
//app.js - client
//...
var config = {
timeout: 6000, // Timeout (in ms) for each request
retry: {
interval: 100, // The start interval unit (in ms)
max_retries: 2 // Number of max retries
},
unsafeAllowRetry: false // for POST requests, whether to allow retrying this post
};
fetcher.read('data_api_fetcher', {id: ###}, config, function (err, data, meta) {
//handle err and/or data returned from data fetcher in this callback
});For requests from the server, the config object is simply passed into the service being called.
This software is free to use under the Yahoo! Inc. BSD license. See the LICENSE file for license text and copyright information.