apigenie-generator server ws

Tier 2 · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · Verification

Generate a TypeScript (Node.js) server of the WebSocket channels of an AsyncAPI document.

Usage

apigenie-generator server ws [...OPTIONS] INPUT_FILE

Description

The input must be an AsyncAPI 3.x document. Documents referencing other files are bundled first.

The server serves the WebSocket channels of the document (see apigenie-generator client ws) at their addresses, using the ws package. By default it implements the application the document describes: it sends the messages of send operations and receives the messages of receive operations. Set the perspective option to counterpart to swap them.

import { createServer } from "chat-api-server";

const server = createServer({
  room: {
    onConnect(session) {
      console.log(`joined ${session.params.roomId}`);
    },
    onJoin(session, payload) {
      session.sendRoomEvent({ kind: "joined", user: payload.user });
    },
  },
});
await server.listen(8080);

For every channel, the generated code has:

  • a session class (RoomSession): a connection of a client, with the values of the address parameters (params), the query parameters converted to the types of the WebSocket binding (query), the handshake headers, the headers of the WebSocket binding typed by its schema (bindingHeaders), what the authenticator returned (principal, see below), send<Message>(payload) methods and close(). The reply messages of an operation whose reply is on the same channel get send<Message> methods too, and, when the request and reply messages have a correlation id in their payloads, replyTo<Operation>(request, reply) sends the reply with the request’s correlation id copied into it (e.g. session.replyToRequestPickup(request, confirmation)).
  • a handler interface (RoomHandler) with onConnect, on<Message> for every message the server receives (when the channel receives one message, or when its messages can be told apart by a property with a distinct constant value), onMessage for every message of a channel receiving several, onUnknownMessage, onClose and onError

The handlers of a session are called one at a time, in the order of the events; a handler returning a promise delays the next one until it settles. Errors thrown by handlers are passed to onError.

createServer(handlers, options) serves the channels with handlers. Connections to other addresses are rejected with status 404, and handshakes without a header that the headers schema of the channel’s WebSocket binding requires with status 400. Options are an existing HTTP server to attach to (server), a path prefix of all addresses (basePath), the authenticators of the security schemes (authenticate) and onAuthenticationError(error, request), called when an authenticator throws or an authenticated connection can’t be accepted (by default, console.error). The result has listen(port, host), close(), address() and httpServer.

Security

A channel takes the security schemes of its operations, or of its servers for an operation without any. When a channel has some, the authenticate option is required: an Authenticators object with a function per scheme, called with the credential that the handshake carries and a context with the scheme key, the scheme, its scopes, the HTTP request and the address parameters. The connection is accepted when the authenticator of one of the channel’s schemes returns a value other than false, null or undefined; that value becomes session.principal. Otherwise the handshake is refused with status 401. When the authenticator throws or rejects, the handshake is refused with status 500 and the error goes to onAuthenticationError.

const server = createServer(handlers, {
  authenticate: {
    streamToken: (token) => tokens.verify(token), // the merchant, or undefined
    oauth2: async (token, { scopes }) => introspect(token, scopes),
  },
});

The credential is read from the handshake by the type of the scheme:

Scheme Credential
httpApiKey the query parameter, header or cookie named by name and in
http with scheme basic user:password of the Authorization header
http with scheme bearer, oauth2, openIdConnect the bearer token of the Authorization header, or of the access_token query parameter

The authenticator checks the scopes; the server doesn’t. Other scheme types, such as userPassword, X509 or the SASL schemes, can’t be sent with a WebSocket handshake: they are left out with a warning.

The generated package contains src/types.ts, src/messages.ts, src/server.ts, src/metadata.ts, src/runtime.ts and src/index.ts, with package.json (depending on ws) and tsconfig.json.

Not supported, and reported as warnings: replies on another channel or at a runtime-expression address, channels without an address, and channels sharing an address with another channel (only the first one is served), and security schemes that a WebSocket handshake can’t carry.

Extensions

Extension Effect
x-apigenie.codegen.name on a channel: the base of its names (LobbyHandler); on a message: the base of its types (PostPayload); on a component schema: the name of its type
x-apigenie.codegen.disabled true on a channel or an operation leaves it out (with the operations of a channel left out)

The extensions can live in an overlay for this target instead of in the document, e.g. ws.overlay.yaml:

overlay: 1.0.0
info:
  title: WebSocket names
  version: 1.0.0
actions:
  - target: $.channels.room
    update:
      x-apigenie:
        codegen:
          name: Lobby
  - target: $.components.messages.ChatMessage
    update:
      x-apigenie:
        codegen:
          name: Post
apigenie-generator server ws asyncapi.yaml --overlay ws.overlay.yaml -o out

Options

-c, –config

Path to the configuration file to use. See the “Configuration” section for more information.

–overlay OVERLAY

Path to an OpenAPI Overlay (1.0 to 1.2) applied to the input before generating, e.g. one setting the extensions of the “Extensions” section. Can be repeated: the overlays apply in order, after those listed under commands.generate.server_ws.overlay in the configuration file (with paths relative to it). Warnings and errors about a value an overlay set point to the overlay. The overlays apply to the AsyncAPI document bundled with the files it references.

–strict

Makes an overlay action whose target selects nothing an error (exit status 2, nothing is generated) instead of a warning (OVERLAY:LINE:COL: action #N (TARGET) selects no nodes.).

–check

Writes nothing: compares what the generator would write with the output directory, prints the files that would be created or changed, and exits with 1 when there are any (since 0.12.0). See Check that generated code is up to date.

-o, –output

Directory where the package is generated.

–package-name

Name of the generated package. Defaults to the title of the API followed by -server.

–package-version

Version of the generated package. Defaults to the version of the API.

Configuration

version: '1.0'
commands:
  generate:
    server_ws:
      layout: package
      import_extension: .js
      perspective: application
Option Description
layout package (default): an npm package with sources in src/; sources: the sources only
import_extension Extension of relative imports: .js (default, Node.js) or an empty string (bundlers)
perspective application (default): the described application; counterpart: its client

Verification

The codegen conformance suite runs this target on the Carpet Express AsyncAPI fixture. Level 1 compares the output with its snapshots and checks each feature, Level 2 runs the language's type checker and linter, and Level 3 runs the generated code in contract tests against the fixture. All targets.

This target's support tier is Tier 2. It goes through all three levels before every release, like Tier 1. It doesn't aim to support every feature: a feature of the fixture can stay unsupported, with the reason its manifest gives.

ResultsLevel 1Level 2Level 3
Release 0.12.0✓ snapshots of 3.0; 30 supported, 0 not yet✓ pass (Version 6.0.3, ESLint 10 + typescript-eslint 8)✓ 4 of 4 operations pass (node)
Development version✓ snapshots of 3.0; 30 supported, 0 not yetruns before a releaseruns before a release
Was this helpful?