Skip to content

facts: Hello entries per protocol - #160

Merged
Kinflou merged 1 commit into
masterfrom
hello/per-protocol-entries
Nov 16, 2026
Merged

Kinflou merged 1 commit into
masterfrom
hello/per-protocol-entries

Conversation

@Kinflou

@Kinflou Kinflou commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Closes #153. Part of the smaller step in core#288 (named connections, decided). Adds facts only: nothing a generator emits today changes.

The change

facts::hello builds one Hello for the package's whole connection, which the generators embed as HELLO. facts::hello_parts gives what that Hello is built from, kept apart, so generated accept / connect can build the Hello of the protocols actually provided and called (runtime#124, comline-rust#133, comline-typescript#173).

HelloParts, once per connection:

  • exchange (offer / symmetric), package (the id, 16 bytes), version and pre;
  • encodings: HelloEncoding { kind, hash } (0 format, 1 framing, 2 handshake), the connection's, the same whichever protocols a Hello lists;
  • protocols: one HelloEntry per protocol on the package connection.

HelloEntry, per protocol: namespace, name, number, line (as the facts spell it) and release (as numbers), shape_hash (16 bytes), functions (name and wire number, in declaration order, for comments and lookups) with function_numbers() (ascending, once each, as the wire lists them), and provider (@provider). A Hello entry carries no direction on the wire; provider is for the generated code, which checks that a side provides only what it provides (settled on runtime#124).

HelloParts::assemble(entries) puts any subset in canonical order: encodings ascending by kind then hash, protocols ascending by wire number, function numbers ascending. The order the protocols are given in, and a protocol given twice, don't reach the wire. assemble_all() lists every entry.

What stays

facts::hello and its output are unchanged: no line of it is touched, and hello_parts is a second path to the same bytes, with the same refusals in the same words. The generators keep using hello until comline-rust#133 and comline-typescript#173 switch over; it can go then.

Byte identity

conformance/tests/hello_entries.rs, on the request each generator gets (Rust and TypeScript encodings alike):

  • for every fixture in the corpus whose connection runs comline@2, hello_parts(..).assemble_all() is hello(..)'s exact bytes, and the same protocols with the same numbers, lines and functions;
  • for each of the fifteen non-empty subsets of the new fixture, the assembled Hello is hello's output for a package of just those protocols, which keep their wire numbers. That compares against the old code, not against itself. It also checks that the encodings come out the same bytes in every Hello, and that order and repeats don't matter.

The subset case

New corpus fixture connections_subset: two applications in one package, Chat / Events in conformance and Admin / Alerts in conformance/admin, a protocol per side in each, all on the defaults (datagram@3, comline@2). The generators bless it when they pin this.

Goldens

No existing golden changes. I checked it against both generators: each of comline-rust (22110d8) and comline-typescript (671f27e) built against this branch through a local [patch], then blessed. The only differences are the new connections_subset goldens and the "proven by" lists in their FEATURES.md / features.json, which now count the new fixture. Their corpus_matches_golden and support_is_proven fail until they bless it, which is what a corpus change does (generation#159).

`facts::hello_parts` gives what a comline@2 Hello is built from, kept apart:
the exchange, the package's id and version and the connection's encodings
once, and one entry per protocol on the connection (number, line, shape
hash, function numbers, and the provider for the generated code).
`HelloParts::assemble` puts any subset of the entries in canonical order, so
generated accept / connect can build the Hello of the protocols actually
provided and called. With every protocol it is `facts::hello`'s output, byte
for byte; `hello` is unchanged and the generators keep using it until they
switch over.

The corpus gains connections_subset: two applications in one package, a
protocol per side in each. A test checks, for every fixture in the corpus
with a Hello, that all entries assemble to `hello`'s bytes, and for every
subset of connections_subset that the assembled Hello is the package-wide
Hello of a package of just those protocols. No existing golden changes; the
generators bless the new fixture when they pin this.

Refs #153
@Kinflou
Kinflou marked this pull request as ready for review November 16, 2026 17:08
@Kinflou
Kinflou merged commit 99187d7 into master Nov 16, 2026
37 of 39 checks passed
@Kinflou
Kinflou deleted the hello/per-protocol-entries branch November 16, 2026 17:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Emit Hello entries per protocol instead of one package-wide Hello

1 participant