API Docs for: 0.8.0
Show:

RequestHandler Class

Responsible for processing a single req by delegating it to the correct controllers

Constructor

RequestHandler

(
  • server
  • req
  • resp
)

Parameters:

  • server Server

    The http server that the request came in on

  • req Request

    The incoming request

  • resp Response

    The outgoing response

Methods

_registerRoute

(
  • descriptor
  • theme
  • site
  • Controller
)
Boolean private static

Parameters:

  • descriptor Object
  • theme String
  • site String
  • Controller Function

Returns:

Boolean:

activateSite

(
  • site
)
static

Parameters:

  • site Object

buildControllerContext

(
  • req
  • res
  • extraData
)
Object static

Builds out the context that is passed to a controller

Parameters:

  • req Request
  • res Response
  • extraData Object

Returns:

Object:

checkAdminLevel

(
  • context
)
Success: boolean static

Parameters:

  • context Object
    • themeRoute Object
      • access_level Number
    • session Object
      • authentication Object
      • authentication.admin_level Number

Returns:

Success: boolean:

}

checkPermissions

(
  • context
)
Success: boolean static

Parameters:

  • context Object
    • themeRoute Object
      • permissions Array
    • session Object
      • authentication Object
      • authentication.user Object
      • authentication.user.permissions Object

Returns:

Success: boolean:

}

checkRequiresAuth

(
  • context
)
Success: boolean static

Parameters:

  • context Object
    • themeRoute Object
    • themeRotue.auth_required Boolean
    • session Object
      • authentication Object
      • authentication.user_id Number
    • req Request
    • hostname String
    • url Object
      • href String

Returns:

Success: boolean:

}

checkSecurity

(
  • activeTheme
  • method
  • site
  • cb
)

Verifies that the incoming request meets all necessary security critiera

Parameters:

  • activeTheme String
  • method String
  • site String
  • cb Function

deactivateSite

(
  • site
)
static

Parameters:

  • site Object

deriveLocalization

(
  • context
)

Derives the locale and localization instance.

Parameters:

  • context Object
    • [session] Object optional
    • [routeLocalization] String optional

doRedirect

(
  • location
  • [statusCode=302]
)

Parameters:

  • location String
  • [statusCode=302] Integer optional

doRender

(
  • context
)

Begins the rendering process by initializing the controller. This is done by gathering all initialization parameters and calling the controller's "init" function.

Parameters:

  • context Object
    • pathVars Object

      The URL path's variables

    • cInstance BaseController

      An instance of the controller to be executed

    • themeRoute Object
    • activeTheme String

      The user set active theme

emitThemeRouteRetrieved

(
  • cb
)

Emits the event to let listeners know that a request has derived the route and theme that matches the incoming request

Parameters:

  • cb Function

generateRedirect

(
  • location
)
Object static

Generates the controller callback object that will trigger the redirect header to be sent back as part of the response.

Parameters:

  • location String

    The fully qualified or relative URL to be redirected to

Returns:

Object:

The object for the controller to call back with.

getBodyParsers

() Object static

Retrieves the body parser mapping

Returns:

Object:

MIME string as the key and parser as the value

getMimeFromPath

(
  • resourcePath
)
String | Undefined deprecated static

Defined in include/http/request_handler.js:688

Deprecated: since 0.8.0 Use mime.lookup instead

Attempts to derive the MIME type for a resource path based on the extension of the path.

Parameters:

  • resourcePath String

    The file path to a resource

Returns:

String | Undefined:

The MIME type or NULL if could not be derived.

getPathVariables

(
  • route
)

Parameters:

  • route Object
    • path_vars Object

getRoute

(
  • path
)
Object

Compares the path against the registered routes's to lookup the route object.

Parameters:

  • path String

    The URL path for the incoming request

Returns:

Object:

The route object or NULL if the path does not match any route

getRoutePattern

(
  • path
)
Object | Null static

Generates a regular expression based on the specified path. In addition the algorithm extracts any path variables that are included in the path. Paths can include two types of wild cards. The traditional glob pattern style of "/some/api/*" can be used as well as path variables ("/some/api/:action"). The path variables will be passed to the controllers.

