raffel 0.2.3 → 1.0.0-next.f81d4db

package/dist/server/types.d.ts

@@ -20,9 +20,11 @@ import type { GraphQLOptions, GraphQLAdapter } from '../graphql/index.js';
 import type { MetricsConfig, MetricRegistry } from '../metrics/index.js';
 import type { TracingConfig, Tracer } from '../tracing/index.js';
 import type { Codec } from '../utils/content-codecs.js';
-import type { USDDocument, USDProtocol, USDTag, USDExternalDocs, USDServer, USDSecurityScheme } from '../usd/index.js';
+import type { USDDocument, USDProtocol, USDTag, USDTagGroup, USDExternalDocs, USDServer, USDSecurityScheme } from '../usd/index.js';
 import type { OpenAPIDocument } from '../usd/export/openapi.js';
 import type { SchemaRegistry } from '../validation/index.js';
+import type { EnvelopeConfig } from '../middleware/types.js';
+import type { SessionConfig } from '../middleware/session/types.js';
 /**
  * Provider factory function.
  * Called once at server startup to create the singleton instance.
@@ -74,6 +76,149 @@ export interface NormalizedError {
  * @param ctx - Request context (if available)
  */
 export type GlobalErrorHandler = (error: Error, protocol: ErrorProtocol, ctx?: Context) => void | Promise<void>;
