@znight/core 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@znight/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Znight core runtime: compile-time DI container, lifecycle, plugins and marker decorators",
   "license": "MIT",
   "author": "Ugho STEPHAN",

package/src/errors.ts

@@ -6,8 +6,8 @@
  * - `ZNIGHT001`–`ZNIGHT029`: the core, the compiler and the features shipped in 0.1 (http,
  *   messaging, config, observability).
  * - From `ZNIGHT030`, each first-party package reserves a block of ten: `ZNIGHT030`–`039`
- *   `@znight/openapi`, `ZNIGHT040`–`049` `@znight/schedule`, `ZNIGHT050`–`059` `@znight/websocket`
- *   (reserved), `ZNIGHT060`–`069` `@znight/graphql`, `ZNIGHT070`–`079` `@znight/events`.
+ *   `@znight/openapi`, `ZNIGHT040`–`049` `@znight/schedule`, `ZNIGHT050`–`059` `@znight/websocket`,
+ *   `ZNIGHT060`–`069` `@znight/graphql`, `ZNIGHT070`–`079` `@znight/events`.
  *
  * Within a range, codes are allocated in order without gaps. A package uses its block for its own
  * failure modes, with one catch-all code for invalid usage and options, and reuses a lower code
@@ -101,6 +101,18 @@ export const ErrorCode = {
   /** A scheduled run was aborted (`ctx.signal.reason`, `JobAbortedError`); never thrown by the framework. */
   JobAborted: 'ZNIGHT044',
 
+  // ZNIGHT050–059: @znight/websocket (RFC 0003)
+  /**
+   * Invalid gateway: `@Gateway` options, lifecycle methods, events handled twice, reserved event
+   * names, parameters; at boot, invalid `WebSocketPlugin` options or `metadata.extensions.websocket`.
+   */
+  InvalidGateway: 'ZNIGHT050',
+  /**
+   * Gateways cannot be served: no `HttpPlugin`, an adapter without upgrade support, `ws` missing on
+   * Node.js, a transport that does not match the server.
+   */
+  WebSocketTransportUnavailable: 'ZNIGHT051',
+
   // ZNIGHT060–069: @znight/graphql (RFC 0005, RFC 0007)
   /** A TypeScript type cannot be mapped to a GraphQL type, or a resolver lacks the annotation it needs. */
   InvalidGraphQLType: 'ZNIGHT060',
@@ -188,6 +200,8 @@ export const ERROR_DESCRIPTIONS: Readonly<Record<ErrorCode, string>> = {
   ZNIGHT042: 'Unknown job: no job has this name',
   ZNIGHT043: 'Missing lock store: a job requires a lock but SchedulePlugin has no store',
   ZNIGHT044: 'Job aborted: a scheduled run was aborted (timeout, lost lock, removal or shutdown)',
+  ZNIGHT050: 'Invalid gateway: a WebSocket gateway, its handlers or the WebSocketPlugin options are invalid',
+  ZNIGHT051: 'WebSocket transport unavailable: gateways cannot be served by the HTTP server',
   ZNIGHT060: 'Invalid GraphQL type: a TypeScript type cannot be mapped to a GraphQL type',
   ZNIGHT061: 'GraphQL name conflict: two types or root fields share a name, or a name is invalid or reserved',
   ZNIGHT062: 'Invalid resolver: the structure of a GraphQL resolver is invalid',

package/src/hooks.ts

@@ -33,6 +33,13 @@ export interface ZnightHooks {
    * emitted when listeners exist.
    */
   'graphql:operation': GraphQLOperationEvent
+  /**
+   * One inbound WebSocket message handled by `@znight/websocket` (RFC 0003): wrapped with
+   * `hooks.run` when wrappers exist, then emitted when listeners exist. `$ping` frames do not run it.
+   */
+  'websocket:message': WebSocketMessageEvent
+  /** A WebSocket connection of `@znight/websocket` opened or closed (emitted only). */
+  'websocket:connection': WebSocketConnectionEvent
   /**
    * One publication of `@znight/events` (`EventPublisher.publish()` or `emit()`) that matched at least
    * one listener (RFC 0011): wraps the inline phase with `hooks.run` when wrappers exist, then is
@@ -108,6 +115,61 @@ export interface MessageDeliveryEvent {
   error?: unknown
 }
 
+/** Outcome of an inbound WebSocket message (`WebSocketMessageEvent.outcome`). */
+export type WebSocketMessageOutcome = 'ok' | 'error' | 'rejected' | 'unhandled' | 'timeout'
+
+/** Who closed a WebSocket connection (`WsCloseInfo.initiator` of `@znight/websocket`). */
+export type WebSocketCloseInitiator = 'client' | 'server' | 'shutdown' | 'heartbeat' | 'backpressure' | 'error'
+
+/**
+ * Instrumentation event of the `websocket:message` hook (RFC 0003 §8.10), one per inbound message
+ * of a gateway. `outcome` and `error` are set before `hooks.run` resolves.
+ */
+export interface WebSocketMessageEvent {
+  /** Display name of the gateway class. */
+  readonly gateway: string
+  /** Gateway path pattern, HTTP prefix included (`/api/chat`). */
+  readonly path: string
+  /** Event name (`events` gateways); `undefined` on `raw` gateways or for an undecodable frame. */
+  readonly event: string | undefined
+  /** Handler method; `undefined` when no handler matched. */
+  readonly handler: string | undefined
+  readonly connectionId: string
+  /** The request id of the handshake. */
+  readonly requestId: string
+  /** Size of the frame, in bytes (characters for a text frame). */
+  readonly bytes: number
+  /** `WsMessageContext` from `@znight/websocket`. */
+  readonly context: unknown
+  /** `performance.now()` when the message was dispatched. */
+  readonly startTime: number
+  outcome?: WebSocketMessageOutcome
+  error?: unknown
+}
+
+/** Instrumentation event of the `websocket:connection` hook (RFC 0003 §8.10). */
+export interface WebSocketConnectionEvent {
+  readonly type: 'open' | 'close'
+  /** Display name of the gateway class. */
+  readonly gateway: string
+  /** Gateway path pattern, HTTP prefix included. */
+  readonly path: string
+  readonly connectionId: string
+  /** The request id of the handshake. */
+  readonly requestId: string
+  /** `WsConnection` from `@znight/websocket`. */
+  readonly connection: unknown
+  /** `performance.now()` when the connection opened. */
+  readonly openedAt: number
+  /** Close code (`close` events). */
+  readonly code?: number
+  readonly reason?: string
+  readonly initiator?: WebSocketCloseInitiator
+  /** Messages received and sent by the connection (`close` events). */
+  readonly messagesIn?: number
+  readonly messagesOut?: number
+}
+
 /** How a scheduled run was triggered (`ScheduledRunEvent.trigger`). */
 export type ScheduledRunTrigger = 'schedule' | 'start' | 'manual' | 'queued'
 

package/src/index.ts

@@ -59,6 +59,10 @@ export {
   type ScheduledRunEvent,
   type ScheduledRunOutcome,
   type ScheduledRunTrigger,
+  type WebSocketCloseInitiator,
+  type WebSocketConnectionEvent,
+  type WebSocketMessageEvent,
+  type WebSocketMessageOutcome,
   type ZnightHooks,
 } from './hooks.ts'
 export {