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
servethat provides its protocols and nothing else, and its ownconnect. - 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:
- Group the protocols so one ("mono") package can generate several connections.
- 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, oneClientServices, oneaccept,serveandconnect, and theConnection<T>,FramingandFormatthey name, inconnection.rs(TypeScript:connection.ts). See the Rust and TypeScript guides. The generator models it as onePackageConnectionper package (generation/codegen/src/connections.rs). - Every protocol must be wired.
Serviceshas a field for every protocol the server provides, andClientServicesone 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, andserveevery server-provided one. - A subset is wired by hand. Serving only some protocols means opening a
Connectionyourself and callingChatDispatcher(..).provide_on(&mut conn)for each, as the guide's By hand section shows. Undercomline@2, the default, the generatedacceptandconnectalso 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,serveandconnectaren't generated,comline generationwarns, and each protocol keeps its own dispatcher and sender. The format is the package's onewire.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. Undercomline@1withdatagram@2it is the protocol's position among the package's protocols, andCONNECTION_IR_HASHdigests every schema in the package. Thecomline@2code in the runtime doesn't read that hash; its Hello carries per-protocol lines and shape hashes instead. comline@2already compares per protocol. A protocol only one end has isunknown_protocol, refused on its own, andscope = protocolkeeps a refusal to that protocol. Withscope = 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 byusewhen 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
.idsfiles 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,@framingand@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
useputs 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.
- 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. - The name is
connection: the annotation, the generated module and the docs share it. - 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
.idsfiles, andconfig.idpfor what question 7 adds), never incomline.toml. -
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_ontakes 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, notconnection::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. -@connectionon a protocol that runs on no connection (lockstepdatagram, 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.idpmay overridewireper 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'swire. A member's own@framingand@handshakemust agree with its set's; a protocol in two sets whose framings differ can't pin@framingitself. 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'scodecwith a format-independentLayout(codec.decode<RpcPingParams>(params, RpcPingParamsLayout)). 8. A dependency's protocol joins a set only oncecomline@3exists (Proposal A), with its encodings matching as A decided. A's accepted rule thatuseputs 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 ofadminthat reaches thepublicendpoint gets a connection carrying only what the two share (the health check), with the restUnavailable; underscope = packageit is refused whole. Carrying the set's name in the Hello, for a clear refusal, is acomline@3matter, not a blocker. 11. Sets need a handshake that compares protocol by protocol.comline@1withdatagram@2numbers 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 underconnection:connection::admin::{Services, ClientServices, accept, serve, connect, Connection, Framing, Format}, and the same layout in TypeScript. The default connection stays atconnection::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. -asyncstays one setting for the whole target.Raised with it, and separate from sets: Comline decides the method name that goes on the wire (
send, ornamespace.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 oncomline@3except answer 8. - the handshake: a set's Hello lists only its members, so the peer refuses every
other protocol (
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:
ClientServicesmakes every dialler provide every client-provided protocol;- a subset wired by hand loses the negotiation;
- every application's Hello lists the others' protocols, which is noise under
offerand exposure undersymmetric, where the server sends its list; - 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
ServicesandClientServicestake 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.
ServicesandClientServicesaccept 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
symmetricsends that list to every client, so problem 3 would be solved only in part. provide_onis 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 withcomline@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, withCONNECTION_IR_HASHand 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. Runningcomline@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 undercomline@2a 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.
- 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
ServicesandClientServicestake 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? - What is it called?
groupis taken. Candidates: connection (the page's provisional "named connection"; it matchesconnection.rsand theConnection<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. - Who owns the declaration: the package or its consumer?
wireandhandshakeare inconfig.idp, which is frozen, hashed and published.comline.tomlis, in its own words, "consumer-owned", "never frozen, and never part of a published package", and the wire defaults proposal moveddefault_framingout of it because "the framing is part of the contract both peers build from, so the producer decides it". A set incomline.tomlis then presentation, like a dependency group, and each consumer could define its own; a set inconfig.idpor the IDL is part of the package's contract. Which is meant? (The idea was first put as a table "next towire" incomline.toml;wireis inconfig.idp, so that placement can't be taken as written.) - A grouping for code generation, or a constraint? The Connections decision called the
declared set "a constraint". Is a set only what a generated
serveandconnecttake, 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? Undercomline@2, a peer outside the set is toldunknown_protocolfor each protocol it lacks; is that enough? - 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@1is today? - 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.
- 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 ownwireandhandshake, and, if so, its own format, which today isn't a per-protocol or IR fact? - May a set name a dependency's protocol, and when? Only once
comline@3exists (A), and with all three encodings matching, as A decided? Or also undercomline@2, where step 0 leaves a dependency's protocols off the connection? If a set names one, doesusestill put a protocol on the connection by itself, or does the set replaceuseas 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)? - 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?
- 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_protocolfor the rest, and calls to them fail locally, asUnavailable), and differs from a package whose subset is wired by hand. Is that the intended behaviour? - Do sets reach
comline@1anddatagram@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 todatagram@3withcomline@2and later; keep the positions, with a hash per set; or the whole-package hash as today. - 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; inlibmode, whether a set's items are re-exported at the crate root; incodemode, the file for a set and how thelayouttemplate names it; and TypeScript's form (a file per set, or a namespace inconnection.ts). Which names are reserved: a set calledconnection, or named like a schema, as a schema namedconnectioncan't be used incodemode today. - Do JSON-RPC and
asyncgo 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.asynciscomline.toml's[generate]key, a setting for the whole target; does it stay so? - For Option 3, where does direction live? A protocol's side is
@providertoday (Server,ClientorMultiple) andServicesandClientServicesfollow 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? - 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.idpgrammar 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:
PackageConnectionbecomes a set of them;package_connection_among,checkandhellorun per set; the request carries the sets, additively, asdependencieswas 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.rsandconnection.tsemit 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 andConnectionare unchanged, and only the embedded Hello differs per set. Undercomline@1, the hash passed toacceptandconnectcould be per set (question 11). - cli:
comline generationandcomline inspectshow the sets, andcomline inspectis 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.idporcomline.tomlreference (and its JSON Schema), thecomline@2page on what a Hello lists, and this proposal's status.