From 0df74676675bad23ccb4c75df8103b3416d52468 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Sun, 8 Nov 2026 06:21:32 +0800 Subject: [PATCH 1/2] datagram@3 and comline@2 are the defaults Names the new defaults wherever the old ones were named, drops the "available, not the default" notes, explains the breaking bump a package taking the defaults gets on its first release after the change and how to keep the old wire, the per-package rule for the default handshake, and that comline generate works out provisional numbers without a build (runtime#15). --- docs/docs/developer/extending/encodings.md | 2 +- docs/docs/guides/idl/protocol.md | 28 +++++++---- docs/docs/guides/packages/index.md | 10 +++- docs/docs/guides/runtime/call-system.md | 17 ++++--- .../languages/rust/framing-and-wire-format.md | 9 ++-- .../typescript/framing-and-wire-format.md | 13 ++--- docs/docs/reference/congregation/config-id.md | 4 +- docs/docs/reference/languages/rust.md | 2 +- docs/docs/reference/languages/typescript.md | 2 +- docs/docs/reference/tools/cli.md | 2 +- docs/docs/reference/tools/cli/inspect.md | 2 +- docs/docs/reference/versioning.md | 14 +++++- docs/docs/reference/wire/framings/index.md | 16 +++--- docs/docs/reference/wire/handshakes/index.md | 50 ++++++++++++++----- 14 files changed, 112 insertions(+), 59 deletions(-) diff --git a/docs/docs/developer/extending/encodings.md b/docs/docs/developer/extending/encodings.md index 72af216..e897e35 100644 --- a/docs/docs/developer/extending/encodings.md +++ b/docs/docs/developer/extending/encodings.md @@ -162,7 +162,7 @@ it up. The usual [@unverified rules](../../guides/idl/protocol.md#giving-up-a-guarantee) apply to any protocol that uses it, through `wire.format`, `wire.framing` or -`@framing`, and the default `packed@1` and `datagram@2` are official so they +`@framing`, and the defaults `packed@1` and `datagram@3` are official so they don't. A missing marker is a build error, a needless one is a warning, and a consumer accepts the set with `accept_unverified`. The diagnostic names the cause: diff --git a/docs/docs/guides/idl/protocol.md b/docs/docs/guides/idl/protocol.md index 777dfb3..0923e5d 100755 --- a/docs/docs/guides/idl/protocol.md +++ b/docs/docs/guides/idl/protocol.md @@ -93,8 +93,10 @@ protocol Mail { - **`@framing`** picks the wire framing the generated code uses (what a framing is: [Call systems](../runtime/call-system.md#the-layers)). Without it, the protocol takes the package's `wire.framing` from `config.idp` - ([Wire defaults](../packages/index.md#wire-defaults)), else `"datagram@2"`, - which puts it on a [connection](#calls-in-both-directions). + ([Wire defaults](../packages/index.md#wire-defaults)), else `"datagram@3"`, + which puts it on a [connection](#calls-in-both-directions) and addresses its + calls by [wire number](../../reference/versioning.md#number). `"datagram@2"` + is the same connection, its calls addressed by position. `"jsonrpc"` (`json-rpc`, `jsonrpc-2.0`) emits a [JSON-RPC 2.0](https://www.jsonrpc.org/specification) stack, and `"datagram"` (`datagram@1`) the lockstep framing, with a client and a server @@ -115,12 +117,13 @@ protocol Mail { - **`@consumer`** is the other side, which follows from `@provider`. You don't need to write it, but if you do, it has to agree. - **`@handshake`** picks what runs on a connection before the first call: - `"comline@1"` (the default) checks that both ends share the schema, format - and framing; `"comline@2"` checks they're compatible, and takes + `"comline@2"` (the default) checks they're compatible, and takes [parameters](../../reference/wire/handshakes/index.md#parameters), as in - `{ name = "comline@2", scope = package }`; `"none"` sends and checks nothing. + `{ name = "comline@2", scope = package }`; `"comline@1"` checks that both + ends share the schema, format and framing; `"none"` sends and checks nothing. Without it, the protocol takes the package's `handshake` from `config.idp`, - else `comline@1`. + else `comline@2`, or `comline@1` in a package whose protocols aren't all on + `datagram@3` ([Handshakes](../../reference/wire/handshakes/index.md)). - **`@unverified`** says why a protocol gives up a guarantee Comline would otherwise give its peers. It's required where one is given up, as with `@handshake = "none"`; see [Giving up a guarantee](#giving-up-a-guarantee). @@ -152,15 +155,16 @@ flowchart LR - **`@provider = Client`**: the client implements it and the server calls it. **`@provider = Multiple`**: both sides implement it and either can call. - **The framing has to tell requests from replies,** since both ends now send - both. The default, `datagram@2`, does, and so does + both. The default, `datagram@3`, does, as do `datagram@2` and [JSON-RPC](#json-rpc-on-a-connection). The lockstep `datagram` can't, so a `Client` or `Multiple` protocol on it is a build error (`validation::reverse-calls-need-framing`). - **`@consumer` that disagrees with `@provider`** is a build error (`validation::provider-consumer-mismatch`). -Every protocol on `datagram@2` — all of them, unless they pick another -framing — runs on a **connection** instead of a client and a server: +Every protocol on `datagram@3` or `datagram@2` — all of them, unless they +pick another framing — runs on a **connection** instead of a client and a +server: - **One connection carries all of them.** Each side provides the protocols it implements and calls the others. The generated package `serve` takes one @@ -168,8 +172,10 @@ framing — runs on a **connection** instead of a client and a server: - **Calls can nest.** A handler receives the peer that called it, so it can call back before it answers. While a side waits for a reply, it keeps serving the peer's requests. -- **Each protocol has a number on the wire:** its position among the - package's protocols, in schema order. +- **Each protocol has a number on the wire:** on `datagram@3`, its + [wire number](../../reference/versioning.md#number), kept across versions; + on `datagram@2`, its position among the package's protocols, in schema + order. - **A connection keeps typed data of its own** (a session, a user id) that every handler on it can reach. diff --git a/docs/docs/guides/packages/index.md b/docs/docs/guides/packages/index.md index 922f220..b3d1402 100644 --- a/docs/docs/guides/packages/index.md +++ b/docs/docs/guides/packages/index.md @@ -43,13 +43,13 @@ Both ends of a connection have to frame and encode calls alike, so the package says how, once: ```idp -wire = { format = "packed@1" framing = "datagram@2" } +wire = { format = "packed@1" framing = "datagram@3" } ``` | Key | Values | Default | |---|---|---| | `format` | `"packed@1"`, `"json@1"`, `"msgpack@1"` | `"packed@1"`: fixed-width fields with no tags or names — see [`packed@1`](../../reference/wire/formats/packed@1.md) | -| `framing` | `"datagram@2"`, `"datagram"` (`"datagram@1"`), `"jsonrpc"` | `"datagram@2"`: every protocol on a [connection](../idl/protocol.md#calls-in-both-directions) | +| `framing` | `"datagram@3"`, `"datagram@2"`, `"datagram"` (`"datagram@1"`), `"jsonrpc"` | `"datagram@3"`: every protocol on a [connection](../idl/protocol.md#calls-in-both-directions), calls addressed by [wire number](../../reference/versioning.md#number) | Either key can be left out, and so can `wire`: the defaults are what a package that says nothing gets. The values are strings, quoted. @@ -57,6 +57,12 @@ that says nothing gets. The values are strings, quoted. - **`framing`** applies to every protocol with no `@framing` of its own. The build writes it into each one, so it's part of the schema, and changing it is a major change. +- **Before `datagram@3` and `comline@2` were the defaults,** a package that + said nothing got `datagram@2` and `comline@1`. Such a package's first build + after the change is a wire change, and its next release a breaking one (a + minor bump in 0.x). To keep the old wire, state it: + `wire = { framing = "datagram@2" }` and `handshake = "comline@1"`. See + [Defaults before `comline@2`](../../reference/wire/handshakes/index.md#defaults-before-comline2). - **`format`** is what the generated code encodes with: Rust's and TypeScript's `Format`. Changing it is a major change too. - **JSON-RPC carries JSON.** A package with a JSON-RPC protocol (through its diff --git a/docs/docs/guides/runtime/call-system.md b/docs/docs/guides/runtime/call-system.md index 5d142cf..fab20e0 100644 --- a/docs/docs/guides/runtime/call-system.md +++ b/docs/docs/guides/runtime/call-system.md @@ -37,8 +37,8 @@ The reply goes back the same way. Each layer is chosen separately: | Layer | What it does | Built in | Chosen by | | --- | --- | --- | --- | | **Format** | turns values into bytes | **`packed@1`** (the default: fixed-width fields, no tags or names, see [`packed@1`](../../reference/wire/formats/packed@1.md)), `json@1`, `msgpack@1` (Rust only, for now) | the package's `wire.format` | -| **Framing** | wraps a call or a reply around those bytes | **`datagram@2`** (the default, for [connections](#connections)), its lockstep first version `datagram`, and [JSON-RPC 2.0](https://www.jsonrpc.org/specification) | a protocol's `@framing`, else the package's `wire.framing` | -| **Handshake** | checks both ends agree, before the first call | **`comline@1`** (the default), `none` | a protocol's `@handshake`, else the package's `handshake` | +| **Framing** | wraps a call or a reply around those bytes | **`datagram@3`** (the default, for [connections](#connections), calls by wire number), `datagram@2` (calls by position), its lockstep first version `datagram`, and [JSON-RPC 2.0](https://www.jsonrpc.org/specification) | a protocol's `@framing`, else the package's `wire.framing` | +| **Handshake** | checks both ends agree, before the first call | **`comline@2`** (the default), `comline@1`, `none` | a protocol's `@handshake`, else the package's `handshake` | | **Transport** | carries the frames | TCP and in-memory in Rust, in-memory in TypeScript | your code, when you connect | The format, framing and handshake are part of the schema: both ends have to @@ -55,8 +55,9 @@ says. Which combinations each language supports is on its ## Handshake -Before the first call, `connect` and `serve` run the protocol's handshake. -`comline@1` exchanges one small fixed-size frame each way: +Before the first call, `connect` and `serve` run the protocol's handshake: +`comline@2` by default, which checks compatibility (below). `comline@1` +checks identity instead, and exchanges one small fixed-size frame each way: ```mermaid sequenceDiagram @@ -78,10 +79,10 @@ exchanged too, but a difference there is advisory. `comline@2` checks compatibility instead of identity. It compares each protocol's line, shape hash and wire numbers, so a newer consumer can still -call an older provider. It's in the runtime but not yet the default: -see [Handshakes](../../reference/wire/handshakes/index.md). Its companion framing, -`datagram@3`, addresses calls by wire number -([Datagram framings](../../reference/wire/framings/index.md)). +call an older provider. It's the default, with its companion framing +`datagram@3`, which addresses calls by wire number: see +[Handshakes](../../reference/wire/handshakes/index.md) and +[Datagram framings](../../reference/wire/framings/index.md). A protocol talking to a peer that can't take part (a legacy service, say) declares `@handshake = "none"` and says why with `@unverified`; see diff --git a/docs/docs/languages/rust/framing-and-wire-format.md b/docs/docs/languages/rust/framing-and-wire-format.md index 2f3231e..c6505e1 100644 --- a/docs/docs/languages/rust/framing-and-wire-format.md +++ b/docs/docs/languages/rust/framing-and-wire-format.md @@ -28,12 +28,15 @@ protocol Mail { } ``` -Three framings exist: +Four framings exist: -- **`Datagram2Framing`** (`datagram@2`, the default): every frame says whether +- **`Datagram3Framing`** (`datagram@3`, the default): every frame says whether it's a request or a reply, and which protocol it's for, so protocols run on a [connection](connections.md), where either end can call and one transport - carries them all. + carries them all. Calls are addressed by + [wire number](../../reference/versioning.md#number). +- **`Datagram2Framing`** (`datagram@2`): the same, with calls addressed by + position. The default before `datagram@3`. - **`DatagramFraming`** (`datagram`, also spelled `datagram@1`): the lockstep framing. A client sends a request and reads the next frame as its reply, one protocol per transport. A protocol on it gets a `Client` and a diff --git a/docs/docs/languages/typescript/framing-and-wire-format.md b/docs/docs/languages/typescript/framing-and-wire-format.md index 56c3d78..a1e16b1 100644 --- a/docs/docs/languages/typescript/framing-and-wire-format.md +++ b/docs/docs/languages/typescript/framing-and-wire-format.md @@ -7,12 +7,13 @@ choice, from `config.idp`'s `wire` key — see ## Framing -All three framings are implemented and wire-compatible with the Rust runtime: -`Datagram2Framing` (`datagram@2`, the default, for -[connections](connections.md)), `DatagramFraming` (the lockstep `datagram`) -and `JsonRpcFraming`. Which one generated code uses is decided at generation -time: the protocol's `@framing` annotation, else the package's `wire.framing`, -else `datagram@2` — exactly as on the +All four framings are implemented and wire-compatible with the Rust runtime: +`Datagram3Framing` (`datagram@3`, the default, for +[connections](connections.md), calls by wire number), `Datagram2Framing` +(`datagram@2`, calls by position), `DatagramFraming` (the lockstep +`datagram`) and `JsonRpcFraming`. Which one generated code uses is decided at +generation time: the protocol's `@framing` annotation, else the package's +`wire.framing`, else `datagram@3` — exactly as on the [Rust page](../rust/framing-and-wire-format.md). A lockstep `Client` / `serve` takes an optional `framing` diff --git a/docs/docs/reference/congregation/config-id.md b/docs/docs/reference/congregation/config-id.md index 293dbae..fae7d23 100644 --- a/docs/docs/reference/congregation/config-id.md +++ b/docs/docs/reference/congregation/config-id.md @@ -57,8 +57,8 @@ settings = { | `id` | 32 lowercase hex digits, random | The package's identity. `comline new` writes it, and `comline build` adds one to a package without it. A copy of the package must change it. Changing it is a major change. See [Compatibility facts](../versioning.md#compatibility-facts). | | `specification_version` | an integer, `1` | The edition of the schema language the files are written in. | | `code_generation` | `{ languages = { # = {} ... } }` | The languages the package can be generated as, each with the oldest toolchain its output must build on. `comline build` proves each one. See [Language versions](../../guides/codegen/generating-code.md#language-versions). | -| `wire` | `{ format = "..." framing = "..." }` | The format and framing every protocol uses unless it says otherwise. Defaults: `packed@1` and `datagram@2`. See [Wire defaults](../../guides/packages/index.md#wire-defaults). | -| `handshake` | `"comline@1"`, `"comline@2"` or `"none"`, or `{ name = "comline@2" scope = "package" }` to set [its parameters](../wire/handshakes/index.md#parameters) | What a protocol with no `@handshake` runs before its first call. Default `comline@1`. See [Giving up a guarantee](../../guides/idl/protocol.md#giving-up-a-guarantee). | +| `wire` | `{ format = "..." framing = "..." }` | The format and framing every protocol uses unless it says otherwise. Defaults: `packed@1` and `datagram@3`. See [Wire defaults](../../guides/packages/index.md#wire-defaults). | +| `handshake` | `"comline@1"`, `"comline@2"` or `"none"`, or `{ name = "comline@2" scope = "package" }` to set [its parameters](../wire/handshakes/index.md#parameters) | What a protocol with no `@handshake` runs before its first call. Default `comline@2`, or `comline@1` in a package whose protocols aren't all on `datagram@3`. See [Giving up a guarantee](../../guides/idl/protocol.md#giving-up-a-guarantee). | | `dependencies` | a dictionary of entries by name | Other packages this one imports, from a path or a git commit, each optionally pinned by `hash`, and what it accepts of their [`@unverified`](../../guides/idl/protocol.md#giving-up-a-guarantee) protocols (`accept_unverified`). See [Dependencies](../../guides/packages/index.md#dependencies). | | `settings` | a dictionary, or `::settings::` | The package-wide authoring policy every schema starts from. See [Settings](../../guides/idl/settings.md). | | `encodings` | a dictionary of entries by name | The formats, framings and handshakes this package defines. See [Formats and framings](../../developer/extending/encodings.md). | diff --git a/docs/docs/reference/languages/rust.md b/docs/docs/reference/languages/rust.md index fb6b9f8..ee0538b 100644 --- a/docs/docs/reference/languages/rust.md +++ b/docs/docs/reference/languages/rust.md @@ -36,7 +36,7 @@ Generator `rust#1.85.0`. | `validate_on_decode`
`validate-on-decode` | `[generate] validate_on_decode`: decoding runs the checks | ✅ supported | `validators_on_decode` | | JSON-RPC framing
`framing-jsonrpc` | `@framing = "jsonrpc"` (or as the package default) | ✅ supported | `framing_jsonrpc`, `connections_jsonrpc` | | no handshake
`handshake-none` | `@handshake = "none"` (or as the package default) | ✅ supported | `handshake_none` | -| connections
`connections` | protocols on a connection, with calls in both directions: `datagram@2` (the default), or `@provider = Client` / `Multiple` | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json`, `format_msgpack` | +| connections
`connections` | protocols on a connection, with calls in both directions: `datagram@3` (the default) or `datagram@2`, or `@provider = Client` / `Multiple` | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json`, `format_msgpack` | | `async`
`async` | `[generate] async`: connection protocols get async handlers and senders | ✅ supported | `connections_async` | | the `packed@1` format
`format-packed` | `wire.format = "packed@1"`, the default: fixed-width fields, no tags | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `connections`, `connections_async` | | the `json@1` format
`format-json` | `wire.format = "json@1"` | ✅ supported | `format_json` | diff --git a/docs/docs/reference/languages/typescript.md b/docs/docs/reference/languages/typescript.md index c840627..7dcec42 100644 --- a/docs/docs/reference/languages/typescript.md +++ b/docs/docs/reference/languages/typescript.md @@ -36,7 +36,7 @@ Generator `typescript#5.0`. | `validate_on_decode`
`validate-on-decode` | `[generate] validate_on_decode`: decoding runs the checks | ⚪ ignored: no checks are generated to run on decode yet ([core#96](https://github.com/ComlineProject/core/issues/96)) | `validators_on_decode` | | JSON-RPC framing
`framing-jsonrpc` | `@framing = "jsonrpc"` (or as the package default) | ✅ supported | `framing_jsonrpc`, `connections_jsonrpc` | | no handshake
`handshake-none` | `@handshake = "none"` (or as the package default) | ✅ supported | `handshake_none` | -| connections
`connections` | protocols on a connection, with calls in both directions: `datagram@2` (the default), or `@provider = Client` / `Multiple` | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json` | +| connections
`connections` | protocols on a connection, with calls in both directions: `datagram@3` (the default) or `datagram@2`, or `@provider = Client` / `Multiple` | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json` | | `async`
`async` | `[generate] async`: connection protocols get async handlers and senders | ⚪ ignored: handlers and senders always return Promises: the output is async either way | `connections_async` | | the `packed@1` format
`format-packed` | `wire.format = "packed@1"`, the default: fixed-width fields, no tags | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `connections`, `connections_async` | | the `json@1` format
`format-json` | `wire.format = "json@1"` | ✅ supported | `format_json` | diff --git a/docs/docs/reference/tools/cli.md b/docs/docs/reference/tools/cli.md index 52e5e4f..a1ec9a3 100644 --- a/docs/docs/reference/tools/cli.md +++ b/docs/docs/reference/tools/cli.md @@ -37,7 +37,7 @@ parse → resolve imports → validate → (freeze into .comline/) → (generate | `comline check` | Parse, resolve and validate. No `.comline/` write (beyond fetching git dependencies), no version bump — safe for editors, hooks, CI. | | `comline inspect [--json]` | Show each protocol's format, framing and handshake, with their parameters and where each came from (`@framing`/`@handshake`, `config.idp`, or core's default), then every guarantee, held or given up, with the cause, the `@unverified` reason and whether it's accepted. No `.comline/` write. `--json` prints the same as JSON. See [comline inspect](cli/inspect.md). | | `comline build [--watch] [--reconcile ]` | Compile, validate, and freeze a build into `.comline/` under a pre-release version (`0.3.0-dev.2`); print the changelog, the bump, and the next release. `--reconcile ` puts a head dropped in a Git merge back beside the current one, so the build [reconciles the two](../../guides/ir/cas.md); the output says when a build reconciled. A project with [unbounded strings or lists](../../guides/idl/types.md#every-string-and-list-has-a-maximum) fails with each position listed and the `settings` block to add; on a terminal, the build offers to write it with maxima you type in. Before freezing, proves every declared `code_generation.languages` target against this binary's generators ([Language versions](../../guides/codegen/generating-code.md#language-versions)). Releasing is `comline release`. | -| `comline generate [--target ] [--out ] [--layout ] [--mode ] [--external-std] [--no-external-std] [--validate-on-decode ] [--dry-run] [--list] [--watch]` | Validate (no freeze), then write generated code. Location/layout from [`comline.toml`](../congregation/comline-toml.md); targets from there or `config.idp`. A target can use an [external generator](../../developer/extending/generators.md) (`generator = ""`) and map [encodings](../../developer/extending/encodings.md#5-map-it-to-a-type). | +| `comline generate [--target ] [--out ] [--layout ] [--mode ] [--external-std] [--no-external-std] [--validate-on-decode ] [--dry-run] [--list] [--watch]` | Validate (no freeze), then write generated code. Wire numbers and the rest of the [facts](../versioning.md#number) come from the last build when nothing changed since, else are worked out as the next build would assign them, provisional until a release; no build is needed. Location/layout from [`comline.toml`](../congregation/comline-toml.md); targets from there or `config.idp`. A target can use an [external generator](../../developer/extending/generators.md) (`generator = ""`) and map [encodings](../../developer/extending/encodings.md#5-map-it-to-a-type). | | `comline release [1.0] [--raise --reason ] [--yes]` | Build, then release: create the version from the highest bump since the last release ([builds and releases](../versioning.md#builds-and-releases)). `--raise patch\|minor\|major` goes higher, with a `--reason` recorded with the release; it never lowers. `1.0` makes a `0.x` package stable after showing what that commits to (its protocols, and what's worth settling first). Raising to major and `1.0` ask on a terminal; without one they refuse (exit `2`) unless `--yes` (`-y`). | | `comline diff []` | Show schema changes between two built versions. Each argument is a version (`0.2.0`), a commit hash (4+ chars), or `HEAD` (`` default). | | `comline doc [--out ] [--version ] [--changelog-from ] [--format ] [--open]` | Write the package's documentation for every version (each release, dev build and the unreleased working state), each into `///` with the changelog from the version before it: Markdown pages (an index, one page per module with its `//!` header, every declaration's `///` docs and each protocol's wire summary, a changelog, an mkdocs/zensical `nav.yml`), `--format html` for a self-contained static site with the same content, a search box, a version picker and a page comparing versions, or `--format json` for the documentation model. Built versions are cached, so a run re-renders only the unreleased state and new versions; `--version` documents one built version. Defaults from [`comline.toml`](../congregation/comline-toml.md#doc)'s `[doc]`. `comline doc open []` (or `--open` after a render) opens the result with the system's default handler, rendering first if it isn't there. No `.comline/` write. See [comline doc](cli/doc.md). | diff --git a/docs/docs/reference/tools/cli/inspect.md b/docs/docs/reference/tools/cli/inspect.md index ec828f9..97c9abe 100644 --- a/docs/docs/reference/tools/cli/inspect.md +++ b/docs/docs/reference/tools/cli/inspect.md @@ -35,7 +35,7 @@ For each protocol, the package's own and then its dependencies': |---|---|---| | `from @framing`, `from @handshake` | `annotation` | The protocol's own annotation. | | `from config.idp ...` | `package_default` | The package's `wire.format`, `wire.framing` or `handshake` ([Wire defaults](../../../guides/packages/index.md#wire-defaults)). | -| `core's default` | `core_default` | Nothing named one, so core's default applies: `packed@1`, `datagram@2`, `comline@1`. | +| `core's default` | `core_default` | Nothing named one, so core's default applies: `packed@1`, `datagram@3`, `comline@2` (`comline@1` in a package whose protocols aren't all on `datagram@3`). | | `JSON-RPC's format` | `framing` | The framing is JSON-RPC and the package names no format, so the format is JSON. | A dependency's protocol shows its own package's defaults, not yours. diff --git a/docs/docs/reference/versioning.md b/docs/docs/reference/versioning.md index f0e58bc..17c2dc7 100644 --- a/docs/docs/reference/versioning.md +++ b/docs/docs/reference/versioning.md @@ -64,7 +64,8 @@ conformance vectors) and applies the **strictest** among the encodings in play. - **In play:** each protocol's framing (its `@framing`, else the package's - `wire.framing`, else `datagram@2`) and the package's format (`wire.format`, + `wire.framing`, else `datagram@3`; `datagram@2` for a version built before + that was the default) and the package's format (`wire.format`, else `json@1` under JSON-RPC, else `packed@1`), in both versions compared. A package without protocols has its defaults in play. - **Unknown encodings:** one whose profile the comparison can't read (any @@ -255,6 +256,12 @@ version's facts, never in the schema. whatever neither released. - **Never reused.** When an item is removed, its number is retired. A re-added item gets a new number. A renamed protocol keeps its number. +- **Generated without a build.** `comline generate` takes the numbers from + the last build when the schemas haven't changed since. Otherwise it works + them out as the next `comline build` would, against the last release and + every retired number, and writes nothing. A package that was never built + generates too. Like a build's, those numbers are provisional until + `comline release`. **`@id = N`** (decimal, 0 to 65535) on a protocol or a function writes its number out. It's optional: Comline numbers everything anyway. @@ -337,7 +344,10 @@ in `encodings`, its profile's hash. Lines, sinces and numbers need history, so each build records them in its commit as a `facts` blob beside `config` and `docs`. The blob also records the format, framing and handshake each protocol used, resolved at that build, so a later change to core's -defaults can't change how the version reads. The schema blobs, `schema_ir_hash` +defaults can't change how the version reads. A version that recorded none was +built before `datagram@3` and `comline@2` were the defaults, and reads as +`datagram@2` and `comline@1` wherever it stated nothing: see +[Defaults before `comline@2`](wire/handshakes/index.md#defaults-before-comline2). The schema blobs, `schema_ir_hash` and generated code don't change. A version built before facts were recorded gets them computed from its history when read, as does one recorded before numbers were (its stored lines and sinces are kept), and recomputing a stored blob diff --git a/docs/docs/reference/wire/framings/index.md b/docs/docs/reference/wire/framings/index.md index 0a53d38..9ebdd65 100644 --- a/docs/docs/reference/wire/framings/index.md +++ b/docs/docs/reference/wire/framings/index.md @@ -1,13 +1,13 @@ # Framings -How a call and its reply are framed on a connection: `datagram@2`, the -default, and `datagram@3`, which addresses a call by wire numbers. - -!!! note "`datagram@3` is available, not the default" - The runtime ships `datagram@3`, and core declares it, so a package can - name it ([runtime#15](https://github.com/ComlineProject/runtime/issues/15)). - The generators don't emit wire numbers for it yet. Core makes it the - default after they do. Until then, packages keep `datagram@2`. +How a call and its reply are framed on a connection: `datagram@3`, the +default, which addresses a call by wire numbers, and `datagram@2`, which +addresses it by position. + +Before `datagram@3` became the default, a package that took the defaults ran +on `datagram@2`. Its first build after the change is a wire change, and its +next release a breaking one. Stating `wire = { framing = "datagram@2" }` keeps +the old wire. See [Defaults before `comline@2`](../handshakes/index.md#defaults-before-comline2). Both framings carry frames in either direction, so either end can start a call, and several protocols can share one connection. Every frame starts diff --git a/docs/docs/reference/wire/handshakes/index.md b/docs/docs/reference/wire/handshakes/index.md index 8f741ef..1b19ba0 100644 --- a/docs/docs/reference/wire/handshakes/index.md +++ b/docs/docs/reference/wire/handshakes/index.md @@ -1,22 +1,24 @@ # Handshakes What two ends exchange when a connection opens, before the first call: -`comline@1`, the default, and `comline@2`, which checks compatibility -instead of identity. - -!!! note "`comline@2` is available, not the default" - The runtime ships `comline@2`, and core declares it, so a package can name - it ([runtime#15](https://github.com/ComlineProject/runtime/issues/15)). - The generators don't embed the facts it needs yet. Core makes it the - default after they do, as it did for `datagram@2`. `comline@1` stays - available. +`comline@2`, the default, which checks compatibility, and `comline@1`, which +checks identity. + +`comline@2` is the default where all of a package's protocols are on +`datagram@3`, which is every package that takes the defaults. It runs one +handshake per connection, so a package whose protocols can't share one +(one on `jsonrpc`, `datagram@2` or a lockstep framing, say, or one naming +another handshake) gets `comline@1` for every protocol that names none, as +before. A package's `handshake` in `config.idp` overrides both. See +[Defaults before `comline@2`](#defaults-before-comline2) for what the change +of default means for a released package. ## Official handshakes | Name | Does | Gives up | | --- | --- | --- | -| `comline@1` (the default) | exchanges and checks schema, format and framing | nothing | -| `comline@2` | exchanges each version's facts, and decides by each protocol's line | nothing, unless `same_version_differs = warn`: then version honesty | +| `comline@2` (the default) | exchanges each version's facts, and decides by each protocol's line | nothing, unless `same_version_differs = warn`: then version honesty | +| `comline@1` | exchanges and checks schema, format and framing | nothing | | `none` | sends and checks nothing | schema agreement and encoding agreement | `none` is the absence of a handshake, so it is not declared anywhere. @@ -24,7 +26,7 @@ instead of identity. ## Usage resolution A protocol's `@handshake` is picked first, then its package's `handshake` key in `config.idp`, then the official default -(which is `comline@1`): +(`comline@2`, or `comline@1` in a package whose protocols can't all run `comline@2`): ```ids @handshake = "com.acme.hello@1" @@ -243,3 +245,27 @@ The `handshake-comline2` vectors in the runtime's corpus `comline@2`'s profile states `schema_agreement` and `encoding_agreement`, proven by an accepted peer and by peers refused for a moved line, another package, other encodings or another exchange. + +## Defaults before `comline@2` + +Until `comline@2` became the default, a protocol that named no handshake ran +`comline@1`, on `datagram@2`. A version built then is read as it was built: +its facts record the encodings it used, and one built before they were +recorded reads as `datagram@2` and `comline@1`, never as today's defaults. + +So a package that takes the defaults shows a wire change on its first build +after the change: each protocol's framing and handshake change, its line +moves, and the next release takes a breaking bump (a minor one in 0.x). A +peer built from an older release refuses it, as it would any wire change. + +To keep the old wire instead, state it in `config.idp`: + +```idp +wire = { framing = "datagram@2" } +handshake = "comline@1" +``` + +A package that states them sees no change: not in its IR, its facts or its +version. Either can also be stated on its own, per protocol, with +`@framing` and `@handshake`. + From a7a8057469f0621cf87bc63b2a62cc9226968917 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Sun, 8 Nov 2026 06:34:28 +0800 Subject: [PATCH 2/2] languages: regenerate the support pages from the conformance results --- docs/docs/reference/languages/index.md | 8 ++++-- docs/docs/reference/languages/rust.md | 32 ++++++++++++--------- docs/docs/reference/languages/typescript.md | 30 ++++++++++--------- 3 files changed, 41 insertions(+), 29 deletions(-) diff --git a/docs/docs/reference/languages/index.md b/docs/docs/reference/languages/index.md index 3de883c..33b4c1d 100644 --- a/docs/docs/reference/languages/index.md +++ b/docs/docs/reference/languages/index.md @@ -88,13 +88,15 @@ commit. A runtime's suite runs every example against it: | `validate_on_decode`
`validate-on-decode` | ✅ supported | ⚪ ignored: no checks are generated to run on decode yet ([core#96](https://github.com/ComlineProject/core/issues/96)) | | JSON-RPC framing
`framing-jsonrpc` | ✅ supported | ✅ supported | | no handshake
`handshake-none` | ✅ supported | ✅ supported | +| `datagram@3` framing
`framing-datagram3` | ✅ supported | ✅ supported | +| `comline@2` handshake
`handshake-comline2` | ✅ supported | ✅ supported | | connections
`connections` | ✅ supported | ✅ supported | | `async`
`async` | ✅ supported | ⚪ ignored: handlers and senders always return Promises: the output is async either way | | the `packed@1` format
`format-packed` | ✅ supported | ✅ supported | | the `json@1` format
`format-json` | ✅ supported | ✅ supported | | the `msgpack@1` format
`format-msgpack` | ✅ supported | ❌ unsupported: `@comline/runtime` has no MessagePack codec yet | -| bounds
`bounds` | ⚪ ignored: a bounded string is a `String` and a bounded list a `Vec`; nothing checks the maximum yet ([core#98](https://github.com/ComlineProject/core/issues/98)) | ⚪ ignored: a bounded string is a `string` and a bounded list an array; nothing checks the maximum yet ([core#98](https://github.com/ComlineProject/core/issues/98)) | -| single characters
`chars` | ❌ unsupported: no wire format carries a single `char` yet ([core#98](https://github.com/ComlineProject/core/issues/98)) | ❌ unsupported: no wire format carries a single `char` yet ([core#98](https://github.com/ComlineProject/core/issues/98)) | +| bounds
`bounds` | ✅ supported | ✅ supported | +| single characters
`chars` | ✅ supported | ✅ supported | @@ -110,6 +112,8 @@ commit. A runtime's suite runs every example against it: | envelope
`envelope` | ✅ supported | ✅ supported | | datagram framing
`framing-datagram` | ✅ supported | ✅ supported | | datagram@2 framing
`framing-datagram2` | ✅ supported | ✅ supported | +| datagram@3 framing
`framing-datagram3` | ✅ supported | ✅ supported | +| comline@2 handshake
`handshake-comline2` | ✅ supported | ❌ unsupported: Comline2Handshake runs on the Comline core (ABI 0.2), whose C and Node replays in the runtime repo prove these vectors; this harness doesn't drive the core's steps itself yet | | stream framing
`stream` | ✅ supported | ❌ unsupported: no length-prefixed framing or frame limit yet: the transports are message-oriented ([comline-typescript#80](https://github.com/ComlineProject/comline-typescript/issues/80)) | | JSON-RPC framing
`framing-jsonrpc` | ✅ supported | ✅ supported | | JSON wire format
`format-json` | ✅ supported | 🟡 partial: decoding doesn't check enum variants or integer ranges ([comline-typescript#57](https://github.com/ComlineProject/comline-typescript/issues/57)) | diff --git a/docs/docs/reference/languages/rust.md b/docs/docs/reference/languages/rust.md index ee0538b..19dbfce 100644 --- a/docs/docs/reference/languages/rust.md +++ b/docs/docs/reference/languages/rust.md @@ -16,7 +16,7 @@ Generator `rust#1.85.0`. | Feature | What it covers | State | Proven by | |---|---|---|---| -| structs
`structs` | `struct` declarations | ✅ supported | `primitives`, `optional_and_arrays`, `type_refs`, `protocol`, `shapes`, `cross_schema`, `import_alias`, `import_glob`, `nested_namespace`, `external_std`, `validators`, `validators_on_decode`, `format_json`, `format_msgpack`, `bounds` | +| structs
`structs` | `struct` declarations | ✅ supported | `primitives`, `optional_and_arrays`, `type_refs`, `protocol`, `shapes`, `cross_schema`, `import_alias`, `import_glob`, `nested_namespace`, `external_std`, `validators`, `validators_on_decode`, `format_json`, `format_msgpack`, `bounds`, `chars` | | enums
`enums` | `enum` declarations | ✅ supported | `enum_basic` | | optional fields
`optional-fields` | fields marked `optional` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode`, `bounds` | | arrays
`arrays` | variable-length arrays, `T[]` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode`, `bounds` | @@ -25,7 +25,7 @@ Generator `rust#1.85.0`. | unions
`unions` | `union(A B ...)` types | ❌ unsupported: Rust has no anonymous sum type to render one as | `unions` | | type aliases
`type-aliases` | `type Name = ...` declarations | ✅ supported | `validators`, `validators_on_decode`, `bounds` | | constants
`constants` | `const` declarations | ✅ supported | `constant`, `shapes`, `validators`, `validators_on_decode` | -| protocols
`protocols` | `protocol` declarations and their functions | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `framing_jsonrpc`, `handshake_none`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json`, `format_msgpack` | +| protocols
`protocols` | `protocol` declarations and their functions | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `framing_jsonrpc`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json`, `format_msgpack` | | errors
`errors` | `error` declarations | ✅ supported | `protocol`, `error_shapes`, `format_json`, `format_msgpack` | | functions that throw
`throws` | functions declared with `! Error` | ✅ supported | `protocol`, `error_shapes`, `format_json`, `format_msgpack` | | validators
`validators` | `@validators` on fields and type aliases, checked in generated code | ✅ supported | `validators`, `validators_on_decode` | @@ -36,13 +36,15 @@ Generator `rust#1.85.0`. | `validate_on_decode`
`validate-on-decode` | `[generate] validate_on_decode`: decoding runs the checks | ✅ supported | `validators_on_decode` | | JSON-RPC framing
`framing-jsonrpc` | `@framing = "jsonrpc"` (or as the package default) | ✅ supported | `framing_jsonrpc`, `connections_jsonrpc` | | no handshake
`handshake-none` | `@handshake = "none"` (or as the package default) | ✅ supported | `handshake_none` | -| connections
`connections` | protocols on a connection, with calls in both directions: `datagram@3` (the default) or `datagram@2`, or `@provider = Client` / `Multiple` | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json`, `format_msgpack` | +| `datagram@3` framing
`framing-datagram3` | `@framing = "datagram@3"` (or as the package default): calls addressed by wire numbers | ✅ supported | `framing_datagram3`, `handshake_comline2` | +| `comline@2` handshake
`handshake-comline2` | `@handshake = "comline@2"` (or as the package default): compatibility checked by each version's facts, calls the peer lacks failing locally | ✅ supported | `handshake_comline2` | +| connections
`connections` | protocols on a connection, with calls in both directions: `datagram@3` (the default) or `datagram@2`, or `@provider = Client` / `Multiple` | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json`, `format_msgpack` | | `async`
`async` | `[generate] async`: connection protocols get async handlers and senders | ✅ supported | `connections_async` | -| the `packed@1` format
`format-packed` | `wire.format = "packed@1"`, the default: fixed-width fields, no tags | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `connections`, `connections_async` | +| the `packed@1` format
`format-packed` | `wire.format = "packed@1"`, the default: fixed-width fields, no tags | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `connections`, `connections_async` | | the `json@1` format
`format-json` | `wire.format = "json@1"` | ✅ supported | `format_json` | | the `msgpack@1` format
`format-msgpack` | `wire.format = "msgpack@1"` | ✅ supported | `format_msgpack` | -| bounds
`bounds` | a maximum or exact length on a string or list (`char[max 64]`, `char[8]`, `T[max N]`), or a depth limit (`@max_depth`): checked while decoding and encoding | ⚪ ignored: a bounded string is a `String` and a bounded list a `Vec`; nothing checks the maximum yet ([core#98](https://github.com/ComlineProject/core/issues/98)) | `bounds` | -| single characters
`chars` | `char`: one Unicode scalar value | ❌ unsupported: no wire format carries a single `char` yet ([core#98](https://github.com/ComlineProject/core/issues/98)) | `chars` | +| bounds
`bounds` | a maximum or exact length on a string or list (`char[max 64]`, `char[8]`, `T[max N]`), or a depth limit (`@max_depth`): checked while decoding and encoding | ✅ supported | `bounds` | +| single characters
`chars` | `char`: one Unicode scalar value | ✅ supported | `chars` | @@ -60,16 +62,18 @@ Runtime `rust`. | Feature | What it covers | State | Proven by | |---|---|---|---| -| name hash
`name-hash` | FNV-1a 64 of a wire format or framing name, as the handshake carries it | ✅ supported | [8 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/name-hash.json) | -| handshake
`handshake` | the fixed 31-byte frame each side sends first: magic, version, IR hash, wire format, framing, capabilities | ✅ supported | [13 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/handshake.json) | +| name hash
`name-hash` | FNV-1a 64 of a wire format or framing name, as the handshake carries it | ✅ supported | [9 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/name-hash.json) | +| handshake
`handshake` | the fixed 31-byte frame each side sends first: magic, version, IR hash, wire format, framing, capabilities | ✅ supported | [14 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/handshake.json) | | envelope
`envelope` | a response's outcome: ok with a payload, an error ordinal with its body, or a provider fault | ✅ supported | [8 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/envelope.json) | -| datagram framing
`framing-datagram` | Comline's own binary framing of requests and responses | ✅ supported | [9 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram.json) | -| datagram@2 framing
`framing-datagram2` | the datagram framing with a request/reply kind and a protocol number, for calls in both directions and several protocols on one connection | ✅ supported | [12 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram2.json) | +| datagram framing
`framing-datagram` | Comline's own binary framing of requests and responses | ✅ supported | [12 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram.json) | +| datagram@2 framing
`framing-datagram2` | the datagram framing with a request/reply kind and a protocol number, for calls in both directions and several protocols on one connection | ✅ supported | [16 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram2.json) | +| datagram@3 framing
`framing-datagram3` | the datagram framing that addresses a call by its protocol's and function's wire numbers, both varints (calls = by_id); replies as datagram@2 | ✅ supported | [18 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram3.json) | +| comline@2 handshake
`handshake-comline2` | the compatibility-checking handshake: its hello, answer and verdict messages, and its negotiation steps under every parameter, with every refusal reason | ✅ supported | [66 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/handshake-comline2.json) | | stream framing
`stream` | frames on a byte stream (TCP, a pipe): each behind a u32 little-endian length prefix, refused over the limit, by default 16 MiB (16777216 bytes) in every runtime | ✅ supported | [24 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/stream.json) | -| JSON-RPC framing
`framing-jsonrpc` | JSON-RPC 2.0 requests and responses, a fault as -32603 | ✅ supported | [26 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-jsonrpc.json) | -| JSON wire format
`format-json` | values as UTF-8 JSON: a struct as an object | ✅ supported | [48 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-json.json) | -| MessagePack wire format
`format-msgpack` | values as MessagePack: a struct as an array | ✅ supported | [48 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-msgpack.json) | -| packed wire format
`format-packed` | values as packed@1: fixed-width fields back to back, varint lengths, no tags | ✅ supported | [59 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-packed.json) | +| JSON-RPC framing
`framing-jsonrpc` | JSON-RPC 2.0 requests and responses, a fault as -32603 | ✅ supported | [62 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-jsonrpc.json) | +| JSON wire format
`format-json` | values as UTF-8 JSON: a struct as an object | ✅ supported | [96 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-json.json) | +| MessagePack wire format
`format-msgpack` | values as MessagePack: a struct as an array | ✅ supported | [98 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-msgpack.json) | +| packed wire format
`format-packed` | values as packed@1: fixed-width fields back to back, varint lengths, no tags | ✅ supported | [110 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-packed.json) | diff --git a/docs/docs/reference/languages/typescript.md b/docs/docs/reference/languages/typescript.md index 7dcec42..f5f3db6 100644 --- a/docs/docs/reference/languages/typescript.md +++ b/docs/docs/reference/languages/typescript.md @@ -16,7 +16,7 @@ Generator `typescript#5.0`. | Feature | What it covers | State | Proven by | |---|---|---|---| -| structs
`structs` | `struct` declarations | ✅ supported | `primitives`, `optional_and_arrays`, `type_refs`, `protocol`, `shapes`, `cross_schema`, `import_alias`, `import_glob`, `nested_namespace`, `external_std`, `validators`, `validators_on_decode`, `unions`, `large_fixed_arrays_nested`, `format_json`, `bounds` | +| structs
`structs` | `struct` declarations | ✅ supported | `primitives`, `optional_and_arrays`, `type_refs`, `protocol`, `shapes`, `cross_schema`, `import_alias`, `import_glob`, `nested_namespace`, `external_std`, `validators`, `validators_on_decode`, `unions`, `large_fixed_arrays_nested`, `format_json`, `bounds`, `chars` | | enums
`enums` | `enum` declarations | ✅ supported | `enum_basic` | | optional fields
`optional-fields` | fields marked `optional` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode`, `large_fixed_arrays_nested`, `bounds` | | arrays
`arrays` | variable-length arrays, `T[]` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode`, `large_fixed_arrays_nested`, `bounds` | @@ -25,7 +25,7 @@ Generator `typescript#5.0`. | unions
`unions` | `union(A B ...)` types | ✅ supported | `unions` | | type aliases
`type-aliases` | `type Name = ...` declarations | ✅ supported | `validators`, `validators_on_decode`, `unions`, `bounds` | | constants
`constants` | `const` declarations | ✅ supported | `constant`, `shapes`, `validators`, `validators_on_decode` | -| protocols
`protocols` | `protocol` declarations and their functions | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `framing_jsonrpc`, `handshake_none`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json` | +| protocols
`protocols` | `protocol` declarations and their functions | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `framing_jsonrpc`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json` | | errors
`errors` | `error` declarations | ✅ supported | `protocol`, `error_shapes`, `format_json` | | functions that throw
`throws` | functions declared with `! Error` | ✅ supported | `protocol`, `error_shapes`, `format_json` | | validators
`validators` | `@validators` on fields and type aliases, checked in generated code | ⚪ ignored: the types are generated; the checks aren't run yet ([core#96](https://github.com/ComlineProject/core/issues/96)) | `validators`, `validators_on_decode` | @@ -36,13 +36,15 @@ Generator `typescript#5.0`. | `validate_on_decode`
`validate-on-decode` | `[generate] validate_on_decode`: decoding runs the checks | ⚪ ignored: no checks are generated to run on decode yet ([core#96](https://github.com/ComlineProject/core/issues/96)) | `validators_on_decode` | | JSON-RPC framing
`framing-jsonrpc` | `@framing = "jsonrpc"` (or as the package default) | ✅ supported | `framing_jsonrpc`, `connections_jsonrpc` | | no handshake
`handshake-none` | `@handshake = "none"` (or as the package default) | ✅ supported | `handshake_none` | -| connections
`connections` | protocols on a connection, with calls in both directions: `datagram@3` (the default) or `datagram@2`, or `@provider = Client` / `Multiple` | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json` | +| `datagram@3` framing
`framing-datagram3` | `@framing = "datagram@3"` (or as the package default): calls addressed by wire numbers | ✅ supported | `framing_datagram3`, `handshake_comline2` | +| `comline@2` handshake
`handshake-comline2` | `@handshake = "comline@2"` (or as the package default): compatibility checked by each version's facts, calls the peer lacks failing locally | ✅ supported | `handshake_comline2` | +| connections
`connections` | protocols on a connection, with calls in both directions: `datagram@3` (the default) or `datagram@2`, or `@provider = Client` / `Multiple` | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json` | | `async`
`async` | `[generate] async`: connection protocols get async handlers and senders | ⚪ ignored: handlers and senders always return Promises: the output is async either way | `connections_async` | -| the `packed@1` format
`format-packed` | `wire.format = "packed@1"`, the default: fixed-width fields, no tags | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `connections`, `connections_async` | +| the `packed@1` format
`format-packed` | `wire.format = "packed@1"`, the default: fixed-width fields, no tags | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `framing_datagram3`, `handshake_comline2`, `connections`, `connections_async` | | the `json@1` format
`format-json` | `wire.format = "json@1"` | ✅ supported | `format_json` | | the `msgpack@1` format
`format-msgpack` | `wire.format = "msgpack@1"` | ❌ unsupported: `@comline/runtime` has no MessagePack codec yet | `format_msgpack` | -| bounds
`bounds` | a maximum or exact length on a string or list (`char[max 64]`, `char[8]`, `T[max N]`), or a depth limit (`@max_depth`): checked while decoding and encoding | ⚪ ignored: a bounded string is a `string` and a bounded list an array; nothing checks the maximum yet ([core#98](https://github.com/ComlineProject/core/issues/98)) | `bounds` | -| single characters
`chars` | `char`: one Unicode scalar value | ❌ unsupported: no wire format carries a single `char` yet ([core#98](https://github.com/ComlineProject/core/issues/98)) | `chars` | +| bounds
`bounds` | a maximum or exact length on a string or list (`char[max 64]`, `char[8]`, `T[max N]`), or a depth limit (`@max_depth`): checked while decoding and encoding | ✅ supported | `bounds` | +| single characters
`chars` | `char`: one Unicode scalar value | ✅ supported | `chars` | @@ -60,16 +62,18 @@ Runtime `typescript`. | Feature | What it covers | State | Proven by | |---|---|---|---| -| name hash
`name-hash` | FNV-1a 64 of a wire format or framing name, as the handshake carries it | ✅ supported | [8 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/name-hash.json) | -| handshake
`handshake` | the fixed 31-byte frame each side sends first: magic, version, IR hash, wire format, framing, capabilities | ✅ supported | [13 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/handshake.json) | +| name hash
`name-hash` | FNV-1a 64 of a wire format or framing name, as the handshake carries it | ✅ supported | [9 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/name-hash.json) | +| handshake
`handshake` | the fixed 31-byte frame each side sends first: magic, version, IR hash, wire format, framing, capabilities | ✅ supported | [14 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/handshake.json) | | envelope
`envelope` | a response's outcome: ok with a payload, an error ordinal with its body, or a provider fault | ✅ supported | [8 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/envelope.json) | -| datagram framing
`framing-datagram` | Comline's own binary framing of requests and responses | ✅ supported | [9 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram.json) | -| datagram@2 framing
`framing-datagram2` | the datagram framing with a request/reply kind and a protocol number, for calls in both directions and several protocols on one connection | ✅ supported | [12 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram2.json) | +| datagram framing
`framing-datagram` | Comline's own binary framing of requests and responses | ✅ supported | [12 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram.json) | +| datagram@2 framing
`framing-datagram2` | the datagram framing with a request/reply kind and a protocol number, for calls in both directions and several protocols on one connection | ✅ supported | [16 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram2.json) | +| datagram@3 framing
`framing-datagram3` | the datagram framing that addresses a call by its protocol's and function's wire numbers, both varints (calls = by_id); replies as datagram@2 | ✅ supported | [18 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram3.json) | +| comline@2 handshake
`handshake-comline2` | the compatibility-checking handshake: its hello, answer and verdict messages, and its negotiation steps under every parameter, with every refusal reason | ❌ unsupported: Comline2Handshake runs on the Comline core (ABI 0.2), whose C and Node replays in the runtime repo prove these vectors; this harness doesn't drive the core's steps itself yet | — | | stream framing
`stream` | frames on a byte stream (TCP, a pipe): each behind a u32 little-endian length prefix, refused over the limit, by default 16 MiB (16777216 bytes) in every runtime | ❌ unsupported: no length-prefixed framing or frame limit yet: the transports are message-oriented ([comline-typescript#80](https://github.com/ComlineProject/comline-typescript/issues/80)) | — | -| JSON-RPC framing
`framing-jsonrpc` | JSON-RPC 2.0 requests and responses, a fault as -32603 | ✅ supported | [26 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-jsonrpc.json) | -| JSON wire format
`format-json` | values as UTF-8 JSON: a struct as an object | 🟡 partial: decoding doesn't check enum variants or integer ranges ([comline-typescript#57](https://github.com/ComlineProject/comline-typescript/issues/57))
fails: `format-json/decode-unknown-variant`, `format-json/decode-wider-integer-overflow` | [46 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-json.json) | +| JSON-RPC framing
`framing-jsonrpc` | JSON-RPC 2.0 requests and responses, a fault as -32603 | ✅ supported | [62 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-jsonrpc.json) | +| JSON wire format
`format-json` | values as UTF-8 JSON: a struct as an object | 🟡 partial: decoding doesn't check enum variants or integer ranges ([comline-typescript#57](https://github.com/ComlineProject/comline-typescript/issues/57))
fails: `format-json/decode-unknown-variant`, `format-json/decode-wider-integer-overflow` | [94 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-json.json) | | MessagePack wire format
`format-msgpack` | values as MessagePack: a struct as an array | ❌ unsupported: JSON and packed@1 ship | — | -| packed wire format
`format-packed` | values as packed@1: fixed-width fields back to back, varint lengths, no tags | ✅ supported | [59 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-packed.json) | +| packed wire format
`format-packed` | values as packed@1: fixed-width fields back to back, varint lengths, no tags | ✅ supported | [110 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-packed.json) |