Modules: Stick 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/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/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 browsers are not able to send HTTP requests 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.

    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 to apply to every page
    • 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, and del 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 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")

  • 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.

.. show more