Skip to content

Services and ClientServices that take a subset - #140

Draft
Kinflou wants to merge 1 commit into
mainfrom
feat/133-subset-services
Draft

Kinflou wants to merge 1 commit into
mainfrom
feat/133-subset-services

Conversation

@Kinflou

@Kinflou Kinflou commented Nov 16, 2026

Copy link
Copy Markdown
Member

Closes #133

Services and ClientServices now take a subset of the protocols their side provides, blocking and async = true. accept / connect build the comline@2 Hello at runtime from what was given plus the protocols this side calls (every protocol of the other side, the default in the Decided section), instead of embedding the package's whole Hello.

API shape

// All provided: the struct literal, unchanged.
serve(transport, Services { chat: ChatImpl, admin: AdminImpl })

// A subset: a builder from nothing...
serve(transport, Services::new().with_chat(ChatImpl))
connect(transport, ClientServices::new().with_events(EventsImpl))

// ...or the same literal, `Absent` in the fields left out.
serve(transport, Services { chat: ChatImpl, admin: Absent })

Why this and not Option fields or a plain builder:

  • Option fields make the all-provided case longer (chat: Some(ChatImpl)), and None can't be inferred: Services<A, B> is generic over each implementation, so every omitted field needs a turbofish. That fails "as short to write as today".
  • A runtime builder (a Vec of boxed registrations) would change the all-provided literal and type-erase the dispatchers.
  • This: each field stays generic, and its bound is a hidden per-protocol trait (ProvideConformanceChat) with two impls, one for anything that implements the protocol's trait and one for Absent. Coherence holds because both the trait and Absent are local to the generated crate. Existing code that writes the literal compiles untouched. Services::new() is Services<Absent, ..> and each with_<field> swaps one type parameter, so the type of a partly built value is exact and a wrong implementation is still a compile error naming the protocol's trait. The trait carries the protocol's Hello entry as a const (Absent has none), so what is listed is decided by the types, with no runtime flags.
  • with_ prefixes the setters so a protocol named New or Entries can't collide with new / entries.
  • Not done: narrowing what a side calls (also "settled" in the proposal). The default (every other-side protocol) is what Services and ClientServices that take a subset #133 asks for; an API for narrowing is a follow-up on top of handshake(provided, called).

Generated code

  • Package module: HEADER (c2::HelloHeader) and one P_<PATH> (c2::ProtocolEntry) per protocol, from generation's hello_parts; function numbers only. HELLO and the zero-argument handshake() are gone. handshake(provided, called) is Comline2Handshake::new(params, Hello::build(&HEADER, provided, called)).
  • accept builds it from services.entries() and the client's protocols; connect from its own services and the server's. A protocol in both lists (@provider = Multiple) is listed once by Hello::build.
  • Direction is by construction: Services only has the protocols the accepting side provides, ClientServices the dialling side's. The runtime checks the rest (check_provide).
  • provide_on (the dispatchers', and Services::provide_on) return Result<(), RuntimeError> and accept / connect propagate it. Under comline@2 a protocol the handshake didn't accept is Unavailable. With comline@1 / none / JSON-RPC a subset means fewer dispatchers and nothing else (the proposal's note).

Pins

generation 99187d7, runtime e736221 (rev = lines only, plus RUNTIME_REV, the rev the generated code's manifests name). One comline-core (69039e7) across generation, the runtime's dev-dependency and this repo, checked with cargo metadata. xtask --check shows no drift in std-extra/.

Goldens

Blessed with CONFORMANCE_BLESS=1. Existing goldens change in three ways only, all consequences of the runtime bump or of this feature:

  1. comline-runtime rev in the // ... add it to your Cargo.toml comment (bounds, connections_async).
  2. Every connection protocol file: provide_on returns Result<(), RuntimeError> (+ a doc paragraph saying when it fails).
  3. Every connection.rs: Absent, the per-protocol slot trait, Services / ClientServices with new / with_* / entries, a doc bullet on subsets, ? on provide_on; for comline@2 also HELLO / handshake() replaced by HEADER / P_* / handshake(provided, called).

New: connections_subset (code and lib). FEATURES.md / features.json: the fixture is listed as proof for protocols, connections, nested namespaces, datagram@3, comline@2 and packed@1; no feature changes state.

wire_invariants.txt is unchanged for every existing fixture: the test now rebuilds the whole connection's Hello from HEADER and the P_* entries and prints the same HELLO = ... bytes it pinned before (the file only gains the connections_subset sections). Other test updates: entry_points / compiles (rustdoc) list the new hidden items, and compiles gains behaviour tests for the subset, sync and async: a protocol left out is refused by the peer (Unavailable, UnknownProtocol) in both directions, a side providing nothing, and the literal with all and with Absent.

No #[ignore], ledger entries or waivers.

Open questions

  • A refused protocol now fails accept / connect. With the default Hello (everything called) it only happens when the peer is a different version that refuses a protocol under scope = protocol (provide -> Unavailable), where before the connection came up with that protocol disabled. That is the runtime#126 behaviour as decided; flagging that it reaches generated accept / connect as an error.
  • Narrowing what a side calls: an API on Services (e.g. .calls(&[..])), or a parameter of accept / connect?

Both take a subset of the protocols their side provides, blocking or async:
`Services::new().with_chat(..)` adds one, `Absent` in a field leaves one out,
and the all-provided struct literal is what it was. accept / connect build the
`comline@2` Hello at runtime from what was given plus the protocols this side
calls (every protocol of the other side), through `Hello::build`, instead of
embedding the package's whole Hello.

- The package module emits `HEADER` and one `P_<path>` entry per protocol
  (from generation's `hello_parts`) in place of the `HELLO` bytes; `handshake`
  takes the entries provided and called.
- A dispatcher's `provide_on`, and `Services::provide_on`, return the runtime's
  `Result` (a protocol the handshake didn't accept is `Unavailable`), and
  accept / connect propagate it.
- Pins: generation 99187d7, runtime e736221 (also the generated code's
  `RUNTIME_REV`). `connections_subset` goldens, FEATURES and features.json
  blessed. wire_invariants rebuilds the whole-connection Hello from the header
  and entries, so its pinned bytes are unchanged.

Closes #133
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.

Services and ClientServices that take a subset

1 participant