opinionated-machine 6.16.0 → 6.18.0

package/README.md

@@ -84,6 +84,15 @@ Very opinionated DI framework for fastify, built on top of awilix
   - [Registering Dual-Mode Controllers](#registering-dual-mode-controllers)
   - [Accept Header Routing](#accept-header-routing)
   - [Testing Dual-Mode Controllers](#testing-dual-mode-controllers)
+- [Gateway Configuration](#gateway-configuration)
+  - [Quick Start](#quick-start)
+  - [Annotating Routes](#annotating-routes)
+  - [Avoiding Repetition With Defaults](#avoiding-repetition-with-defaults)
+  - [Type-Safe Matching](#type-safe-matching)
+  - [Field Reference](#field-reference)
+  - [Generating Gateway Configs](#generating-gateway-configs)
+  - [Inspecting the Manifest at Runtime](#inspecting-the-manifest-at-runtime)
+  - [What's Not Covered](#whats-not-covered)
 
 ## Basic usage
 
@@ -2799,3 +2808,313 @@ describe('DashboardDualModeController', () => {
   })
 })
 
+## Gateway Configuration
+
+Most services keep two copies of every route's policy: one in code, another in
+a hand-edited Envoy / KrakenD / Kong config. They drift, and outages happen at
+the seam. This feature lets you declare routing policy — timeouts, retries,
+rate limits, CORS, JWT auth, caching, header transforms, traffic matching —
+**next to the controller route it applies to**, then generate the gateway
+config from a single source of truth.
+
+Generators ship as separate npm packages so your service binary doesn't pull
+them in:
+
+| Gateway | Package | Output |
+| ------- | ------- | ------ |
+| Envoy   | [`@opinionated-machine/gateway-envoy`](./packages/gateway-envoy)     | static v3 YAML/JSON |
+| KrakenD | [`@opinionated-machine/gateway-krakend`](./packages/gateway-krakend) | declarative v3 JSON |
+| Kong    | [`@opinionated-machine/gateway-kong`](./packages/gateway-kong)       | DB-less declarative YAML/JSON |
+
+### Quick Start
+
+A complete round-trip in two steps. First, annotate routes in your existing
+controller:
+
+```ts
+import { buildRestContract } from '@lokalise/api-contracts'
+import { buildFastifyRoute } from '@lokalise/fastify-api-contracts'
+import {
+  AbstractController,
+  type BuildRoutesReturnType,
+  type GatewayMetadataValue,
+  withGatewayMetadata,
+} from 'opinionated-machine'
+import { z } from 'zod/v4'
+
+const getUser = buildRestContract({
+  method: 'get',
+  successResponseBodySchema: z.object({ id: z.string() }),
+  requestPathParamsSchema: z.object({ userId: z.string() }),
+  pathResolver: (p) => `/users/${p.userId}`,
+})
+const createUser = buildRestContract({
+  method: 'post',
+  requestBodySchema: z.object({ name: z.string() }),
+  successResponseBodySchema: z.object({ id: z.string() }),
+  pathResolver: () => '/users',
+})
+
+export class UsersController extends AbstractController<typeof UsersController.contracts> {
+  static readonly contracts = { getUser, createUser } as const
+
+  // Applies to every route in this controller; routes can override.
+  override readonly gatewayDefaults: GatewayMetadataValue = {
+    upstream: 'users-service',
+    timeouts: { request: '5s' },
+    auth: { required: true },
+  }
+
+  private getUser    = buildFastifyRoute(UsersController.contracts.getUser,    async (req, reply) => { /* … */ })
+  private createUser = buildFastifyRoute(UsersController.contracts.createUser, async (req, reply) => { /* … */ })
+
+  buildRoutes(): BuildRoutesReturnType<typeof UsersController.contracts> {
+    return {
+      getUser: withGatewayMetadata(UsersController.contracts.getUser, this.getUser, {
+        cache: { ttl: '60s' },
+      }),
+      createUser: withGatewayMetadata(UsersController.contracts.createUser, this.createUser, {
+        rateLimit: { requests: 10, per: '1m', key: 'ip' },
+      }),
+    }
+  }
+}
+```
+
+Then write a small script that turns the running service definition into a
+gateway config — wire it into your build / CI pipeline:
+
+```ts
+// bin/render-envoy.ts
+import { writeFileSync } from 'node:fs'
+import { renderEnvoyConfig } from '@opinionated-machine/gateway-envoy'
+import { buildContext } from '../src/diContext.ts'   // your DIContext factory
+
+const ctx = await buildContext()
+const manifest = ctx.buildGatewayManifest({
+  service: 'users-api',
+  defaults: { cors: { origins: ['https://app.example.com'], credentials: true } },
+})
+
+const { yaml, warnings } = renderEnvoyConfig(manifest, {
+  listenPort: 8080,
+  clusters: { 'users-service': { hosts: ['users:8081'] } },
+})
+
+writeFileSync('envoy.yaml', yaml)
+if (warnings.length) console.warn('[envoy]', warnings)
+```
+
+```sh
+$ tsx bin/render-envoy.ts && envoy --mode validate -c envoy.yaml
+configuration 'envoy.yaml' OK
+```
+
+The rest of this section unpacks each piece in detail.
+
+### Annotating Routes
+
+`withGatewayMetadata(contract, route, metadata)` takes:
+
+- the **contract** — used purely for type inference on `match.headers`,
+  `match.query` and `rateLimit.key`,
+- the **route** built by `buildFastifyRoute(...)` (or `buildApiRoute(...)`),
+- the **metadata** — see [Field Reference](#field-reference).
+
+Apply it inside `buildRoutes()` (or in the `routes` array for
+`AbstractApiController`) so every route's gateway policy is in one scannable
+block. Annotated and un-annotated routes mix freely, and your existing
+`buildFastifyRoute(...)` calls don't change at all:
+
+```ts
+buildRoutes() {
+  return {
+    getUser:    withGatewayMetadata(c.getUser,    this.getUser,    { cache: { ttl: '60s' } }),
+    createUser: withGatewayMetadata(c.createUser, this.createUser, { rateLimit: { requests: 10, per: '1m', key: 'ip' } }),
+    deleteUser: this.deleteUser,    // no per-route policy; inherits defaults
+  }
+}
+```
+
+For api-contract controllers, drop it directly into `routes`:
+
+```ts
+class UsersApiController extends AbstractApiController {
+  readonly routes = [
+    withGatewayMetadata(getUser, buildApiRoute(getUser, async (req) => /* … */), { cache: { ttl: '60s' } }),
+    buildApiRoute(deleteUser, async (req) => /* … */),
+  ]
+}
+```
+
+Annotations are invisible to Fastify — adding them never changes runtime
+behaviour, so you can introduce them gradually on an existing service.
+
+### Avoiding Repetition With Defaults
+
+Most fields you'd write per route — upstream, base timeouts, auth posture,
+shared tags — are the same across every route in a controller, or every route
+in a service. Declare them once:
+
+| Layer | Where | When to use |
+| ----- | ----- | ----------- |
+| Service-wide | `buildGatewayManifest({ defaults: … })` | Cross-cutting policy: CORS, idle timeouts, observability tags |
+| Controller   | `override readonly gatewayDefaults = { … }` | Per-controller upstream, auth posture, base timeouts |
+| Per-route    | `withGatewayMetadata(...)` | Anything specific to one endpoint |
+
+Layers deep-merge in that order: service → controller → route. **Arrays in
+later layers replace** (not append), which keeps `weights`, `tags`, and
+`match.headers` predictable.
+
+```ts
+context.buildGatewayManifest({
+  service: 'users-api',
+  defaults: {
+    timeouts: { idle: '60s', connect: '1s' },
+    cors: { origins: ['https://app.example.com'], credentials: true },
+    tags: ['users-api'],
+  },
+})
+```
+
+### Type-Safe Matching
+
+`match.headers` and `match.query` keys are inferred from the contract's
+`requestHeaderSchema` / `requestQuerySchema`. Typos and stale references
+become compile errors before you ever ship a config:
+
+```ts
+const getUser = buildRestContract({
+  method: 'get',
+  successResponseBodySchema: ResponseBody,
+  requestHeaderSchema: z.object({ 'x-trace-id': z.string() }),
+  requestPathParamsSchema: z.object({ userId: z.string() }),
+  pathResolver: (p) => `/users/${p.userId}`,
+})
+
+withGatewayMetadata(getUser, this.getUser, {
+  match: {
+    headers: {
+      'x-trace-id': { regex: '^[a-f0-9]+$' },   // ✅ type-checked against the contract
+      'x-typo':     'foo',                       // ❌ compile error
+    },
+    customHeaders: {
+      'x-cf-tenant': 'enterprise',               // ✅ explicit escape hatch for headers not in the contract
+    },
+  },
+})
+```
+
+`rateLimit.key` narrows the same way — `{ header: 'x-trace-id' }` only works
+if `'x-trace-id'` is in `requestHeaderSchema`; otherwise use
+`{ customHeader: '…' }`.
+
+### Field Reference
+
+Every field is optional. The shapes below cover the common cases — see
+[`gatewayMetadata.ts`](./lib/gateway/gatewayMetadata.ts) for the complete Zod
+schema, which is also what produces precise validation errors at generation
+time.
+
+| Field | Example | Notes |
+| ----- | ------- | ----- |
+| `upstream` | `'users-service'` | Logical cluster name; resolved to a host by the generator |
+| `timeouts` | `{ request: '5s', idle: '60s', connect: '1s' }` | Duration units: `ms` / `s` / `m` / `h` |
+| `retry` | `{ attempts: 2, on: ['5xx', 'connect-failure'], perTryTimeout: '2s' }` | |
+| `rateLimit` | `{ requests: 100, per: '1m', key: 'ip' }` | `key`: `'ip'`, `{ header }`, `{ customHeader }`, `{ query }`, `{ customQuery }` |
+| `cache` | `{ ttl: '60s', methods: ['GET'], vary: ['Accept-Language'] }` | |
+| `cors` | `{ origins: ['https://app.example.com'], credentials: true }` | |
+| `auth` | `{ required: true, jwt: { issuer: '…', audiences: ['…'], jwksUri: '…' } }` | |
+| `circuitBreaker` | `{ maxRequests: 100, maxRetries: 3 }` | |
+| `match` | `{ headers, customHeaders, query, customQuery, host }` | Rule values: bare string (exact), `{ exact }`, `{ prefix }`, `{ regex }` |
+| `rewrite` | `{ stripPrefix: '/v2' }` or `{ replacePrefix: { from: '/v1', to: '/v2' } }` | |
+| `traffic` | `{ weights: [{ upstream: 'a', weight: 80 }, { upstream: 'b', weight: 20 }] }` | Also `shadow: { upstream, percent }` |
+| `headers` | `{ request: { add: { 'x-internal': 'true' }, remove: ['cookie'] }, response: … }` | Free-form keys; typically infra headers not in the contract |
+| `tags`, `visibility` | `tags: ['users']`, `visibility: 'internal'` | Documentation / partitioning |
+| `extensions` | `{ envoy: { … }, krakend: { … }, kong: { … } }` | Vendor escape hatch; merged onto the generated route last |
+
+### Generating Gateway Configs
+
+Each generator is a pure function — manifest in, config out — so you typically
+call them from a small build-time script. Pick one or all:
+
+```ts
+import { writeFileSync } from 'node:fs'
+import { renderEnvoyConfig }   from '@opinionated-machine/gateway-envoy'
+import { renderKrakendConfig } from '@opinionated-machine/gateway-krakend'
+import { renderKongConfig }    from '@opinionated-machine/gateway-kong'
+
+const manifest = context.buildGatewayManifest({ service: 'users-api' })
+
+writeFileSync('envoy.yaml',
+  renderEnvoyConfig(manifest, {
+    listenPort: 8080,
+    clusters: { 'users-service': { hosts: ['users:8081'] } },
+  }).yaml)
+
+writeFileSync('krakend.json',
+  JSON.stringify(renderKrakendConfig(manifest, {
+    port: 8080,
+    upstreams: { 'users-service': 'http://users:8081' },
+  }).json, null, 2))
+
+writeFileSync('kong.yaml',
+  renderKongConfig(manifest, {
+    upstreams: { 'users-service': { url: 'http://users:8081' } },
+  }).yaml)
+```
+
+Each result includes `warnings: string[]` listing metadata fields the gateway
+can't natively express — log them so policy isn't silently dropped (e.g. Envoy
+doesn't ship an HTTP cache filter, so `cache.ttl` will appear in
+`warnings` under the Envoy generator). When you need a knob the universal
+model doesn't cover, hand-write it under `extensions.<vendor>` on the route —
+generators merge that block onto the rendered route last.
+
+For each gateway's full mapping table and quirks:
+
+- [`@opinionated-machine/gateway-envoy`](./packages/gateway-envoy/README.md)
+- [`@opinionated-machine/gateway-krakend`](./packages/gateway-krakend/README.md)
+- [`@opinionated-machine/gateway-kong`](./packages/gateway-kong/README.md)
+
+### Inspecting the Manifest at Runtime
+
+When you want the manifest from outside Node — a deployment CLI written in
+another language, an ops dashboard, a debug-time `curl` — register
+`fastifyGatewayPlugin`. The running service then exposes its manifest both in
+code and over HTTP:
+
+```ts
+import { fastifyGatewayPlugin } from 'opinionated-machine'
+
+await app.register(fastifyGatewayPlugin, {
+  context,                                    // your DIContext
+  defaults: { service: 'users-api' },         // service name + any service-wide defaults
+  // exposeRoute: '/__gateway/manifest',      // opt-in HTTP route; omit to keep the manifest in-process only
+})
+
+// In code, e.g. in another plugin or a graceful-shutdown drain hook:
+const manifest = app.buildGatewayManifest()
+
+// Optionally fetch over HTTP from a CLI / sibling process — only when you
+// set `exposeRoute` above. The plugin never registers an HTTP route by
+// default to avoid leaking internal routing topology to unauthenticated
+// callers; pair it with auth middleware appropriate for your service.
+//   curl http://localhost:8080/__gateway/manifest | jq '.routes'
+```
+
+The manifest is rebuilt on every call, so it always reflects the current set
+of registered controllers.
+
+### What's Not Covered
+
+- **SSE and dual-mode controllers.** Only routes from `AbstractController` and
+  `AbstractApiController` appear in the manifest today. Streaming routes still
+  proxy through every gateway, but they aren't listed.
+- **Fields a particular gateway can't natively express.** They show up in
+  `result.warnings` rather than disappearing. Reach for `extensions.<vendor>`
+  to hand-write the missing piece on a per-route basis.
+- **Runtime drift detection.** The manifest is built from your code; the
+  gateway runs separately. The generators don't compare deployed gateway
+  state against the manifest.
+

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export type { NestedPartial } from './lib/configUtils.js';
 export { type DependencyInjectionOptions, DIContext, type RegisterDependenciesParams, } from './lib/DIContext.js';
 export { ENABLE_ALL, isAnyMessageQueueConsumerEnabled, isEnqueuedJobWorkersEnabled, isJobQueueEnabled, isMessageQueueConsumerEnabled, isPeriodicJobEnabled, resolveJobQueuesEnabled, } from './lib/diConfigUtils.js';
 export * from './lib/dualmode/index.js';
+export * from './lib/gateway/index.js';
 export * from './lib/resolverFunctions.js';
 export * from './lib/routes/index.js';
 export * from './lib/sse/index.js';

package/dist/index.js

@@ -6,6 +6,8 @@ export { DIContext, } from './lib/DIContext.js';
 export { ENABLE_ALL, isAnyMessageQueueConsumerEnabled, isEnqueuedJobWorkersEnabled, isJobQueueEnabled, isMessageQueueConsumerEnabled, isPeriodicJobEnabled, resolveJobQueuesEnabled, } from './lib/diConfigUtils.js';
 // Dual-mode (SSE + JSON)
 export * from './lib/dualmode/index.js';
+// Gateway metadata & manifest
+export * from './lib/gateway/index.js';
 export * from './lib/resolverFunctions.js';
 // Routes (unified route builder)
 export * from './lib/routes/index.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAA8B,MAAM,6BAA6B,CAAA;AAC5F,OAAO,EACL,cAAc,GAKf,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,0BAA0B,GAE3B,MAAM,qCAAqC,CAAA;AAC5C,cAAc,8BAA8B,CAAA;AAE5C,OAAO,EAEL,SAAS,GAEV,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,UAAU,EACV,gCAAgC,EAChC,2BAA2B,EAC3B,iBAAiB,EACjB,6BAA6B,EAC7B,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,wBAAwB,CAAA;AAC/B,yBAAyB;AACzB,cAAc,yBAAyB,CAAA;AACvC,cAAc,4BAA4B,CAAA;AAC1C,iCAAiC;AACjC,cAAc,uBAAuB,CAAA;AACrC,MAAM;AACN,cAAc,oBAAoB,CAAA;AAClC,wBAAwB;AACxB,cAAc,wBAAwB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAA8B,MAAM,6BAA6B,CAAA;AAC5F,OAAO,EACL,cAAc,GAKf,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,0BAA0B,GAE3B,MAAM,qCAAqC,CAAA;AAC5C,cAAc,8BAA8B,CAAA;AAE5C,OAAO,EAEL,SAAS,GAEV,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,UAAU,EACV,gCAAgC,EAChC,2BAA2B,EAC3B,iBAAiB,EACjB,6BAA6B,EAC7B,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,wBAAwB,CAAA;AAC/B,yBAAyB;AACzB,cAAc,yBAAyB,CAAA;AACvC,8BAA8B;AAC9B,cAAc,wBAAwB,CAAA;AACtC,cAAc,4BAA4B,CAAA;AAC1C,iCAAiC;AACjC,cAAc,uBAAuB,CAAA;AACrC,MAAM;AACN,cAAc,oBAAoB,CAAA;AAClC,wBAAwB;AACxB,cAAc,wBAAwB,CAAA"}

package/dist/lib/AbstractController.d.ts

@@ -1,6 +1,7 @@
 import type { CommonRouteDefinition, DeleteRouteDefinition, GetRouteDefinition, PayloadRouteDefinition } from '@lokalise/api-contracts';
 import type { buildFastifyRoute } from '@lokalise/fastify-api-contracts';
 import type { z } from 'zod/v4';
+import type { GatewayMetadataValue } from './gateway/gatewayMetadata.ts';
 type AnyCommonRouteDefinition = CommonRouteDefinition<any, any, any, any, any, any, any, any>;
 type OptionalZodSchema = z.Schema | undefined;
 type FastifyPayloadRouteReturnType<RequestBody extends OptionalZodSchema, ResponseBody extends OptionalZodSchema, Path extends OptionalZodSchema, Query extends OptionalZodSchema, Headers extends OptionalZodSchema, ResponseHeaders extends OptionalZodSchema, IsNonJSONResponseExpected extends boolean, IsEmptyResponseExpected extends boolean, ResponseSchemasByStatusCode extends Record<number, any> | undefined> = ReturnType<typeof buildFastifyRoute<RequestBody, ResponseBody, Path, Query, Headers, ResponseHeaders, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>>;
@@ -10,5 +11,25 @@ export type BuildRoutesReturnType<APIContracts extends Record<string, AnyCommonR
 };
 export declare abstract class AbstractController<APIContracts extends Record<string, AnyCommonRouteDefinition>> {
     abstract buildRoutes(): BuildRoutesReturnType<APIContracts>;
+    /**
+     * Optional controller-level defaults for gateway metadata.
+     *
+     * Merged underneath per-route metadata when `DIContext.buildGatewayManifest()`
+     * assembles a manifest. Use this for fields that apply to every route in the
+     * controller (e.g. `upstream`, `auth`, baseline `timeouts`).
+     *
+     * Service-wide defaults (passed to `buildGatewayManifest({ defaults })`) sit
+     * underneath these.
+     *
+     * @example
+     * ```ts
+     * public readonly gatewayDefaults: GatewayMetadataValue = {
+     *   upstream: 'users-service',
+     *   timeouts: { request: '5s' },
+     *   auth: { required: true },
+     * }
+     * ```
+     */
+    readonly gatewayDefaults?: GatewayMetadataValue;
 }
 export {};

package/dist/lib/AbstractController.js

@@ -1,3 +1,23 @@
 export class AbstractController {
+    /**
+     * Optional controller-level defaults for gateway metadata.
+     *
+     * Merged underneath per-route metadata when `DIContext.buildGatewayManifest()`
+     * assembles a manifest. Use this for fields that apply to every route in the
+     * controller (e.g. `upstream`, `auth`, baseline `timeouts`).
+     *
+     * Service-wide defaults (passed to `buildGatewayManifest({ defaults })`) sit
+     * underneath these.
+     *
+     * @example
+     * ```ts
+     * public readonly gatewayDefaults: GatewayMetadataValue = {
+     *   upstream: 'users-service',
+     *   timeouts: { request: '5s' },
+     *   auth: { required: true },
+     * }
+     * ```
+     */
+    gatewayDefaults;
 }
 //# sourceMappingURL=AbstractController.js.map

package/dist/lib/AbstractController.js.map

@@ -1 +1 @@
-{"version":3,"file":"AbstractController.js","sourceRoot":"","sources":["../../lib/AbstractController.ts"],"names":[],"mappings":"AAsHA,MAAM,OAAgB,kBAAkB;CAIvC"}
+{"version":3,"file":"AbstractController.js","sourceRoot":"","sources":["../../lib/AbstractController.ts"],"names":[],"mappings":"AAuHA,MAAM,OAAgB,kBAAkB;IAKtC;;;;;;;;;;;;;;;;;;OAkBG;IACa,eAAe,CAAuB;CACvD"}

package/dist/lib/DIContext.d.ts

@@ -4,6 +4,7 @@ import type { FastifyInstance } from 'fastify';
 import type { AbstractModule } from './AbstractModule.js';
 import { type NestedPartial } from './configUtils.js';
 import type { ENABLE_ALL } from './diConfigUtils.js';
+import { type BuildGatewayManifestOptions, type GatewayManifest } from './gateway/index.js';
 import { type RegisterDualModeRoutesOptions, type RegisterSSERoutesOptions } from './routes/index.js';
 export type RegisterDependenciesParams<Dependencies, Config, ExternalDependencies> = {
     modules: readonly AbstractModule<unknown, ExternalDependencies>[];
@@ -38,6 +39,30 @@ export declare class DIContext<Dependencies extends object, Config extends objec
     private registerModule;
     registerDependencies(params: RegisterDependenciesParams<Dependencies, Config, ExternalDependencies>, externalDependencies: ExternalDependencies, resolveControllers?: boolean): void;
     registerRoutes(app: FastifyInstance<any, any, any, any>): void;
+    /**
+     * Build a vendor-neutral gateway manifest from all registered REST and
+     * api-contract controllers. Routes carrying gateway metadata (attached via
+     * `withGatewayMetadata()`) get that metadata merged with controller-level
+     * `gatewayDefaults` and the `defaults` passed here. Routes without any
+     * metadata still appear in the manifest with empty metadata.
+     *
+     * The returned object is JSON-serializable; pass it to a generator package
+     * like `@opinionated-machine/gateway-envoy` or
+     * `@opinionated-machine/gateway-krakend` to produce a config.
+     *
+     * SSE and dual-mode controllers are not included in v1.
+     *
+     * @example
+     * ```ts
+     * const manifest = context.buildGatewayManifest({
+     *   service: 'users-api',
+     *   defaults: { cors: { origins: ['https://app.example.com'] } },
+     * })
+     * const envoy = renderEnvoyConfig(manifest, { listenPort: 8080, clusters: { 'users-service': { hosts: ['users:8081'] } } })
+     * writeFileSync('envoy.yaml', envoy.yaml)
+     * ```
+     */
+    buildGatewayManifest(options: BuildGatewayManifestOptions): GatewayManifest;
     /**
      * Check if any SSE controllers are registered.
      * Use this to conditionally call registerSSERoutes().

package/dist/lib/DIContext.js

@@ -1,6 +1,7 @@
 import { AwilixManager } from 'awilix-manager';
 import { merge } from 'ts-deepmerge';
 import { mergeConfigAndDependencyOverrides } from './configUtils.js';
+import { buildGatewayManifestFrom, } from './gateway/index.js';
 import { buildFastifyRoute, } from './routes/index.js';
 export class DIContext {
     options;
@@ -53,7 +54,7 @@ export class DIContext {
                 targetDiConfig[name] = resolver;
             }
             else {
-                this.controllerResolvers.push(resolver);
+                this.controllerResolvers.push({ name, resolver: resolver });
             }
         }
     }
@@ -99,9 +100,9 @@ export class DIContext {
     }
     // biome-ignore lint/suspicious/noExplicitAny: we don't care about what instance we get here
     registerRoutes(app) {
-        for (const controllerResolver of this.controllerResolvers) {
+        for (const { resolver } of this.controllerResolvers) {
             // biome-ignore lint/suspicious/noExplicitAny: any controller works here
-            const controller = controllerResolver.resolve(this.diContainer);
+            const controller = resolver.resolve(this.diContainer);
             const routes = controller.buildRoutes();
             for (const route of Object.values(routes)) {
                 // Cast needed: GET/DELETE routes have body:undefined, POST/PATCH have body:unknown
@@ -116,6 +117,42 @@ export class DIContext {
             }
         }
     }
+    /**
+     * Build a vendor-neutral gateway manifest from all registered REST and
+     * api-contract controllers. Routes carrying gateway metadata (attached via
+     * `withGatewayMetadata()`) get that metadata merged with controller-level
+     * `gatewayDefaults` and the `defaults` passed here. Routes without any
+     * metadata still appear in the manifest with empty metadata.
+     *
+     * The returned object is JSON-serializable; pass it to a generator package
+     * like `@opinionated-machine/gateway-envoy` or
+     * `@opinionated-machine/gateway-krakend` to produce a config.
+     *
+     * SSE and dual-mode controllers are not included in v1.
+     *
+     * @example
+     * ```ts
+     * const manifest = context.buildGatewayManifest({
+     *   service: 'users-api',
+     *   defaults: { cors: { origins: ['https://app.example.com'] } },
+     * })
+     * const envoy = renderEnvoyConfig(manifest, { listenPort: 8080, clusters: { 'users-service': { hosts: ['users:8081'] } } })
+     * writeFileSync('envoy.yaml', envoy.yaml)
+     * ```
+     */
+    buildGatewayManifest(options) {
+        const collected = [];
+        for (const { name, resolver } of this.controllerResolvers) {
+            // biome-ignore lint/suspicious/noExplicitAny: any controller works here
+            const controller = resolver.resolve(this.diContainer);
+            collected.push({ name, kind: 'rest', controller });
+        }
+        for (const name of this.apiControllerNames) {
+            const controller = this.diContainer.resolve(name);
+            collected.push({ name, kind: 'api', controller });
+        }
+        return buildGatewayManifestFrom(collected, options);
+    }
     /**
      * Check if any SSE controllers are registered.
      * Use this to conditionally call registerSSERoutes().

package/dist/lib/DIContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"DIContext.js","sourceRoot":"","sources":["../../lib/DIContext.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DIContext.js","sourceRoot":"","sources":["../../lib/DIContext.ts"],"names":[],"mappings":"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"}

package/dist/lib/api-contracts/AbstractApiController.d.ts

@@ -1,4 +1,5 @@
 import type { RouteOptions } from 'fastify';
+import type { GatewayMetadataValue } from '../gateway/gatewayMetadata.ts';
 /**
  * Abstract base class for controllers that use the `ApiContract` API.
  *
@@ -16,4 +17,12 @@ import type { RouteOptions } from 'fastify';
  */
 export declare abstract class AbstractApiController {
     abstract readonly routes: RouteOptions[];
+    /**
+     * Optional controller-level defaults for gateway metadata.
+     *
+     * Merged underneath per-route metadata (attached via `withGatewayMetadata`)
+     * when `DIContext.buildGatewayManifest()` assembles a manifest. See
+     * `AbstractController.gatewayDefaults` for full semantics.
+     */
+    readonly gatewayDefaults?: GatewayMetadataValue;
 }

package/dist/lib/api-contracts/AbstractApiController.js

@@ -14,5 +14,13 @@
  * ```
  */
 export class AbstractApiController {
+    /**
+     * Optional controller-level defaults for gateway metadata.
+     *
+     * Merged underneath per-route metadata (attached via `withGatewayMetadata`)
+     * when `DIContext.buildGatewayManifest()` assembles a manifest. See
+     * `AbstractController.gatewayDefaults` for full semantics.
+     */
+    gatewayDefaults;
 }
 //# sourceMappingURL=AbstractApiController.js.map

package/dist/lib/api-contracts/AbstractApiController.js.map

@@ -1 +1 @@
-{"version":3,"file":"AbstractApiController.js","sourceRoot":"","sources":["../../../lib/api-contracts/AbstractApiController.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAgB,qBAAqB;CAE1C"}
+{"version":3,"file":"AbstractApiController.js","sourceRoot":"","sources":["../../../lib/api-contracts/AbstractApiController.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAgB,qBAAqB;IAGzC;;;;;;OAMG;IACa,eAAe,CAAuB;CACvD"}

package/dist/lib/api-contracts/apiRouteBuilder.js

@@ -49,7 +49,7 @@ function getSchemaForStatusCode(contract, status) {
             if (isSseResponse(anyResponse) ||
                 isTextResponse(anyResponse) ||
                 isBlobResponse(anyResponse)) {
-                return null;
+                continue;
             }
             return anyResponse;
         }
@@ -265,6 +265,15 @@ request, reply) {
 // ============================================================================
 // Internal Helpers — Schema
 // ============================================================================
+function buildResponseSchemas(contract) {
+    return Object.keys(contract.responsesByStatusCode).reduce((acc, statusCode) => {
+        const schema = getSchemaForStatusCode(contract, Number(statusCode));
+        if (schema) {
+            acc[Number(statusCode)] = schema;
+        }
+        return acc;
+    }, {});
+}
 function buildBaseSchema(contract) {
     const schema = {};
     if (contract.requestPathParamsSchema)
@@ -273,11 +282,10 @@ function buildBaseSchema(contract) {
         schema.querystring = contract.requestQuerySchema;
     if (contract.requestHeaderSchema)
         schema.headers = contract.requestHeaderSchema;
-    if ('requestBodySchema' in contract &&
-        contract.requestBodySchema !== undefined &&
-        contract.requestBodySchema !== ContractNoBody) {
+    if (contract.requestBodySchema !== undefined && contract.requestBodySchema !== ContractNoBody) {
         schema.body = contract.requestBodySchema;
     }
+    schema.response = buildResponseSchemas(contract);
     return schema;
 }
 // ============================================================================