@grest-ts/http 0.0.23 → 0.0.25

package/src/client/GGHttpSchema.createClient.ts

@@ -9,10 +9,40 @@ declare module "../schema/GGHttpSchema" {
     }
 }
 
+/**
+ * HTTP transport function. The signature mirrors `fetch` (URL string + init bag),
+ * which lets the default implementation just be `fetch`. Pass a custom transport
+ * to plug in pinned-TLS dialing, custom dispatchers, signed-request proxies,
+ * or any other wire-layer concern that `fetch` can't accommodate.
+ *
+ * The `url` arg is `(config.url ?? "") + path-built-from-schema`, so when you
+ * pass `url: ""` (or rely on transport-implies-empty), your transport receives
+ * just the request path and decides the host itself.
+ *
+ * The init bag is a fetch-compatible subset: only the fields createClient
+ * actually populates. Extending it later is a non-breaking change.
+ */
+export type GGHttpTransport = (
+    url: string,
+    init: {
+        method: string
+        headers: Record<string, string>
+        body: string | FormData | undefined
+        signal: AbortSignal
+    }
+) => Promise<Response>
+
 export interface GGHttpClientConfig {
     url?: string;
     timeout?: number;
     noValidation?: boolean
+    /**
+     * Override the wire-layer call. Defaults to `fetch`. When provided,
+     * service discovery is skipped (the transport is presumed to know how
+     * to reach the target) and `url` defaults to `""` so the transport sees
+     * just the schema-built path.
+     */
+    transport?: GGHttpTransport
 }
 
 GGHttpSchema.prototype.createClient = function <TContract extends GGContractApiDefinition, TContext>(
@@ -29,6 +59,14 @@ export function createClient<TContract extends GGContractApiDefinition, TContext
     config ??= {};
     config.timeout ??= 15000;
 
+    // A custom transport implies "I take over the wire layer" — discovery is
+    // off the table (the transport knows how to find the target), and the
+    // default base URL becomes "" so the transport sees just the request path.
+    const transport: GGHttpTransport = config.transport ?? defaultFetchTransport;
+    if (config.transport && config.url === undefined) {
+        config.url = "";
+    }
+
     if (config.url === undefined && isBrowser()) {
         throw new Error("Must define URL for GGHttpClient when running in browser! Use empty string for same-origin requests.");
     }
@@ -69,7 +107,7 @@ export function createClient<TContract extends GGContractApiDefinition, TContext
                 const fetchRequest = await wireFormat.createRequest(validatedInput);
                 const controller = new AbortController();
                 const timeoutId = setTimeout(() => controller.abort(), config.timeout);
-                const wireResponse = await fetch(baseUrl + fetchRequest.url, {
+                const wireResponse = await transport(baseUrl + fetchRequest.url, {
                     method: fetchRequest.method,
                     signal: controller.signal,
                     headers: fetchRequest.headers,
@@ -101,7 +139,10 @@ export function createClient<TContract extends GGContractApiDefinition, TContext
         }
 
     }
-    // @TODO Next line is just so test would register it correctly.
-    httpSchema.contract.implement(transportImplementation as GGContractImplementation<TContract>)
+    // Per-client stub — doesn't belong in the callOn registry (server's impl does).
+    httpSchema.contract.implement(transportImplementation as GGContractImplementation<TContract>, {skipLocatorRegistration: true})
     return transportImplementation;
-}
+}
+
+const defaultFetchTransport: GGHttpTransport = (url, init) =>
+    fetch(url, init as RequestInit)

package/src/index-node.ts

@@ -17,6 +17,8 @@ export * from "./server/GG_HTTP_REQUEST";
 export * from "./schema/GGHttpSchema";
 export * from "./schema/httpSchema";
 export * from "./rpc/GGHttpRouteRPC";
+export * from "./rpc/openApiSuccessResponse";
+export * from "./rpc/openApiHelpers";
 export * from "./rpc/RpcRequest/GGRpcRequestBuilder";
 export * from "./rpc/RpcRequest/GGRpcRequestParser";
 export * from "./rpc/RpcResponse/GGRpcResponseBuilder";

package/src/rpc/GGHttpRouteRPC.ts

@@ -1,7 +1,11 @@
 import {HttpMethod} from "@grest-ts/common"
-import {ClientHttpRouteToRpcTransformClientCodec, ClientHttpRouteToRpcTransformClientConfig, ClientHttpRouteToRpcTransformServerCodec, ClientHttpRouteToRpcTransformServerConfig, GGHttpCodec} from "../schema/GGHttpSchema"
+import {ClientHttpRouteToRpcTransformClientCodec, ClientHttpRouteToRpcTransformClientConfig, ClientHttpRouteToRpcTransformServerCodec, ClientHttpRouteToRpcTransformServerConfig, GGHttpCodec, GGHttpCodecOpenApiConfig} from "../schema/GGHttpSchema"
 import {GGRpcRequestBuilder} from "./RpcRequest/GGRpcRequestBuilder";
 import {GGRpcResponseParser} from "./RpcResponse/GGRpcResponseParser";
+import type {OpenAPIV3_1} from "openapi-types";
+import {GGSchema} from "@grest-ts/schema";
+import {buildRpcSuccessResponses} from "./openApiSuccessResponse";
+import {buildOpenApiParameters} from "./openApiHelpers";
 
 export type GGRpcServerCodecFactory = (method: HttpMethod, path: string, config: ClientHttpRouteToRpcTransformServerConfig) => ClientHttpRouteToRpcTransformServerCodec;
 
@@ -12,20 +16,23 @@ export function _registerRpcServerCodecFactory(factory: GGRpcServerCodecFactory)
 }
 
 export const GGRpc = {
-    GET: (path: string) => new GGHttpRpcCodec("GET", path),
-    DELETE: (path: string) => new GGHttpRpcCodec("DELETE", path),
-    POST: (path: string) => new GGHttpRpcCodec("POST", path),
-    PUT: (path: string) => new GGHttpRpcCodec("PUT", path),
+    GET:    (path: string, opts?: {deprecated?: boolean}) => new GGHttpRpcCodec("GET",    path, opts?.deprecated),
+    DELETE: (path: string, opts?: {deprecated?: boolean}) => new GGHttpRpcCodec("DELETE", path, opts?.deprecated),
+    POST:   (path: string, opts?: {deprecated?: boolean}) => new GGHttpRpcCodec("POST",   path, opts?.deprecated),
+    PUT:    (path: string, opts?: {deprecated?: boolean}) => new GGHttpRpcCodec("PUT",    path, opts?.deprecated),
 }
 
 class GGHttpRpcCodec implements GGHttpCodec {
 
     public readonly method: HttpMethod
     public readonly path: string
+    public readonly deprecated: boolean | undefined
+    public readonly responseHeaders: Record<string, GGSchema<string | undefined>> = {}
 
-    constructor(method: HttpMethod, path: string) {
+    constructor(method: HttpMethod, path: string, deprecated?: boolean) {
         this.method = method
         this.path = path
+        this.deprecated = deprecated
     }
 
     public createForClient(config: ClientHttpRouteToRpcTransformClientConfig): ClientHttpRouteToRpcTransformClientCodec {
@@ -39,4 +46,25 @@ class GGHttpRpcCodec implements GGHttpCodec {
         if (!_serverCodecFactory) throw new Error("Server RPC codec not available. Ensure @grest-ts/http server entry is imported.");
         return _serverCodecFactory(this.method, this.path, config);
     }
+
+    public toOpenApiOperation(config: GGHttpCodecOpenApiConfig): Partial<OpenAPIV3_1.OperationObject> {
+        const hasBody = this.method === "POST" || this.method === "PUT" || this.method === "PATCH";
+        const operationId = config.methodName;
+
+        const parameters = buildOpenApiParameters(this.path, hasBody, config.contract.input ?? undefined, config.schemaResolver);
+        const operation: Partial<OpenAPIV3_1.OperationObject> = {
+            operationId,
+            parameters,
+            responses: buildRpcSuccessResponses(config.contract, config.schemaResolver)
+        };
+
+        if (hasBody && config.contract.input) {
+            operation.requestBody = {
+                required: true,
+                content: {'application/json': {schema: config.schemaResolver(config.contract.input.toSchemaDescription())}}
+            };
+        }
+
+        return operation;
+    }
 }

package/src/rpc/openApiHelpers.ts

@@ -0,0 +1,87 @@
+import type {GGSchema, GGSchemaDescription} from "@grest-ts/schema";
+import type {GGOpenApiSchemaResolver} from "../schema/GGHttpSchema";
+import type {OpenAPIV3_1} from "openapi-types";
+
+/**
+ * Build OpenAPI parameter objects for a route from the contract's input schema.
+ *
+ * Path parameters are extracted from the path template (:id → {id}).
+ * For GET/DELETE (no body), remaining input fields become query parameters.
+ *
+ * Uses toSchemaDescription() to walk the input object's fields as
+ * GGSchemaDescription instances, then passes each to schemaResolver so named
+ * schemas are emitted as $ref where applicable.
+ *
+ * Type-cast note: openapi-types@12 defines OpenAPIV3_1.ParameterObject as a
+ * direct alias of OpenAPIV3.ParameterObject, whose `schema` field resolves to
+ * V3 schema types (missing `type:"null"` as a valid NonArraySchemaObjectType).
+ * The casts to ParameterObject["schema"] are the precise boundary of that
+ * typedef limitation — runtime objects are fully valid OpenAPI 3.1 parameters.
+ */
+export function buildOpenApiParameters(
+    pathTemplate: string,
+    hasBody: boolean,
+    inputSchema: GGSchema<unknown> | undefined,
+    schemaResolver: GGOpenApiSchemaResolver
+): OpenAPIV3_1.ParameterObject[] {
+    const pathParams = (pathTemplate.match(/:(\w+)/g) || []).map(m => m.slice(1));
+    if (!inputSchema) return pathParams.map(name => buildPathParam(name, undefined, schemaResolver));
+
+    // Use toSchemaDescription() to get GGSchemaDescription instances per field.
+    // This gives us the format-agnostic tree without coupling to internal def structure.
+    const desc = inputSchema.toSchemaDescription();
+    if (desc.node.kind !== 'object') {
+        // Input schemas must be object schemas so their fields can be mapped to
+        // path/query parameters. Any other kind is a contract definition error.
+        throw new Error(
+            `buildOpenApiParameters: input schema must be an object schema (kind='object'), ` +
+            `got kind='${desc.node.kind}'. Contract input schemas must use IsObject({...}).`
+        );
+    }
+
+    const properties = desc.node.properties;
+
+    const params: OpenAPIV3_1.ParameterObject[] = pathParams.map(name =>
+        buildPathParam(name, properties[name], schemaResolver)
+    );
+
+    if (!hasBody) {
+        for (const [name, fieldDesc] of Object.entries(properties)) {
+            if (pathParams.includes(name)) continue;
+            const resolved = schemaResolver(fieldDesc);
+            const {description, ...schemaWithoutDescription} = resolved as any;
+            const isRequired = !fieldDesc.optional && (resolved as any).default === undefined;
+            const param: OpenAPIV3_1.ParameterObject = {
+                name,
+                in: 'query' as const,
+                required: isRequired,
+                schema: schemaWithoutDescription as OpenAPIV3_1.ParameterObject["schema"]
+            };
+            if (description) param.description = description;
+            params.push(param);
+        }
+    }
+    return params;
+}
+
+function buildPathParam(
+    name: string,
+    fieldDesc: GGSchemaDescription | undefined,
+    schemaResolver: GGOpenApiSchemaResolver
+): OpenAPIV3_1.ParameterObject {
+    if (!fieldDesc) {
+        // Path params are always non-empty — an empty segment cannot be routed.
+        return {name, in: 'path' as const, required: true as const,
+            schema: {type: 'string', minLength: 1} as OpenAPIV3_1.ParameterObject["schema"]};
+    }
+    const resolved = schemaResolver(fieldDesc);
+    const {description, ...schemaWithoutDescription} = resolved as any;
+    const param: OpenAPIV3_1.ParameterObject = {
+        name,
+        in: 'path' as const,
+        required: true as const,
+        schema: schemaWithoutDescription as OpenAPIV3_1.ParameterObject["schema"]
+    };
+    if (description) param.description = description;
+    return param;
+}

package/src/rpc/openApiSuccessResponse.ts

@@ -0,0 +1,38 @@
+import type {GGContractMethod} from "@grest-ts/schema";
+import type {OpenAPIV3_1} from "openapi-types";
+import type {GGOpenApiSchemaResolver} from "../schema/GGHttpSchema";
+
+/**
+ * Builds the standard GGRpc JSON-envelope success response for OpenAPI.
+ *
+ * On-wire the response is always:
+ *   { success: true, type: "OK", data: <success schema> }   (200)
+ *   or no body                                               (204 when no success schema)
+ *
+ * The resolver is used to emit $ref for named success schemas rather than
+ * inlining them. Pass config.schemaResolver from toOpenApiOperation().
+ */
+export function buildRpcSuccessResponses(
+    contract: GGContractMethod,
+    resolver: GGOpenApiSchemaResolver
+): OpenAPIV3_1.ResponsesObject {
+    if (contract.success) {
+        const dataSchema = resolver(contract.success.toSchemaDescription());
+        const successSchema: OpenAPIV3_1.NonArraySchemaObject = {
+            type: "object",
+            properties: {
+                success: {type: "boolean", enum: [true]},
+                type: {type: "string", enum: ["OK"]},
+                data: dataSchema
+            },
+            required: ["success", "type", "data"]
+        };
+        return {
+            "200": {
+                description: "Success",
+                content: {"application/json": {schema: successSchema}}
+            }
+        };
+    }
+    return {"204": {description: "No content"}};
+}

package/src/schema/GGHttpSchema.ts

@@ -1,7 +1,8 @@
-import {ERROR, ERROR_JSON, GGContractApiDefinition, GGContractClass, GGContractMethod, OK} from "@grest-ts/schema";
+import {ERROR, ERROR_JSON, GGContractApiDefinition, GGContractClass, GGContractMethod, GGSchema, GGSchemaDescription, OK} from "@grest-ts/schema";
 import type {HttpMethod} from "@grest-ts/common";
 import type http from "http";
 import type {GGHttpServerMiddleware} from "../server/GGHttpSchema.startServer";
+import type {OpenAPIV3_1} from "openapi-types";
 
 export class GGHttpSchema<TContract extends GGContractApiDefinition, TContext> {
 
@@ -69,14 +70,63 @@ export interface ClientHttpRouteToRpcTransformServerCodec {
 // Codec
 // --------------------------------------------------------------------------------------------------------
 
+/**
+ * Config passed to toOpenApiOperation? — gives the codec access to the contract and route context
+ * so it can produce accurate OpenAPI operation metadata.
+ */
+/**
+ * Resolves a GGSchemaDescription to an OpenAPI SchemaObject or ReferenceObject.
+ * When provided via GGHttpCodecOpenApiConfig, codecs should use this for all schema
+ * conversions — it enables $ref extraction for named schemas.
+ * For standalone use (tests, custom tools), use inlineSchemaResolver from @grest-ts/openapi.
+ */
+export type GGOpenApiSchemaResolver = (desc: GGSchemaDescription) => OpenAPIV3_1.SchemaObject | OpenAPIV3_1.ReferenceObject;
+
+export interface GGHttpCodecOpenApiConfig {
+    readonly pathPrefix: string;
+    readonly methodName: string;
+    readonly contract: GGContractMethod;
+    /**
+     * Resolves a GGSchema to an OpenAPI SchemaObject or ReferenceObject.
+     * Provided by the document builder (toOpenApi) as registry.schemaOrRef.
+     * For standalone codec use or tests, pass inlineSchemaResolver from @grest-ts/openapi.
+     */
+    readonly schemaResolver: GGOpenApiSchemaResolver;
+}
+
+
 export interface GGHttpCodec {
     readonly method: HttpMethod;
     readonly path: string;
 
+    /**
+     * Mark this operation as deprecated in the OpenAPI spec.
+     * Swagger UI renders deprecated operations with a strikethrough.
+     * @default false
+     */
+    readonly deprecated?: boolean;
+
+    /**
+     * Response headers this codec sets, mapped to their value schemas.
+     * Keys are header names; values describe the header value format.
+     * Used for CORS Access-Control-Expose-Headers and OpenAPI response header docs.
+     * Use {} if the codec sets no custom response headers.
+     */
+    readonly responseHeaders: Record<string, GGSchema<string | undefined>>;
+
     createForClient(config: ClientHttpRouteToRpcTransformClientConfig): ClientHttpRouteToRpcTransformClientCodec
 
     createForServer(config: ClientHttpRouteToRpcTransformServerConfig): ClientHttpRouteToRpcTransformServerCodec
 
+    /**
+     * Optional hook for custom codecs to describe their OpenAPI operation semantics.
+     * The returned partial is merged on top of the auto-generated operation object,
+     * allowing overrides for requestBody content type, security schemes, etc.
+     *
+     * Built-in GGRpc.* codecs implement this automatically.
+     * Custom codec authors (e.g. GGFileUpload) may implement it for accurate docs.
+     */
+    toOpenApiOperation?(config: GGHttpCodecOpenApiConfig): Partial<OpenAPIV3_1.OperationObject>
 }
 
 // --------------------------------------------------------------------------------------------------------
@@ -84,6 +134,28 @@ export interface GGHttpCodec {
 // --------------------------------------------------------------------------------------------------------
 
 export interface GGHttpTransportMiddleware {
+    /**
+     * Request headers this middleware reads or writes, mapped to their value schemas.
+     * Keys are header names; values describe the header value format for validation and docs.
+     * Used for CORS Access-Control-Allow-Headers and OpenAPI parameter docs.
+     * Use {} if the middleware touches no custom request headers.
+     *
+     * @example
+     * headers: {
+     *   "authorization": IsString.nonEmpty.docs({title: "Bearer token", example: "Bearer ..."}),
+     *   "accept-language": IsLocale.orUndefined
+     * }
+     */
+    readonly headers: Record<string, GGSchema<string | undefined>>;
+
+    /**
+     * Response headers this middleware sets, mapped to their value schemas.
+     * Keys are header names; values describe the header value format for validation and docs.
+     * Used for CORS Access-Control-Expose-Headers and OpenAPI response header docs.
+     * Use {} if the middleware sets no custom response headers.
+     */
+    readonly responseHeaders: Record<string, GGSchema<string | undefined>>;
+
     /**
      * Client-side: modify outgoing request (add headers, etc.)
      */

package/src/schema/httpSchema.ts

@@ -1,7 +1,7 @@
 import type http from "http";
 import {GGHttpCodec, GGHttpSchema} from "./GGHttpSchema";
 import {GGHttpRequest, GGHttpTransportMiddleware} from "./GGHttpSchema";
-import {GGContractApiDefinition, GGContractClass} from "@grest-ts/schema";
+import {GGContractApiDefinition, GGContractClass, GGSchema} from "@grest-ts/schema";
 import {GGContextKey} from "@grest-ts/context";
 
 /**
@@ -60,9 +60,23 @@ class GGHttpSchemaBuilder<TContract extends GGContractApiDefinition, TContext =
             throw new Error(`Context key '${contextKey.name}' does not have an 'http-header' codec registered.`);
         }
 
+        // Build the typed header map from codec.inputSchema — the IsObject({headerName: schema})
+        // that describes which headers this codec reads and what format each value has.
+        const inputSchema = codec.inputSchema;
+        const headers: Record<string, GGSchema<string | undefined>> = {};
+        if (inputSchema) {
+            const desc = inputSchema.toSchemaDescription();
+            if (desc.node.kind === 'object') {
+                for (const [k, fieldDesc] of Object.entries(desc.node.properties)) {
+                    headers[k] = fieldDesc.schema as GGSchema<string | undefined>;
+                }
+            }
+        }
+
         const middleware: GGHttpTransportMiddleware = {
+            headers,
+            responseHeaders: {},
             updateRequest(req: GGHttpRequest) {
-                // Client-side: context -> headers
                 const contextValue = contextKey.get();
                 if (contextValue !== undefined) {
                     const result = codec.decode(contextValue);
@@ -70,7 +84,6 @@ class GGHttpSchemaBuilder<TContract extends GGContractApiDefinition, TContext =
                         Object.assign(req.headers, result.value);
                     }
                 } else {
-                    // Clear any default headers by decoding an empty context
                     const emptyResult = codec.decode({} as Input);
                     if (emptyResult.success) {
                         for (const key of Object.keys(emptyResult.value as object)) {
@@ -80,7 +93,6 @@ class GGHttpSchemaBuilder<TContract extends GGContractApiDefinition, TContext =
                 }
             },
             parseRequest(req: http.IncomingMessage) {
-                // Server-side: headers -> context
                 const headers = req.headers as Record<string, string>;
                 const result = codec.encode(headers);
                 if (result.success) {

package/src/server/GGHttp.ts

@@ -5,7 +5,12 @@ import {GGHttpServer} from "./GGHttpServer";
 
 export class GGHttp<TContext = undefined> {
 
-    private readonly httpServer: GGHttpServer
+    /**
+     * Protected (not private) so that plugin modules can access the underlying server
+     * via module augmentation (e.g. @grest-ts/openapi adds .openApi() to the builder).
+     * Do not tighten back to private.
+     */
+    protected readonly httpServer: GGHttpServer
     private readonly middlewares: GGHttpServerMiddleware[] = [];
 
     constructor(httpServer: GGHttpServer) {

package/src/server/GGHttpSchema.startServer.ts

@@ -65,11 +65,25 @@ function setupRoutes<TContract extends GGContractApiDefinition>(
     const server = config.http ?? GGLocator.getScope().get(GG_HTTP_SERVER);
     if (!server) throw new Error(`No HTTP server found. Make sure to register GGHttpServerAdapter in the scope or pass handler via config`)
 
+    server._registerSchema(httpSchema as GGHttpSchema<any, any>);
+
     const pathPrefix = "/" + httpSchema.pathPrefix + "/"
     const apiMiddlewares = httpSchema.apiMiddlewares;
     const scope = GGLocator.getScope();
     const parentContext = GGContextStore.tryGetContext();
 
+    for (const mw of apiMiddlewares) {
+        const hKeys = Object.keys(mw.headers);
+        const rhKeys = Object.keys(mw.responseHeaders);
+        if (hKeys.length) server.registerCorsHeaders(hKeys);
+        if (rhKeys.length) server.registerCorsExposeHeaders(rhKeys);
+    }
+    for (const methodName in httpSchema.codec) {
+        const codec: GGHttpCodec = httpSchema.codec[methodName];
+        const rhKeys = Object.keys(codec?.responseHeaders ?? {});
+        if (rhKeys.length) server.registerCorsExposeHeaders(rhKeys);
+    }
+
     server.onStart(() => {
         GG_DISCOVERY.tryGet()?.registerRoutes([{
             runtime: scope.serviceName,

package/src/server/GGHttpServer.ts

@@ -5,6 +5,10 @@ import {GGLocator, GGLocatorKey, GGLocatorScope, GGLocatorServiceType} from "@gr
 import {GG_HTTP_SERVER} from "./GG_HTTP_SERVER";
 import {GGLog} from "@grest-ts/logger";
 import findMyWay, {HTTPMethod} from "find-my-way";
+import type {GGHttpSchema} from "../schema/GGHttpSchema";
+// Forward declaration — actual type lives in @grest-ts/websocket to avoid circular dep.
+// GGHttpServer only stores the array; callers cast as needed.
+type AnyWebSocketSchema = {name: string; path: string; contract: unknown; middlewares: readonly unknown[]};
 
 export interface GGHttpServerAdapterConfig {
     key?: GGLocatorKey<GGHttpServer>;
@@ -34,10 +38,31 @@ export class GGHttpServer {
     private readonly _onStart: Array<() => void> = [];
     private readonly _onTeardown: Array<() => void> = [];
 
+    /**
+     * Mutable during compose(); frozen and exposed as ReadonlyArray once the server starts.
+     * Framework-internal — only setupRoutes() (in GGHttpSchema.startServer.ts) should push here.
+     */
+    private readonly _registeredSchemas: GGHttpSchema<any, any>[] = [];
+
+    /**
+     * All GGHttpSchema instances registered on this server, in registration order.
+     * Available from the moment compose() begins; frozen (no further push allowed) once start() is called.
+     */
+    get registeredSchemas(): ReadonlyArray<GGHttpSchema<any, any>> {
+        return this._registeredSchemas;
+    }
+
     public readonly httpServer: http.Server;
     private activeRequests = 0;
     private router = findMyWay<findMyWay.HTTPVersion.V1>();
 
+    private static readonly DEFAULT_CORS_HEADERS = ['Content-Type'];
+    private readonly _corsHeaders = new Set<string>(GGHttpServer.DEFAULT_CORS_HEADERS);
+    private _corsHeadersCache: string = GGHttpServer.DEFAULT_CORS_HEADERS.join(', ');
+
+    private readonly _corsExposeHeaders = new Set<string>();
+    private _corsExposeHeadersCache: string = '';
+
     constructor(config?: GGHttpServerAdapterConfig) {
 
         this.runtimeName = GGLocator.getScope().serviceName;
@@ -61,8 +86,10 @@ export class GGHttpServer {
                 if (req.headers.origin) { // For browsers
                     res.setHeader('Access-Control-Allow-Origin', '*');
                     res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
-                    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, x-org-token');
-                    res.setHeader('Access-Control-Expose-Headers', 'Content-Disposition');
+                    res.setHeader('Access-Control-Allow-Headers', this._corsHeadersCache);
+                    if (this._corsExposeHeadersCache) {
+                        res.setHeader('Access-Control-Expose-Headers', this._corsExposeHeadersCache);
+                    }
                 }
                 if (req.method === 'OPTIONS') {
                     res.writeHead(204);
@@ -90,6 +117,40 @@ export class GGHttpServer {
             : http.createServer(handler);
     }
 
+    /**
+     * Register custom header names for CORS Access-Control-Allow-Headers.
+     * Called automatically during schema registration based on middleware declarations.
+     */
+    public registerCorsHeaders(headers: readonly string[]): void {
+        let changed = false;
+        for (const h of headers) {
+            if (!this._corsHeaders.has(h)) {
+                this._corsHeaders.add(h);
+                changed = true;
+            }
+        }
+        if (changed) {
+            this._corsHeadersCache = Array.from(this._corsHeaders).join(', ');
+        }
+    }
+
+    /**
+     * Register custom header names for CORS Access-Control-Expose-Headers.
+     * Called automatically during schema registration based on codec and middleware declarations.
+     */
+    public registerCorsExposeHeaders(headers: readonly string[]): void {
+        let changed = false;
+        for (const h of headers) {
+            if (!this._corsExposeHeaders.has(h)) {
+                this._corsExposeHeaders.add(h);
+                changed = true;
+            }
+        }
+        if (changed) {
+            this._corsExposeHeadersCache = Array.from(this._corsExposeHeaders).join(', ');
+        }
+    }
+
     /**
      * Current port the server is listening to.
      * May be undefined before start() is called.
@@ -102,11 +163,32 @@ export class GGHttpServer {
     // Common implementation
     // =========================================================================
 
+    /** @internal Called by setupRoutes() during compose(). Do not call directly. */
+    public _registerSchema(schema: GGHttpSchema<any, any>): void {
+        this._registeredSchemas.push(schema);
+    }
+
+    private readonly _registeredWebSocketSchemas: AnyWebSocketSchema[] = [];
+
+    /**
+     * All GGWebSocketSchema instances registered on this server, in registration order.
+     * Populated automatically by GGWebSocketSchema.startServer() / .register().
+     */
+    get registeredWebSocketSchemas(): ReadonlyArray<AnyWebSocketSchema> {
+        return this._registeredWebSocketSchemas;
+    }
+
+    /** @internal Called by GGWebSocketSchema.startServer(). Do not call directly. */
+    public _registerWebSocketSchema(schema: AnyWebSocketSchema): void {
+        this._registeredWebSocketSchemas.push(schema);
+    }
+
     public registerRoute(method: HttpMethod, path: string, handler: GGHttpRequestCallback): void {
         this.router.on(method as HTTPMethod, path, handler as unknown as findMyWay.Handler<findMyWay.HTTPVersion.V1>);
     }
 
     public async start(): Promise<void> {
+        Object.freeze(this._registeredSchemas);
         this._port = await new Promise((resolve) => {
             this.httpServer.listen(this.configuredPort, '0.0.0.0', () => {
                 const port = (this.httpServer.address() as any).port;