Modules: Stick 0.4 API

• stick

  The stick module provides the Application class which is the centerpiece of the Stick framework.

  A Stick Application is a JSGI application which provides means to compose complex applications out of modular middleware components.

• stick/helpers

  A collection of helper functions that makes working with Stick middleware easier.

• stick/middleware

  Convenience module that provides access to all Stick middleware using a single require() call.

• stick/middleware/accept

  This module provides middleware to check if a HTTP request accepts the possible response and makes content negotiation more convenient.

• stick/middleware/basicauth

  Basic Authentication middleware.

  To apply authentication to parts of your website configure this middleware and call the app's basicauth method with the URI path, user name, and SHA1 digest of the user's password as arguments for each path you want to protect:

• stick/middleware/continuation

  Provide support for JavaScript 1.7 generator actions.

  This middleware supports two types of yield values from generators: Promises and JSGI response objects.

  If a generator action yields a promise, this middleware adds a listener to that promise that will feed the value back to the generator once the promise is resolved. If the promise resolves to an error, the error is thrown in the generator.

  For example, if promise is a promise, the yield statement will interrupt execution of the action until the promise is resolved, at which point the generator is resumed with the value of the promise being assigned to the resolved variable.

  var resolved = yield promise;

  If a generator action yields a JSGI response, the response is sent to the client. To be able to yield more than one response from the same generator, the generator has to be associated with a continuation id and stored in the user's session. This is done by calling continuation.activate() before yielding the first response. The activate() method tells the middleware to store the generator in the user's session and returns a contination id.

  For subsequent invocations of the generator, the continuation id has to be set as query string parameter with name _c. When suspended generator is resumed, the new request object is passed in as value for the last yield statement.

  function continuation(request) {
      var c = app.continuation.activate();
      while(true) {
          request = yield response.html(linkTo(app, {_c: c}));
      }
  }

  See http://blog.ometer.com/2010/11/28/a-sequential-actor-like-api-for-server-side-javascript/ for background.

• stick/middleware/cookies

  This module provides middleware for reading cookies from the request.

• stick/middleware/cors

  Cross-site HTTP Request headers

  Ability to configure all CORS headers. For a detailed explanation on what the different headers do see MDN on CORS

  Even if allowOrigin is defined as "*" (allowOrigin: ['*']) this middleware will always respond with an "Access-Control-Allow-Origin" header with the value of the "Origin" header.

• stick/middleware/csrf

  A middleware for CSRF mitigation, using either the synchronizer token or the double submission cookie pattern (see OWASP CSRF Prevention Cheat Sheet for a detailed explanation).

  This middleware extends the request object by adding two methods:

  • getCsrfToken() returns the CSRF token value for the current request, creating and storing it in the current session if necessary
  • rotateCsrfToken() creates a new CSRF token and stores it in the current session

  Use getCsrfToken() of the request object to add the token value as hidden input to all forms generated by the application, and make sure the name of the form input is configured accordingly (defaults to "csrftoken").

  The token value returned by getCsrfToken() is additionally stored either in the current session (default) or in a cookie. The POST parameter and the token value stored are compared, and in case of a mismatch this middleware returns a 403 "Forbidden" response.

  For non-POST requests this middleware accepts the token sent as query parameter or custom header field.

  Configuration options:

  app.csrf() accepts an object as parameter containing the following properties (default values in brackets):

  • tokenLength: The length of the CSRF token (32)
  • checkReferrer: Enable strict referrer checking for HTTPS requests (true)
  • rotate: If true tokens are only used once and modified after each validation (false)
  • getToken: By default the middleware expects the submitted CSRF token in either a post or query parameter csrftoken or in a custom request header x-csrf-token (in this order). To customize this define a function that will receive the request object as single argument and is expected to return the CSRF token (or null).
  • getFailureResponse: An optional function receiving the request as single argument. This method is called if the CSRF validation failed, and is expected to return a valid JSGI response (default: 403 forbidden).
  • safeMethods: An array containing request method names that are considered safe, so no token validation is done (["GET", "HEAD", "OPTIONS", "TRACE"])

  Cookie mode

  The following options switch the middleware into "double submission cookie" mode, and allow detailed configuration of the cookie:

  • useCookie: If true the CSRF token is stored in a cookie
  • cookieName: The name of the cookie to set ("csrftoken")
  • cookieHttpOnly: If true the httpOnly flag of the cookie is set (true)
  • cookieSecure: If true the secure flag of the cookie is set (false)

• stick/middleware/error

  Middleware to catch errors and generate simple error pages.

  By default, resource stick/middleware/error.html is used as page template. This can be set through the app.error.template property. This is the complete list of properties that influence the behaviour of this middleware:

  • template the error page template (string)
  • message static error message to use instead of actual message (string)
  • location whether to report any information about the code location of the error (boolean)
  • stack whether to include a JavaScript stack trace (boolean)
  • javaStack whether to include a Java stack trace (boolean)

• stick/middleware/etag

  Middleware for conditional HTTP GET request based on response body message digests.

  The response body must implement a digest() method for this middleware to work.

• stick/middleware/gzip

  Middleware for on-the-fly GZip compression of response bodies.

  By default only text content types are compressed. This can be controlled using the gzip.contentTypes property:

