@techspokes/typescript-wsdl-client 1.1.5 → 1.2.0

package/dist/gateway/generateCheckedGateway.js

@@ -0,0 +1,293 @@
+/**
+ * Lowers issued direct mappings into HTTP documentation and a checked gateway.
+ * @since 1.1.6
+ * @constraints Serialized descriptions never issue native source or execution authority.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { componentSourceCapsuleBytes, inspectReconstructedComponentSource, inspectComponentSourceService } from '../compiler/directSourceCapsule.js';
+import { lowerComponentShape } from '../generation/componentShape.js';
+import { checkSemanticBudget } from '../compiler/semanticBudget.js';
+import { inspectDirectOperation } from '../compiler/directOperation.js';
+import { inspectComponentValueMapping } from '../compiler/directValues.js';
+import { composeGeneratedSource, resolvePreamble } from '../generation/preamble.js';
+const draft07 = 'http://json-schema.org/draft-07/schema#';
+/** Lower component mappings through the existing checked gateway emitter, retaining native supplemental validation. */
+export async function generateComponentGateway(expected, options) {
+    inspectReconstructedComponentSource(expected);
+    return generateGatewayFromReconstruction(expected, options);
+}
+async function generateGatewayFromReconstruction(expected, options) {
+    if (options.signal?.aborted)
+        throw new Error('Checked gateway generation cancelled');
+    inspectReconstructedComponentSource(expected);
+    const capsule = { bytes: componentSourceCapsuleBytes(expected, options.signal) };
+    const runtime = 'checkedComponentRuntimeV1';
+    if (!options.routePath.startsWith('/') || options.routePath.split('/').slice(1)
+        .some(segment => !segment || !/^(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+$/.test(segment))) {
+        throw new TypeError('Checked routePath requires literal nonempty path segments');
+    }
+    const input = expected.mappings.find(mapping => mapping.direction.kind === 'input');
+    const output = expected.mappings.find(mapping => mapping.direction.kind === 'output');
+    if (!input || !output)
+        throw new TypeError('Issued input and output mappings required');
+    const schema = (mapping, role) => {
+        const { budget } = inspectDirectOperation(expected.contract).context;
+        return lowerComponentShape(expected.contract, mapping, role, () => {
+            checkSemanticBudget(budget);
+            if (options.signal?.aborted)
+                throw new Error('Checked gateway generation cancelled');
+        }).schema;
+    };
+    const request = schema(input, 'Request'), response = schema(output, 'Response');
+    const faults = expected.mappings.filter(mapping => mapping.direction.kind === 'fault').map(mapping => {
+        if (mapping.direction.kind !== 'fault')
+            throw new TypeError('Declared fault mapping required');
+        return { name: mapping.direction.name, value: schema(mapping, `Fault_${expected.mappings.filter(item => item.direction.kind === 'fault').indexOf(mapping)}`) };
+    });
+    const faultVariants = faults.map(fault => ({
+        type: 'object', additionalProperties: false, required: ['fault', 'value'],
+        properties: {
+            value: fault.value,
+            fault: {
+                type: 'object', additionalProperties: false, required: ['name', 'code', 'string'],
+                properties: {
+                    name: { const: fault.name }, string: { type: 'string' }, actor: { type: 'string' },
+                    code: { type: 'object', additionalProperties: false, required: ['namespace', 'local'],
+                        properties: { namespace: { type: 'string' }, local: { type: 'string' } } },
+                },
+            },
+        },
+    }));
+    const fault = faultVariants.length ? { oneOf: faultVariants } : { not: {} };
+    const schemas = { request: { $schema: draft07, ...request }, response: { $schema: draft07, ...response }, fault: { $schema: draft07, ...fault } };
+    const grouped = expected.mappings.some(mapping => mapping.kind === 'component-mapping'
+        && inspectComponentValueMapping(mapping, expected.contract).applicationGroups);
+    const components = Object.create(null);
+    const documented = (value, dictionary = false) => {
+        if (Array.isArray(value))
+            return value.map(item => documented(item));
+        if (!value || typeof value !== 'object')
+            return value;
+        const record = value, result = Object.create(null);
+        // @why Property names belong to the application; definitions and $id are keywords only at schema nodes.
+        if (dictionary) {
+            for (const [key, item] of Object.entries(record))
+                result[key] = documented(item);
+            return result;
+        }
+        if (Object.hasOwn(record, 'definitions'))
+            for (const [key, definition] of Object.entries(record.definitions)) {
+                const resolved = documented(definition);
+                if (components[key] && JSON.stringify(components[key]) !== JSON.stringify(resolved))
+                    throw new TypeError(`applicationGroups OpenAPI component collision ${key}`);
+                components[key] = resolved;
+            }
+        for (const [key, item] of Object.entries(record)) {
+            if (key === 'definitions' || key === '$id')
+                continue;
+            result[key] = ['const', 'enum', 'default', 'examples'].includes(key) ? item
+                : key === '$ref' && typeof item === 'string' && item.startsWith('#/definitions/') ? item.replace('#/definitions/', '#/components/schemas/')
+                    : documented(item, ['properties', 'patternProperties', 'dependencies', 'dependentSchemas'].includes(key));
+        }
+        return result;
+    };
+    const documentation = grouped ? { request: documented(request), response: documented(response), fault: documented(fault) } : { request, response, fault };
+    const doc = {
+        openapi: '3.1.1', jsonSchemaDialect: 'https://json-schema.org/draft/2020-12/schema',
+        info: { title: expected.selection.service.local, version: '1.0.0' },
+        ...(grouped ? { components: { schemas: components } } : {}),
+        'x-checked-model': { model: 'checked-components-v1', scope: 'native-component-structured-soap11',
+            ...(expected.responseProjection
+                ? { responseProjection: { spec: expected.responseProjection.spec, delivery: 'buffered', retainedValue: 'complete-companion-payload' } } : {}),
+            documentationDialect: '2020-12', runtimeDialect: 'draft-07', jsonShapeComplete: false,
+            supplementalValidation: ['native-source-compatibility', 'native-xml-scalar-and-particle'], admitted: false,
+            selection: { selector: expected.contract.selector, ...expected.selection } },
+        paths: { [options.routePath]: { post: { operationId: expected.contract.selector.operation,
+                    ...(expected.responseProjection
+                        ? { 'x-response-projection': { spec: expected.responseProjection.spec, delivery: 'buffered', retainedValue: 'complete-companion-payload' } } : {}),
+                    requestBody: { required: true, content: { 'application/json': { schema: documentation.request } } },
+                    responses: { '200': { description: 'Independently validated SOAP response', content: { 'application/json': { schema: documentation.response } } },
+                        '400': { description: 'Invalid HTTP request; no SOAP request is dispatched' },
+                        '502': { description: 'Declared SOAP fault or refused upstream response', content: { 'application/json': { schema: { oneOf: [documentation.fault,
+                                            { type: 'object', additionalProperties: false, required: ['kind', 'rule'], properties: { kind: { type: 'string' }, rule: { type: 'string' } } }] } } } },
+                        '500': { description: 'Incompatible artifacts or gateway configuration' } } } } },
+    };
+    let clientImport = path.relative(options.gatewayDir, path.join(options.clientDir, 'client.js')).replace(/\\/g, '/');
+    if (!clientImport.startsWith('.'))
+        clientImport = './' + clientImport;
+    const literal = (value) => JSON.stringify(value).replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+    // language=TypeScript
+    const body = `import type {FastifyPluginAsync} from 'fastify';
+import {Ajv} from 'ajv';
+import {types} from 'node:util';
+import {${runtime}} from '@techspokes/typescript-wsdl-client';
+import {createClient, expectedCapsuleBase64, type Options, type Request} from ${literal(clientImport)};
+
+export interface CheckedGatewayOptions { readonly clientOptions: Options }
+// @constraints JSON parsing preserves XML names such as __proto__ as ordinary own data properties.
+export const schemas = JSON.parse(${literal(JSON.stringify(schemas))}) as {request: Record<string, unknown>; response: Record<string, unknown>; fault: Record<string, unknown>};
+export const expectedOpenApiJson = ${literal(JSON.stringify(doc))};
+
+// @constraints Read only data properties before composing per-request cancellation.
+function dataCopy<T extends object>(value: T): T {
+  if (!value || typeof value !== 'object' || types.isProxy(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value) as object | null)) throw new TypeError('Data-only checked gateway options required');
+  const copy: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
+    if (typeof key !== 'string' || !Object.hasOwn(descriptor, 'value')) throw new TypeError('Data-only checked gateway options required');
+    copy[key] = descriptor.value;
+  }
+  return copy as T;
+}
+
+const plugin: FastifyPluginAsync<CheckedGatewayOptions> = async (fastify, options) => {
+  if (expectedCapsuleBase64 !== ${literal(Buffer.from(capsule.bytes).toString('base64'))}) throw new Error('incompatible-artifact: generated gateway/client mismatch; regenerate the complete project');
+  const client = createClient(${runtime});
+  const ajv = new Ajv({coerceTypes: false, useDefaults: false, removeAdditional: false, ownProperties: true, strict: true, allErrors: true});
+  const validateRequest = ajv.compile(schemas.request);
+  const validateResponse = ajv.compile(schemas.response);
+  const validateFault = ajv.compile(schemas.fault);
+  const base = dataCopy(options.clientOptions);
+  const soap = dataCopy(base.soap);
+  fastify.post(${literal(options.routePath)}, {
+    schema: {body: schemas.request},
+    validatorCompiler: () => validateRequest,
+    // @constraints Serialization preserves every validated member and never establishes validity.
+    serializerCompiler: () => value => JSON.stringify(value),
+  }, async (request, reply) => {
+    const controller = new AbortController();
+    const disconnected = () => {if (!reply.raw.writableEnded) controller.abort();};
+    request.raw.once('aborted', disconnected);
+    reply.raw.once('close', disconnected);
+    if (request.raw.aborted || reply.raw.destroyed) controller.abort();
+    try {
+      const signal = soap.signal ? AbortSignal.any([soap.signal, controller.signal]) : controller.signal;
+      const result = await client[${literal(expected.contract.selector.operation)}](request.body as Request,
+        {...base, soap: {...soap, signal}});
+      if (result.kind === 'soap-response') {
+        if (!validateResponse(result.value)) return reply.code(502).send({kind: 'value-invalid', rule: 'http-response-shape'});
+        return reply.type('application/json').serializer(value => JSON.stringify(value)).send(result.value);
+      }
+      if (result.kind === 'soap-fault') {
+        const fault = {name: result.fault.name, code: {namespace: result.fault.code.namespace, local: result.fault.code.local},
+          string: result.fault.string, ...(result.fault.actor === undefined ? {} : {actor: result.fault.actor})};
+        const value = {fault, value: result.value};
+        if (!validateFault(value)) return reply.code(502).send({kind: 'value-invalid', rule: 'http-fault-shape'});
+        return reply.code(502).type('application/json').serializer(value => JSON.stringify(value)).send(value);
+      }
+      const status = result.kind === 'incompatible-artifact' || result.kind === 'missing-authority' ? 500
+        : result.kind === 'cancelled' ? 499 : result.phase === 'input' ? 400 : 502;
+      return reply.code(status).send({kind: result.kind, rule: result.rule});
+    } finally {
+      request.raw.removeListener('aborted', disconnected);
+      reply.raw.removeListener('close', disconnected);
+    }
+  });
+};
+export default plugin;
+`;
+    if (options.signal?.aborted)
+        throw new Error('Checked gateway generation cancelled');
+    const source = composeGeneratedSource(body, resolvePreamble('gateway'));
+    const emit = async () => {
+        inspectReconstructedComponentSource(expected);
+        checkSemanticBudget(inspectDirectOperation(expected.contract).context.budget);
+        if (options.signal?.aborted)
+            throw new Error('Checked gateway generation cancelled');
+        await mkdir(options.gatewayDir, { recursive: true });
+        await mkdir(path.dirname(options.openapiFile), { recursive: true });
+        await writeFile(path.join(options.gatewayDir, 'plugin.ts'), source, 'utf8');
+        await writeFile(path.join(options.gatewayDir, 'schemas.json'), JSON.stringify(schemas, null, 2) + '\n', 'utf8');
+        await writeFile(options.openapiFile, JSON.stringify(doc, null, 2) + '\n', 'utf8');
+    };
+    if (options.emit !== false)
+        await emit();
+    return { doc, emit };
+}
+/** Compose per-operation checked routers without merging native source, service or binding identities.
+ * @returns One OpenAPI document and exact operation-to-route mapping, both descriptions rather than authority.
+ * @throws For mixed native handles, invalid/colliding paths, cancellation or filesystem failures.
+ */
+export async function generateComponentServiceGateway(expected, options) {
+    const operations = inspectComponentSourceService(expected), routes = Object.create(null);
+    const paths = Object.create(null);
+    const documents = [];
+    const emissions = [];
+    const tick = () => {
+        checkSemanticBudget(inspectDirectOperation(operations[0].contract).context.budget);
+        if (options.signal?.aborted)
+            throw new Error('Checked gateway generation cancelled');
+    };
+    for (const [index, operation] of operations.entries()) {
+        tick();
+        const name = operation.contract.selector.operation, routePath = `${options.basePath}/${encodeURIComponent(name)}`;
+        const result = await generateComponentGateway(operation, { clientDir: path.join(options.clientDir, 'operations', String(index)),
+            gatewayDir: path.join(options.gatewayDir, 'routes', String(index)), openapiFile: path.join(options.gatewayDir, 'routes', String(index), 'openapi.json'), routePath, signal: options.signal, emit: false });
+        emissions.push(result.emit);
+        const doc = result.doc;
+        documents.push(doc);
+        routes[name] = routePath;
+        for (const [route, value] of Object.entries(doc.paths)) {
+            if (Object.hasOwn(paths, route))
+                throw new TypeError('Duplicate checked route');
+            paths[route] = value;
+        }
+    }
+    const { responseProjection: firstProjection, ...serviceModel } = documents[0]['x-checked-model'];
+    void firstProjection;
+    const componentSchemas = Object.create(null);
+    for (const document of documents) {
+        const schemas = document.components?.schemas ?? {};
+        for (const [name, schema] of Object.entries(schemas)) {
+            if (componentSchemas[name] && JSON.stringify(componentSchemas[name]) !== JSON.stringify(schema))
+                throw new TypeError(`applicationGroups OpenAPI component collision ${name}`);
+            componentSchemas[name] = schema;
+        }
+    }
+    const doc = { ...documents[0], ...(Object.keys(componentSchemas).length ? { components: { schemas: componentSchemas } } : {}), 'x-checked-model': { ...serviceModel,
+            selection: { service: operations[0].selection.service, port: operations[0].selection.port,
+                selectors: operations.map(operation => operation.contract.selector) } }, paths };
+    let clientImport = path.relative(options.gatewayDir, path.join(options.clientDir, 'client.js')).replaceAll('\\', '/');
+    if (!clientImport.startsWith('.'))
+        clientImport = './' + clientImport;
+    const literal = (value) => JSON.stringify(value).replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+    const names = operations.map(operation => operation.contract.selector.operation);
+    const lines = ["import type {FastifyPluginAsync} from 'fastify';", "import {types} from 'node:util';",
+        `import type {Options} from ${literal(clientImport)};`,
+        ...operations.map((_, index) => `import operation_${index} from './routes/${index}/plugin.js';`),
+        'export interface CheckedGatewayOptions {readonly clientOptions: Options; readonly capsules: Readonly<Record<string, Uint8Array>>}',
+        `export const expectedOpenApiJson = ${literal(JSON.stringify(doc))};`,
+        'function data(value: unknown, allowed: readonly string[]): Record<string, unknown> {',
+        "  if (!value || typeof value !== 'object' || types.isProxy(value) || ![null, Object.prototype].includes(Object.getPrototypeOf(value) as object | null)) throw new TypeError('Data-only service options required');",
+        '  const result: Record<string, unknown> = Object.create(null) as Record<string, unknown>;',
+        '  for (const key of Reflect.ownKeys(value)) {',
+        '    const descriptor = Object.getOwnPropertyDescriptor(value, key)!;',
+        "    if (typeof key !== 'string' || !allowed.includes(key) || !Object.hasOwn(descriptor, 'value')) throw new TypeError('Unsupported service option');",
+        '    result[key] = descriptor.value;', '  }', '  return result;', '}',
+        'const plugin: FastifyPluginAsync<CheckedGatewayOptions> = async (fastify, options) => {',
+        "  const outer = data(options, ['clientOptions', 'capsules', 'prefix']);",
+        "  const clientOptions = data(outer.clientOptions, ['localSource', 'fileRoots', 'sourceResources', 'sourceOrigins', 'sourceUri', 'namespaceLocations', 'standardLibraries', 'recordSources', 'soap']) as unknown as Options;",
+        `  const capsules = data(outer.capsules, ${literal(names)});`,
+        ...operations.map((operation, index) => `  if (!Object.hasOwn(capsules, ${literal(operation.contract.selector.operation)})) throw new TypeError('Missing operation capsule');
+  await fastify.register(operation_${index}, {clientOptions: {...clientOptions, capsule: capsules[${literal(operation.contract.selector.operation)}] as Uint8Array}});`),
+        '};', 'export default plugin;', '',
+    ];
+    tick();
+    const source = composeGeneratedSource(lines.join('\n'), resolvePreamble('gateway'));
+    const emit = async () => {
+        tick();
+        for (const write of emissions) {
+            tick();
+            await write();
+        }
+        await mkdir(options.gatewayDir, { recursive: true });
+        await mkdir(path.dirname(options.openapiFile), { recursive: true });
+        await writeFile(path.join(options.gatewayDir, 'plugin.ts'), source, 'utf8');
+        await writeFile(options.openapiFile, JSON.stringify(doc, null, 2) + '\n', 'utf8');
+    };
+    if (options.emit !== false)
+        await emit();
+    return { doc, routes: Object.freeze(routes), emit };
+}

package/dist/gateway/generateComposedGateway.d.ts

@@ -0,0 +1,16 @@
+export interface ComposedGatewayService {
+    key: string;
+    clientDir: string;
+    gatewayDir: string;
+    clientClassName: string;
+}
+/** Build a typed aggregate over independently generated service routers.
+ * @returns Complete generated source; the caller publishes it only after composition succeeds.
+ * @constraints Routes already carry generation-time prefixes. Runtime prefixing is refused to keep the served definition accurate.
+ */
+export declare function buildComposedGatewaySource(services: readonly ComposedGatewayService[], options: {
+    outDir: string;
+    openapiFile: string;
+    imports?: "js" | "ts" | "bare";
+    openapiPath?: string | false;
+}): string;

package/dist/gateway/generateComposedGateway.js

@@ -0,0 +1,65 @@
+import path from "node:path";
+import { composeGeneratedSource, resolvePreamble } from "../generation/preamble.js";
+/** Build a typed aggregate over independently generated service routers.
+ * @returns Complete generated source; the caller publishes it only after composition succeeds.
+ * @constraints Routes already carry generation-time prefixes. Runtime prefixing is refused to keep the served definition accurate.
+ */
+export function buildComposedGatewaySource(services, options) {
+    const suffix = options.imports === "bare" ? "" : `.${options.imports ?? "js"}`;
+    const literal = (value) => JSON.stringify(value).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+    const relative = (target) => {
+        const resolved = path.relative(options.outDir, target).replaceAll("\\", "/");
+        if (path.isAbsolute(resolved) || /^[a-z]:/i.test(resolved))
+            throw new Error("Composed outputs must share a filesystem root");
+        return resolved.startsWith(".") ? resolved : "./" + resolved;
+    };
+    const ordered = [...services].sort((a, b) => a.key.localeCompare(b.key));
+    const lines = [
+        'import type {FastifyPluginAsync} from "fastify";',
+        'import {types} from "node:util";',
+        `import definition from ${literal(relative(options.openapiFile))} with {type: "json"};`,
+        ...ordered.flatMap((service, index) => [
+            `import {${service.clientClassName} as Client${index}} from ${literal(relative(path.join(service.clientDir, "client" + suffix)))};`,
+            `import type {${service.clientClassName}Operations as Operations${index}} from ${literal(relative(path.join(service.clientDir, "operations" + suffix)))};`,
+            `import service${index} from ${literal(relative(path.join(service.gatewayDir, "plugin" + suffix)))};`,
+        ]),
+        "",
+        "export const openapi = definition;",
+        "export interface MultiServiceClients {",
+        ...ordered.map((service, index) => `  ${literal(service.key)}: Operations${index};`),
+        "}",
+        "export interface MultiServiceClientOptions {",
+        ...ordered.map((service, index) => `  ${literal(service.key)}: ConstructorParameters<typeof Client${index}>[0];`),
+        "}",
+        "export interface MultiServiceGatewayOptions {clients: MultiServiceClients}",
+        "function registry(value: unknown): void {",
+        '  if (!value || typeof value !== "object" || types.isProxy(value) || ![null, Object.prototype].includes(Object.getPrototypeOf(value) as object | null)) throw new TypeError("Service registry must be a data object");',
+        `  const expected = ${literal(ordered.map(service => service.key))};`,
+        '  if (Reflect.ownKeys(value).length !== expected.length) throw new TypeError("Service registry must contain exactly the configured services");',
+        "  for (const key of expected) {",
+        "    const property = Object.getOwnPropertyDescriptor(value, key);",
+        '    if (!property || !Object.hasOwn(property, "value") || !property.value) throw new TypeError("Missing service registry value: " + key);',
+        "  }",
+        "}",
+        "",
+        "/** Bind each generated SOAP client to its own explicit runtime WSDL and options. */",
+        "export function createClients(options: MultiServiceClientOptions): {",
+        ...ordered.map((service, index) => `  ${literal(service.key)}: Client${index};`),
+        "} {",
+        "  registry(options);",
+        "  return {",
+        ...ordered.map((service, index) => `    ${literal(service.key)}: new Client${index}(options[${literal(service.key)}]),`),
+        "  };",
+        "}",
+        "",
+        "const plugin: FastifyPluginAsync<MultiServiceGatewayOptions> = async (fastify, options) => {",
+        '  if (fastify.prefix) throw new TypeError("Configure service OpenAPI basePath instead of a runtime aggregate prefix");',
+        "  registry(options.clients);",
+        ...ordered.map((service, index) => `  await fastify.register(async scope => {await scope.register(service${index}, {client: options.clients[${literal(service.key)}]});});`),
+        ...(options.openapiPath === false ? [] : [`  fastify.get(${literal(options.openapiPath ?? "/openapi.json")}, async () => openapi);`]),
+        "};",
+        "export default plugin;",
+        "",
+    ];
+    return composeGeneratedSource(lines.join("\n"), resolvePreamble("gateway"));
+}

package/dist/gateway/generateGateway.d.ts

@@ -83,4 +83,3 @@ export interface GenerateGatewayOptions {
  * });
  */
 export declare function generateGateway(opts: GenerateGatewayOptions): Promise<void>;
