@telorun/http-server 0.19.0 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @telorun/http-server
 
+## 0.20.0
+
+### Minor Changes
+
+- c8d457b: One value-type annotation: `x-telo-type` says what a value IS, and the
+  vocabulary is data both runtimes read.
+
+  Three annotations answered one question — _what is the value at this slot, beyond
+  what JSON Schema's `type` vocabulary can say?_ — and each answered it
+  differently: `x-telo-type: TcpPort` (a nominal brand from a closed kernel table),
+  `x-telo-binary: true` (raw bytes, the one annotation that emitted validation
+  code), `x-telo-stream: true` (a live handle, exempt from schema walks). They
+  differ in _posture_ toward the JSON Schema layer — refine, replace, exempt — not
+  in kind, so a fourth cost eleven files across four packages, and three defects
+  followed from the spread: an unrecognized brand degraded silently, a byte slot's
+  expression typed as `dyn` because nothing consulted `x-telo-binary`, and a module
+  string-matched the keyword because a module may import `@telorun/sdk` and there
+  was nothing there to read.
+
+  - **The vocabulary is DATA; the binding to a language is not.** A type is one
+    JSON file under `sdk/value-types/`, copied into the SDK by its `prepare` and
+    embedded by Rust with `include_str!` — the `analyzer/migrations/` arrangement,
+    for the same reason. An entry declares `name`, `representation` (`json` + a
+    `base`, or `instance` + a symbolic `binding`), `live`, `parameters` and a
+    `description`, and nothing about any runtime. Each runtime carries its own
+    table mapping `binding` to its own identity; a binding with **no row is a hard
+    startup error**, never a skipped assertion, because a type that cannot be
+    asserted would silently exempt every slot declaring it.
+  - **`registerTeloKeywords`** replaces five drifted AJV registration sites — the
+    analyzer's `createAjv` and the kernel's `schema-validator`, `resource-context`,
+    `observed-state` and `manifest-schemas`, which registered overlapping lists of
+    twelve, four, one and one. Drift there is not cosmetic: a keyword that emits
+    code was simply missing from any instance that forgot it, so one schema
+    validated two ways depending on which AJV saw it.
+  - **Exemption is a property of the TYPE, not of a position.** The old walk
+    neutralized only a key it found in a `properties` map, so an array-of-streams
+    element was reached and left constrained even though it descended into `items`.
+    Reading liveness off the declared type makes an item, a union branch and a
+    property one case. It is exemption from **validation**, never from **typing**:
+    a live type's arguments still travel through every schema-typing walk.
+  - **Value types are generic.** An entry declares named type parameters and the
+    annotation's object form supplies arguments — `{ name: Telo.Stream, of:
+Telo.Bytes }`. An argument is a schema node, so it nests with no new grammar,
+    and a bare name is sugar for a node carrying only the annotation, normalized in
+    the single reader. Comparison is **covariant and gradual**: an omitted argument
+    is _any_ in both directions, so every producer and consumer that has not
+    declared an element keeps checking exactly as it did. A definite conflict is
+    `CEL_TYPE_ARGUMENT_MISMATCH`, reported where a produced value's schema meets a
+    consuming slot's — a step's `inputs:` against the invoked target's contract,
+    which is the one place both halves are in hand.
+  - **A shape is named with `!ref`**, Telo's one reference grammar, and `use:
+schema` has been in the `x-telo-ref` vocabulary for exactly this relation all
+    along. The loader normalizes it to the canonical `telo:<module>/<Type>` `$ref`
+    — authoring surface and internal form, the split `resolveRefSentinels` and
+    `resolveSchemaRefKinds` already have. Normalizing rather than inlining is what
+    preserves schema identity (the compiled-validator cache is keyed on it) and
+    leaves a recursive shape expressible; carrying the owning module is what makes
+    resolution alias-aware, where matching a bare `metadata.name` across a
+    flattened list silently dropped the alias.
+  - **A tag's produced type is declared by its ENGINE.** `TemplatingEngine` gains
+    `producedType()`; `!include-bytes` declares `Telo.Bytes` and `!include-text`
+    declares `type: string`, and `substituteCelFields` loses its tag-name branch —
+    the only place a tag's produced type was written down, written in the consumer.
+  - **`X_TELO_TYPE_UNKNOWN`** (Levenshtein-suggested) and
+    **`X_TELO_TYPE_ARGUMENT_UNKNOWN`** replace the silent degrade, on every
+    schema-bearing field of every manifest — not only definition docs, since an
+    inline `inputType:` on an ordinary resource carries a schema too.
+  - **The migration selector gains a schema region.** `inSchema: true` bounds a
+    rule to the kernel's own schema-valued keys, and only with it may `inKind` /
+    `under` be `["*"]`, and only for a rule keyed on an `x-telo-*` annotation. That
+    pairing is the containment: an annotation keyword occurs in author-written
+    schema fragments inside ordinary resource documents, and that set of kinds is
+    open, so enumerating it would be both incomplete and a violation of the
+    topology-driven constraint.
+
+  **Breaking:** `x-telo-binary` and `x-telo-stream` are rewritten to `x-telo-type`
+  at load by the `normalize-value-types` migration, so every published manifest
+  keeps working and `telo migrate` repairs a file in place. `binaryKeyword` /
+  `isBinarySlot` / `X_TELO_BINARY` are removed from `@telorun/analyzer` in favour
+  of `registerTeloKeywords` and the SDK accessors; `withStreamPropertiesSkipped` is
+  now `withLiveValuesSkipped`. Value brands are `Telo.`-qualified (`TcpPort` →
+  `Telo.TcpPort`), which the same migration rewrites.
+
+### Patch Changes
+
+- @telorun/http-dispatch@0.4.2
+
 ## 0.19.0
 
 ### Minor Changes

package/dist/http-api-controller.js

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import { CatchEntry, dispatchCatches, dispatchReturns, ReturnEntry, validateNoContentTypeHeader, validateStreamWhenDoesNotReferenceResult, } from "@telorun/http-dispatch";
-import { InvokeError, isCancellationError, isInvokeError, Ref, Stream, } from "@telorun/sdk";
+import { InvokeError, isCancellationError, isInvokeError, isLiveSlot, Ref, Stream, } from "@telorun/sdk";
 import { fastifyReplySink } from "./fastify-reply-sink.js";
 const HttpApiRouteManifest = Type.Object({
     request: Type.Object({
@@ -61,10 +61,16 @@ export class HttpServerApi {
         const handlerName = handlerRef?.name ?? "";
         const translatedPath = joinMountPath(prefix, translateOpenApiPath(route.request.path));
         const schema = { response: {} };
-        // A stream-marked body is delivered as a raw `Stream<Uint8Array>` (see the
+        // A live-typed body is delivered as a raw `Stream<Uint8Array>` (see the
         // server's `contentTypeParsers[].stream`); it is opaque to AJV, so skip
         // body-schema registration and wrap the raw request stream in the handler.
-        const streamBody = route.request.schema?.body?.["x-telo-stream"] === true;
+        //
+        // Read through the SDK accessor rather than by string-matching the keyword.
+        // A module may import `@telorun/sdk` and nothing else, and before the value
+        // types were unified there was nothing on that surface to read — so this was
+        // a literal key comparison, the same shape as the four surfaces that
+        // string-matched `x-telo-ref` before `ref-slot.ts`.
+        const streamBody = isLiveSlot(route.request.schema?.body);
         if (route.request.schema?.query)
             schema.querystring = route.request.schema.query;
         if (route.request.schema?.params)

package/dist/http-server-controller.js

@@ -164,8 +164,35 @@ class HttpServer {
             }, { eventName: "http.server.request" });
         });
     }
+    /**
+     * Accept a multipart body out of the box.
+     *
+     * Fastify ships parsers for JSON and urlencoded and nothing else, so a route
+     * receiving a file upload answered 415 before any handler ran — a failure that
+     * names a media type the author DID send and points at no fix. Every server
+     * taking an upload had to discover `contentTypeParsers` first.
+     *
+     * Registered as RAW BYTES rather than a string, because that is what a
+     * multipart body is: decoding it as text corrupts every binary part, and the
+     * parts are the point. The handler receives the undrained request stream, which
+     * `Multipart.Decoder` consumes.
+     *
+     * Registered UNCONDITIONALLY, as a regex. Fastify keys a duplicate on the exact
+     * string (or the regex's `toString()`) and consults its string parsers before
+     * its regex ones, so a declared `multipart/form-data` neither collides with this
+     * nor is shadowed by it — it simply wins for its own type. Skipping the default
+     * whenever any multipart parser was declared would instead disable it for the
+     * SIBLING subtypes the author did not customize, so declaring a parser for
+     * `form-data` would silently restore the 415 for `related` and `mixed`.
+     */
+    installDefaultMultipartParser() {
+        this.app.addContentTypeParser(/^multipart\//, (_req, payload, done) => {
+            done(null, payload);
+        });
+    }
     async setupPlugins() {
         this.installRequestLogging();
+        this.installDefaultMultipartParser();
         for (const { contentType, parser, stream } of this.resource.contentTypeParsers ?? []) {
             if (stream) {
                 // Raw passthrough: omit `parseAs` so Fastify hands the handler the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.19.0",
+  "version": "0.26.0",
   "description": "Telo HTTP Server module - HTTP server and API resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -49,13 +49,13 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "fastify": "^5.7.2",
-    "@telorun/http-dispatch": "0.4.2"
+    "@telorun/http-dispatch": "0.11.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.70.0"
+    "@telorun/sdk": "0.75.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/http-api-controller.ts

@@ -14,6 +14,7 @@ import {
   InvokeError,
   isCancellationError,
   isInvokeError,
+  isLiveSlot,
   KindRef,
   Ref,
   ResourceContext,
@@ -95,10 +96,16 @@ export class HttpServerApi implements ResourceInstance {
 
     const schema: any = { response: {} };
 
-    // A stream-marked body is delivered as a raw `Stream<Uint8Array>` (see the
+    // A live-typed body is delivered as a raw `Stream<Uint8Array>` (see the
     // server's `contentTypeParsers[].stream`); it is opaque to AJV, so skip
     // body-schema registration and wrap the raw request stream in the handler.
-    const streamBody = route.request.schema?.body?.["x-telo-stream"] === true;
+    //
+    // Read through the SDK accessor rather than by string-matching the keyword.
+    // A module may import `@telorun/sdk` and nothing else, and before the value
+    // types were unified there was nothing on that surface to read — so this was
+    // a literal key comparison, the same shape as the four surfaces that
+    // string-matched `x-telo-ref` before `ref-slot.ts`.
+    const streamBody = isLiveSlot(route.request.schema?.body);
 
     if (route.request.schema?.query) schema.querystring = route.request.schema.query;
     if (route.request.schema?.params) schema.params = route.request.schema.params;

package/src/http-server-controller.ts

@@ -261,8 +261,36 @@ class HttpServer implements ResourceInstance {
     });
   }
 
+  /**
+   * Accept a multipart body out of the box.
+   *
+   * Fastify ships parsers for JSON and urlencoded and nothing else, so a route
+   * receiving a file upload answered 415 before any handler ran — a failure that
+   * names a media type the author DID send and points at no fix. Every server
+   * taking an upload had to discover `contentTypeParsers` first.
+   *
+   * Registered as RAW BYTES rather than a string, because that is what a
+   * multipart body is: decoding it as text corrupts every binary part, and the
+   * parts are the point. The handler receives the undrained request stream, which
+   * `Multipart.Decoder` consumes.
+   *
+   * Registered UNCONDITIONALLY, as a regex. Fastify keys a duplicate on the exact
+   * string (or the regex's `toString()`) and consults its string parsers before
+   * its regex ones, so a declared `multipart/form-data` neither collides with this
+   * nor is shadowed by it — it simply wins for its own type. Skipping the default
+   * whenever any multipart parser was declared would instead disable it for the
+   * SIBLING subtypes the author did not customize, so declaring a parser for
+   * `form-data` would silently restore the 415 for `related` and `mixed`.
+   */
+  private installDefaultMultipartParser(): void {
+    this.app.addContentTypeParser(/^multipart\//, (_req, payload, done) => {
+      done(null, payload);
+    });
+  }
+
   private async setupPlugins() {
     this.installRequestLogging();
+    this.installDefaultMultipartParser();
     for (const { contentType, parser, stream } of this.resource.contentTypeParsers ?? []) {
       if (stream) {
         // Raw passthrough: omit `parseAs` so Fastify hands the handler the