• stick/middleware/method

  JSGI middleware for HTTP method override.

  Since older browsers are not able to send XMLHttpRequest with methods other than GET and POST, this middleware allows the method of POST requests to be overridden based on the value of a HTTP form parameter. The default name for the override parameter is _method. This can be configured through the method.key property.

• stick/middleware/mount

  This module provides middleware for mounting other applications on a specific URI path or virtual host.

  Applying this middleware adds a mount method to the application. The mount method takes a path or virtual host specification and an application as arguments. If the spec is a string, it is interpreted as the URI path on which the app will be mounted. If it is an object, it may contain path or host properties that will be matched against the URI path and Host header of incoming requests. Note that virtual host based mounting has not been tested so far.

  The mount method accepts an optional third boolean noRedirect argument. If set to true it will disable redirecting GET requests to the mount base URL without a trailing slash to the same URL with trailing slash. By default, mount middleware will send a redirect to the mount URL with trailing slash.

  Mounting one application within another causes the scriptName and pathInfo properties in the request object to be adjusted so that the mounted application receives the same pathInfo as if it was the main application. This means that forward and reverse request routing will usually work as expected.

  This middleware maintains an index mapping applications to mount points which can be accessed using the lookup function. The [stick/helpers][helpers] module provides higher level functions for this which include support for the route middleware.

• stick/middleware/notfound

  Middleware for simple Not-Found pages.

  By default, resource stick/middleware/notfound.html is used as page template. This can be set through the app.notfound.template property.

  • template the notfound page template (string)

• stick/middleware/params

  This module provides middleware for parsing HTTP parameters from the query string and request body.

  It does not parse multipart MIME data such as file uploads which are handled by the [upload][middleware/upload] module.

• stick/middleware/profiler

  This module provides profiling middleware to measure the application's runtime behaviour.

  Profiler data is written to the module's logger. You have to run the application in interpreted mode (passing -o -1 on the command line) to get meaningful results.

• stick/middleware/render

  This module provides middleware for rendering responses using ringo/mustache.

  This middleware installs a render function in the application object which is used to render HTTP responses. The behaviour of app.render can be tweaked by setting the following properties:

  • render.base - the base path or repository to look for templates
  • render.helpers - helper functions that will be merged in the context
  • render.master - master template which is applied on the top of processing the page with template given in the .render function.
  • render.contentType - MIME type to use for HTTP response
  • render.charset - charset name to use for HTTP response

• stick/middleware/requestlog

  Middleware for collecting log messages issued during execution of the current request.

  This adds a requestlog property to the application object with an items property. During execution of a request items contains an array containing all the log messages issued for the request. Log messages are represented as arrays in the format [time, level, name, message].

  During request execution, the requestlog property also defines a property called start containing the time the execution started.

  By default, messages are appended to the response if its Content-Type is text/html. This can be controlled using the app.requestlog.append boolean flag.

• stick/middleware/route

  Middleware for HTTP method based local request routing.

  This installs get, post, put, del and options methods in the application object for routing requests with the corresponding HTTP methods. These methods take a path spec as first argument and a function as second argument.

  Paths and Placeholders

  The path spec can consist of static parts and placeholders. Named placeholders are prefixed by : (colon) and match all characters except for / (slash) and . (dot). A named placeholder can be marked as optional by appending ? (question mark). Unnamed placeholders are denoted by the asterisk character * and match all characters including slashes and dots.

  In the following example, ":id" is a named placeholder:

  "/post/:id"

  All placeholders are passed to the action function as positional arguments following the request object in the order in which they appear in the path spec. Unmatched optional placeholders will be undefined.

  app.get("/post/:id", function(req, id) {...});

  Reverse Routing

  The route middleware supports generating URLs from route names and parameters required by the route.

  Routes names can either be defined explicitly by passing the route name as third argument, or are derived from the route's path spec by stripping out all placeholders and removing a leading slash. For example, a path spec /post/:id.html results in route name "post.html". If a path spec does not contain any static part, its route name is "index".

  Passing a valid route name and the parameters required by the route to the route.reverse method will return the URI path for the corresponding action. For example, with a route spec /post/:id.html, calling app.route.reverse({action: "post.html", id: 5}) will return the string "/post/5.html".

  The [stick/helpers][helpers] module provides higher level helpers for reverse routing including support for mounted applications.

• stick/middleware/session

  This module provides middleware for HTTP sessions.

  It adds a session property to the request object that allows to store arbitrary data on on a per-visitor basis.

  The default session implementation is based on Java Servlet sessions. This can be overridden by setting the app.session.impl property to an alternative session constructor.

  app.session.impl = MySession;

  The session constructor will be called with the request object as only argument when the session is first accessed.

• stick/middleware/static

  Middleware for serving static resources.

  This installs a static() method in the application that accepts the following arguments:

  • base: the base resource directory (required)

  • index: the name of a file to serve if the path matches a directory (e.g. "index.html")

  • baseURI: a common prefix for a resource URI (e.g. "/static")

  You can call static() multiple times to register multiple resources to be served.

• stick/middleware/upload

  This module provides support for parsing multipart MIME messages used for file uploads.

  This module behaves analogous and can be used in combination with the [params][middleware/params] middleware.