Skip to content

A Hello built from what an end provides and calls, and provide refusing what the handshake didn't accept - #126

Merged
Kinflou merged 2 commits into
mainfrom
hello/subset-and-provide-check
Nov 16, 2026
Merged

Kinflou merged 2 commits into
mainfrom
hello/subset-and-provide-check

Conversation

@Kinflou

@Kinflou Kinflou commented Nov 16, 2026

Copy link
Copy Markdown
Member

Closes #124. Part of the epic ComlineProject/core#288 (connections with a subset of the package's protocols), on the decisions in docs#186 and the review settled in docs#188.

Two commits. The first re-vendors the specification; the second is the runtime.

Re-vendors the specification at 3254e0e (specification#19, spec 0.12). It adds seven handshake-comline2 cases: hello-subset, offer-subset-offered, offer-subset-local, conclude-subset, conclude-answer-beyond-offer, symmetric-subset-local and finish-refused-unlisted. The reference (conformance/src/comline2.rs) writes them; the vendored file is byte-identical to what it blessed, so vectors_are_current holds. No existing case changes (checked by id: seven added, none removed or changed).

A Hello for a subset.

  • HelloHeader (exchange, package id, version, pre-release, encodings) and ProtocolEntry (number, line, shape hash, function numbers) are the structured pieces a generator emits as constants.
  • Hello::build(&header, provided, called) lists the union of the two sets, each protocol once (the first entry for a number), in canonical() order. The header's encodings and each entry's functions are sorted and deduplicated.
  • The runtime doesn't know direction, so it doesn't default the called set: the generator passes the other side's protocols, or fewer if the application narrowed it.
  • With every protocol the bytes are the whole Hello's. A test builds the specification's hello vector's bytes from every split of its two protocols, in either order, listed twice, with the functions scrambled, and hello-subset's from protocol 1 alone.

provide refuses what the handshake didn't accept.

  • Negotiated::accepts(protocol): this end's result holds it and it isn't refused. That is the set whose calls already fail locally. check_provide returns RuntimeError::Unavailable for the rest.
  • Handshake and AsyncHandshake gain agreed(), None by default; Comline2Handshake returns its negotiated(). connect_with / accept_with keep it on the connection. Nothing to change for a custom handshake.
  • Connection::provide and AsyncConnection::provide now return Result<(), RuntimeError> and check it. Without a comline@2 Hello (comline@1, none, new_unverified) nothing is checked and they take any protocol, as today.
  • The error is the existing Unavailable, which is already what a protocol outside the result gives a call. A caller that wants the reason reads the Negotiated it holds (the generated Negotiation has it).
  • No direction check: an entry carries none, so that stays with the generated code, which knows @provider.

Breaking, on purpose. provide returned (); it returns a Result now, so a generated provide_on that ends in conn.provide(..) stops compiling at the next bump until it returns the Result. That belongs to the generators (comline-rust#133); the call sites in this repository's tests are updated. JSON-RPC (comline@1) is untouched.

Senders. Confirmed in comline-rust's generator: sync and async senders both call the generated check_call before writing a request, which is Negotiated::check_call, and a protocol the result doesn't hold is Unavailable. The runtime-side test below holds the contract (the specification's ops can't ask about it; specification#20 may make these cases).

Tests (core/tests/comline2_subset.rs):

  • the Hello built whole is the hello vector's bytes however the protocols are split, a subset is hello-subset, encodings reach the wire in order, and the header's version and exchange are the Hello's;
  • providing refuses a protocol the Hello didn't list, one the peer refused as unknown_protocol, one refused for a line mismatch, and accepts the rest, on a blocking and an async connection, in both exchanges;
  • no check on new_unverified or comline@1, blocking and async;
  • a call to a protocol outside the result fails with Unavailable and writes nothing to a counting transport; one the Hello listed is written.

Not run locally; CI is the check.

Kinflou added 2 commits November 17, 2026 01:20
Vendors ComlineProject/specification at 3254e0e (#19). It adds seven
`handshake-comline2` cases for a Hello that lists some of the package's
protocols: `hello-subset`, `offer-subset-offered`, `offer-subset-local`,
`conclude-subset`, `conclude-answer-beyond-offer`, `symmetric-subset-local`
and `finish-refused-unlisted`. No existing case changes.

The vectors are written by the reference (`conformance/src/comline2.rs`), which
gains the cases; the re-vendored file is byte-identical to what it blessed, and
the report lists them.
…shake didn't accept

A Hello can list some of the package's protocols (named connections,
core#288): what an end provides plus the ones it calls.

- `Hello::build(header, provided, called)` puts a Hello together from a
  `HelloHeader` (exchange, package id, version, encodings) and the
  `ProtocolEntry`s of what the end provides and calls, in `canonical()` order,
  each protocol once. A generator emits the header and the entries as constants
  and passes the ones it wants. With every protocol among them the bytes are
  the whole Hello's.
- `Negotiated::accepts` / `check_provide`: whether the handshake accepted a
  protocol, that is its result holds it and it isn't refused. The protocols
  whose calls already fail locally (`check_call`).
- `Handshake` / `AsyncHandshake` gain `agreed()`, `None` unless the handshake
  negotiates per protocol (`comline@2`). `connect_with` / `accept_with` keep it
  on the connection.
- `Connection::provide` and `AsyncConnection::provide` return `Result` and
  refuse, with `RuntimeError::Unavailable`, a protocol the handshake didn't
  accept: one the Hello didn't list, or one the peer refused. Without a Hello
  (`comline@1`, `none`, `new_unverified`) there is nothing to check against and
  they take any protocol. Direction isn't checked: an entry carries none, so the
  generated code checks it.

Tests: the Hello built whole is the specification's `hello` bytes however the
protocols are split, and a subset is `hello-subset`; both refusals on blocking
and async connections in both exchanges; no check without a Hello; and calls to
a protocol outside the result fail locally with nothing written.
@Kinflou
Kinflou marked this pull request as ready for review November 16, 2026 18:47
@Kinflou
Kinflou merged commit e736221 into main Nov 16, 2026
78 of 80 checks passed
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.

A Hello built from the protocols provided and called, and provide_on limited to it

1 participant