Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/docs/proposals/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -199,7 +199,9 @@ to [core#277](https://github.com/ComlineProject/core/issues/277) and
IDL, a world-like declaration) and prior art from protoc, gRPC, Thrift,
Cap'n Proto, Smithy, WIT and FIDL. Develops the declared set that
[Connections](connections.md#several-protocols-on-one-connection) left
unbuilt. *draft; nothing decided, the questions are open.*
unbuilt. *smaller step accepted, sets designed and deferred (2026-11-15): a Hello
built from what is provided now; an `@connection` annotation, package-owned,
a constraint, when sets are needed.*

#### [A dependency's protocols on a connection](dependency-protocols/index.md)

Expand Down
134 changes: 125 additions & 9 deletions docs/docs/proposals/named-connections/index.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,8 @@
# Named connections

Status: **draft** · nothing here is decided: every choice is an open question at the
[end of this page](#open-questions) · develops a point left unbuilt by
[Connections](../connections.md#several-protocols-on-one-connection) (the declared set of
protocols allowed together) · sits beside
[A dependency's protocols on a connection](../dependency-protocols/index.md), whose
Proposals A and C are accepted · three parts: this overview, [the options](options.md) and
[prior art](prior-art.md)
Status: **the smaller step is accepted; sets are designed and deferred** (2026-11-15) · the
user's [answers](#answers-so-far) shape the design of sets, and [the decision](#decided)
says what is built now · the [original questions](#open-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
Expand Down Expand Up @@ -133,10 +129,130 @@ All four are described, with what each generates and checks, on [the options pag
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](#open-questions). They
shape the design; they are the design sets will be built to, when [they are](#decided).

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](../dependency-protocols/multi-package-connection.md)),
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](../dependency-protocols/capabilities.md)), 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](https://github.com/ComlineProject/core/issues/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](#answers-so-far) 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](options.md#option-0-status-quo)), which also keeps an admin package
private.

## Open questions

Nothing is decided; each of these is for the user to answer. The options page has the detail
behind each one.
The questions as first asked; the [answers](#answers-so-far) 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
Expand Down
Loading