carbond.Service

extends Endpoint

Service is the main entry point to a carbond service

Static Properties

ALL_METHODS	Object Inherited fromEndpoint
Required
Description	A list of all HTTP methods recognized by carbond

Instance Properties

adminRoot	string
Default	'/service-admin'
Description	The “administrative” root URL path component (this is only enabled if the “swagger” command line option is present)

allowUnauthenticated	string[] Inherited fromEndpoint
Required
Description	Skip authentication for the HTTP methods listed on this endpoint

apiRoot	string
Default	undefined
Description	The root component of the URL path component. This will be prepended to any routes that are yielded by the Endpoint tree.

authenticator	Authenticator
Default	undefined
Description	The root authenticator. If present, all requests will be passed through the authenticator resulting in a 401 if authentication fails.

cluster	boolean
Default	false
Description	Whether or not to use Node’s cluster module

cmdargs	Object
Default	{}
Description	Additional command line argument definitions (will be merged into defaultCmdargs)

corsEnabled	boolean
Default	true
Description	Flag determining whether CORS is enabled

db	Object
Required
Description	The connection object for dbUri

dbs	Object.<string, Object>
Required
Description	The connection objects for dbUri. The keys for this object will mirror those in dbUri, while the values will be the connection objects themselves.

dbUri	string
Required
Description	The database URI to connect to at startup (currently restricted to MongoDB)

dbUris	Object.<string, string>
Required
Description	Database URIs to connect to at startup (currently restricted to MongoDB)

defaultCmdargs	Object
Default	{...}
Description	The default command line arguments definition. Service#cmdargs can be used to extend the default set of command line arguments.

defaultDocgenOptions	Object
Default	{...}
Description	Default options for the “aglio” documentation generator

description	string
Default	'This is a Service'
Description	A short description of this service

endpoints	Object
Default	{}
Description	The endpoint tree. Note, keys in the endpoint tree will be used to construct routes to the various Endpoint.

env	string
Required
Description	carbond.DEFAULT_ENV}

errorHandlingMiddleware	function()[]
Default	[]
Description	Middleware that will be invoked in the event that an error is thrown. Error-handling middleware function signatures should conform to fn(err, req, res, next).

errors	Object
Default	HttpErrors
Description	A shortcut reference to the @carbon-io/http-errors module to be accessed using the service reference available throughout the carbond component hierarchy

fiberPoolSize	number
Default	120
Description	Sets the pool size for the underlying fibers module. Note, a new fiber will be created and destroyed for every fiber created beyond the pool size. If this occurs regularly, it can lead to significant performance degradation. While the default should usually suffice, this parameter should be tuned according to the expected number of concurrent requests.

generateOptionsMethodsInDocs	boolean
Default	false
Description	Whether or not to include OPTIONS methods in static documentation

gracefulShutdown	boolean
Default	true
Description	Whether or not the service should gracefully shutdown when a stop is requested (i.e., whether or not open sockets should be allowed to timeout or severed immediately). The default for this is computed using DEFAULT_ENV (e.g., DEFAULT_ENV === 'production').

hostname	string
Default	'127.0.0.1'
Description	The address that this service should listen on

logger	logging.Logger
Default	{...}
Description	The logger instance used by service log methods (e.g. undefined)

middleware	function()[]
Default	[]
Description	Middleware functions that will be executed via express before control is passed on to any Operation. Middleware function signatures should conform to fn(req, res, next).

noDocument	boolean Inherited fromEndpoint
Default	false
Description	Controls whether documentation for this endpoint is included in generated static documentation

numClusterWorkers	number
Default	undefined
Description	The number of cluster workers to start. If left undefined or set to 0, it will be set to the number of CPUs present.

parameterParser	ParameterParser
Default	o({_type: './ParameterParser'})
Description	The parameter parser used to parse all incoming request parameters (i.e., query, header, body, and path). In most cases, the default parser should be sufficient.

parameters	Object.<string, carbond.OperationParameter> Inherited fromEndpoint
Required
Description	Operation parameter definitions that apply to all operations supported by this endpoint. Note, these will be merged with any parameter definitions on the operations themselves and their parsed values will be passed to the handler via req.parameters[<parameter name>].

parent	Endpoint Inherited fromEndpoint (read-only)
Description	The parent endpoint for this endpoint in the endpoint tree

path	string
Default	''
Description	Since Service is itself an Endpoint, this can be used to set the URL path component that the service endpoint is accessible at