+export type FrontDoorTransport = 'http' | 'websocket' | 'jsonrpc' | 'tcp' | 'udp' | 'grpc' | 'graphql' | 'rpc' | 'jrpc' | (string & {});
+export type SinglePortProtocolKind = 'http' | 'websocket' | 'jsonrpc' | 'tcp' | 'udp' | 'grpc' | 'graphql' | 'tls' | 'http2' | 'unknown' | (string & {});
+export type SinglePortDecisionReason = 'matched' | 'unsupported' | 'timeout' | 'limit_exceeded' | 'concurrency_limit' | 'unknown';
+export interface ProtocolDecisionPayload {
+    protocol: SinglePortProtocolKind;
+    detector: string;
+    reason: SinglePortDecisionReason;
+    elapsedMs: number;
+    bytesRead: number;
+    timedOut: boolean;
+}
+export interface ProtocolSnifferContext {
+    remoteAddress?: string;
+    remotePort?: number;
+    connectionId?: string;
+    protocol?: string;
+    bytesRead: number;
+}
+export interface ProtocolSniffer {
+    name: string;
+    detect(input: {
+        chunk: Buffer;
+        bytesRead: number;
+        context?: ProtocolSnifferContext;
+    }): SinglePortProtocolKind | null;
+}
+export type ProtocolAliasMode = 'standard' | 'extended';
+export interface SinglePortConfig {
+    /** Enable single-port transport fusion mode */
+    enabled?: boolean;
+    /** Alias for enabled */
+    protocolFusion?: boolean;
+    /** TLS key for HTTPS on single-port */
+    cert?: string | Buffer;
+    /** TLS certificate chain for single-port */
+    key?: string | Buffer;
+    /** Optional ALPN values to pass to TLS handshakes */
+    alpn?: string[];
+    /** Max bytes read before protocol fallback/timeout */
+    sniffMaxBytes?: number;
+    /** Max ms allowed per detection cycle */
+    sniffTimeoutMs?: number;
+    /** Max concurrent detections in progress */
+    maxConcurrentDetections?: number;
+    /** Custom protocol sniffers for shared TCP listener */
+    sniffers?: ProtocolSniffer[];
+    /** Optional protocol allowlist for single-port detection.
+     * If omitted, all default detectors are executed.
+     */
+    protocols?: SinglePortProtocolKind[];
+    /**
+     * Alias expansion mode for single-port protocol names.
+     * `standard` keeps built-in aliases minimal and strict.
+     * `extended` enables the full alias set (`icmp`, `whois`, `telnet`, etc.).
+     * If omitted, inherits from `protocolAliasMode` in `ServerOptions`.
+     */
+    protocolAliasMode?: ProtocolAliasMode;
+}
+export interface ProtocolPreviewConfig {
+    enabled: boolean;
+    shared?: boolean;
+    frontDoor?: boolean;
+    strategy?: FrontDoorStrategy;
+    path?: string;
+    host?: string;
+    port?: number;
+    source?: 'singlePort' | 'offload' | 'native' | 'custom' | 'unknown';
+}
+export interface ServerPresetOptions {
+    websocketPath?: string;
+    jsonrpcPath?: string;
+    graphqlPath?: string;
+}
+export type ServerPreset = 'api' | 'realtime' | 'rpc' | 'dev' | 'full';
+export interface ServerConfigPreview {
+    entrypoint: {
+        host: string;
+        port: number;
+        source: 'frontDoor' | 'native';
+    };
+    frontDoor: {
+        enabled: boolean;
+        host: string;
+        port: number;
+        protocols: FrontDoorTransport[] | null;
+        protocolAliasMode: ProtocolAliasMode;
+    };
+    singlePort: {
+        enabled: boolean;
+        protocolFusion: boolean;
+        protocolAliasMode: ProtocolAliasMode;
+        sniffMaxBytes: number;
+        sniffTimeoutMs: number;
+        maxConcurrentDetections: number;
+        protocols?: SinglePortProtocolKind[];
+    };
+    protocols: {
+        http: {
+            enabled: true;
+            shared: true;
+            source: 'singlePort' | 'offload' | 'native' | 'custom' | 'unknown';
+        };
+        websocket?: ProtocolPreviewConfig;
+        jsonrpc?: ProtocolPreviewConfig;
+        graphql?: ProtocolPreviewConfig;
+        tcp?: ProtocolPreviewConfig;
+        grpc?: ProtocolPreviewConfig;
+        streams?: {
+            enabled: boolean;
+        };
+    };
+    warnings: string[];
+}
+/**
+ * Strategy for how a protocol is handled by the server entrypoint.
+ */
+export type FrontDoorStrategy = 'shared' | 'native' | 'offload';
+/**
+ * Front-door configuration for single entrypoint composition.
+ */
+export interface FrontDoorConfig {
+    /** Enable unified front-door orchestration */
+    enabled: boolean;
+    /** Port for the front-door listener */
+    port?: number;
+    /** Host for the front-door listener */
+    host?: string;
+    /**
+     * Protocols allowed on the front-door.
+     * If omitted, HTTP + WebSocket + JSON-RPC + GraphQL are included by default.
+     * TCP/gRPC/UDP require explicit inclusion when front-door is enabled.
+     */
+    protocols?: FrontDoorTransport[];
+    /**
+     * Alias expansion mode for front-door protocol names.
+     * `standard` keeps built-in aliases minimal and strict.
+     * `extended` enables the full alias set (`icmp`, `whois`, `telnet`, etc.).
+     * If omitted, inherits from `protocolAliasMode` in `ServerOptions`.
+     */
+    protocolAliasMode?: ProtocolAliasMode;
+    /** Optional per-protocol strategy */
+    strategy?: Partial<Record<FrontDoorTransport, FrontDoorStrategy>>;
+}
 export interface ServerOptions {
     /** Port to listen on (HTTP) */
     port: number;
@@ -85,6 +230,18 @@ export interface ServerOptions {
     cors?: CorsOptions | boolean;
     /** HTTP adapter options */
     http?: HttpOptions;
+    /** Front-door entrypoint options */
+    frontDoor?: FrontDoorConfig;
+    /** Unified single-port transport options */
+    singlePort?: SinglePortConfig;
+    /**
+     * Global protocol alias expansion mode.
+     * `standard` keeps aliasing strict and predictable.
+     * `extended` enables more permissive alias resolution (`icmp`, `whois`, `telnet`, etc.).
+     *
+     * Defaults to `standard`.
+     */
+    protocolAliasMode?: ProtocolAliasMode;
     /**
      * WebSocket configuration.
      * - `true` enables with defaults (path: '/')
@@ -138,10 +295,33 @@ export interface ServerOptions {
      * ```
      */
     graphql?: GraphQLOptions | boolean;
+    /**
+     * gRPC configuration (requires a separate port).
+     */
+    grpc?: GrpcOptions;
     /**
      * Custom protocol adapters registered at startup.
      */
     protocolExtensions?: ProtocolExtensionConfig[];
+    /**
+     * Enable response envelope wrapper for all protocol responses.
+     * - `true` enables default Standard envelope config.
+     * - Object provides custom envelope settings.
+     *
+     * @example
+     * ```typescript
+     * createServer({
+     *   port: 3000,
+     *   envelope: true,
+     * })
+     *
+     * createServer({
+     *   port: 3000,
+     *   envelope: { includeDuration: true },
+     * })
+     * ```
+     */
+    envelope?: boolean | EnvelopeConfig;
     /**
      * Global middleware applied to all handlers.
      *
@@ -200,14 +380,14 @@ export interface ServerOptions {
      * @example
      * ```typescript
      * import { PrismaClient } from '@prisma/client'
-     * import { S3DB } from 's3db.js'
+     * import { Redis } from 'ioredis'
      *
      * const server = createServer({
      *   port: 3000,
      *   providers: {
      *     db: () => new PrismaClient(),
-     *     s3db: () => new S3DB({ bucket: 'my-bucket' }),
-     *     config: () => ({
+     *     cacheStore: () => new Redis(),
+      *     config: () => ({
      *       apiKey: process.env.API_KEY,
      *       environment: process.env.NODE_ENV,
      *     }),
@@ -221,6 +401,34 @@ export interface ServerOptions {
      * ```
      */
     providers?: ProvidersConfig;
+    /**
+     * Session store configuration.
+     * Injects `ctx.session` into every handler via the session interceptor.
+     *
+     * - `driver: 'memory'` — in-memory store (dev/single-instance)
+     * - `driver: 'custom'` — custom `SessionStore` instance (e.g. redis/session table adapter)
+     *
+     * Set to `false` to explicitly disable session support (default: disabled).
+     *
+     * @example
+     * ```typescript
+     * const server = createServer({
+     *   port: 3000,
+     *   session: {
+     *     driver: 'memory',
+     *     ttl: 3600,
+     *     cookie: { name: 'sid', secure: true },
+     *   },
+     * })
+     *
+     * server.procedure('auth.login').handler(async (input, ctx) => {
+     *   ctx.session.data.userId = input.userId
+     *   ctx.session.touch()
+     *   return { ok: true }
+     * })
+     * ```
+     */
+    session?: SessionConfig | false;
     /** Event delivery configuration (for at-least-once/at-most-once) */
     eventDelivery?: EventDeliveryOptions;
     /**
@@ -369,24 +577,29 @@ export interface AddressInfo {
 export type ProtocolAddress = AddressInfo & {
     path?: string;
     shared?: boolean;
+    source?: 'singlePort' | 'offload' | 'native' | 'custom' | 'unknown';
+};
+export type FrontDoorProtocolAddress = ProtocolAddress & {
+    frontDoor?: boolean;
+    strategy?: FrontDoorStrategy;
 };
 export interface ServerAddresses {
-    http: AddressInfo;
-    websocket?: AddressInfo & {
+    http: FrontDoorProtocolAddress;
+    websocket?: FrontDoorProtocolAddress & {
         path: string;
         shared: boolean;
     };
-    jsonrpc?: AddressInfo & {
+    jsonrpc?: FrontDoorProtocolAddress & {
         path: string;
         shared: boolean;
     };
-    graphql?: AddressInfo & {
+    graphql?: FrontDoorProtocolAddress & {
         path: string;
         shared: boolean;
     };
-    grpc?: AddressInfo;
-    tcp?: AddressInfo;
-    udp?: AddressInfo;
+    grpc?: FrontDoorProtocolAddress;
+    tcp?: FrontDoorProtocolAddress;
+    udp?: FrontDoorProtocolAddress;
     protocols?: Record<string, ProtocolAddress>;
 }
 /**
@@ -438,14 +651,6 @@ export interface HttpRouteOptions<TInput = unknown, TOutput = unknown> {
     /** Middleware interceptors */
     use?: Interceptor[];
 }
-/**
- * Helper type to infer input type from HttpRouteOptions
- */
-export type InferHttpInput<T> = T extends HttpRouteOptions<infer I, unknown> ? I : unknown;
-/**
- * Helper type to infer output type from HttpRouteOptions
- */
-export type InferHttpOutput<T> = T extends HttpRouteOptions<unknown, infer O> ? O : unknown;
 /**
  * HTTP protocol namespace for Hono-style routes.
  * Provides organized access to HTTP route registration methods with full type inference.
@@ -1073,6 +1278,49 @@ export interface UnifiedProtocolConfig {
     /** gRPC: requires proto path */
     grpc?: GrpcOptions;
 }
