WebSocketControllerBase

class WebSocketControllerBase<T extends WebSocketDescriptor = WebSocketDescriptor> extends FlareBase

Base class for a class-form WebSocket endpoint. Override any of open, message, close, error; act on the connection through this.socket, resolve dependencies with this.inject, and keep durable per-connection state in this.socket.state (never raw instance fields, which a hibernation wake discards).

How you get one

new WebSocketControllerBase(container, socket, input)

Constructor

new WebSocketControllerBase(container: Container, socket: FlareWebSocketContext<WebSocketOutgoing<T>>, input: WebSocketInput<T>): WebSocketControllerBase<T>

container Container

socket FlareWebSocketContext<WebSocketOutgoing<T>> · The live connection (the ws the function form receives): send/close/state over the socket.

input WebSocketInput<T> · Connect-time typed input: the upgrade path params and query (stable for the connection's life).

Properties

config

config: readonly ConfigToken<unknown>[]

Declares the config tokens this class requires.

Parallel to static deps. When declared, this.config(token) validates that the token is in this array before resolving, identical to how this.inject(token) validates static deps.

contract

contract: WebSocketToken

The route’s socketContract entry (validates messages + upgrade input), like HTTP’s controller static contract.

deps

deps: ServiceToken<FlareService>[]

DI allow-list; overrides FlareBase.deps.

input

input: WebSocketInput<T>

Connect-time typed input: the upgrade path params and query (stable for the connection’s life).

socket

socket: FlareWebSocketContext<WebSocketOutgoing<T>>

The live connection (the ws the function form receives): send/close/state over the socket.

state

state: StateToken[]

State tokens this endpoint’s this.socket.state uses (build-validated).

Methods

close()

close(code: number, reason: string, wasClean: boolean): void | Promise<void>

Runs at the terminal close. wasClean is true when both sides completed the closing handshake.

code number

reason string

wasClean boolean

returns void | Promise<void>

config()

config<T>(token: ConfigToken<T>): T

Resolves a typed config section by token.

Mirrors inject() + static deps: the class must declare a static config array, and the requested token must appear in it. Both checks throw a developer-facing error when violated.

token ConfigToken<T>

returns T

Example:

class DbService extends FlareService {
  static config = [DbConfig];

  async onStart() {
    const { url } = this.config(DbConfig);
  }
}

Throws:

When the class has no static config declaration.

Throws:

When the token is not present in static config.

error()

error(err: Error): void

Runs on a transport or protocol error; a terminal close still follows.

err Error

inject()

inject<T extends FlareService>(token: ServiceToken<T>): Injected<T>

Resolves a dependency declared on static deps, returning the service with framework members hidden from its static type.

token ServiceToken<T>

returns Injected<T>

Throws:

When the token is not present in this class’s static deps array.

message()

message(message: WebSocketIncoming<T>): void | Promise<void>

Runs for each inbound message (validated + typed from contract.incoming); async => backpressure.

message WebSocketIncoming<T>

returns void | Promise<void>

open()

open(): void | Promise<void>

Runs once when the connection reaches OPEN; may be async (inbound messages wait for it).

returns void | Promise<void>

Learn: Controller classes