-//# sourceMappingURL=generateGateway.d.ts.map

package/dist/gateway/generateGateway.js

@@ -131,6 +131,7 @@ export async function generateGateway(opts) {
     }
     // Resolve client metadata for full handler generation
     const clientMeta = resolveClientMeta({
+        gatewayDir: opts.outDir,
         clientDir: opts.clientDir,
         catalogFile: opts.catalogFile,
         clientClassName: opts.clientClassName,

package/dist/gateway/generators.d.ts

@@ -170,4 +170,3 @@ export declare function emitTypeCheckFixture(outDir: string, clientMeta: ClientM
  * @param {any} [catalog] - Compiled catalog for detecting ArrayOf* wrapper types to unwrap
  */
 export declare function emitRouteFilesWithHandlers(outDir: string, routesDir: string, versionSlug: string, serviceSlug: string, operations: OperationMetadata[], importsMode: "js" | "ts" | "bare", clientMeta: ClientMeta, catalog?: any): void;
-//# sourceMappingURL=generators.d.ts.map

package/dist/gateway/generators.js

@@ -922,7 +922,7 @@ export function emitRouteFilesWithHandlers(outDir, routesDir, versionSlug, servi
             ? "toJsonArray"
             : "toNdjson";
         const runtimeImport = op.stream
-            ? `import { ${streamHelperName} } from "../runtime${suffix}";`
+            ? `import { ${streamHelperName}${hasUnwrap ? ", unwrapArrayWrappers" : ""} } from "../runtime${suffix}";`
             : hasUnwrap
                 ? `import { buildSuccessEnvelope, unwrapArrayWrappers } from "../runtime${suffix}";`
                 : `import { buildSuccessEnvelope } from "../runtime${suffix}";`;
@@ -942,9 +942,24 @@ export function emitRouteFilesWithHandlers(outDir, routesDir, versionSlug, servi
         const handlerBody = op.stream
             ? `    handler: async (request, reply) => {
       const client = fastify.${clientMeta.decoratorName};
-      const result = await client.${clientMethod}(${bodyArg});
-      reply.type(${JSON.stringify(op.stream.mediaType)});
-      return reply.send(${streamHelperName}(result.records));
+      const controller = new AbortController();
+      const disconnected = () => { if (!reply.raw.writableEnded) controller.abort(); };
+      request.raw.once("aborted", disconnected);
+      reply.raw.once("close", disconnected);
+      if (request.raw.aborted || reply.raw.destroyed) controller.abort();
+      try {
+        const result = await client.${clientMethod}(${bodyArg}, { signal: controller.signal });
+        reply.type(${JSON.stringify(op.stream.mediaType)});
+        ${hasUnwrap ? `async function* mappedRecords() {
+          for await (const record of result.records) yield unwrapArrayWrappers(record, ${JSON.stringify(op.stream.recordTypeName ?? "unknown")});
+        }
+        // @constraints Keep disconnect cancellation active until the response stream finishes.
+        return await reply.send(${streamHelperName}(mappedRecords()));` : `// @constraints Keep disconnect cancellation active until the response stream finishes.
+        return await reply.send(${streamHelperName}(result.records));`}
+      } finally {
+        request.raw.removeListener("aborted", disconnected);
+        reply.raw.removeListener("close", disconnected);
+      }
     },`
             : `    handler: async (request) => {
       const client = fastify.${clientMeta.decoratorName};

package/dist/gateway/helpers.d.ts

@@ -199,6 +199,7 @@ export interface ResolvedOperationMeta {
  * @property {"js"|"ts"|"bare"} importsMode - Import extension mode
  */
 export interface ResolveClientMetaOptions {
+    gatewayDir?: string;
     clientDir?: string;
     catalogFile?: string;
     clientClassName?: string;
@@ -256,4 +257,3 @@ export declare function resolveOperationMeta(operationId: string, operationSlug:
  * @returns Number of unique schema components reachable via $ref
  */
 export declare function measureSchemaRefComplexity(startSchemaName: string, allSchemas: Record<string, any>, limit?: number): number;
-//# sourceMappingURL=helpers.d.ts.map

package/dist/gateway/helpers.js

@@ -11,6 +11,7 @@
  * - Automatic version/service detection from OpenAPI paths
  */
 import { pascal, trimRepeatedEdgeChar } from "../util/tools.js";
+import path from "node:path";
 /**
  * Converts a name to a deterministic slug for use in file names and URN IDs
  *
@@ -393,6 +394,20 @@ export function resolveClientMeta(opts, catalog) {
     const operationsImportPath = opts.clientDir
         ? `../client/operations${suffix}`
         : `./client/operations${suffix}`;
+    const modulePath = (from, module) => {
+        const relative = path.relative(from, path.join(opts.clientDir, module + suffix)).replaceAll("\\", "/");
+        if (path.isAbsolute(relative) || /^[a-z]:/i.test(relative))
+            throw new Error("Generated client and gateway modules must share a filesystem root");
+        return relative.startsWith(".") ? relative : "./" + relative;
+    };
+    if (opts.clientDir && opts.gatewayDir)
+        return {
+            className, decoratorName,
+            importPath: modulePath(path.join(opts.gatewayDir, "routes"), "client"),
+            typesImportPath: modulePath(path.join(opts.gatewayDir, "routes"), "types"),
+            pluginImportPath: modulePath(opts.gatewayDir, "client"),
+            operationsImportPath: modulePath(opts.gatewayDir, "operations"),
+        };
     return {
         className,
         decoratorName,

package/dist/generation/componentShape.d.ts

@@ -0,0 +1,14 @@
+import type { DirectOperationContract } from '../compiler/directOperation.js';
+type Schema = Record<string, unknown>;
+/** Lower an authenticated mapping to recursive TypeScript and JSON shape descriptions.
+ * @remarks Scalar restrictions, fixed/default semantics, ordered occurrence correlation and strict wildcard
+ *   declaration membership require native validation. These descriptions never grant source/runtime authority.
+ * @returns Role-scoped definitions and root descriptions; no native handles or retrieval paths are emitted.
+ * @throws TypeError For foreign mappings or unsupported scalar representation. Caller cancellation propagates.
+ */
+export declare function lowerComponentShape(contract: DirectOperationContract, supplied: unknown, role: string, check: () => void): {
+    type: string;
+    declarations: readonly string[];
+    schema: Schema;
+};
+export {};