@znight/core 0.5.0 → 0.6.0

package/dist/index.d.mts

@@ -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
@@ -96,6 +96,16 @@ export declare const ErrorCode: {
   readonly MissingLockStore: "ZNIGHT043";
   /** A scheduled run was aborted (`ctx.signal.reason`, `JobAbortedError`); never thrown by the framework. */
   readonly JobAborted: "ZNIGHT044";
+  /**
+   * Invalid gateway: `@Gateway` options, lifecycle methods, events handled twice, reserved event
+   * names, parameters; at boot, invalid `WebSocketPlugin` options or `metadata.extensions.websocket`.
+   */
+  readonly 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.
+   */
+  readonly WebSocketTransportUnavailable: "ZNIGHT051";
   /** A TypeScript type cannot be mapped to a GraphQL type, or a resolver lacks the annotation it needs. */
   readonly InvalidGraphQLType: "ZNIGHT060";
   /** Two declarations or root fields share a GraphQL name, or a name is invalid or reserved. */
@@ -658,6 +668,13 @@ 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
@@ -729,6 +746,57 @@ interface MessageDeliveryEvent {
   outcome?: "ack" | "retry" | "dead-letter";
   error?: unknown;
 }
+/** Outcome of an inbound WebSocket message (`WebSocketMessageEvent.outcome`). */
+type WebSocketMessageOutcome = "ok" | "error" | "rejected" | "unhandled" | "timeout";
+/** Who closed a WebSocket connection (`WsCloseInfo.initiator` of `@znight/websocket`). */
+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.
+ */
+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). */
+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`). */
 type ScheduledRunTrigger = "schedule" | "start" | "manual" | "queued";
 /** Outcome of a scheduled run (`ScheduledRunEvent.outcome`). */
@@ -1309,5 +1377,5 @@ export declare class ZnightAggregateError extends ZnightError {
  * that were attached to it instead of being thrown. Empty when there are none.
  */
 export declare function getSuppressedErrors(error: unknown): readonly unknown[];
-export type { ApplicationOptions, ApplicationState, ClassKey, ClassMarker, ConsoleLike, ConsoleLoggerOptions, CoreLogger, EventListenerEvent, EventPublishEvent, EventPublishMode, GraphQLOperationError, GraphQLOperationEvent, GraphQLOperationOutcome, GraphQLOperationTransport, GraphQLOperationType, HookEvent, HookListener, HookName, HookWrapper, HooksOptions, HotContext, HttpRequestEvent, InitOptions, InjectableOptions, InterceptMethodOptions, InterceptOptionsArgs, InterceptorClass, InterceptorLink, LogContext, LogLevel, ManagedInstance, MessageDeliveryEvent, MessagePublishEvent, MethodInterceptor, MethodInvocation, MethodMarker, OnReady, OnStart, OnStop, OpenedScope, ParamContexts, ParamDataArgs, ParamDecorator, ParamFunctionOf, ParamResolver, ParamResolverClass, ParamResolverFunction, ParamResolverOf, ParamResolvers, ParameterMarker, Plugin, PluginContext, PluginHook, PluginOptions, PluginRootsContext, ProcessLike, ProviderKey, ProviderValues, ProvidesOptions, ScheduledRunAbortReason, ScheduledRunEvent, ScheduledRunOutcome, ScheduledRunTrigger, ScopeContext, ScopeValues, ShutdownOptions, ShutdownSignal, TypedToken, ZnightHooks };
+export type { ApplicationOptions, ApplicationState, ClassKey, ClassMarker, ConsoleLike, ConsoleLoggerOptions, CoreLogger, EventListenerEvent, EventPublishEvent, EventPublishMode, GraphQLOperationError, GraphQLOperationEvent, GraphQLOperationOutcome, GraphQLOperationTransport, GraphQLOperationType, HookEvent, HookListener, HookName, HookWrapper, HooksOptions, HotContext, HttpRequestEvent, InitOptions, InjectableOptions, InterceptMethodOptions, InterceptOptionsArgs, InterceptorClass, InterceptorLink, LogContext, LogLevel, ManagedInstance, MessageDeliveryEvent, MessagePublishEvent, MethodInterceptor, MethodInvocation, MethodMarker, OnReady, OnStart, OnStop, OpenedScope, ParamContexts, ParamDataArgs, ParamDecorator, ParamFunctionOf, ParamResolver, ParamResolverClass, ParamResolverFunction, ParamResolverOf, ParamResolvers, ParameterMarker, Plugin, PluginContext, PluginHook, PluginOptions, PluginRootsContext, ProcessLike, ProviderKey, ProviderValues, ProvidesOptions, ScheduledRunAbortReason, ScheduledRunEvent, ScheduledRunOutcome, ScheduledRunTrigger, ScopeContext, ScopeValues, ShutdownOptions, ShutdownSignal, TypedToken, WebSocketCloseInitiator, WebSocketConnectionEvent, WebSocketMessageEvent, WebSocketMessageOutcome, ZnightHooks };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -8,8 +8,8 @@ import { AsyncLocalStorage } from "node:async_hooks";
 * - `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
@@ -98,6 +98,16 @@ const ErrorCode = {
 	MissingLockStore: "ZNIGHT043",
 	/** A scheduled run was aborted (`ctx.signal.reason`, `JobAbortedError`); never thrown by the framework. */
 	JobAborted: "ZNIGHT044",
+	/**
+	* 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",
 	/** A TypeScript type cannot be mapped to a GraphQL type, or a resolver lacks the annotation it needs. */
 	InvalidGraphQLType: "ZNIGHT060",
 	/** Two declarations or root fields share a GraphQL name, or a name is invalid or reserved. */
@@ -179,6 +189,8 @@ const ERROR_DESCRIPTIONS = {
 	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",