@whook/whook

Build strong and efficient REST web services.

whook allows you to create REST and GraphQL web services by providing its ingredients and the recipe to make it work altogether.

The recipe is your Open API (version 3.1) definition while ingredients are routes, crons, consumers, wrappers, services, commands and some environment configuration.

Quick start

npm init @whook

Looks at the repository's main README for more documentation.

API

Functions

prepareProcess(servicesNames, $) ⇒

Runs the Whook's process

prepareEnvironment($) ⇒

Prepare the Whook process environment

pickFirstHeaderValue(name, headers) ⇒ string

Pick the first header value if exists

pickAllHeaderValues(name, headers) ⇒ Array

Pick header values

initAPM(services) ⇒ Promise.<Object>

Application monitoring service that simply log stringified contents.

initBaseURL(services) ⇒ Promise.<String>

Initialize the BASE_URL service according to the HOST/PORT so that applications fallbacks to that default base URL.

initBuildConstants(constants) ⇒ Promise.<Object>

Allow to proxy constants directly by serializing it in the build, saving some computing and increasing boot time of the build.

initCommands(services) ⇒ Promise.<Object>

Initialize the COMMANDS service gathering the project commands.

initCronsDefinitions(services) ⇒ Promise.<Object>

Initialize the CRONS_DEFINITIONS service gathering the project crons.

initCronsHandlers(services) ⇒ Promise.<function()>

Initialize the Whook cron handlers used by the router to know which cron to run for a given cron name.

initCronsWrappers(services) ⇒ Promise.<function()>

A simple passthrough service proxying the CRONS_WRAPPERS.

initDefinitions(services) ⇒ Promise.<String>

Initialize the DEFINITIONS service.

initErrorHandler(services) ⇒ Promise

Initialize an error handler for the HTTP router

initHost(services) ⇒ Promise.<String>

Initialize the HOST service from ENV or auto-detection if none specified in ENV

initHTTPRouter(services) ⇒ Promise

Initialize an HTTP router

initHTTPServer(services) ⇒ Promise.<HTTPServer>

Initialize an HTTP server

initHTTPTransaction(services) ⇒ Promise.<WhookHTTPTransaction>

Instantiate the httpTransaction service

initMainHandler(services) ⇒ Promise.<function()>

An initializer to build a single Whook route handler.

initObfuscator(services) ⇒ Promise.<Object>

Obfuscate sensible informations.

initPort(services) ⇒ Promise.<Number>

Initialize the PORT service from ENV or auto-detection if none specified in ENV

wrapEnvForBuild(services) ⇒ Promise.<Object>

Wrap the ENV service in order to filter ENV vars for the build

initRoutesDefinitions(services) ⇒ Promise.<Object>

Initialize the ROUTES_DEFINITIONS service gathering the project routes definitions.

initRoutesHandlers(services) ⇒ Promise.<function()>

Initialize the Whook routes handlers used by the router to know which handler to run for a given route.

initRoutesWrappers(services) ⇒ Promise.<function()>

A simple passthrough service proxying the ROUTES_WRAPPERS.

initSchemaValidators(services) ⇒ Promise.<Number>

Initialize the schema validator service for application schemas validation. This central place is aimed to compile schemas once and use them many times.

initWhookResolvedPlugins(services) ⇒ Promise.<string>

Resolves the Whook plugins from their names

Typedefs

HTTPServer

WhookHTTPTransaction

prepareProcess(servicesNames, $) ⇒

Runs the Whook's process

Kind: global function
Returns: Object A promise of the injected services

Param	Type	Description
servicesNames	Array.<String>	Root dependencies names to instanciate and return
$	Knifecycle	The Knifecycle instance to use for the run

prepareEnvironment($) ⇒

Prepare the Whook process environment

Kind: global function
Returns: Promise A promise of the Knifecycle instance

Param	Type	Description
$	Knifecycle	The Knifecycle instance to set the various services

pickFirstHeaderValue(name, headers) ⇒ string

Pick the first header value if exists