+/**
+ * Extended protocol configuration with per-protocol `enabled` toggle and UDP support.
+ * Used by `withProtocols()` for richer DX.
+ */
+export interface ExtendedProtocolConfig {
+    /** HTTP is enabled by default */
+    http?: boolean | {
+        enabled: boolean;
+    };
+    /** WebSocket: toggle + optional path/options */
+    websocket?: boolean | string | WebSocketOptions | ({
+        enabled: boolean;
+    } & Partial<WebSocketOptions>);
+    /** JSON-RPC: toggle + optional path/options */
+    jsonrpc?: boolean | string | JsonRpcOptions | ({
+        enabled: boolean;
+    } & Partial<JsonRpcOptions>);
+    /** SSE Streams: toggle + optional path */
+    streams?: boolean | string;
+    /** GraphQL: toggle + optional path/options */
+    graphql?: boolean | string | GraphQLOptions | ({
+        enabled: boolean;
+    } & Partial<GraphQLOptions>);
+    /** TCP: toggle + optional port/options (port required when enabled) */
+    tcp?: TcpOptions | ({
+        enabled: boolean;
+    } & Partial<TcpOptions>);
+    /** UDP: test-scope marker only, no production adapter */
+    udp?: boolean | {
+        enabled: boolean;
+    };
+    /** gRPC: toggle + optional options (protoPath required when enabled) */
+    grpc?: GrpcOptions | ({
+        enabled: boolean;
+    } & Partial<GrpcOptions>);
+}
+/**
+ * Environment profile for `withProfile()`.
+ * - `local`: development/mock mode with extended protocol aliases
+ * - `staging`: neutral defaults
+ * - `production`: production hardening with warnings for dev-only options
+ */
+export type ServerProfile = 'local' | 'staging' | 'production';
 export interface ProtocolAdapterContext {
     router: Router;
     registry: Registry;
@@ -1096,8 +1344,10 @@ export interface ProtocolExtensionConfig<TOptions = unknown> {
 }
 export interface RaffelServer {
     /**
+     * @deprecated Prefer {@link withProtocols} for extended protocol options and
+     * explicit disable support.
      * Enable multiple protocols with a single configuration object.
-     * This is the recommended way to configure protocols for multi-protocol servers.
+     * Legacy compatibility alias that maps to {@link withProtocols()}.
      *
      * @example
      * ```typescript
@@ -1110,6 +1360,55 @@ export interface RaffelServer {
      * ```
      */
     protocols(config: UnifiedProtocolConfig): this;
+    /**
+     * Enable multiple protocols with per-protocol `enabled` toggle, UDP marker, and eager
+     * conflict warnings logged via `logger.warn()`.
+     *
+     * @example
+     * ```typescript
+     * createServer({ port: 3000 })
+     *   .withProtocols({
+     *     websocket: { enabled: true, path: '/ws' },
+     *     tcp: { enabled: false },
+     *   })
+     * ```
+     */
+    withProtocols(config: ExtendedProtocolConfig): this;
+    /**
+     * Apply environment-specific server profile.
+     * - `local`: extended protocol aliases for mocks
+     * - `staging`: neutral defaults
+   * - `production`: production hardening + dev-option warnings
+     *
+     * @param profile - Target environment
+     * @param overrides - Optional protocol overrides applied after profile defaults
+     *
+     * @example
+     * ```typescript
+     * createServer({ port: 3000 })
+     *   .withProfile('production')
+     *   .withProtocols({ websocket: true })
+     *
+     * // With overrides
+     * createServer({ port: 3000 })
+     *   .withProfile('local', { protocols: { tcp: { port: 9000 } } })
+     * ```
+     */
+    withProfile(profile: ServerProfile, overrides?: {
+        protocols?: ExtendedProtocolConfig;
+    }): this;
+    /**
+     * Apply a common protocol preset to speed up setup.
+     * Presets:
+     * - api / dev / full: enable shared websocket + jsonrpc + graphql
+     * - realtime: enable websocket only
+     * - rpc: enable jsonrpc only
+     */
+    withPreset(preset: ServerPreset, options?: ServerPresetOptions): this;
+    /**
+     * Enable or disable single-port transport fusion after server creation.
+     */
+    enableSinglePort(config?: SinglePortConfig | boolean): this;
     /**
      * Register a custom protocol adapter to start with the server.
      */
@@ -1245,7 +1544,9 @@ export interface RaffelServer {
      * ```typescript
      * const server = createServer({ port: 3000 })
      *   .provide('db', () => new PrismaClient())
-     *   .provide('s3db', () => new S3DB({ bucket: 'my-bucket' }))
+     *   .provide('cacheStore', () => ({
+     *     host: process.env.CACHE_HOST,
+     *   }))
      *   .provide('config', () => ({ apiKey: process.env.API_KEY }))
      *
      * // In handlers:
@@ -1736,6 +2037,10 @@ export interface RaffelServer {
      * ```
      */
     readonly providers: ResolvedProviders;
+    /**
+     * Preview final protocol bootstrap decision graph without starting the server.
+     */
+    previewConfig(): ServerConfigPreview;
     /**
      * GraphQL adapter info.
      * Only available when `graphql` option is enabled.
@@ -1839,6 +2144,8 @@ export interface USDDocsConfig {
         primaryColor?: string;
         /** Logo URL */
         logo?: string;
+        /** Favicon URL */
+        favicon?: string;
         /** Enable "Try It Out" feature */
         tryItOut?: boolean;
         /** Code generation options */
@@ -1846,11 +2153,95 @@ export interface USDDocsConfig {
             enabled?: boolean;
             languages?: ('typescript' | 'python' | 'go' | 'curl')[];
         };
+        /** Hero section configuration (Docsify-style cover page) */
+        hero?: {
+            /** Override title from info.title */
+            title?: string;
+            /** Version badge */
+            version?: string;
+            /** Tagline/description */
+            tagline?: string;
+            /** Feature list */
+            features?: string[];
+            /** Background style */
+            background?: 'gradient' | 'solid' | 'pattern' | 'image';
+            /** Background image URL */
+            backgroundImage?: string;
+            /** Background color (for solid) */
+            backgroundColor?: string;
+            /** CTA buttons */
+            buttons?: Array<{
+                text: string;
+                href?: string;
+                primary?: boolean;
+            }>;
+            /** Quick links */
+            quickLinks?: Array<{
+                title: string;
+                description?: string;
+                href: string;
+                icon?: string;
+            }>;
+            /** GitHub URL (corner octocat) */
+            github?: string;
+        };
+        /** Sidebar configuration */
+        sidebar?: {
+            search?: boolean;
+            expandAll?: boolean;
+            showCounts?: boolean;
+        };
+    };
+    /** Documentation customization for USD spec (portable, included in x-usd) */
+    documentation?: {
+        /** Hero section configuration */
+        hero?: {
+            title?: string;
+            version?: string;
+            tagline?: string;
+            features?: string[];
+            background?: 'gradient' | 'solid' | 'pattern' | 'image';
+            backgroundImage?: string;
+            backgroundColor?: string;
+            buttons?: Array<{
+                text: string;
+                href?: string;
+                primary?: boolean;
+            }>;
+            quickLinks?: Array<{
+                title: string;
+                description?: string;
+                href: string;
+                icon?: string;
+            }>;
+            github?: string;
+        };
+        /** Introduction markdown (displayed after hero) */
+        introduction?: string;
+        /** Logo URL */
+        logo?: string;
+        /** Favicon URL */
+        favicon?: string;
+        /** External links */
+        externalLinks?: Array<{
+            title: string;
+            url: string;
+            description?: string;
+        }>;
     };
     /** Include standard error schemas */
     includeErrorSchemas?: boolean;
     /** Include stream event schemas */
     includeStreamEventSchemas?: boolean;
+    /** Global content types for documentation and content negotiation */
+    contentTypes?: {
+        /** Default content type */
+        default?: string;
+        /** Supported content types */
+        supported?: string[];
+    };
+    /** Tag groups for the documentation sidebar */
+    tagGroups?: USDTagGroup[];
     /** JSON-RPC generation options */
     jsonrpc?: {
         endpoint?: string;
@@ -1895,24 +2286,34 @@ export interface ProtocolConfig {
         enabled: boolean;
         options: WebSocketOptions;
         shared: boolean;
+        frontDoor?: boolean;
+        strategy?: FrontDoorStrategy;
     };
     jsonrpc?: {
         enabled: boolean;
         options: JsonRpcOptions;
         shared: boolean;
+        frontDoor?: boolean;
+        strategy?: FrontDoorStrategy;
     };
     graphql?: {
         enabled: boolean;
         options: GraphQLOptions;
         shared: boolean;
+        frontDoor?: boolean;
+        strategy?: FrontDoorStrategy;
     };
     tcp?: {
         enabled: boolean;
         options: TcpOptions;
+        frontDoor?: boolean;
+        strategy?: FrontDoorStrategy;
     };
     grpc?: {
         enabled: boolean;
         options: GrpcOptions;
+        frontDoor?: boolean;
+        strategy?: FrontDoorStrategy;
     };
 }
 export interface ActiveAdapters {