port	number
Default	8888
Description	The port that this service should bind

processUser	string
Default	undefined
Description	If set, privileges will be dropped and the effective user for the process will be set to this

publicDirectories	Object.<string, string>
Default	{}
Description	Directories with static assets that should be exposed by the service. Keys are the URL paths under which these static assests should be served while values are the local filesystem paths at which the assets exist.

serverSocketTimeout	number
Default	undefined
Description	The socket timeout for all incoming connections. Note, the system default is 2 minutes.

service	Service Inherited fromEndpoint (read-only)
Deprecated
Description	The root service object managing the endpoint tree. Getting a reference to this object is sometimes necessary or just convenient (i.e., HTTP error classes can be accessed via errors).

signalHandler	Object.<string, function()>
Default	{...}
Description	An object whose keys are signal names (e.g., “SIGINT”) and whose values are functions invoked to handle the signal(s) corresponding to their aforementioned keys. Note, keys here can be a string of signal names delineated by spaces (e.g. “SIGINT SIGHUP”). In this case, the corresponding function will be called for any of the signals named in the key.

sslOptions	SslOptions
Default	o({_type: './SslOptions'})
Description	SSL options to use if running HTTPS

validateOutput	boolean Inherited fromEndpoint
Default	true
Description	Controls whether or not response bodies are validated using the response schema corresponding to the current response code

Abstract Methods

doStart
Arguments	options (Object) – Parsed command line options
Return type	undefined
Description	Performs custom startup operations. This method will be called after initialization (e.g., database connections will be established and the endpoint tree will be built) but before the server’s socket is bound. Override this method if your app requires further initialization.

doStop
Return type	undefined
Description	Performs custom teardown operations. This method will be called first in the stop sequence.

Methods

getOperation	Inherited fromEndpoint
Arguments	method (string) – The HTTP method corresponding to the operation to retrieve
Return type	Operation
Description	Retrieves the operation instance corresponding to the passed HTTP method

getService	Inherited fromEndpoint
Return type	Service
Description	Returns the root Service instance (note, this is preferred over accessing the service property itself)

isOperationAuthorized	Inherited fromEndpoint
Arguments	method (string) – The HTTP method corresponding to the operation that we are attempting to authorize user (Object) – The user object req (Request) – The request object
Returns	Whether of not the operation is authorized
Return type	boolean
Description	Tests whether an operation is authorized given a user (as returned by the root authenticator) and any Acl that may apply to this endpoint

logDebug
Return type	undefined
Description	Log a message at the “debug” level

logError
Return type	undefined
Description	Log a message at the “error” level

logFatal
Return type	undefined
Description	Log a message at the “fatal” level

logInfo
Return type	undefined
Description	Log a message at the “info” level

logTrace
Return type	undefined
Description	Log a message at the “trace” level

logWarning
Return type	undefined
Description	Log a message at the “warn” level

on
Arguments	event (String) – [choices: “start”, “stop”] listener (function) – Callback to fire when event occurs
Return type	EventEmitter
Description	Register a service event callback

once
Arguments	event (String) – the event type [choices: “start”, “stop”] listener (function) – callback to fire when event occurs
Return type	EventEmitter
Description	Register a service event callback that executes once

operations	Inherited fromEndpoint
Return type	Operation[]
Description	Gathers all operations defined on this endpoint

options	Inherited fromEndpoint
Arguments	req (Request) – The request object res (Response) – The response object
Return type	undefined
Description	Implements the OPTIONS method handler

removeAllListeners
Arguments	event (...String) – the event type [choices: “start”, “stop”]
Return type	EventEmitter
Description	Remove all listeners. If event is passed, remove all listeners for that specific event (or events).

removeListener
Arguments	event (String) – the event type [choices: “start”, “stop”] listener (function) – callback to fire when event occurs
Return type	EventEmitter
Description	Remove a specific listener for a particular event.

start
Arguments	options (Object) – Parsed command line options cb (function) – Async callback (this can be omitted if calling from within a Fiber)
Throws	Error
Return type	undefined
Description	Initializes and starts the service

stop
Arguments	cb (function) – Async callback (this can be omitted if calling from within a Fiber)
Return type	undefined
Description	Stops the service

supportedMethods	Inherited fromEndpoint
Return type	string[]
Description	Returns a list of HTTP methods supported by this endpoint