Parameters:

  • path String

    The URL path

Returns:

Object | Null:

An object containing three properties: The specified "path". The generated regular expression "pattern" as a string. Lastly, a hash of the path variables and their position in the path coorelating to its depth in the path.

getRouteTheme

(
  • activeTheme
  • route
)
Object

Determines the theme that will be executed for the route. The themes will be prioritized as: active theme, pencilblue, followed by iterating over all other inherited themes.

Parameters:

  • activeTheme String
  • route Object

Returns:

Object:

An object with two properties: theme and method

handleRequest

()

Processes a request:

  1. Initialize localization
  2. if Public Route:
    1. If Valid Content
      1. Serve Public Content
    2. Else Serve 404
  3. Else Parse Cookies
  4. Open/Create a session
  5. Get Route

init

() static

Initializes the request handler prototype by registering the core routes for the system. This should only be called once at startup.

isAdminURL

(
  • urlPath
)
Boolean static

Determines if the provided URL pathname "/admin/content/articles" is a valid admin URL.

Parameters:

  • urlPath String

Returns:

Boolean:

isPublicRoute

(
  • path
)
Boolean static

Determines if the path is mapped to static resources

Parameters:

  • path String

    URL path to a resource

Returns:

Boolean:

TRUE if mapped to a public resource directory, FALSE if not

isSystemSafeURL

(
  • url
  • id
  • [site]
  • cb
)
static

Parameters:

  • url String
  • id String
  • [site] String optional
  • cb Function

isValidRoute

(
  • descriptor
)
static

Validates a route descriptor. The specified object must have a "controller" property that points to a valid file and the "path" property must specify a valid URL path structure.

Parameters:

  • descriptor Object

    The object to validate

    • controller String

      The file path to the controller file

    • path String

      The URL path

loadSite

(
  • site
)
static

Parameters:

  • site Object

onControllerInitialized

(
  • controller
  • themeRoute
)

Parameters:

onErrorOccurred

(
  • err
)

Parameters:

  • err Error

onRenderComplete

