Skip to content

Named connections

Status: the smaller step is accepted; sets are designed and deferred (2026-11-15) · the user's answers shape the design of sets, and the decision says what is built now · the original questions stay at the end

The question. A package gets exactly one connection: one Services, one ClientServices, one accept, serve and connect, and one Connection<T>, however many protocols it declares. Should a package be able to declare several named sets of protocols, each generating entry points of its own, or should "one package, one connection" stay the rule, with a separate package for each application? Either way has a cost, and this page sets both out so the choice can be made.

"Named connection" is the provisional name used here. group is already taken, by dependency groups, so the feature needs another word: see the name.

The problem, as framed

A package is one application's connection today. Two situations strain that:

  • Several applications on one schema. A shop has a public API and an admin API; a game has server to client and server to worker. They share types, and often some protocols (a health check, say). Each application wants its own serve that provides its protocols and nothing else, and its own connect.
  • A subset of one application. A test server, or a gateway, serves some of a package's protocols and not the rest.

Two answers pull in opposite directions:

  1. Group the protocols so one ("mono") package can generate several connections.
  2. Keep one package per application. An application is a package; what several of them share is a package they depend on. The cost is that there is no one package for more than one application.

Neither is assumed here. Option 0 is the second, with what exists today.

Where things stand

Each point below was checked against the docs and the generators' code and golden output.

  • One connection per package. A package with a protocol on a connection gets one Services, one ClientServices, one accept, serve and connect, and the Connection<T>, Framing and Format they name, in connection.rs (TypeScript: connection.ts). See the Rust and TypeScript guides. The generator models it as one PackageConnection per package (generation/codegen/src/connections.rs).
  • Every protocol must be wired. Services has a field for every protocol the server provides, and ClientServices one for every protocol the dialling side provides, so leaving one out doesn't compile. connect(transport, ClientServices { .. }) therefore makes the dialling side provide every client-provided protocol in the package, and serve every server-provided one.
  • A subset is wired by hand. Serving only some protocols means opening a Connection yourself and calling ChatDispatcher(..).provide_on(&mut conn) for each, as the guide's By hand section shows. Under comline@2, the default, the generated accept and connect also run the package's generated Hello (marked #[doc(hidden)]) and keep the negotiated result in the connection's extensions, which the senders consult before each call. A connection opened some other way "has nothing to check against, and every call goes", in the generated code's own words.
  • The protocols on a connection must agree. If those on connections differ in framing or handshake, no one connection carries them all: Services, serve and connect aren't generated, comline generation warns, and each protocol keeps its own dispatcher and sender. The format is the package's one wire.format, not a protocol's, so it can't differ; a JSON-RPC protocol is JSON by definition.
  • Wire numbers are per package. Under the defaults (datagram@3, comline@2) a protocol's number comes from the package's history. Under comline@1 with datagram@2 it is the protocol's position among the package's protocols, and CONNECTION_IR_HASH digests every schema in the package. The comline@2 code in the runtime doesn't read that hash; its Hello carries per-protocol lines and shape hashes instead.
  • comline@2 already compares per protocol. A protocol only one end has is unknown_protocol, refused on its own, and scope = protocol keeps a refusal to that protocol. With scope = protocol, a connection whose every protocol is refused is refused (the handshake). The Hello the generator embeds lists the protocols on the package's connection and that connection's three encodings (facts::hello).
  • So a set changes no wire number and no handshake message. Each protocol keeps its package number, line and shape hash. What changes is which protocols a given end's Hello lists, and which entry points the generators write. That is a generation and compiler concept, not a wire one, under comline@2.
  • The declared set was never built. Connections, decision 2 (2026-10-20), says: "Which protocols a connection carries is negotiated at the handshake: whatever the client offers and the server accepts. A package can optionally declare the set allowed together, as a constraint." Its What it touches lists "the optional declared set of protocols" under core, and What's built doesn't include it. A search of core, generation, the two generators and the runtime finds no trace of it. This proposal develops it, and asks whether it is still a constraint or has become a grouping for code generation (question 4).
  • Proposals A and C are accepted. A (comline@3) puts several packages on one connection, a dependency's protocol joining by use when its framing, handshake and format match the connection's. C gives each package a connection of its own, for protocols that can't share one and for isolation. C is the "one package per application" model that Option 0 builds on.

The options

All four are described, with what each generates and checks, on the options page.

0: status quo 1: sets in the manifest 2: sets in the IDL 3: a world-like declaration
In one line one connection per package; separate applications are separate packages a table beside wire lists protocols by path a connection block, or an annotation on each protocol a declaration that also names a dependency's protocols
Mono package for several applications no yes yes yes
A subset of one application by hand, without the generated negotiation a set of its own a set of its own a set of its own
Where it is declared nowhere: it is the package boundary config.idp (the package) or comline.toml (the consumer): open the .ids files, in the frozen IR the .ids files, or the manifest
New compiler concept none a manifest key a declaration kind (block) or a known annotation a declaration kind, with direction
Frozen IR format unchanged unchanged if in comline.toml; if in config.idp, to be checked block: a new unit kind; annotation: probably not, to be checked a new unit kind
Dependency protocols in a set joins by use under A, as accepted not without A not without A named in the declaration, under A
Encodings checked per package, as today per set per set per set
Default output with nothing declared today's today's today's today's
Reuse of one protocol by two applications in a shared package, served on its own connection (C) or joined (A) listed in both sets named in both sets named in both worlds
Version covers the package the package's every set the package's every set the package's every set

How the options differ in what they ask of the user

  • Option 0 asks nothing of the tools and the cost lands on the schema's authors: a types package and one package per application, and shared protocols in a package of their own.
  • Option 1 is the smallest addition to the language: the .ids files don't change, and protocols stay where they are. The set is described away from the protocol.
  • Option 2 puts the set beside what it contains. A block lists the set in one place; an annotation sits on each protocol, in the style of @provider, @framing and @handshake, and a protocol's sets are read off the protocol.
  • Option 3 is the only one that can name a protocol from a dependency in the declaration itself. It leans on Proposal A being built, and it touches A's accepted rule that use puts a protocol on the connection.

The options aren't exclusive. Option 1 or 2 could ship first, and a world-like form could extend it later, or Option 0 could stay as the rule and nothing be added.

Answers so far

Given by the user on 2026-11-15, numbered as the open questions. They shape the design; they are the design sets will be built to, when they are.

  1. An annotation on the protocol (Option 2): @connection = "admin", or a list (@connection = ["admin", "public"]), which annotation values already allow (@validators = [...]). No block, no manifest table.
  2. The name is connection: the annotation, the generated module and the docs share it.
  3. The package owns the declaration. A set changes what its Hello lists, which is part of the contract both peers build from, so it lives with the package (the .ids files, and config.idp for what question 7 adds), never in comline.toml.
  4. A constraint: a connection carries exactly what its Hello lists. It is enforced in two places, not in the types:

    • the handshake: a set's Hello lists only its members, so the peer refuses every other protocol (unknown_protocol);
    • the runtime: a connection refuses to provide or call a protocol that the Hello it ran didn't list. The senders already check the negotiated result before each call; the same check is added to provide_on. An admin handler then can't be put on a public connection by mistake.

    A distinct connection type per set, whose provide_on takes only members, was considered and not taken: it costs generated machinery for what the two checks above already give. 5. All or nothing. - With no protocol annotated, every protocol on a connection is on the one default connection, generated where it is today (connection::serve, not connection::default::serve), so existing output doesn't change. - Once one protocol is annotated, every protocol that runs on a connection must be: one left out is an error. Nothing reaches a connection without a decision. - @connection on a protocol that runs on no connection (lockstep datagram, a server-only JSON-RPC protocol off the connection) is an error. - No setting to forbid sets. Where sets can't work is derived from the encodings' facts instead (answer 11); a lint for organisations that want none can come later. 6. A protocol may be in several sets (a health check in every application's). 7. Each set's encodings are checked on their own, and a set may state its own. The framing and handshake check runs per set. config.idp may override wire per set, in its dictionary form keyed by the set's name (its grammar has no list values, and needs none for this), defaulting to the package's wire. A member's own @framing and @handshake must agree with its set's; a protocol in two sets whose framings differ can't pin @framing itself. A format per set is new (the format is package-wide today), and both generators already allow it: Rust's generated types are format-independent through serde, and TypeScript's decode through the connection's codec with a format-independent Layout (codec.decode<RpcPingParams>(params, RpcPingParamsLayout)). 8. A dependency's protocol joins a set only once comline@3 exists (Proposal A), with its encodings matching as A decided. A's accepted rule that use puts a protocol on the connection is not changed by this proposal. 9. Fixed version rules, not configurable: adding a set, or a protocol to a set, is a minor change; removing either, or renaming a set (which renames generated code), is a major change, as A treats a dependency's protocol joining the connection. A rule a package could choose would make a version number mean different things to different consumers. 10. A set's Hello lists only its members. The handshake's guarantee is per protocol (line and shape hash), and a subset keeps it. Noted gap: the set's name isn't on the wire. A client of admin that reaches the public endpoint gets a connection carrying only what the two share (the health check), with the rest Unavailable; under scope = package it is refused whole. Carrying the set's name in the Hello, for a clear refusal, is a comline@3 matter, not a blocker. 11. Sets need a handshake that compares protocol by protocol. comline@1 with datagram@2 numbers protocols by position and hashes every schema, so a change in one set would refuse every set: a package on them can't declare sets. The rule comes from the encodings' facts (Part 1), not from a setting. 12. A module per set under connection: connection::admin::{Services, ClientServices, accept, serve, connect, Connection, Framing, Format}, and the same layout in TypeScript. The default connection stays at connection:: itself. 13. Rules follow the framing's facts, scoped to a set. The page states the facts rather than "JSON-RPC": - A framing that addresses calls by name (JSON-RPC's method, not a protocol number) needs those names unique among the protocols one side provides on a connection; with sets, within the set. Any framing with that fact gets the rule. - "Once one JSON-RPC protocol is on a connection, all are" is a generation policy, not a fact of the framing: a JSON-RPC message looks the same on a connection and in lockstep, so one side can't mix the two on a transport. With sets it applies within the set. - async stays one setting for the whole target.

    Raised with it, and separate from sets: Comline decides the method name that goes on the wire (send, or namespace.Protocol/function), so it can't yet serve or call an existing JSON-RPC API whose methods are named otherwise (textDocument/hover, eth_getBalance). No annotation sets a function's wire name today, and params and error codes have the same problem. Filed on its own as core#287. 14. Direction stays on the protocol (@provider). With the annotation, the question doesn't arise; a world-like declaration (Option 3) isn't taken. 15. The house order: the specification's cases first, then core, generation, the two generators, the CLI and language server, and the docs. Nothing waits on comline@3 except answer 8.

Decided

  • Whether sets are worth building, or a smaller step is enough. Raised while answering question 11, and decided by the user on 2026-11-15 (below). Sets solve four things today:

    1. ClientServices makes every dialler provide every client-provided protocol;
    2. a subset wired by hand loses the negotiation;
    3. every application's Hello lists the others' protocols, which is noise under offer and exposure under symmetric, where the server sends its list;
    4. one format and framing for the whole package.

    Against them: a new concept across every repo; a mono package publishes every application's schemas together, where separate packages could keep an admin package private; and one package version covers every application, so an admin breaking change is a major bump for the public API's consumers, though not on the wire. The smaller step: build the Hello at runtime from the protocols actually provided, and let Services and ClientServices take a subset. That covers 1 to 3 with no new language concept; sets would then add only the named entry points and the per-set encodings (4).

    Decided:

    • The smaller step is built now, as the first part of sets. Services and ClientServices accept a subset, and the Hello is built at runtime from what this side actually provides, plus the protocols it calls on the other side (all of them by default: the peer refuses those it doesn't have). A connection then carries exactly what its Hello lists, enforced as answer 4 says. It is designed so sets can build on it without throwing anything away.
    • Sets are not built now. Their design (the answers above) stays recorded, to be taken up when per-application encodings or named entry points are actually needed. Until then, several applications are separate packages sharing a package they depend on (Option 0), which also keeps an admin package private.

    Settled with it (2026-11-15), from a review of the smaller step:

    • A side can narrow what it calls, too. Beside the subset it provides, a side may list the protocols it calls on the other side; the default stays all of them. Without it, a public server still lists every client-provided protocol it might call, other applications' included, and under symmetric sends that list to every client, so problem 3 would be solved only in part.
    • provide_on is checked against what was accepted, and direction by the generated code. The runtime refuses to provide a protocol the handshake didn't accept, not merely one the Hello didn't list: providing one the peer refused is harmless on the wire, but is almost certainly a mistake. A Hello entry carries no direction (number, line, shape hash, functions), so the runtime can't tell a protocol listed to be called from one listed to be provided; the generated code, which knows @provider, checks that. The check applies only when a Hello ran: a connection opened with comline@1, or by hand without one, has nothing to check against.
    • Noted: JSON-RPC connections get only "fewer handlers". The generated JSON-RPC connection runs comline@1, with CONNECTION_IR_HASH and no Hello per protocol, so the smaller step's negotiation doesn't reach it: a subset there means fewer dispatchers and nothing else. By answer 11 sets don't reach it either. Running comline@2, whose messages are binary, over a JSON-RPC connection is a separate design, related to core#287.
    • Noted: Option 0 has a gap until comline@3. A protocol several applications share (a health check) lives in a package they depend on, and under comline@2 a dependency's protocol doesn't join the application's connection (step 0): it needs a connection of its own (C) until A is built.

Open questions

The questions as first asked; the answers are above. The options page has the detail behind each one.

  1. Which direction? Option 0 (nothing added: one package per application, Proposal C's model), 1 (sets in the manifest, in either of its two places), 2 (a block or an annotation), 3 (a world-like declaration), or a sequence of them (for example, one of 1 or 2 first, 3 later). And a smaller step that isn't in the list: let Services and ClientServices take a subset, by an explicit per-protocol opt-out, without any new declaration. Is that enough for the "subset of one application" case, which the sets would otherwise cover?
  2. What is it called? group is taken. Candidates: connection (the page's provisional "named connection"; it matches connection.rs and the Connection<T> the set generates), endpoint, world (WIT's word, which fits Option 3 and brings WIT's meaning of imports and exports with it), role (fits "server to client" and "server to worker" and reads oddly for a public and an admin API), surface. And whether the keyword, the table key and the generated module share one word.
  3. Who owns the declaration: the package or its consumer? wire and handshake are in config.idp, which is frozen, hashed and published. comline.toml is, in its own words, "consumer-owned", "never frozen, and never part of a published package", and the wire defaults proposal moved default_framing out of it because "the framing is part of the contract both peers build from, so the producer decides it". A set in comline.toml is then presentation, like a dependency group, and each consumer could define its own; a set in config.idp or the IDL is part of the package's contract. Which is meant? (The idea was first put as a table "next to wire" in comline.toml; wire is in config.idp, so that placement can't be taken as written.)
  4. A grouping for code generation, or a constraint? The Connections decision called the declared set "a constraint". Is a set only what a generated serve and connect take, or does something enforce it: a runtime refusing a request for a protocol outside the connection's set, a build error when a handler for a protocol outside the set is registered? Under comline@2, a peer outside the set is told unknown_protocol for each protocol it lacks; is that enough?
  5. What happens to the whole-package connection once sets are declared? The default, with nothing declared, must stay exactly today's output. When sets are declared, does the unnamed connection (every protocol, as today) still exist beside them, or only the named ones? And a protocol that is in no set: an error, put in a default set, or left off every connection, as a protocol on datagram@1 is today?
  6. May a protocol be in more than one set? A health check in every application's set is the case for it. The case against is that two sets then provide the same dispatcher and a reader can't tell from a protocol which connections it is on.
  7. What does a set say about encodings? Framing and handshake are per protocol today (@framing, @handshake) and checked to agree across a package's connection; the format is the package's. With sets, the framing and handshake check applies per set, so two sets can differ. Should a set be able to state its own wire and handshake, and, if so, its own format, which today isn't a per-protocol or IR fact?
  8. May a set name a dependency's protocol, and when? Only once comline@3 exists (A), and with all three encodings matching, as A decided? Or also under comline@2, where step 0 leaves a dependency's protocols off the connection? If a set names one, does use still put a protocol on the connection by itself, or does the set replace use as the reach (a change to an accepted point of A)? When the encodings differ, is the error the one A gives, pointing to a connection of its own (C)?
  9. How do versions treat sets? The package version still covers every set, since lines and shape hashes are per protocol. Is adding a set, or a protocol to a set, a minor change, and removing one a major change, by analogy with how A treats a dependency's protocol joining the connection? Is a rename of a set breaking, since it renames generated code? Or does a set not move the version at all, as with groups?
  10. What does a set's Hello list? Today the generated Hello lists every protocol on the package's connection. A set's Hello listing only its members is honest to the peer (it sees unknown_protocol for the rest, and calls to them fail locally, as Unavailable), and differs from a package whose subset is wired by hand. Is that the intended behaviour?
  11. Do sets reach comline@1 and datagram@2? Under them, numbers are positions among the package's protocols, and the hash digests every schema, so a change in one set refuses connections in every set. Options: restrict sets to datagram@3 with comline@2 and later; keep the positions, with a hash per set; or the whole-package hash as today.
  12. What does the generated code look like? A module per set (connection::admin::{Services, serve, connect, Connection, Framing, Format}), or prefixed names (AdminServices, admin_serve) at the same level; in lib mode, whether a set's items are re-exported at the crate root; in code mode, the file for a set and how the layout template names it; and TypeScript's form (a file per set, or a namespace in connection.ts). Which names are reserved: a set called connection, or named like a schema, as a schema named connection can't be used in code mode today.
  13. Do JSON-RPC and async go per set? For JSON-RPC, once one JSON-RPC protocol in a package is client-provided, all of them share the connection, and the bare-name collision check runs over that one connection. Per set, both would apply within the set. async is comline.toml's [generate] key, a setting for the whole target; does it stay so?
  14. For Option 3, where does direction live? A protocol's side is @provider today (Server, Client or Multiple) and Services and ClientServices follow from it. A world-like declaration could say which side provides each member instead. Does the declaration replace @provider, sit beside it with the two checked against each other, or leave direction on the protocol?
  15. Order of work and where it ships. The specification's conformance cases first (the house order for a compiler rule), then core, generation and the generators, the CLI and language server, and the docs. Does any of it wait for comline@3, and does it ship as a draft behind a switch, or not until the questions above are answered?

What it touches

Nothing is built; this lists where each option would reach.

  • core: the declaration (a manifest key, a block, or an annotation), its parsing and validation, the encoding check applied per set (the compiler's check of which encodings may share a connection isn't built yet, so a set is part of its design), the frozen IR if the declaration is in the IDL (a change under the IR migrations framework if it adds a unit kind), the facts and the version rules for a set, and the diagnostics. Whether the package's config.idp grammar can hold it: its values have no list form, only strings, numbers, names and dictionaries.
  • specification: compiler cases for the new errors and the unchanged default output, catalog entries for the diagnostic codes (shared vocabulary), and generator conformance output for a package with sets.
  • generation: PackageConnection becomes a set of them; package_connection_among, check and hello run per set; the request carries the sets, additively, as dependencies was added, so a request without them is today's; the JSON-RPC and bare-name checks scope to a set; warnings name the set.
  • comline-rust and comline-typescript: connection.rs and connection.ts emit one block per set, and the golden outputs gain a case for sets, and the default's stay as they are.
  • runtime: none under comline@2: the handshake, framing and Connection are unchanged, and only the embedded Hello differs per set. Under comline@1, the hash passed to accept and connect could be per set (question 11).
  • cli: comline generation and comline inspect show the sets, and comline inspect is the place for what a set carries (A has that open already).
  • language-server: completion, hover, go to definition and diagnostics for the declaration, and for each set's members.
  • docs: the Rust and TypeScript connections guides, the packages guide, the config.idp or comline.toml reference (and its JSON Schema), the comline@2 page on what a Hello lists, and this proposal's status.