Foxx service context

The service context provides access to methods and attributes that are specific to a given service. In a Foxx service the context is generally available as the module.context variable. Within a router's request handler the request and response objects' context attribute also provide access to the context of the service the route was mounted in (which may be different from the one the route handler was defined in).

Examples

// in service /my-foxx-1
const createRouter = require('@arangodb/foxx/router');
const router = createRouter();

// See the chapter on dependencies for more info on
// how exports and dependencies work across services
module.exports = {routes: router};

router.get(function (req, res) {
  module.context.mount === '/my-foxx-1';
  req.context.mount === '/my-foxx-2';
  res.write('Hello from my-foxx-1');
});

// in service /my-foxx-2
const createRouter = require('@arangodb/foxx/router');
const router2 = createRouter();

module.context.use(router2);

router2.post(function (req, res) {
  module.context.mount === '/my-foxx-2';
  req.context.mount === '/my-foxx-2';
  res.write('Hello from my-foxx-2');
});

const router1 = module.context.dependencies.myFoxx1.routes;
module.context.use(router1);

The service context specifies the following properties:

argv: any

Any arguments passed in if the current file was executed as a script or queued job.
basePath: string

The file system path of the service, i.e. the folder in which the service was installed to by ArangoDB.
baseUrl: string

The base URL of the service, relative to the ArangoDB server, e.g. /_db/_system/my-foxx.
collectionPrefix: string

The prefix that will be used by collection and collectionName to derive the names of service-specific collections. This is derived from the service's mount point, e.g. /my-foxx becomes my_foxx.
configuration: Object

Configuration options for the service.
dependencies: Object

Configured dependencies for the service.
isDevelopment: boolean

Indicates whether the service is running in development mode.
isProduction: boolean

The inverse of isDevelopment.
manifest: Object

The parsed manifest file of the service.
mount: string

The mount point of the service, e.g. /my-foxx.

apiDocumentation

module.context.apiDocumentation([options]): Function

DEPRECATED

Creates a request handler that serves the API documentation.

Note: This method has been deprecated in ArangoDB 3.1 and replaced with the more straightforward createDocumentationRouter method providing the same functionality.

Arguments

See createDocumentationRouter below.

Examples

// Serve the API docs for the current service
router.get('/docs/*', module.context.apiDocumentation());

// Note that the path must end with a wildcard
// and the route must use HTTP GET.

createDocumentationRouter

module.context.createDocumentationRouter([options]): Router

Creates a router that serves the API documentation.

Note: The router can be mounted like any other child router (see examples below).

Arguments

options: Object (optional)

An object with any of the following properties:
- mount: string (Default: module.context.mount)
  
  The mount path of the service to serve the documentation of.
- indexFile: string (Default: "index.html")
  
  File name of the HTML file serving the API documentation.
- swaggerRoot: string (optional)
  
  Full path of the folder containing the Swagger assets and the indexFile. Defaults to the Swagger assets used by the web interface.
- before: Function (optional)
  
  A function that will be executed before a request is handled.
  
  If the function returns false the request will not be processed any further.
  
  If the function returns an object, its attributes will be used to override the options for the current request.
  
  Any other return value will be ignored.

If options is a function it will be used as the before option.

If options is a string it will be used as the swaggerRoot option.

Returns a Foxx router.

Examples

// Serve the API docs for the current service
router.use('/docs', module.context.createDocumentationRouter());

// -- or --

// Serve the API docs for the service the router is mounted in
router.use('/docs', module.context.createDocumentationRouter(function (req) {
  return {mount: req.context.mount};
}));

// -- or --

// Serve the API docs only for users authenticated with ArangoDB
router.use('/docs', module.context.createDocumentationRouter(function (req, res) {
  if (req.suffix === 'swagger.json' && !req.arangoUser) {
    res.throw(401, 'Not authenticated');
  }
}));

collection

module.context.collection(name): ArangoCollection | null

Passes the given name to collectionName, then looks up the collection with the prefixed name.

Arguments

name: string

Unprefixed name of the service-specific collection.

Returns a collection or null if no collection with the prefixed name exists.

collectionName

module.context.collectionName(name): string

Prefixes the given name with the collectionPrefix for this service.

Arguments

name: string

Unprefixed name of the service-specific collection.

Returns the prefixed name.

Examples

module.context.mount === '/my-foxx'
module.context.collectionName('doodads') === 'my_foxx_doodads'

file

module.context.file(name, [encoding]): Buffer | string

Passes the given name to fileName, then loads the file with the resulting name.

Arguments

name: string

Name of the file to load, relative to the current service.
encoding: string (optional)

Encoding of the file, e.g. utf-8. If omitted the file will be loaded as a raw buffer instead of a string.

Returns the file's contents.

fileName

module.context.fileName(name): string

Resolves the given file name relative to the current service.

Arguments

name: string

Name of the file, relative to the current service.

Returns the absolute file path.

use

module.context.use([path], router): Endpoint

Mounts a given router on the service to expose the router's routes on the service's mount point.

Arguments

path: string (Default: "/")

Path to mount the router at, relative to the service's mount point.
router: Router | Middleware

A router or middleware to mount.

Returns an Endpoint for the given router or middleware.

Note: Mounting services at run time (e.g. within request handlers or queued jobs) is not supported.