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
| Name | Description |
|---|---|
Context | The type of the context property. |
Constructors
constructor
• new WebService<Context>(context, config?)
Type parameters
| Name |
|---|
Context |
Parameters
| Name | Type | Description |
|---|---|---|
context | Context | The web service's context, which will provided to filter and resource constructors. |
config? | WebServiceConfig | The 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
| Name | Type | Description |
|---|---|---|
mountPoint | string | The 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
| Name | Type | Description |
|---|---|---|
filter | WebFilterCtor<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
| Name | Type | Description |
|---|---|---|
filters | Iterable<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
| Name | Type | Description |
|---|---|---|
resource | WebResourceCtor<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
| Name | Type |
|---|---|
resources | Iterable<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
| Name | Type | Description |
|---|---|---|
webreq | WebRequest | The 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
| Name | Type |
|---|---|
req | IncomingMessage |
res | ServerResponse |
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
| Name | Type | Description |
|---|---|---|
errorHandler | undefined | 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
| Name | Type | Description |
|---|---|---|
rsrc? | WebResource | The resource to produce an Allow header for. |
Returns
string
A comma-separated list of allowed HTTP methods.