Kind: global function
Returns: string - The value if defined.

Param	Type	Description
name	string	The header name
headers	Object	The headers map

pickAllHeaderValues(name, headers) ⇒ Array

Pick header values

Kind: global function
Returns: Array - The values in an array.

Param	Type	Description
name	string	The header name
headers	Object	The headers map

initAPM(services) ⇒ Promise.<Object>

Application monitoring service that simply log stringified contents.

Kind: global function
Returns: Promise.<Object> - A promise of the apm service.

Param	Type	Description
services	Object	The services to inject
[services.log]	function	A logging function

initBaseURL(services) ⇒ Promise.<String>

Initialize the BASE_URL service according to the HOST/PORT so that applications fallbacks to that default base URL.

Kind: global function
Returns: Promise.<String> - A promise of a containing the actual host.

Param	Type	Default	Description
services	Object		The services BASE_URL depends on
services.ENV	Object		The process environment
services.CONFIG	Object		The injected CONFIG value
[services.PROTOCOL]	Object		The injected PROTOCOL value
services.HOST	Object		The injected HOST value
services.PORT	Object		The injected PORT value
[services.log]	Object	noop	An optional logging service

initBuildConstants(constants) ⇒ Promise.<Object>

Allow to proxy constants directly by serializing it in the build, saving some computing and increasing boot time of the build.

Kind: global function
Returns: Promise.<Object> - A promise of an object containing the gathered constants.

Param	Type	Description
constants	Object	The serializable constants to gather

Example

import { initBuildConstants } from '@whook/whook';
import { alsoInject } from 'knifecycle';

export default alsoInject(['MY_OWN_CONSTANT'], initBuildConstants);

initCommands(services) ⇒ Promise.<Object>

Initialize the COMMANDS service gathering the project commands.

Kind: global function
Returns: Promise.<Object> - A promise of a containing the actual host.

Param	Type	Default	Description
services	Object		The services COMMANDS depends on
[services.WHOOK_PLUGINS]	Array.<String>		The activated plugins
services.WHOOK_RESOLVED_PLUGINS	Array		The resolved plugins
[services.COMMANDS_DEFINITIONS_OPTIONS]	Object		The options to load the project commands
[services.COMMAND_DEFINITION_FILTER]	Object		A function to filter the project commands per definitions
services.importer	Object		A service allowing to dynamically import ES modules
[services.log]	Object	noop	An optional logging service

initCronsDefinitions(services) ⇒ Promise.<Object>

Initialize the CRONS_DEFINITIONS service gathering the project crons.

Kind: global function
Returns: Promise.<Object> - A promise of a containing the actual host.

Param	Type	Default	Description
services	Object		The services CRONS_DEFINITIONS depends on
[services.WHOOK_PLUGINS]	Array.<String>		The activated plugins
services.WHOOK_RESOLVED_PLUGINS	Array		The resolved plugins
[services.CRONS_DEFINITIONS_OPTIONS]	Object		The options to load the project crons
[services.CRON_DEFINITION_FILTER]	Object		A function to filter the project crons per definitions
services.importer	Object		A service allowing to dynamically import ES modules
[services.log]	Object	noop	An optional logging service

initCronsHandlers(services) ⇒ Promise.<function()>

Initialize the Whook cron handlers used by the router to know which cron to run for a given cron name.

Kind: global function
Returns: Promise.<function()> - A promise of the CRONS_HANDLERS hash.

Param	Type	Default	Description
services	Object		The services CRONS_HANDLERS depends on
services.CRONS_WRAPPERS	Array		An optional list of wrappers to inject
[services.log]	Object	noop	An optional logging service
services.CRONS_HANDLERS	Object		The rest is a hash of crons handlers mapped by name

initCronsWrappers(services) ⇒ Promise.<function()>

A simple passthrough service proxying the CRONS_WRAPPERS.

Kind: global function
Returns: Promise.<function()> - A promise of the CRONS_WRAPPERS hash.

