delegator Documentation

Transcription

1 delegator Documentation Release Daniel Knell August 25, 2014

2

3 Contents 1 Getting Started Installation Quickstart Tutorial Mapping File License Reference Delegator Errors Parsers i

4 ii

5 Delegator is a standalone library for request delegation in node.js inspired by pythons selector. It provides a component for RESTful dispatching of requests to callbacks based on the URI path and HTTP request method as well as a connect middleware for automatic dispatching. There is a very simple format for path matching expressions and there is also support for an external mapping file that can be used to express the mappings outside of your JavaScript code. Contents 1

6 2 Contents

7 CHAPTER 1 Getting Started 1.1 Installation There are multiple options for installing delegator in your node.js application, the package.json method is recommended package.json Add artisan-delegator to the dependencies section of your packages.json { "dependencies": { "artisan-delegator": "latest" and then install dependencies with $ npm install npm You can install artisan-delegator manually using npm $ npm install artisan-delegator 1.2 Quickstart Connect.js Delegator twins well with connectjs, by using the Mapping File you can create a minimal app.js such as the following. app.js: var delegator = require( artisan-delegator ), connect = require( connect ), app = connect() ; 3

8 app.use(connect.logger( dev )); app.use(connect.static( public )); app.use(delegator({ filename: dirname + /uri.map )); app.listen(3000); The view functions for the app can then be bound to in the mapping file, which will handle the importing and everything for you. uri.map: /hello/{name GET./lib/views:hello And lastly we need to implement our view function itself in the file specified in the mapping file. lib/views.js: exports.hello = function(req, res) { res.writehead(200, { Content-Type : text/plain ); res.end( Hello + req.params.name +! ); With this we have a fully functional app, which we can run via node. $ node app.js Vanilla Delegator can also be used stand alone, which may be more appropriate for small single file projects. var http = require( http ), delegator = require( artisan-delegator )() ; delegator.add( /hello/{name, { GET: function(req, res) { res.writehead(200, { Content-Type : text/plain ); res.end( Hello + req.params.name +! ); ); http.createserver(function(req, res) { delegator(req, res, function(err) { var status = err && err.status 404 ; res.writehead(status, { Content-Type : text/plain ); res.end( NOT FOUND ); ); ).listen(3000); 4 Chapter 1. Getting Started

9 1.3 Tutorial Introduction Delegator is a middleware for node.js that uses the request HTTP path and method to determine which callback to trigger. When a path is added the path expression is converted into a regular expression, when the delegator.delegator() instance receives a request it checks each regular expression against the request path until it finds a match and checks that a callback is defined for the requests HTTP method, if both of these are satisfied then the parameters from the regular expression match are added to the request objects params property and the request is forwarded. If no match can be found then the next method is called passing an error when a regular expression match was found, but a callback was not Path Expressions Path Expressions are strings provided to the parser to be compiled into regular expressions, by default an instance of delegator.parser.simpleparser() is used. Using the default parser you can extract parameters from the URI pathname via place holders in the path expression, these place holders take the form of {PARAMNAME:DATATYPE for named parameters and {:DATATYPE for positional. When not provided the datatype will fall back to the default and thus the shorthand {PARAMNAME and { can be also be used. A full list of datatypes provided by the default parser can be found in the delegator.parser.simpleparser() documentation. d.add( /collection/{:digits/{docname:chunk.{filetype:chunk, { GET: foo ); The path expression format also supports optional sections enclosed in [ and ] characters, these can be nested, and can also contain parameter placeholders. d.add( "/recent-articles[/{topic[/{subtopic]][/], { GET: recent_articles ); Custom Data Types / Parsers The parser is easily overridden, all that is required is an object with exposes a parse method. This method must take a single argument and return a new object containing an expr property containing the compiled regular expression and a keys property containing an array of key names to be extracted from the regular expression matches. The following example is a crude implementation of a parser to handle rails style expressions such as /foo/:bar/baz and extract the segments starting with a colon. var parser = { parse: function(expr) { var result = { keys: [] ; result.expr = new RegExp( ^ + expr.replace(/\/\:([^\/]+)/, function(m, key) { result.keys.push(key); return /(.*) ; ) + $ ); 1.3. Tutorial 5

10 return result; Custom pattern types can also be added to the default parser at instantiation. parser = delegator.parser.simpleparser({ patterns: { mytype : MYREGEX ); Adding Mappings There are three methods of adding mappings to the delegator. One by One Single path expressions can be added using the delegator.add() method. d.add( /foo, { GET : get_foo, POST : create_foo ); In Batch The delegator.batch() method will import multiple mappings at once. var mappings = [ ( /foo, { GET : foo ), ( /bar, { GET : bar ) ]; var d = new Delegator({ mappings: mappings ) d.batch(mappings) Mapping Files Mappings can be loaded from a Mapping File using the delegator.load() method. var filename = dirname + /uri.map ; var d = new Delegator({ filename: filename ); d.load(filename); Matching Matching against the path expressions in a delegator instance takes two forms, there is the generic delegator.match() method and the connect.js middleware delegator.middleware() method. var match = d.match(pathname, method); d.middleware(req, res, next); 6 Chapter 1. Getting Started

11 The delegator.match() method will return a delegator.match() object which will contain a callback method and the parameters extracted form the path. When using the connect.js middleware, the parameters will be added to the passed request object under the params key. 1.4 Mapping File Delegator can load mappings from an external file, allowing the configuration of mappings to be separated from your JavaScript code. uri.map: # homepage / GET./lib/views:index # widget api /widget/{id:word GET./lib/views:widget_read PUT./lib/views:widget_save DELETE./lib/views:widget_delete /widget GET./lib/views:widget_list POST./lib/views:widget_create The format is read line by line, ignoring any text after a # character, all blank lines are ignored, any lines without preceding white space are treated as path expressions, and any line with preceding white space is treated as a HTTP method to callback mapping. The mapping file can either be passed to the delegator.delegator() instance at instantiation via the filename option: var handler = new Delegator({ filename: dirname + /uri.map ); var middleware = delegator({ filename: dirname + /uri.map ); or used to add additional mappings to an existing instance via the delegator.load() method: handler.load( dirname + /uri.map ); All filenames should be expressed as full paths. 1.5 License The MIT License (MIT) Copyright 2012 Daniel Knell, 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 Mapping File 7

12 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 PAR- TICULAR 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 SOFT- WARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 8 Chapter 1. Getting Started

13 CHAPTER 2 Reference 2.1 Delegator A delegator object allows a request to be delegated to an alternative callback based on URI path and HTTP method Standard Options wrap A function to wrap around callbacks. prefix A prefix for path expressions. parser A parser for path expressions Delegator Class class delegator.delegator(options) The constructor supports additional options: filename A filename to pass to delegator.load(). mappings A mappings array to pass to delegator.batch(). parser A parser for path expressions. var delegator = new Delegator() ; delegator.add( /, { GET: function(req, res, next) { //... ); http.createserver(function (req, res) { var match ; try { match = delegator.match(req.url, req.method); req.params = match.params; 9

14 match.callback(req, res); catch (e) { console.log(e); ); options (object) A dictionary of options. delegator.parser The default path expression parser to use when adding routes. Value delegator.parser.simpleparser() delegator.prefix The default path expression prefix to use when adding routes. Default delegator.wrap The default wrapper for callback functions. Default null delegator.length The number of mappings in the delegator. delegator.add(path, callbacks[, options]) path (string) A path expression. callbacks (object) A dictionary of methods to callbacks. options (object) A dictionary of options. Throws delegator.errors.parsererror Return type delegator.mapping() delegator.match(path, method) Find a matching endpoint for a path and HTTP method. Throws path (string) A URI path method (string) A HTTP method. delegator.errors.notfounderror delegator.errors.methodnotallowederror Return type delegator.match() delegator.batch(mappings, options) Add multiple mappings to the delegator. mappings (array) An array of objects with path and method objects. 10 Chapter 2. Reference

15 options (object) A dictionary of options. Throws delegator.errors.parsererror delegator.load(filename, options) Load mappings from a Mapping File. filename (string) The path to a mappings file. options (object) A dictionary of options. Throws delegator.errors.parsererror delegator.middleware(req, res[, next]) A connect.js compatible middleware. req (object) A node.js http.request() like object. res (object) A node.js http.response() like object. next (function) A function to be called when a methods unavailible Mapping class delegator.mapping(expr, keys, callbacks) The constructor supports additional options: mapping.expr A regular expression. mapping.keys An array of key names for the regular expression groups. mapping.callbacks A dictionary of methods to callbacks. mapping.match(path) Test if a mapping matches a path and return the params. path (string) A path to match against. Returns A dictionary of parameters or null when non matching Matches class delegator.match(params, callback) The constructor supports additional options: match.params A dictionary of parameters. match.callback A callback function Delegator 11

16 2.1.5 Factory delegator(options) A factory method to instantiate a delegator.delegator(). and return delegator.middleware(). var delegator = require( artisan-delegator ) ; app.use(delegator({ filename: dirname + /url.map )); options (object) A dictionary of options. Returns A connect.js compatible middleware. 2.2 Errors This module implements the error classes thrown by other parts of the library Not Found class delegator.errors.notfounderror([message]) Bases: Error() Thrown when a match cannot be found for the current request. message (string) The error message text error.message The error message text Default Not Found error.code The http status code. Value 404 error.name The name of the error. Value NotFoundError Method Not Allowed class delegator.errors.methodnotallowederror([message]) Bases: Error() Thrown when a match can be found for the current request, but does not contain a callback for the http method. message (string) The error message text 12 Chapter 2. Reference

17 error.message The error message text Default Method Not Allowed error.code The http status code. Value 405 error.name The name of the error. Value MethodNotAllowedError Parser class delegator.errors.parsererror(message) Bases: Error() Thrown when a pattern can not be parsed by the current parser. message (string) The error message text error.message The error message text Default Parser Error error.name The name of the error. Value ParserError Mapping File class delegator.errors.parsererror(message) Bases: Error() Thrown when a mapping file can not be parsed. message (string) The error message text error.message The error message text Default Mapping File Error error.name The name of the error. Value MappingFileError 2.2. Errors 13

18 2.3 Parsers This module implements the parsers used to convert string path expressions into regular expressions used in the matching stage of request delegation Simple Parser class delegator.parser.simpleparser(patterns) Parser to turn path expressions into regular expressions with a list of group names. parser.parse( /hello/{name:chunk ) == { expr: /^\/hello\/([^\/.]+)/$, keys: [ name ] Additional patterns can be passed in as a dictionary to the constructor, by default the following are defined: word \w+ alpha [a-za-z]+ digits \d+ number \d*\.?\d+ chunk [^/\.]+ segment [^/]+ any.+ patterns (string) A dictionary of names and regular expression patterns matching parser.defaultpattern The pattern to use when non provided. Default chunk parser.patternstart The start character for pattern matching. Default { parser.patternend The start character for pattern matching. Default parser.optionalstart The start character for pattern matching. Default [ parser.optionalend The start character for pattern matching. Default ] parser.parse(pattern) Parse a string into a regular expression 14 Chapter 2. Reference

19 string (pattern) the pattern string to parse Throws delegator.errors.parsererror For invalid patterns. Returns A dictionary containing the regular expression and an array of keys If you can t find the information you re looking for, have a look at the index or try to find it using the search function: genindex search 2.3. Parsers 15