@loutrejs/loutre 0.9.2 → 0.10.0

package/dist/websocket/extension.d.ts

@@ -1,6 +1,10 @@
-import { type ExecutionDefinition, type ExecutionContextView, type ExecutionExtensionDrainContext, type RuntimeCapabilityBinding, type SchemaOutput, type StandardSchemaV1 } from '../core/index.js';
+import { type WebSocketSessionId, type WebSocketProcedureName, type NegotiatedSubprotocol } from './identity.js';
+import { type HttpPathTemplate, type HttpNormalizedPath } from '../http/identity.js';
+import type { ParsedHttpPath } from '../http/path.js';
+import type { Descriptor } from '../internal/brand.js';
+import { type ExecutionDefinition, type ExecutionContextView, type ExecutionExtensionDrainContext, type LayerState, type RuntimeCapabilityBinding, type SchemaOutput, type StandardSchemaV1 } from '../core/index.js';
 import type { HttpRequestHeadDefinition } from '../http/request-head.js';
-import { type HttpPathSegment } from '../http/index.js';
+import { type HttpRawRouteDefinition } from '../http/index.js';
 export type WebSocketDataMessage = {
     readonly type: 'text';
     readonly data: string;
@@ -29,8 +33,8 @@ export interface WebSocketUpgradeOptions {
     readonly protocol?: string;
 }
 export interface WebSocketSession {
-    readonly id: string;
-    readonly protocol: string;
+    readonly id: WebSocketSessionId;
+    readonly protocol: NegotiatedSubprotocol;
 }
 export interface WebSocketServerDriver {
     readonly runtime: string;
@@ -57,6 +61,7 @@ export interface WebSocketBranchDefinition {
 }
 export interface WebSocketHandshakeDefinition extends HttpRequestHeadDefinition {
     readonly protocols?: readonly string[];
+    readonly middlewares?: HttpRawRouteDefinition['middlewares'];
 }
 export interface WebSocketRouteDefinition {
     readonly path: string;
@@ -64,7 +69,7 @@ export interface WebSocketRouteDefinition {
     readonly messages?: WebSocketMessageCodec;
 }
 export type WebSocketRouteTree = Readonly<Record<string, WebSocketRouteDefinition | WebSocketBranchDefinition>>;
-export interface WebSocketContract<TRoutes extends WebSocketRouteTree = WebSocketRouteTree> {
+export interface WebSocketContract<TRoutes extends WebSocketRouteTree = WebSocketRouteTree> extends Descriptor<'websocket-contract'> {
     readonly kind: 'websocket-contract';
     readonly routes: TRoutes;
 }
@@ -95,6 +100,11 @@ type OpeningRequestInput<TRoute extends WebSocketRouteDefinition> = {
 };
 export type WebSocketHandlerContext<TRoute extends WebSocketRouteDefinition = WebSocketRouteDefinition> = {
     readonly request: Request;
+    readonly state: Readonly<TRoute extends {
+        readonly handshake: {
+            readonly middlewares: infer TLayers extends NonNullable<WebSocketHandshakeDefinition['middlewares']>;
+        };
+    } ? LayerState<TLayers> : {}>;
     readonly session: WebSocketSession;
     readonly protocol: string;
     readonly execution: ExecutionContextView;
@@ -116,10 +126,10 @@ export interface WebSocketImplementationDefinition<TContract extends WebSocketCo
     readonly factory: () => WebSocketHandlers<TContract>;
 }
 interface CompiledWebSocketRoute {
-    readonly name: string;
-    readonly path: string;
-    readonly normalizedPath: string;
-    readonly segments: readonly HttpPathSegment[];
+    readonly name: WebSocketProcedureName;
+    readonly path: HttpPathTemplate;
+    readonly normalizedPath: HttpNormalizedPath;
+    readonly segments: ParsedHttpPath;
     readonly handshake?: WebSocketHandshakeDefinition;
     readonly messages?: WebSocketMessageCodec;
 }

package/dist/websocket/extension.js

@@ -1,4 +1,8 @@
-import { collectInjectedDependencies, defineExecution, defineExecutionExtension, runtimeCapability, runInInjectionContext, validateSchema, } from '../core/index.js';
+import { dependencyConsumerId } from '../core/identity.js';
+import { milliseconds } from '../core/units.js';
+import { createWebSocketSessionId, webSocketProcedureName, negotiatedSubprotocol, observedCloseCode, } from './identity.js';
+import { requestPathname, } from '../http/identity.js';
+import { collectInjectedDependencies, getSourceLocation, composeLayers, defineExecution, defineExecutionExtension, runtimeCapability, runInInjectionContext, validateSchema, } from '../core/index.js';
 import { IngressGate } from '../runtime/ingress-gate.js';
 import { WebSocketConnectionNotOpenError, WebSocketMessageDecodeError, WebSocketMessageEncodeError, } from './errors.js';
 import { compareHttpPathSpecificity, HttpPathDecodeError, matchHttpPath, normalizeHttpPath, parseHttpPath, } from '../http/index.js';
@@ -8,20 +12,37 @@ export const websocketExtension = defineExecutionExtension({
     abiVersion: '2',
     name: 'loutre:websocket',
     compile(definition, context) {
+        const id = definition.name ||
+            `${context.moduleId}.websocket.${context.definitionIndex}`;
+        const routes = compileRouteTree(definition.contract.routes);
+        const dependencies = new Set(collectInjectedDependencies({
+            kind: 'execution',
+            id: dependencyConsumerId(`websocket:${id}`),
+            name: id,
+        }, () => definition.factory()));
+        for (const route of routes) {
+            route.handshake?.middlewares?.forEach((middleware, index) => {
+                for (const dependency of collectInjectedDependencies({
+                    kind: 'layer',
+                    id: dependencyConsumerId(`websocket:${id}:${route.name}:${index}`),
+                    name: middleware.name,
+                }, () => middleware.factory()))
+                    dependencies.add(dependency);
+            });
+        }
         return {
             kind: 'execution',
-            id: definition.name ||
-                `${context.moduleId}.websocket.${context.definitionIndex}`,
+            id,
             executionKind: 'websocket.session',
-            dependencies: collectInjectedDependencies({
-                kind: 'execution',
-                id: `websocket:${definition.name || `${context.moduleId}.websocket.${context.definitionIndex}`}`,
-                name: definition.name ||
-                    `${context.moduleId}.websocket.${context.definitionIndex}`,
-            }, () => definition.factory()),
-            capabilities: [WEBSOCKET_SERVER],
+            dependencies: [...dependencies],
+            capabilities: [
+                ...new Set([
+                    WEBSOCKET_SERVER,
+                    ...routes.flatMap((route) => route.handshake?.middlewares?.flatMap((middleware) => middleware.capabilities) ?? []),
+                ]),
+            ],
             compiled: Object.freeze({
-                routes: Object.freeze(compileRouteTree(definition.contract.routes)),
+                routes: Object.freeze(routes),
                 factory: definition.factory,
             }),
         };
@@ -50,6 +71,17 @@ export const websocketExtension = defineExecutionExtension({
         routes: execution.compiled.routes.map((route) => ({
             name: route.name,
             path: route.path,
+            ...(route.handshake?.middlewares?.length
+                ? {
+                    middlewares: route.handshake.middlewares.map((middleware) => ({
+                        name: middleware.name,
+                        capabilities: middleware.capabilities.map((capability) => capability.id),
+                        ...(getSourceLocation(middleware) === undefined
+                            ? {}
+                            : { source: getSourceLocation(middleware) }),
+                    })),
+                }
+                : {}),
             ...(route.messages === undefined
                 ? {}
                 : {
@@ -69,7 +101,10 @@ export const websocketExtension = defineExecutionExtension({
     },
 });
 export function defineWebSocketContract(routes) {
-    return Object.freeze({ kind: 'websocket-contract', routes });
+    return Object.freeze({
+        kind: 'websocket-contract',
+        routes,
+    });
 }
 export function defineWebSocketImplementation(definition) {
     return defineExecution(websocketExtension, {
@@ -104,7 +139,7 @@ export const websocket = Object.freeze({
 function compileRouteTree(tree, parentPath = '', prefix = '', routeNames = new Set()) {
     return Object.entries(tree).flatMap(([name, node]) => {
         if ('request' in node || 'responses' in node)
-            throw new TypeError('WebSocket v2ではhandshakeを使用してください。');
+            throw new TypeError('Use handshake for WebSocket v2 routes.');
         if (isBranch(node)) {
             const branchPath = node.path ?? '';
             if (branchPath !== '')
@@ -115,14 +150,14 @@ function compileRouteTree(tree, parentPath = '', prefix = '', routeNames = new S
         const path = joinPath(parentPath, node.path);
         const segments = parseHttpPath(path);
         assertExactPathParams(path, segments, node.handshake?.params);
-        const routeName = prefix ? `${prefix}.${name}` : name;
+        const routeName = webSocketProcedureName(prefix ? `${prefix}.${name}` : name);
         if (routeNames.has(routeName))
             throw new TypeError(`Duplicate nested WebSocket route name: ${routeName}`);
         routeNames.add(routeName);
         return [
             Object.freeze({
                 name: routeName,
-                path,
+                path: path,
                 normalizedPath: normalizeHttpPath(segments),
                 segments,
                 ...(node.handshake === undefined
@@ -150,6 +185,9 @@ function assertExactPathParams(path, segments, params) {
 function snapshotHandshake(handshake) {
     return Object.freeze({
         ...handshake,
+        ...(handshake.middlewares === undefined
+            ? {}
+            : { middlewares: Object.freeze([...handshake.middlewares]) }),
         ...(handshake.params === undefined
             ? {}
             : { params: Object.freeze({ ...handshake.params }) }),
@@ -179,15 +217,16 @@ function createWebSocketRuntime(bindings, driver, applicationRuntime) {
         handlers.set(execution.id, runInInjectionContext({
             consumer: {
                 kind: 'execution',
-                id: `websocket:${execution.id}`,
+                id: dependencyConsumerId(`websocket:${execution.id}`),
                 name: execution.id,
             },
             resolve: (token, consumer) => resolve(token, { consumer }),
         }, () => execution.compiled.factory()));
     }
     const routes = bindings
-        .flatMap(({ execution }) => execution.compiled.routes.map((route) => ({
+        .flatMap(({ execution, resolve }) => execution.compiled.routes.map((route) => ({
         executionId: execution.id,
+        resolve,
         route,
     })))
         .toSorted((left, right) => compareHttpPathSpecificity(left.route.segments, right.route.segments));
@@ -196,6 +235,12 @@ function createWebSocketRuntime(bindings, driver, applicationRuntime) {
             if (state !== 'running') {
                 return Response.json({ error: 'Service Unavailable' }, { status: 503 });
             }
+            if (request.method !== 'GET') {
+                return new Response('WebSocket handshake requires GET.', {
+                    status: 405,
+                    headers: { allow: 'GET' },
+                });
+            }
             let match;
             try {
                 match = findRoute(routes, request);
@@ -225,7 +270,7 @@ function createWebSocketRuntime(bindings, driver, applicationRuntime) {
                 .filter(Boolean);
             const protocol = match.route.handshake?.protocols?.find((value) => offered.includes(value));
             if (match.route.handshake?.protocols?.length && protocol === undefined) {
-                return new Response('WebSocket subprotocolが一致しません。', {
+                return new Response('WebSocket subprotocol mismatch.', {
                     status: 400,
                 });
             }
@@ -247,16 +292,42 @@ function createWebSocketRuntime(bindings, driver, applicationRuntime) {
                 throw error;
             }
             let upgraded;
+            let handshakeState = {};
+            const signal = AbortSignal.any([request.signal, lease.signal]);
             try {
-                upgraded = await driver.upgrade(request, protocol === undefined ? {} : { protocol });
+                const dispatch = () => composeLayers({
+                    context: { request, input: { ...input, body: undefined }, signal },
+                    layers: match.route.handshake?.middlewares ?? [],
+                    resolve: match.resolve,
+                    terminal: async ({ state: middlewareState }) => {
+                        signal.throwIfAborted();
+                        handshakeState = middlewareState;
+                        upgraded = await driver.upgrade(request, protocol === undefined ? {} : { protocol });
+                        return upgraded.response;
+                    },
+                });
+                const response = await (lease.run ? lease.run(dispatch) : dispatch());
+                if (!(response instanceof Response))
+                    throw new TypeError('WebSocket handshake middleware must return a Response.');
+                signal.throwIfAborted();
+                if (!upgraded) {
+                    lease.complete();
+                    completePendingIngress();
+                    return response;
+                }
             }
             catch (error) {
-                lease.fail?.(error);
-                lease.complete();
-                completePendingIngress();
+                try {
+                    await upgraded?.connection.terminate();
+                }
+                finally {
+                    lease.fail?.(error);
+                    lease.complete();
+                    completePendingIngress();
+                }
                 throw error;
             }
-            const session = createSession(upgraded.connection, request, applicationRuntime, match.route, input, lease, handlers.get(match.executionId)?.[match.route.name], lease.run);
+            const session = createSession(upgraded.connection, request, applicationRuntime, match.route, input, handshakeState, lease, handlers.get(match.executionId)?.[match.route.name], lease.run);
             sessions.add(session.active);
             void session.completion.then(() => sessions.delete(session.active), () => sessions.delete(session.active));
             completePendingIngress();
@@ -306,10 +377,11 @@ function createWebSocketRuntime(bindings, driver, applicationRuntime) {
 function findRoute(routes, request) {
     const url = new URL(request.url);
     for (const candidate of routes) {
-        const params = matchHttpPath(candidate.route.segments, url.pathname);
+        const params = matchHttpPath(candidate.route.segments, requestPathname(url.pathname));
         if (params) {
             return {
                 executionId: candidate.executionId,
+                resolve: candidate.resolve,
                 route: candidate.route,
                 params,
             };
@@ -347,10 +419,10 @@ function decodeQuery(searchParams) {
     }
     return query;
 }
-function createSession(connection, request, applicationRuntime, route, input, lease, handler, runInExecution) {
+function createSession(connection, request, applicationRuntime, route, input, handshakeState, lease, handler, runInExecution) {
     const session = Object.freeze({
-        id: `ws_${crypto.randomUUID()}`,
-        protocol: connection.protocol,
+        id: createWebSocketSessionId(),
+        protocol: negotiatedSubprotocol(connection.protocol),
     });
     lease.annotate?.({
         'websocket.session.id': session.id,
@@ -408,6 +480,7 @@ function createSession(connection, request, applicationRuntime, route, input, le
     const messages = decodeMessages(connection.messages, route.messages);
     const context = {
         request,
+        state: handshakeState,
         session,
         protocol: session.protocol,
         execution: {
@@ -537,13 +610,13 @@ async function encodeMessage(codec, value) {
 }
 function normalizeCloseInfo(info) {
     return {
-        code: Number.isInteger(info.code) ? info.code : 1006,
+        code: observedCloseCode(Number.isInteger(info.code) ? info.code : 1006),
         reason: info.reason ?? '',
         wasClean: info.wasClean === true,
     };
 }
 function webSocketGracefulShutdownBudget(timeoutMs) {
     if (timeoutMs <= 0)
-        return 0;
-    return Math.min(5_000, Math.max(0, Math.floor(timeoutMs * 0.8)));
+        return milliseconds(0);
+    return milliseconds(Math.min(5_000, Math.max(0, Math.floor(timeoutMs * 0.8))));
 }

package/dist/websocket/identity.d.ts

@@ -0,0 +1,9 @@
+import type { Brand } from '../internal/brand.js';
+export type WebSocketSessionId = Brand<string, 'websocket.session-id'>;
+export type WebSocketProcedureName = Brand<string, 'websocket.procedure'>;
+export type NegotiatedSubprotocol = Brand<string, 'websocket.negotiated-subprotocol'>;
+export type ObservedCloseCode = Brand<number, 'websocket.observed-close-code'>;
+export declare const createWebSocketSessionId: () => WebSocketSessionId;
+export declare const webSocketProcedureName: (value: string) => WebSocketProcedureName;
+export declare const negotiatedSubprotocol: (value: string) => NegotiatedSubprotocol;
+export declare const observedCloseCode: (value: number) => ObservedCloseCode;

package/dist/websocket/identity.js

@@ -0,0 +1,4 @@
+export const createWebSocketSessionId = () => `ws_${crypto.randomUUID()}`;
+export const webSocketProcedureName = (value) => value;
+export const negotiatedSubprotocol = (value) => value;
+export const observedCloseCode = (value) => value;

package/dist/websocket/index.d.ts

@@ -3,3 +3,4 @@ export { WebSocketConnectionNotOpenError, WebSocketMessageDecodeError, WebSocket
 export type { WebSocketBranchDefinition, WebSocketHandshakeDefinition, WebSocketSession, WebSocketUpgradeOptions, WebSocketCloseInfo, WebSocketCodecKind, WebSocketConnectionDriver, WebSocketContract, WebSocketDataMessage, WebSocketExecutionDefinition, WebSocketExtensionRuntime, WebSocketHandlerContext, WebSocketHandlers, WebSocketHostApi, WebSocketImplementationDefinition, WebSocketIncomingMessage, WebSocketMessageCodec, WebSocketRouteDefinition, WebSocketRouteTree, WebSocketServerDriver, WebSocketUpgradeResult, } from './extension.js';
 export { createEventWebSocketConnection, createWebSocketDriverChannel, } from './driver.js';
 export type { EventWebSocket, WebSocketDriverChannel } from './driver.js';
+export type { WebSocketSessionId, WebSocketProcedureName, NegotiatedSubprotocol, ObservedCloseCode, } from './identity.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loutrejs/loutre",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "license": "MIT",
   "type": "module",
   "files": [