|
| 1 | +--- |
| 2 | +"@objectstack/spec": major |
| 3 | +--- |
| 4 | + |
| 5 | +refactor(spec)!: retire `HttpServerConfigSchema` — nine documented keys with zero readers AND no way to write them (#4938) |
| 6 | + |
| 7 | +`system/http-server.zod.ts` declared `HttpServerConfigSchema` with nine keys — |
| 8 | +`port`, `host`, `cors`, `requestTimeout`, `bodyLimit`, `compression`, |
| 9 | +`security`, `static`, `trustProxy`. `authorable-surface.json` listed all nine |
| 10 | +and `content/docs/references/` rendered them as protocol documentation. Both |
| 11 | +halves of the contract were empty: |
| 12 | + |
| 13 | +- **Zero runtime readers.** No package in any repo (objectstack / cloud / |
| 14 | + objectui) ever parsed a document with this schema or read a key off it. The |
| 15 | + only non-spec mentions were "Used by:" comments in `shared/http.zod.ts` |
| 16 | + pointing back at it. |
| 17 | +- **Zero authoring entry** — worse than the ordinary declared-but-unread |
| 18 | + defect. `stack.zod.ts` had no `server:` key, `config-schema.json` had no |
| 19 | + `HttpServerConfig`, and no settings manifest carried it, so the configuration |
| 20 | + the docs promised could not even be written down, let alone take effect. |
| 21 | + |
| 22 | +What actually decides these things is three *other* shapes: the CLI `serve` |
| 23 | +arguments, the Hono adapter's `ObjectStackHonoOptions`, and |
| 24 | +`DispatcherPluginConfig.securityHeaders`. `HttpServerConfigSchema` was |
| 25 | +unacquainted with all three. Per ADR-0049 enforce-or-remove, and the 2026-08-04 |
| 26 | +ruling on #4938, the unreachable face is removed. |
| 27 | + |
| 28 | +FROM → TO, per retired key: |
| 29 | + |
| 30 | +| removed | what to do instead | |
| 31 | +|---|---| |
| 32 | +| `HttpServerConfig.port` / `.host` | the deployment owns the socket — `objectstack serve -p <port>` / `PORT` | |
| 33 | +| `HttpServerConfig.static` | the transport plugin's `staticMounts` | |
| 34 | +| `HttpServerConfig.cors` | the transport adapter — `OS_CORS_ORIGIN` / `OS_CORS_CREDENTIALS` / `OS_CORS_MAX_AGE` | |
| 35 | +| `HttpServerConfig.security.helmet` | the dispatcher plugin's `securityHeaders` (on by default) | |
| 36 | +| `HttpServerConfig.security.rateLimit` | `defineStack({ server: { security: { rateLimit } } })` — LIVE since #5006 | |
| 37 | +| `HttpServerConfig.trustProxy` | `defineStack({ server: { trustProxy } })` — LIVE since #5006 | |
| 38 | +| `HttpServerConfig.requestTimeout` / `.bodyLimit` / `.compression` | nothing consumes them; they return with an executor or not at all | |
| 39 | + |
| 40 | +Two of the nine were **activated** rather than lost: #5006 mounted |
| 41 | +`security.rateLimit` and `trustProxy` on the deliberately narrow |
| 42 | +`StackServerConfigSchema`, which grows one key at a time, each arriving with its |
| 43 | +consumer. `cors` is registered as the FIRST per-key admission candidate for that |
| 44 | +shape — embedding (`example-embed-objectql`) is a real scenario — and will |
| 45 | +arrive the #4910 way, key and executor together, rather than sitting on the |
| 46 | +export surface as a dead declaration in the meantime. |
| 47 | + |
| 48 | +The retirement kit: |
| 49 | + |
| 50 | +- **No `retiredKey()` tombstone, deliberately** — route 3 of the retirement |
| 51 | + playbook ("nothing parses it"), the shape #4834 / PR #4878 used for the kernel |
| 52 | + plugin-runtime family. A tombstone is a message to whoever writes the key, and |
| 53 | + the only surface on which anyone can write a server key is |
| 54 | + `StackServerConfigSchema`; it is `strictObject` and already rejects all seven |
| 55 | + by name. Those prescriptions were refreshed from "not authorable — no runtime |
| 56 | + reads it" to name the retirement and its replacement. |
| 57 | +- **No ADR-0087 D2 conversion**, for the same reason: there is no author source |
| 58 | + to rewrite, because the shape was never reachable from an authoring surface. |
| 59 | + The channel for code consumers is `api-surface.json` (which lost all three |
| 60 | + `HttpServerConfig*` entries) feeding the release-time `spec-changes.json` |
| 61 | + diff, plus this changeset. |
| 62 | +- Baselines updated deliberately: `json-schema.manifest.json` (−1, the #2978 |
| 63 | + ratchet fired first and demanded it), `authorable-surface.json` (−9, allowed |
| 64 | + by the #4650 gate's path 3 "def no longer emitted by this build"), |
| 65 | + `api-surface.json` (−3). Reference docs and the strictness-ledger counts |
| 66 | + regenerated. |
| 67 | +- **The container, not the file.** `RouteHandlerMetadata` (consumed by |
| 68 | + `packages/rest`) and `MiddlewareType` / `MiddlewareConfig` (consumed by |
| 69 | + `packages/runtime`) stay, as do `CorsConfigSchema`, `RateLimitConfigSchema` |
| 70 | + and `StaticMountSchema` in `shared/http.zod.ts` — each has live consumers |
| 71 | + outside the retired shape, so none of them was orphaned by it. |
| 72 | + |
| 73 | +No runtime behaviour changes — that impossibility is the reason for the removal. |
0 commit comments