This project is a TypeScript server sdk project that contains autogenerated code based on an [OpenAPI Specification](https://swagger.io/specification/). In many cases, the input specification is defined by an API project in the same repository, which fee
npm install @launchtray/hatch-scim2-server-sdkAuto-generated code within this project calls API delegate methods with parsed, typed parameters in order to
service HTTP requests. API delegates should be registered as middleware for a server using the getApiMiddleware
export of this library. For example, in composeServer.ts for a server (assuming an API called ExampleApi):
``typescript
export default async (): Promise
/ ... /
return {
...commonComposition,
serverMiddleware: [
JSONBodyParser,
RequestLogger,
...getApiMiddleware({
delegateForExampleApi: ExampleApiDelegateImpl,
}),
RouteNotFound, // Catch-all 404 for unimplemented APIs
],
};
};
`
include handler methods for each HTTP endpoint
defined in the API spec. Each of these methods has an explicitly typed request object as its first parameter,
which includes all request parameters and payloads, parsed into a type-safe object. Optionally, the class
implementing the API delegate can define other parameters to be injected, as long as the types of the parameters
can be resolved via dependency injection for the current request context. For example, even though the API delegate
interface has a handler method defined as follows:
`typescript
handleCreateTester(
request: models.CreateTesterRequest & {isLocal: boolean, isFromSsr: boolean},
...optionalInjections: unknown[]
): ApiDelegateResponse;
`
The implementing class might implement it as such, to get a per-request logger and low-level information about the
underlying HTTP request:
typescript
handleCreateTester(
request: CreateTesterRequest,
@inject('Logger') logger: Logger,
basicRouteParams: BasicRouteParams,
): CreateTesterResponse {
/ ... /
}
`
This uses the same mechanism as parameters to routes defined manually. For more information, see the
Manual routes section below.$3
In some cases, it might not make sense to return the expected response object, e.g. in the case of an
error condition. In those cases, API delegate methods can either return an object,
or throw an ApiError to indicate the HTTP status code to use, headers to return, and the contents of
the response body. For example, the two non-successful cases result in the same HTTP response:
`typescript
import {
ApiAlternateAction,
} from '@launchtray/hatch-util';handleCreateTester(
request: CreateTesterRequest,
@inject('Logger') logger: Logger,
basicRouteParams: BasicRouteParams,
): CreateTesterResponse {
return new ApiAlternateAction(500, 'Test error');
}
`
typescript
import {
ApiAlternateAction,
ApiError,
} from '@launchtray/hatch-util';handleCreateTester(
request: CreateTesterRequest,
@inject('Logger') logger: Logger,
basicRouteParams: BasicRouteParams,
): CreateTesterResponse {
throw new ApiError(new ApiAlternateAction(500, 'Test error'), 'Detailed error message');
}
`
This mechanism works for explicit API controller handlers as well as for manually-defined routes.$3
In most cases, the autogenerated code is all that is necessary for building APIs. However, in some cases, it is
necessary to define routes manually, e.g. for wildcard routes that do common processing before other endpoints.Routes can be defined manually using decorators within the
namespace exported by hatch-server. These
decorators use the same routing syntax that is used by express, including support for route
parameters. A simple example of a GET route with a person ID parameter can be seen below:`typescript
import {
BasicRouteParams,
route,
} from '@launchtray/hatch-server';
import {inject, containerSingleton, Logger} from '@launchtray/hatch-util';@containerSingleton()
export default class ExampleApiDelegateImpl {
// Note: dependencies can be injected into the constructor
constructor(@inject('Logger') private readonly logger: Logger) {
}
@route.get('/api/person/:id')
public personEndpoint(params: BasicRouteParams) {
params.res.status(200).send('Person: ' + params.req.params.id);
}
...
`As shown above, route methods can take in a parameter of type
, which contains the Express
Request and Response objects, the
next callback passed to the request handler, a Logger instance, any cookies, and the auth header.However, when a request comes in, the server creates a new dependency injection container specifically for that request.
This container is a child of the root container that is used by composeServer.ts and
composeCommon.ts to register dependency classes. The only objects that get registered
into the child container that are not also in the root container are the fields of
BasicRouteParams. The parameters of
route handler methods are actually auto-resolved using this container. This means that not only could we define the
method with a single BasicRouteParams parameter, but we could also use any parameters, as long as they can be resolved
by the child container described above. For example, imagine a very simple HTTPResponder class which depends on
BasicRouteParams:`typescript
import {BasicRouteParams} from '@launchtray/hatch-server';
import {containerSingleton} from '@launchtray/hatch-util';@containerSingleton()
export default class HTTPResponder {
constructor(public readonly params: BasicRouteParams) {}
public ok(body?: any) {
this.params.res.status(200).send(body);
}
}
`
Since this class is annotated as injectable (via ), and since it only depends on things that are
registered in an HTTP request's child container (in this case, just BasicRouteParams), we can use it as a parameter to
a route like so:`typescript
@route.get('/api/example')
public exampleEndpoint(responder: HTTPResponder) {
this.logger.info('Example endpoint called');
responder.ok('Example GET');
}
`$3
In addition to HTTP method routes, WebSocket server routes can be defined. These routes make use of the
ws library. An example WebSocket route that broadcasts messages to all other clients
is shown below. Note that route parameters (in this case an ID) can also be used with WebSocket routes.typescript
@route.websocket('/ws/:id')
public async handleWebsocket(params: WebSocketRouteParams) {
const ws = params.webSocket; // ws is simply a web socket object from the ws library
ws.on('message', (msg: string) => {
params.webSocketServer.clients.forEach((client: WebSocket) => {
if (client !== ws && client.readyState === WebSocket.OPEN) {
client.send(params.req.params.id + ': ' + msg);
}
});
});
}
`Health checks
Each controller can define health checks that contribute to the overall health result returned by ,
/api/health/liveness and /api/health/readiness. This can be done via @livenessCheck() and @readinessCheck()
decorators. Each controller can have multiple checks of each type.$3
Liveness checks can be used for signaling that the service is alive or if it needs to be restarted.To signal that functionality is healthy, methods decorated with
can return true or
LivenessState.CORRECT. Liveness checks that throw an error, return false or return LivenessState.BROKEN will cause
the overall health check to indicate that the service is down.$3
Readiness checks can be used for signaling that the service is not only alive, but is ready to receive traffic.To signal that functionality is ready, methods decorated with
@readinessCheck() can return true or
ReadinessCheck.ACCEPTING_TRAFFIC. Readiness checks that throw an error, return false or return
ReadinessCheck.REFUSING_TRAFFIC will cause the overall health check to indicate that the service is out of service.$3
By default, /api/health/info will respond with basic information about the build, like commit ID, package name and
version, build time, etc. Custom data can be returned by this endpoint by adding controller methods decorated with
@appInfoProvider(). These methods can be asynchronous and should return an object representing key-value pairs to be
included in the response for /api/health/info`.