(
  • data
  • [data.code
)

Parameters:

  • data Error | Object
    • [redirect] String optional
  • [data.code Integer

onSecurityChecksPassed

(
  • activeTheme
  • routeTheme
  • method
  • site
  • route
)

Parameters:

  • activeTheme String

    The user set active theme

  • routeTheme String

    The plugin/theme who's controller will handle the request

  • method String
  • site String
  • route Object

onSessionRetrieved

(
  • err
  • session
)

Called when the session has been retrieved. Responsible for checking the active theme. It then retrieves the route object and passes it off to onThemeRetrieved.

Parameters:

  • err Error

    Any error that occurred while retrieving the session

  • session Object

    The session for the requesting entity

onThemeRetrieved

(
  • activeTheme
  • route
)

Parameters:

  • activeTheme String
  • route Object

parseBody

(
  • mimes
  • cb
)

Parses the incoming request body when the body type specified matches one of those explicitly allowed by the rotue.

Parameters:

  • mimes Array

    An array of allowed MIME strings.

  • cb Function

    A callback that takes 2 parameters: An Error, if occurred and the parsed body. The parsed value is often an object but the value is dependent on the parser selected by the content type.

parseCookies

(
  • req
)
Object static

Parses cookies passed for a request

Parameters:

  • req Request

Returns:

Object:

registerBodyParser

(
  • mime
  • prototype
)
Boolean static

Registers a body parser prototype for the specified mime

Parameters:

  • mime String

    A non empty string representing the mime type that the prototype can parse

  • prototype Function

    A prototype that can have an instance created and parse the specified mime type

Returns:

Boolean:

TRUE if the body parser was registered, FALSE if not

registerRoute

(
  • descriptor
  • theme
  • site
)
Boolean static

Registers a route

Parameters:

  • descriptor Object

    The route descriptor

    • [method='ALL'] String optional

      The HTTP method associated with the route

    • path String

      The URL path for the route. The route supports wild cards a well as path variables (/get/:id)

    • controller String

      The file path to the controller to execute when the path is matched to an incoming request.

    • [access_level=0] Integer optional

      Use global constants: ACCESS_USER,ACCESS_WRITER,ACCESS_EDITOR,ACCESS_MANAGING_EDITOR,ACCESS_ADMINISTRATOR

    • [setup_required=true] Boolean optional

      If true the system must have gone through the setup process in order to pass validation

    • [auth_required=false] Boolean optional

      If true, the user making the request must have successfully authenticated against the system.

    • [content_type='text/html'] String optional

      The content type header sent with the response

    • [localization=false] Boolean optional
  • theme String

    The plugin/theme UID

  • site String

    The UID of site that owns the route

Returns:

Boolean:

TRUE if the route was registered, FALSE if not

routeSupportsGlobalTheme

(
  • route
  • theme
  • method
)
static

Parameters:

  • route Object
  • theme String
  • method String

routeSupportsMethod

(
  • themeRoutes
  • method
)
static

Determines if the route supports the given HTTP method

Parameters:

  • themeRoutes Object

    The route object that contains the specifics for the theme variation of the route.

  • method String

    HTTP method

routeSupportsTheme

(
  • route
  • theme
  • method
  • site
)
Boolean static

Determines if a route supports a particular theme and HTTP method

Parameters:

  • route Object
  • theme String

    The theme

  • method String

    HTTP method

  • site String

    current site

Returns:

Boolean:

serve404

()

Serves up a 404 page when the path specified by the incoming request does not exist. This function WILL close the connection.

serveError

(
  • err
)
Boolean

Serves up an error page. The page is responsible for displaying an error page

Parameters:

  • err Error

    The failure that was generated by the executed controller

Returns:

Boolean:

TRUE when the error is rendered, FALSE if the request had already been handled

servePublicContent

(
  • [absolutePath]
)

Serves up public content from an absolute file path

Parameters:

  • [absolutePath] String optional

    An absolute file path to the resource

unregisterRoute

(
  • The
  • The
)
Boolean static

Removes a route based on a URL path and theme UID

Parameters:

  • The String

    URL path

  • The String

    theme that owns the route

Returns:

Boolean:

TRUE if the route was found and removed, FALSE if not

unregisterThemeRoutes

(
  • theme
)
Integer static

Unregisters all routes associated with a theme

Parameters:

  • theme String

    The plugin/theme uid

Returns:

Integer:

The number of routes removed

urlExists

(
  • url
  • id
  • [site]
  • cb
)
static

Checks to see if the URL exists in the current context of the system

Parameters:

  • url String
  • id String
  • [site] String optional
  • cb Function

    (Error, boolean)

writeCookie

(
  • descriptor
  • [cookieStr='']
)
String

Creates a cookie string

Parameters:

  • descriptor Object

    The pieces of the cookie that are to be included in the string. These pieces are represented as key value pairs. Each value will be serialized via its implicity "toString" function.

  • [cookieStr=''] String optional

    The current cookie string if it exists

Returns:

String:

The cookie represented as a string

writeResponse

(
  • data
)

Parameters:

  • data Object

Properties

activeTheme

String

BODY_PARSER_MAP

Object private static

A mapping that provides the interface type to parse the body based on the route specification

CORE_ROUTES

Array private static

The list of routes provided by the pencilblue plugin. These routes are loaded first to ensure defaults are in place before other plugins are initialized. In the future this will change so that all plugins are treated equally.

DEFAULT_THEME

String static

The fallback theme (pencilblue)

errorCount

Number

hostname

String

The hostname (host header) of the current request. When no host header is provided the globa context is assumed. We do this because some load balancers including HAProxy use the root as the heartbeat. If we error then the web server will be taken out of the server pool resulting in a 503 from the load balancer

PUBLIC_ROUTE_PREFIXES

Array private static

Provides the list of directories that are publicly available

req

Request

resp

Response

routeTheme

Object

server

Server

startTime

Number

staticRoutes

Object protected static

The internal storage of static routes after they are validated and processed.

storage

Array protected static

The internal storage of routes after they are validated and processed.

THEME_ROUTE_RETRIEVED

String static

The event emitted when a route and theme is derived for an incoming request