Param	Type	Default	Description
services	Object		The services CRONS_WRAPPERS depends on
[services.CRONS_WRAPPERS_NAMES]	Array		The global wrappers names to wrap the crons with
[services.log]	Object	noop	An optional logging service
services.CRONS_WRAPPERS	Object		The dependencies must all be injected wrappers

initDefinitions(services) ⇒ Promise.<String>

Initialize the DEFINITIONS service.

Kind: global function
Returns: Promise.<String> - A promise of a containing the actual host.

Param	Type	Default	Description
services	Object		The services DEFINITIONS depends on
[services.ROUTES_DEFINITIONS]	Object		The API routes modules
[services.COMMANDS_DEFINITIONS]	Object		The commands modules
[services.CRONS_DEFINITIONS]	Object		The crons modules
[services.log]	Object	noop	An optional logging service

initErrorHandler(services) ⇒ Promise

Initialize an error handler for the HTTP router

Kind: global function
Returns: Promise - A promise of a function to handle errors

Param	Type	Description
services	Object	The services the server depends on
services.ENV	Object	The app ENV
[services.DEBUG_NODE_ENVS]	Array	The environnement that activate debugging (prints stack trace in HTTP errors responses)
[services.STRINGIFIERS]	Object	The synchronous body stringifiers
[services.ERRORS_DESCRIPTORS]	Object	An hash of the various error descriptors
[services.DEFAULT_ERROR_CODE]	Object	A string giving the default error code

initErrorHandler~errorHandler(transactionId, responseSpec, err) ⇒ Promise

Handle an HTTP transaction error and map it to a serializable response

Kind: inner method of initErrorHandler
Returns: Promise - A promise resolving when the operation completes

Param	Type	Description
transactionId	String	A raw NodeJS HTTP incoming message
responseSpec	Object	The response specification
err	YHTTPError	The encountered error

initHost(services) ⇒ Promise.<String>

Initialize the HOST service from ENV or auto-detection if none specified in ENV

Kind: global function
Returns: Promise.<String> - A promise of a containing the actual host.

Param	Type	Default	Description
services	Object		The services HOST depends on
[services.ENV]	Object	{}	An optional environment object
[services.log]	Object	noop	An optional logging service
services.importer	Object		A service allowing to dynamically import ES modules

initHTTPRouter(services) ⇒ Promise

Initialize an HTTP router

Kind: global function
Returns: Promise - A promise of a function to handle HTTP requests.

Param	Type	Default	Description
services	Object		The services the server depends on
[services.BUFFER_LIMIT]	String		The maximum bufferisation before parsing the request body
[services.BASE_PATH]	String		API base path
services.ROUTES_HANDLERS	Object		The handlers for the operations decribe by the OpenAPI API definition
services.API	Object		The OpenAPI definition of the API
[services.PARSERS]	Object		The synchronous body parsers (for operations that defines a request body schema)
[services.STRINGIFIERS]	Object		The synchronous body stringifiers (for operations that defines a response body schema)
[services.ENCODERS]	Object		A map of encoder stream constructors
[services.DECODERS]	Object		A map of decoder stream constructors
[services.queryParserBuilder]	Object		A query parser builder from OpenAPI parameters
[services.COERCION_OPTIONS]	Object		Options for type coercion of parameters values
[services.log]	function	noop	A logging function
services.httpTransaction	function		A function to create a new HTTP transaction

initHTTPRouter~httpRouter(req, res) ⇒ Promise

Handle an HTTP incoming message

Kind: inner method of initHTTPRouter
Returns: Promise - A promise resolving when the operation completes

Param	Type	Description
req	HTTPRequest	A raw NodeJS HTTP incoming message
res	HTTPResponse	A raw NodeJS HTTP response

initHTTPServer(services) ⇒ Promise.<HTTPServer>

Initialize an HTTP server

Kind: global function
Returns: Promise.<HTTPServer> - A promise of an object with a NodeJS HTTP server in its service property.

