api

(static) app :Router

Description:

• Default router

Source:

• lib/api.js, line 87

(static) args :Array.<ConfigOptions>

Source:

• lib/api.js, line 41

Default Value:

• [
    {
      "name": "version",
      "descr": "Custom Server: header to return for all requests"
    },
    {
      "name": "port",
      "type": "number",
      "min": 0,
      "descr": "port to listen for the HTTP server, this is global default"
    },
    {
      "name": "bind",
      "descr": "Bind to this address only, if not specified listen on all interfaces"
    },
    {
      "name": "backlog",
      "type": "int",
      "descr": "The maximum length of the queue of pending connections, used by HTTP server in listen."
    },
    {
      "name": "ssl",
      "type": "map",
      "obj": "ssl",
      "merge": 1,
      "descr": "SSL params: port, bind, key, cert, pfx, ca, passphrase, crl, ciphers"
    },
    {
      "name": "allow-middleware",
      "type": "regexp",
      "descr": "Modules allowed to call configureMiddleware, i.e. only allowed endpoints"
    },
    {
      "name": "accesslog-disabled",
      "obj": "accesslog",
      "type": "bool",
      "descr": "Disable access logging in both file or syslog"
    },
    {
      "name": "accesslog-file",
      "obj": "accesslog",
      "descr": "File for access logging"
    },
    {
      "name": "accesslog-level",
      "obj": "accesslog",
      "type": "int",
      "descr": "Syslog level priority, default is local5.info, 21 * 8 + 6"
    },
    {
      "name": "accesslog-fields",
      "obj": "accesslog",
      "array": 1,
      "type": "list",
      "descr": "Additional fields from the request or user to put in the access log, prefix defines where the field is lcoated: q: - query, b: - body, o: - options, h: - headers, u: - user otherwise from the request",
      "example": "api-log-fields = h:Referer,u:name,q:action,b:id"
    },
    {
      "name": "max-requests",
      "type": "number",
      "min": 0,
      "descr": "Max number of requests in the processing queue, if exceeds this value server returns 503 too busy error"
    },
    {
      "name": "requests-per-socket",
      "type": "int",
      "min": 0,
      "descr": "The maximum number of requests a socket can handle before closing keep alive connection"
    },
    {
      "name": "idle-timeout",
      "type": "number",
      "min": 0,
      "max": 3600000,
      "descr": "HTTP request idle timeout for servers in ms, how long to keep the connection socket open, this does not affect Long Poll requests"
    },
    {
      "name": "keep-alive-timeout",
      "type": "int",
      "descr": "Number of milliseconds to keep the HTTP conection alive"
    },
    {
      "name": "request-timeout",
      "type": "int",
      "min": 0,
      "descr": "Number of milliseconds to receive the entire request from the client"
    },
    {
      "name": "reuse-port",
      "type": "bool",
      "descr": "Allow multiple sockets on the same host to bind to the same port"
    },
    {
      "name": "exit-on-error",
      "type": "bool",
      "descr": "Exit on uncaught exception in the route handler, shutdown the worker process gracefully"
    },
    {
      "name": "run-mode",
      "descr": "als - run inside async local storage `lib.als`, domain - run inside node:domain, other - direct callback"
    },
    {
      "name": "trust-proxy",
      "type": "bool",
      "descr": "Trust proxy headers for IP/Host"
    },
    {
      "name": "defaults-([a-z0-9_]+)-(.+)",
      "obj": "defaults.$2",
      "make": "$1",
      "autotype": 1,
      "descr": "Global body limits for `api.validate`, format is: api-defaults-LIMIT-NAME, where LIMIT is an property that performs limiting like max, maxlist, min, required.., NAME is a schema property, it can be path specific",
      "example": "# Limit all names length up to 128 chars\napi-defaults-max-name = 128\n# Limit groups list size for /endpoint to 255\napi-defaults-maxlist-/endpoint-groups = 255"
    },
    {
      "name": "restart-hours",
      "type": "list",
      "datatype": "int",
      "descr": "List of hours when to restart api workers, only done once for each hour"
    },
    {
      "name": "restart-process",
      "descr": "On address in use error condition restart the specified servers, this assumes an external monitor like monit to handle restarts"
    },
    {
      "name": "err-(.+)",
      "descr": "Error messages for various cases"
    }
  ]

(static) defaults :object

Description:

• used by module:api.validate global validation defaults, hardcoded values are set below:

Source:

• lib/api.js, line 128

Properties:

(inner) bind :string

Description:

• listen on the specified local interfcae,

Source:

• lib/api.js, line 74

Default Value:

• 0.0.0.0

(inner) port :int

Description:

• HTTP port to listen to for web server,

Source:

• lib/api.js, line 69

Default Value:

• 8000

(async, static) alimiter(name, options) → {Object}

Description:

• Async verson of module:api.limiter

Source:

• lib/api/util.js, line 174

Parameters:

Returns:

(static) createServer(port, bindopt, restartopt, sslopt, timeoutopt, keepAliveTimeoutopt, requestTimeoutopt, maxRequestsPerSocketopt, maxHeaderSizeopt, reusePortopt, nameopt)

Description:

• Create a Web server with options and request handler, returns a server object.

  Options can have the following properties:

Source:

• lib/api/server.js, line 17

Parameters:

(static) init()

Description:

• Initialize API layer, this must be called before the api module can be used but it is called by the server module automatically so api.init is rearely need to called directly, only for new server implementation or if using in the shell for testing.

  Calls configureMiddleware methods to allow other modules to setup request processing.

Source:

• lib/api.js, line 158

(static) limiter(name, options, callback)

Description:

• Perform rate limiting by name, uses shared or local cache where to keep TokenBucket object

Source:

• lib/api/util.js, line 110

Parameters:

Example

api.limiter(context.path, { rate: 10, interval: 1000 }, lib.log);

api.limiter(context.ip, { rate: 100, interval: 60000 }, lib.log);

api.limiter(context.userId, { rate: 10, interval: 3600000, message: "Slow down please for %s" }, lib.log);

api.limiter([context.userId,context.path], { rate: 10, interval: 3600000 }, lib.log);

(static) shutdown()

Description:

• Gracefully close all connections, call the callback after that

Source:

• lib/api.js, line 259

(static) validate(context, schema, optionsopt) → {object}

Description:

• Validate body/query parameters according to the schema by using module:lib.validate, uses the context.body if parsed or context.query.

  This method uses `module:api~defaults to always limit incoming data and adjust if needed, text fields are limited to 512 chars, object to 32k, json to 4k, arrays to 512 items.

Source:

• lib/api/util.js, line 11

Parameters:

Returns:

Examples

const { err, data } = api.validate(context, { q: { required: 1 } });
 if (err) return context.reply(err)

Overriding defaults, allow longer text fields

const opts = {
    defaults: {
        "*.string": { max: 1024 },
}

const schema = {
    q: { required: 1 },
    name: {},
    amount: { type: "number", minnum: 1 }
}
const { err, data } = api.validate(context, schema, opts);

(static) writeAccesslog(context)

Description:

• Record reauest into access log if enabled

Source:

• lib/api/util.js, line 55

Parameters: