The HTTP server service

It is essential in most use cases, to expose certain functionality to clients.
A common way is a REST API.

PURISTA provides the @purista/httpserver package which contains the service HttpServerService, which spins up a http server.

The HttpServerService is a service which exposes commands of services as http endpoints. All exposed commands must be marked as exposed endpoints in the CommandBuilder.

While the main focus is on development and debug, the HttpServerService will also fit for small projects or running on IoT/edge.

Under the hood, fastify is used as basement. Because of this, the whole fastify ecosystem can be used and integrated.

The service itself, does not use the fastify router or schema validation for exposed commands.
There is one route ALL, which registers a handler with own router to be able to add and remove routes dynamically.

OpenAPI

The HttpServerService can also be configured, to provide the OpenApi-UI in browsers.
The OpenApi definitions is created from the CommandBuilder settings of each command.
This means, that there are no additional steps or code required, to provide the OpenApi definition.
It is autogenerated mostly from input and output schema definitions.

When running on local and with default configuration:

• the OpenAPI UI is available on http://localhost:9090/api
• the OpenAPI definition in JSON format on http://localhost:9090/api/openapi.json

You will see, that the descriptions for commands are used in the OpenAPI documentation.

Usage example

Currently, you must ensure, that the HttpServerService instance is started before all other services!

import fastifyStatic from '@fastify/static'
import { DefaultEventBridge, gracefulShutdown, initLogger } from '@purista/core'
import { httpServerV1Service, HttpServerServiceV1Config } from '@purista/httpserver'

const main = async() => {
  const logger = initLogger()

  const eventBridge = new DefaultEventBridge()

  const httpServerConfig: HttpServerServiceV1Config = {
    fastify: {},
    port: 8080,
    logLevel: 'debug',
    domain: 'localhost',
    apiMountPath: '/api',
    openApi: {
      enabled: true,
      info: {
        title: 'backend api',
        description: 'OpenApi definition for server endpoints',
        version: '1.0.0',
      },
    },
  }

  const httpServerService = httpServerV1Service.getInstance(eventBridge, {
    serviceConfig: httpServerConfig,
  })

  // optional: add a static file handler
  const defaultPublicPath = resolve(__dirname, '..', 'public')
  httpServerService.server?.register(fastifyStatic, {
    root: defaultPublicPath,
    decorateReply: false,
  })

  // start the webserver
  await httpServerService.start()

  // and and start your services here
  // ...
  // ...

  gracefulShutdown(logger, [
    // start with the event bridge to no longer accept incoming messages
    eventBridge,
    // shut down optional services
    // ...
    // ...
    httpServerService,
  ])
}

main()

Endpoints

The generated endpoints will be mounted below the apiMountPath which is set in the configuration.
Endpoints will automatically add the service version, like /api/v1/register for command register of a service with version 2.
This way, you can expose a versioned API.

The /healthz GET endpoint is a fixed route.

Configuration

• fastify: the Fastify configuration see fastify.io
• logLevel: info, error, warn, debug, trace, fatal
• port: the port on which the server should listen (default 9090)
• host: the host (default empty string),
• domain: the domain localhost,
• uploadDir: the directory where file uploads should get stored (default undefined),
• cookieSecret: (default undefined),
• apiMountPath: (default /api),
• enableHelmet: enable/disable helmet plugin (default true),
• enableHealthz: enable/disable health endpoint on /healthz (default true),
• helmetOptions: Options for helmet plugin see @fastify/helmet documentation (default undefined),
• enableCompress: enable/disable compression plugin (default true),
• compressOptions: Options for compression plugin see @fastify/compress documentation (default undefined),
• enableCors: enable/disable cors plugin (default false),
• corsOptions: Options for cors plugin see @fastify/cors documentation (default undefined),
• openApi: the OpenApi configuration
  • enabled: enable/disable OpenApi UI (default true),
  • path: the endpoint to be used for the OpenAPI UI (default /api),
  • info: OpenAPI documentation info:
    • title: the title of the documentation (default Server api),
    • description: the description of the documentation (default OpenApi definition for server endpoints),
    • version: the version of the documentation (default 1.0.0),
  • servers: Array of servers to be added to the OpenAPI documentation (default undefined),
  • components: (default undefined),
  • security: (default undefined),
  • externalDocs: (default undefined),
  • tags: (default undefined),