Param	Type	Default	Description
services	Object		The services the server depends on
[services.ENV]	Object		The process environment variables
services.ENV.DESTROY_SOCKETS	String		Whether the server sockets whould be destroyed or if the server should wait while sockets are kept alive
[services.HTTP_SERVER_OPTIONS]	Object		See https://nodejs.org/docs/latest/api/http.html#class-httpserver
services.HOST	String		The server host
services.PORT	Number		The server port
services.httpRouter	function		The function to run with the req/res tuple
[services.log]	function	noop	A logging function

initHTTPTransaction(services) ⇒ Promise.<WhookHTTPTransaction>

Instantiate the httpTransaction service

Kind: global function
Returns: Promise.<WhookHTTPTransaction> - A promise of the httpTransaction function

Param	Type	Default	Description
services	Object		The services to inject
[services.TIMEOUT]	Number	30000	A number indicating how many ms the transaction should take to complete before being cancelled.
[services.TRANSACTIONS]	Object	{}	A hash of every current transactions
services.delay	Object		A delaying service
services.obfuscator	Object		A service to avoid logging sensible informations
[services.log]	function		A logging function
[services.apm]	function		An apm function
[services.time]	function		A timing function
[services.uniqueId]	function		A function returning unique identifiers

Example

import initHTTPTransaction from '@whook/whook';
import { log } from 'node:console';

const httpTransaction = await initHTTPTransaction({
  log,
  time: Date.now.bind(Date),
});

initHTTPTransaction~httpTransaction(req, res) ⇒ Array

Create a new HTTP transaction

Kind: inner method of initHTTPTransaction
Returns: Array - The normalized request and the HTTP transaction created in an array.

Param	Type	Description
req	HTTPRequest	A raw NodeJS HTTP incoming message
res	HTTPResponse	A raw NodeJS HTTP response

initMainHandler(services) ⇒ Promise.<function()>

An initializer to build a single Whook route handler.

Kind: global function
Returns: Promise.<function()> - A promise of the MAIN_HANDLER service.

Param	Type	Default	Description
services	Object		The services $autoload depends on
services.WRAPPERS	Array		An optional list of wrappers to inject
services.MAIN_WRAPPER	function		The main route handle wrapper
services.BASE_HANDLER	function		The base handler
[services.log]	function	noop	An optional logging service

initObfuscator(services) ⇒ Promise.<Object>

Obfuscate sensible informations.

Kind: global function
Returns: Promise.<Object> - A promise of an object containing the gathered constants.

Param	Type	Description
services	Object	The service dependend on
[services.SHIELD_CHAR]	Object	The char for replacing sensible informations
[services.MAX_CLEAR_CHARS]	Object	The maximum clear chars to display
[services.MAX_CLEAR_RATIO]	Object	The maximum clear chars ratio to display
[services.SENSIBLE_PROPS]	Object	Sensible properties names
[services.SENSIBLE_HEADERS]	Object	Sensible headers names

Example

import { initObfuscator } from '@whook/whook';
import { alsoInject } from 'knifecycle';
import { log } from 'node:console';

const obfuscator = await initObfuscator();

