Skip to main content

Class: WebService<Context>

@divine/web-service.WebService

A WebService is a collection of registered resources, filters and an optional error handler that forms the web application.

Concepts

Context

When a WebService is created, it can be associated with a custom object called the WebService context. This context is passed to the resources and filters as they are constructed and can provide configuration and/or services to the web application.

Resources

A WebResource is responsible for handling a specific location. It responds to one or more HTTP verbs and produces a WebResponse once finished. A new instance of the resource class is constructed for each incoming request, ensuring that no state is leaked between requests.

Only a single resource will ever match an incoming request.

Filters

Filters are used to modify the behavior of a set of resources. They can be used to handle CORS requests, authentication and authorization, throttling etc. Just like resources, a new instance of the filter will always be constructed for each incoming request.

Multiple filters may match an incoming request. They will be processed in the same order as they were added via addFilter or addFilters.

Error handler

The error handler acts like a global catch block and can be used to produce non-generic error responses in case something is not right.

Type parameters

NameDescription
ContextThe type of the context property.

Constructors

constructor

new WebService<Context>(context, config?)

Type parameters

Name
Context

Parameters

NameTypeDescription
contextContextThe web service's context, which will provided to filter and resource constructors.
config?WebServiceConfigThe web service configuration.

Defined in

web-service/src/service.ts:174

Properties

context

context: Context

The web service's context, which will provided to filter and resource constructors.

Defined in

web-service/src/service.ts:174


webServiceConfig

Readonly webServiceConfig: Required<WebServiceConfig>

The actual WebServiceConfig used by this service.

Defined in

web-service/src/service.ts:161

Accessors

webServiceMountPoint

get webServiceMountPoint(): string

The mount point where this service is mounted. Usually just '/'.

Returns

string

Defined in

web-service/src/service.ts:191

Methods

_mount

Protected _mount(mountPoint): WebService<Context>

Called by mount when this WebService is mounted (attached to a WebServer).

Parameters

NameTypeDescription
mountPointstringThe prefix path where this WebService should be mounted.

Returns

WebService<Context>

This WebService.

Defined in

web-service/src/service.ts:201


_unmount

Protected _unmount(): WebService<Context>

Called by Called by unmount when this WebService is unmounted.

Returns

WebService<Context>

This WebService.

Defined in

web-service/src/service.ts:217


addFilter

addFilter(filter): WebService<Context>

Registers a single filter.

The filter's path property defines what locations the filter is applicable to.

Parameters

NameTypeDescription
filterWebFilterCtor<Context>A filter class to register.

Returns

WebService<Context>

This WebService.

Defined in

web-service/src/service.ts:247


addFilters

addFilters(filters): WebService<Context>

Registers multiple filters.

The filters' path properties defines what locations each filter is applicable to.

Parameters

NameTypeDescription
filtersIterable<WebFilterCtor<Context>>A sequence of filter classes to register.

Returns

WebService<Context>

This WebService.

Defined in

web-service/src/service.ts:264


addResource

addResource(resource): WebService<Context>

Registers a single resource.

The resource's path property defines what locations the resource is applicable to.

Parameters

NameTypeDescription
resourceWebResourceCtor<Context>A resouece class to register.

Returns

WebService<Context>

This WebService.

Defined in

web-service/src/service.ts:280


addResources

addResources(resources): WebService<Context>

Registers multiple resources.

The resources' path properties defines what locations each resource is applicable to.

Parameters

NameType
resourcesIterable<WebResourceCtor<Context>>

Returns

WebService<Context>

This WebService.

Defined in

web-service/src/service.ts:304


dispatchRequest

dispatchRequest(webreq): Promise<WebResponse>

Dispatches a request to the intended resource and also applies all matching filters.

Errors will also be handled, so this method does not normally throw.

Parameters

NameTypeDescription
webreqWebRequestThe HTTP request to handle.

Returns

Promise<WebResponse>

An HTTP response to be sent to the client.

Defined in

web-service/src/service.ts:379


requestEventHandler

requestEventHandler(): (req: IncomingMessage, res: ServerResponse) => Promise<void>

Returns a Node.jss HTTP request handler as specified by createServer.

The request handler will construct a WebRequest and then invoke dispatchRequest. The response will then be serialized and sent to the client.

Returns

fn

A Node.js HTTP request handler for this WebService.

▸ (req, res): Promise<void>

Returns a Node.jss HTTP request handler as specified by createServer.

The request handler will construct a WebRequest and then invoke dispatchRequest. The response will then be serialized and sent to the client.

Parameters
NameType
reqIncomingMessage
resServerResponse
Returns

Promise<void>

A Node.js HTTP request handler for this WebService.

Defined in

web-service/src/service.ts:321


setErrorHandler

setErrorHandler(errorHandler): WebService<Context>

Installs a service-wide error handler.

Whenever a resource of filter throws an exception, the error handler is invoked to handle the error. The error handler can either return a WebResponse or (re-)throw.

Parameters

NameTypeDescription
errorHandlerundefined | WebErrorHandler<Context>The error handler to install, or undefined to restore the default behaviour.

Returns

WebService<Context>

THis WebService.

Defined in

web-service/src/service.ts:233


makeAllowHeader

Static makeAllowHeader(rsrc?): string

Utilitiy method to calculate an Allow header based on an WebResource.

This method checks what methods are implemented on the provided object and generates a comma-separated list of allowed HTTP methods.

Parameters

NameTypeDescription
rsrc?WebResourceThe resource to produce an Allow header for.

Returns

string

A comma-separated list of allowed HTTP methods.

Defined in

web-service/src/service.ts:140