log(obfuscator('my very secret information!));
// my ...on!

initPort(services) ⇒ Promise.<Number>

Initialize the PORT service from ENV or auto-detection if none specified in ENV

Kind: global function
Returns: Promise.<Number> - A promise of a number representing the actual port.

Param	Type	Default	Description
services	Object		The services PORT depends on
[services.ENV]	Object	{}	An optional environment object
[services.log]	Object	noop	An optional logging service
services.importer	Object		A service allowing to dynamically import ES modules

wrapEnvForBuild(services) ⇒ Promise.<Object>

Wrap the ENV service in order to filter ENV vars for the build

Kind: global function
Returns: Promise.<Object> - A promise of an object containing the reshaped env vars.

Param	Type	Default	Description
services	Object		The services ENV depends on
[services.PROXIED_ENV_VARS]	Object	{}	A list of environment variable names to proxy
[services.log]	Object	noop	An optional logging service

initRoutesDefinitions(services) ⇒ Promise.<Object>

Initialize the ROUTES_DEFINITIONS service gathering the project routes definitions.

Kind: global function
Returns: Promise.<Object> - A promise of a containing the actual host.

Param	Type	Default	Description
services	Object		The services ROUTES_DEFINITIONS depends on
[services.WHOOK_PLUGINS]	Array.<String>		The activated plugins
services.WHOOK_RESOLVED_PLUGINS	Array		The resolved plugins
[services.ROUTES_DEFINITIONS_OPTIONS]	Object		The options to load the routes in the file system
[services.ROUTE_DEFINITION_FILTER]	Object		A function to filter the routes per definitions
services.importer	Object		A service allowing to dynamically import ES modules
[services.log]	Object	noop	An optional logging service

initRoutesHandlers(services) ⇒ Promise.<function()>

Initialize the Whook routes handlers used by the router to know which handler to run for a given route.

Kind: global function
Returns: Promise.<function()> - A promise of the ROUTES_HANDLERS hash.

Param	Type	Default	Description
services	Object		The services ROUTES_HANDLERS depends on
services.ROUTES_WRAPPERS	Array		An optional list of wrappers to inject
[services.log]	Object	noop	An optional logging service
services.ROUTES_HANDLERS	Object		The rest is a hash of routesHandlers mapped by their operation id

initRoutesWrappers(services) ⇒ Promise.<function()>

A simple passthrough service proxying the ROUTES_WRAPPERS.

Kind: global function
Returns: Promise.<function()> - A promise of the ROUTES_WRAPPERS hash.

Param	Type	Default	Description
services	Object		The services ROUTES_WRAPPERS depends on
[services.ROUTES_WRAPPERS_NAMES]	Array		The global wrappers names to wrap the routes with
[services.log]	Object	noop	An optional logging service
services.ROUTES_WRAPPERS	Object		The dependencies must all be injected wrappers

initSchemaValidators(services) ⇒ Promise.<Number>

Initialize the schema validator service for application schemas validation. This central place is aimed to compile schemas once and use them many times.

Kind: global function
Returns: Promise.<Number> - A promise of a schema validators registry

Param	Type	Default	Description
services	Object		The services it depends on
[services.SCHEMA_VALIDATORS_OPTIONS]	Object	{}	Options for the schema validators registry
[services.ENV]	Object	{}	An optional environment object
[services.log]	Object	noop	An optional logging service
services.API	Object		A valid Open API file

initWhookResolvedPlugins(services) ⇒ Promise.<string>

Resolves the Whook plugins from their names

Kind: global function
Returns: Promise.<string> - A promise of a number representing the actual port.

Param	Type	Default	Description
services	Object		The services WHOOK_RESOLVED_PLUGINS depends on
[services.WHOOK_PLUGINS]	Array.<String>		The activated plugins
[services.log]	Object	noop	An optional logging service

HTTPServer

Kind: global typedef

WhookHTTPTransaction

Kind: global typedef

• WhookHTTPTransaction
  • .id
  • .start ⇒ Promise.<Object>
  • .catch ⇒ Promise
  • .end ⇒ Promise.<Object>

WhookHTTPTransaction.id

Id of the transaction

Kind: static property of WhookHTTPTransaction

WhookHTTPTransaction.start ⇒ Promise.<Object>

Start the transaction

Kind: static property of WhookHTTPTransaction
Returns: Promise.<Object> - A promise to be resolved with the signed token.

Param	Type	Description
buildResponse	function	A function that builds a response

WhookHTTPTransaction.catch ⇒ Promise

Catch a transaction error

Kind: static property of WhookHTTPTransaction
Returns: Promise - A promise to be resolved with the signed token.

Param	Type	Description
err	Error	A function that builds a response

WhookHTTPTransaction.end ⇒ Promise.<Object>

End the transaction

Kind: static property of WhookHTTPTransaction
Returns: Promise.<Object> - A promise to be resolved with the signed token.

Param	Type	Description
response	Object	A response for the transaction

Authors

• Nicolas Froidure

License

MIT