From 4c810f1e1e885a9e7177f8029dc7ef125ed03afc Mon Sep 17 00:00:00 2001 From: Kinflou Date: Sun, 15 Nov 2026 11:04:23 +0800 Subject: [PATCH] Say what you use from the generated code; own schemas only through relative paths The Rust and TypeScript index pages get a "What you use" table (the default connection, the lockstep datagram, JSON-RPC, by hand). Connections comes first in "Where to go next" and the nav; Client & server becomes the lockstep datagram page. The snippets on both language sections match the generators' output after comline-rust#131/#132 and comline-typescript#172: the entry-point header, hidden/internal plumbing, Framing and Connection, Format and CONNECTION_IR_HASH defined once. The Imports guide and the other snippets reach a package's own schemas only through package::, parent:: and self::, and document import::bare-own-schema-path. --- docs/docs/guides/codegen/generating-code.md | 2 +- docs/docs/guides/idl/index.md | 7 +- docs/docs/guides/idl/use.md | 97 ++++++-- docs/docs/languages/rust/client-and-server.md | 85 ++++++- docs/docs/languages/rust/connections.md | 221 ++++++++++++++---- .../languages/rust/framing-and-wire-format.md | 5 + docs/docs/languages/rust/index.md | 58 ++++- .../languages/typescript/client-and-server.md | 80 +++++-- docs/docs/languages/typescript/connections.md | 195 ++++++++++++---- .../typescript/framing-and-wire-format.md | 4 + docs/docs/languages/typescript/index.md | 43 +++- docs/mkdocs.yml | 8 +- 12 files changed, 655 insertions(+), 150 deletions(-) diff --git a/docs/docs/guides/codegen/generating-code.md b/docs/docs/guides/codegen/generating-code.md index 4b7e900..ad89c8a 100644 --- a/docs/docs/guides/codegen/generating-code.md +++ b/docs/docs/guides/codegen/generating-code.md @@ -289,7 +289,7 @@ import type { Greeting } from "./types.js"; ``` An alias imports the name the other module actually exports -(`use types::Greeting as G` → `import type { Greeting as G }`), and a `use` +(`use package::types::Greeting as G` → `import type { Greeting as G }`), and a `use` nothing refers to produces no import at all. `std` again resolves to its own package when diff --git a/docs/docs/guides/idl/index.md b/docs/docs/guides/idl/index.md index 39f62da..e11de0e 100755 --- a/docs/docs/guides/idl/index.md +++ b/docs/docs/guides/idl/index.md @@ -58,10 +58,11 @@ next declaration. `//!` lines at the top of a file are its ```ids title="imports.ids" use std::http::Request -use mypackage::{User, Post} +use package::types::{User, Post} use external::uuid::Uuid as UUID use parent::common::* ``` -`self::`, `parent::` and `package::` prefixes resolve relative to the current -schema. See [Imports](use.md). +A package's own schemas are reached only through `package::`, `parent::` and +`self::`, which resolve relative to the current schema; any other path means +`std` or a dependency. See [Imports](use.md). diff --git a/docs/docs/guides/idl/use.md b/docs/docs/guides/idl/use.md index fabd488..6240869 100644 --- a/docs/docs/guides/idl/use.md +++ b/docs/docs/guides/idl/use.md @@ -5,23 +5,47 @@ current file. ```ids use std::http::Request -use mypackage::types::User -use mypackage::{User, Post, Comment} -use mypackage::utils::* +use package::types::User +use package::types::{User, Post, Comment} +use package::utils::* use external::uuid::Uuid as UUID use parent::common::Error ``` +## Which path reaches what + +A package's **own schemas are reached only through a relative path**: `package::`, +`parent::` or `self::`. A path that starts with anything else is +**absolute**, and an absolute path always means `std` or a dependency, never the +package itself. + +| To reach | Write | +|---|---| +| a schema of this package, from its root | `use package::types::User` | +| the schema one level up | `use parent::common::Error` | +| the current schema, and what is under it | `use self::nested::Type` | +| a dependency | `use greeting::hello::Greeting` | +| the standard library | `use std::http::Request` | + +`std`, `package`, `parent` and `self` are reserved: none can be the name of a +dependency, so the four are the only first segments that aren't a +dependency's. `package::` is the same wherever the file sits, so moving a schema +to another directory doesn't change what its imports say. + ## Path forms | Form | Example | Brings in | |---|---|---| -| absolute | `use pkg::module::Type` | one item by its full path | -| whole namespace | `use pkg::module` | everything in that module, bare or qualified (`Type` or `pkg::module::Type`) | -| multi | `use pkg::module::{A, B, C}` | several items from one module (plain names, no nesting or `as` inside the braces) | -| glob | `use pkg::module::*` | everything in that module | +| single item | `use package::module::Type` | one item by its full path | +| whole namespace | `use package::module` | everything in that module, bare or qualified (`Type` or `module::Type`) | +| multi | `use package::module::{A, B, C}` | several items from one module (plain names, no nesting or `as` inside the braces) | +| glob | `use package::module::*` | everything in that module | | relative | `use parent::common::Error`, `use self::nested::Type`, `use package::types::User` | resolved against the current schema: `parent::` is one level up, `self::` the schema itself (`self::nested` is a schema under it), `package::` the package root | +The first four rows show `package::`; a dependency's or `std`'s schema takes the +same forms with its own name first (`use greeting::hello::{A, B}`, +`use std::http::*`). + A relative prefix works in every form, including a glob or `{ ... }` straight after it: `use parent::*` and `use parent::{Error, Page}` import from the schema one level up (`api.ids`, for a file `api/v1.ids`), and `use parent::common::*` @@ -29,20 +53,52 @@ from the `common` schema beside it. As with any path, one that names no schema, or an item the schema doesn't declare, fails the build ([below](#when-nothing-matches)). +### A bare path to your own schema is an error + +Writing a package's own schema without a relative prefix, in any form (a single +item, a whole namespace, `{ ... }` or `*`, with or without `as`), is an error at +once: + +```ids +use types::{User, Post} +``` + +The build reports it as `import::bare-own-schema-path`, with: + +- **message:** `'types::{User, Post}' is one of this package's own schemas, reached by a bare path` +- **context:** ``an absolute path starts with `std` or a dependency's name; 'types' is neither`` +- **help:** ``write `package::types::{User, Post}`: a package's own schemas are reached as `package::...`, `parent::...` or `self::...` `` + +`comline check` and `comline build` fail on it. The diagnostic carries a quick +fix, titled ``Write `package::types::{User, Post}` ``, that inserts `package::` at +the start of the path. The language server doesn't offer it yet +([language-server#122](https://github.com/ComlineProject/language-server/issues/122)), +and `comline fix` doesn't apply it across a package yet +([cli#162](https://github.com/ComlineProject/cli/issues/162)). Qualified +references the import brought in don't change: they're written with the +schema's namespace (`types::User`) whichever path reached it. A path whose first segment is neither `std`, a +dependency nor one of the package's own schemas is not this error but a +[path that matches nothing](#when-nothing-matches). + ## Referring to what you imported -After a `use`, a type can be written **bare** or **qualified**, Rust-style: +After a `use`, a type can be written **bare** or **qualified**, Rust-style. The +qualified path is the schema's own namespace (`types::User`), not the path the +`use` was written with: | statement | write the type as | |---|---| -| `use pkg::types::User` | `User` **or** `pkg::types::User` | -| `use pkg::types::{User, Post}` | `User` / `Post`, or the qualified path | -| `use pkg::types::*` | any name from `types`, bare or qualified | -| `use pkg::types` | `User` **or** `pkg::types::User` | -| `use pkg::types::User as Account` | `Account` **or** `pkg::types::User` — **not** bare `User` | +| `use package::types::User` | `User` **or** `types::User` | +| `use package::types::{User, Post}` | `User` / `Post`, or the qualified path | +| `use package::types::*` | any name from `types`, bare or qualified | +| `use package::types` | `User` **or** `types::User` | +| `use package::types::User as Account` | `Account` **or** `types::User` — **not** bare `User` | + +A dependency's schema is qualified by its own path the same way +(`use greeting::hello::Greeting` brings `greeting::hello::Greeting`). A `use` never shadows a declaration in the current file: a local `struct User` -always wins over `use other::User`. +always wins over `use package::other::User`. ## Alias @@ -68,11 +124,16 @@ closest match when there is one: | `use` | Error | |---|---| -| `use typse::User` (no schema `typse`) | `no schema in this package or its dependencies matches 'typse::User' - did you mean 'types'?` | -| `use types::Usr` (`types` has no `Usr`) | `schema 'types' doesn't declare 'Usr' - did you mean 'User'?` | +| `use typse::User` (no schema `typse`, in the package or its dependencies) | `no schema in this package or its dependencies matches 'typse::User' - did you mean 'types'?` | +| `use package::types::Usr` (`types` has no `Usr`) | `schema 'types' doesn't declare 'Usr' - did you mean 'User'?` | + +Both are `import::unresolved`. `use types::User`, with `types` one of the +package's own schemas, isn't one of them: it's the +[bare own-schema path](#a-bare-path-to-your-own-schema-is-an-error) error, which +says to write `package::types::User`. -The editor reports the same errors as you type, with a quick fix to the closest -name. A `std::` path is checked the same way, against the +The editor reports the same unresolved-path errors as you type, with a quick fix +to the closest name. A `std::` path is checked the same way, against the [standard library](#the-standard-library): `std has no schema matching 'std::htp::Request' - did you mean 'std::http'?` diff --git a/docs/docs/languages/rust/client-and-server.md b/docs/docs/languages/rust/client-and-server.md index 073b621..577db38 100644 --- a/docs/docs/languages/rust/client-and-server.md +++ b/docs/docs/languages/rust/client-and-server.md @@ -1,9 +1,11 @@ -# Client & server - -A protocol on the lockstep `datagram` framing gets a client and a server: the -client sends a request and reads the next frame as its reply, one protocol per -transport. Every other protocol runs on a [connection](connections.md), the -default. This page assumes a schema like [Protocols](../../guides/idl/protocol.md)'s +# Lockstep `datagram`: client & server + +A protocol on the lockstep `datagram` framing (`@framing = "datagram"`) gets a +client and a server: the client sends a request and reads the next frame as its +reply, one protocol per transport. This page is only that case. Every other +protocol runs on a [connection](connections.md), the default, with its own +`serve` and `connect`; [What you use](index.md#what-you-use) says which is +which. This page assumes a schema like [Protocols](../../guides/idl/protocol.md)'s `Mail` example has been generated to Rust: ```ids @@ -19,19 +21,70 @@ protocol Mail { Full details are [Code generation](../../guides/codegen/index.md)'s job, not this page's — but the shapes below are what the generated file actually -contains, so the rest of this page can refer to them by name: +contains, so the rest of this page can refer to them by name. A lockstep +protocol's file has no entry-point header; in `lib` mode the crate root's docs list it +with the `serve` and `connect` to use. ```rust +/// Canonical digest of the frozen IR this file was generated from — the +/// two ends of a connection must agree on it, and the handshake checks. +pub const IR_HASH: u64 = 0x7ea94b595fcf4393; + +/// The package's wire format (`wire.format`): what this file's helpers +/// encode with, and what the peer has to speak too. +pub type Format = comline_runtime::format::Packed; + +#[doc(hidden)] +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct MailSendMessageParams { + pub message: Message, +} + pub trait Mail { fn send_message(&self, message: Message) -> Result>; fn fetch_inbox(&self) -> Result, Fault>; } -pub struct MailDispatcher(pub S); // implements `comline_runtime::contract::Dispatch` +#[doc(hidden)] +pub const MAIL_CALLS: &[&str] = &["send_message", "fetch_inbox"]; + +pub struct MailDispatcher(pub S); + +impl Dispatch for MailDispatcher { /* … */ } + +impl MailDispatcher { + pub fn serve(self, transport: &mut T) -> Result<(), RuntimeError> { + self.serve_with_format(transport, Format::default()) + } + + pub fn serve_with_format(self, transport: &mut T, format: W) + -> Result<(), RuntimeError> { + Server::new(self, format).serve(transport, IR_HASH) + } +} + pub struct MailClient(pub Client); -pub const IR_HASH: u64 = 0x…; // schema fingerprint, used in the handshake -pub type Format = comline_runtime::format::Packed; // the package's wire format +impl MailClient { + pub fn new(client: Client) -> Self { /* … */ } + + pub fn connect_with_format(transport: T, format: W) -> Result { + Ok(Self(Client::connect(transport, format, IR_HASH)?)) + } + + pub fn send_message(&mut self, message: Message) -> Result> { + let (reply, fmt) = self.0.call_with_timeout(Call::new(0, "send_message"), &MailSendMessageParams { message }, core::time::Duration::from_millis(1000))?; + // … + } + + pub fn fetch_inbox(&mut self) -> Result, CallError> { /* … */ } +} + +impl MailClient { + pub fn connect(transport: T) -> Result { + Self::connect_with_format(transport, Format::default()) + } +} ``` - `Mail` is the trait your implementation fills in — plain `&self`, a @@ -41,9 +94,19 @@ pub type Format = comline_runtime::format::Packed; // the package's wire format thing the schema does — it cannot raise. See [Error handling](#error-handling-two-layers) for the `Fault` wrapper. - `MailDispatcher` wraps any `S: Mail` and implements the runtime's - `Dispatch` trait — the thing a `Server` actually drives. + `Dispatch` trait — the thing a `Server` actually drives. Its `serve` is the + one call you make to serve. - `MailClient` wraps a `comline_runtime::client::Client` and gives you one method per function, already returning the right types. + `connect` is on `MailClient`, so it encodes with the package's + format; `connect_with_format` takes another. +- `IR_HASH` and `Format` are defined in this file. A package that also has a + [connection](connections.md) defines `Format` once, in `connection.rs`, and + re-exports it here. +- The plumbing is `pub`, so it's there if you wire a `Client` and `Server` by + hand, and `#[doc(hidden)]`, so it isn't in rustdoc: the `…Params` structs and + the `…_CALLS` table. What's left is the trait, the dispatcher, the client and + their error types. ## Transports today diff --git a/docs/docs/languages/rust/connections.md b/docs/docs/languages/rust/connections.md index 14acfe9..97d50a1 100644 --- a/docs/docs/languages/rust/connections.md +++ b/docs/docs/languages/rust/connections.md @@ -2,18 +2,18 @@ Every protocol runs on a [connection](../../guides/idl/protocol.md#calls-in-both-directions) unless it -picks the lockstep `datagram` framing, in which case it gets a [client and server](client-and-server.md) instead. - This page assumed the following schema: +picks the lockstep `datagram` framing, in which case it gets a +[client and server](client-and-server.md) instead. This page is the default +case in [What you use](index.md#what-you-use), and uses this schema: ```ids title="snippet.ids" protocol Chat { - function send(text: string) -> u64; - function count() -> u64; + function send(n: u32) -> u32; } @provider = Client protocol Events { - function message(text: string) -> bool; + function shown(n: u32) -> bool; function ping(); } ``` @@ -30,8 +30,8 @@ when the package has one connection to serve, and left out otherwise. They're left out when: - **No protocol is on a connection.** That includes a package with no - protocols at all. A protocol is on a connection when it uses `datagram@2` - (the default), or when the client provides it (`@provider = Client` or + protocols at all. A protocol is on a connection when it uses `datagram@3` + (the default) or `datagram@2`, or when the client provides it (`@provider = Client` or `Multiple`). A server-only protocol on `datagram@1` isn't, so a package of only those has no `serve`. The same goes for JSON-RPC protocols, which count only once one JSON-RPC protocol in the package is client-provided; then they @@ -68,15 +68,15 @@ serve(transport, Services { chat: ChatImpl })?; // The side that dials: handshake, provide the client's protocols, and call // the server's through their senders. let mut conn = connect(transport, ClientServices { events: EventsImpl::default() })?; -let sent = ChatSender::new(&mut conn).send("hi")?; +let sent = ChatSender::new(&mut conn).send(3)?; ``` - **`accept(transport, Services { .. })`** is `serve` without the serving: it returns the connection, for a server that calls the client first or serves one request at a time. - **`ClientServices`** holds the protocols the dialling side provides - (`@provider = Client` or `Multiple`). With none, `connect` takes only the - transport. + (`@provider = Client` or `Multiple`). With none, there is no `ClientServices` + and `connect` takes only the transport. - **Field names** are the protocol's name in snake case (`CharacterInventory` is `character_inventory`). Where two schemas declare a protocol of the same name, both are prefixed with their namespace. @@ -90,27 +90,119 @@ let sent = ChatSender::new(&mut conn).send("hi")?; ## What codegen emits +The entry points are in `connection.rs`, and open with a header that says, for +this package's protocols, what to implement, serve, dial and call: + ```rust +// Generated by Comline +// For Rust 1.85.0 or later; verified up to 1.99. +//! The package's protocols share one connection: `datagram@3` framing, the `comline@2` handshake. To use it: +//! +//! - Implement the trait of each protocol the server provides: `conformance::Chat`. +//! - Implement the trait of each protocol the client provides: `conformance::Events`. +//! - Serve with [`serve`]`(transport, Services { chat: .. })`, which serves every call until the peer leaves. [`accept`] hands the connection back first, for a server that calls the client or serves one call at a time. +//! - Dial with [`connect`]`(transport, ClientServices { events: .. })`. +//! - Call the server from the dialling side: `ChatSender::new(&mut conn).send(..)`. +//! - Call the client from the accepting side, on the connection [`accept`] returns or the peer a handler is given: `EventsSender::new(&mut conn).shown(..)`. +//! +//! [`Connection`](Connection) names the connection over a transport `T`, written `Connection`; [`Format`] is the package's wire format. + +/// The package's wire format (`wire.format`). +pub type Format = comline_runtime::format::Packed; + +/// Digest of every schema in the package — what a connection's handshake +/// checks, so both ends agree on each protocol's number. +pub const CONNECTION_IR_HASH: u64 = 0x1ad273c98d4e98fb; + +/// The framing the package's connection runs on (`datagram@3`). +pub type Framing = comline_runtime::contract::Datagram3Framing; + +/// The package's connection over the transport `T`: what [`accept`] and [`connect`] +/// return, written `Connection`: [`Format`] over [`Framing`]. +pub type Connection = comline_runtime::connection::Connection; + +pub struct Services { + pub chat: Chat, +} + +pub struct ClientServices { + pub events: Events, +} + +pub fn accept(transport: T, services: Services) -> Result, RuntimeError> { /* … */ } + +pub fn serve(transport: T, services: Services) -> Result<(), RuntimeError> { + accept(transport, services)?.serve() +} + +pub fn connect(transport: T, services: ClientServices) -> Result, RuntimeError> { /* … */ } + +// Also here, for the `comline@2` handshake: `negotiated`, `warnings` and +// `unavailable`, which read what it agreed, and `#[doc(hidden)]` `HELLO` and +// `handshake()`. +``` + +Each protocol's file has its trait, its sender, and the plumbing: + +```rust +// chat.rs (here, conformance.rs) +pub const IR_HASH: u64 = 0x1ad273c98d4e98fb; + +#[doc(hidden)] +pub use crate::connection::{CONNECTION_IR_HASH, Format}; + +#[doc(hidden)] +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct ChatSendParams { + pub n: u32, +} + pub trait Chat { - fn send(&self, peer: &mut impl Peer, text: &str) -> Result>; - fn count(&self, peer: &mut impl Peer) -> Result>; + fn send(&self, peer: &mut impl Peer, n: u32) -> Result>; +} + +#[doc(hidden)] +pub const CHAT_CALLS: &[&str] = &["send"]; + +#[doc(hidden)] +pub struct ChatDispatcher(pub S); + +impl ChatDispatcher { + #[doc(hidden)] + pub const PROTOCOL: ProtocolNumber = 0; + + pub fn provide_on(self, conn: &mut Connection) + where S: 'static { conn.provide(Self::PROTOCOL, self) } } -pub struct ChatDispatcher(pub S); // PROTOCOL, provide_on(&mut Connection) +/// Calls protocol `Chat` on the other end of a connection: the peer a +/// `Connection` reaches, or the one a handler was given. pub struct ChatSender<'p, P: Peer>(pub &'p mut P); -pub trait Events { /* the same shape */ } -pub struct EventsDispatcher(pub S); -pub struct EventsSender<'p, P: Peer>(pub &'p mut P); +impl<'p, P: Peer> ChatSender<'p, P> { + pub fn new(peer: &'p mut P) -> Self { /* … */ } -// Once per package: -pub type Format = comline_runtime::format::Packed; -pub const CONNECTION_IR_HASH: u64 = 0x…; // checked by the handshake -pub struct Services { pub chat: Chat } -pub struct ClientServices { pub events: Events } -pub fn accept(…); pub fn serve(…); pub fn connect(…); + pub fn send(&mut self, n: u32) -> Result> { + crate::connection::check_call(&mut *self.0, Self::PROTOCOL, 0, "conformance::Chat", "send")?; + let (reply, fmt) = self.0.call(Self::PROTOCOL, Call::new(0, "send"), &ChatSendParams { n })?; + // … + } +} + +// Events, EventsDispatcher (PROTOCOL = 1) and EventsSender, the same way; +// `ping` is one-way, so `EventsSender::ping` returns `Result<(), RuntimeError>`. ``` +`Format` and `CONNECTION_IR_HASH` are defined once, in `connection.rs`; each +protocol file re-exports them. The plumbing is `pub`, so you can wire a +connection [by hand](#by-hand), and `#[doc(hidden)]`, so it isn't in rustdoc: +the `…Params` structs, the `…_CALLS` tables, the dispatchers (`Services` provides +them on the connection, so you don't name one) and their `PROTOCOL` numbers. +What rustdoc shows is the traits, the senders, `Services`, `ClientServices`, +`accept`, `serve`, `connect`, `Connection` and `Format`. With +`datagram@2` and `comline@1`, the header is the same, there is no `Framing`, and +`Connection` is `Connection`. + It differs from a client and server in three ways: - **Handlers take the peer first:** the other end of the connection the call @@ -132,69 +224,97 @@ on a connection (see [Over JSON-RPC](#over-json-rpc)). ## By hand `serve` is a few lines over the runtime's `Connection`, which is also how to -pick another format for one connection: +pick another format for one connection. For the default `datagram@3` and +`comline@2`, the package's `handshake()` is the handshake, and `Datagram3Framing` +the framing: ```rust -use comline_runtime::connection::Connection; +use comline_runtime::contract::Datagram3Framing; +use my_package::connection::{handshake, Format, CONNECTION_IR_HASH}; -let mut conn = Connection::accept(transport, Format::default(), CONNECTION_IR_HASH)?; +let mut hs = handshake(); +let mut conn = comline_runtime::connection::Connection::accept_with( + transport, Format::default(), Datagram3Framing, &mut hs, CONNECTION_IR_HASH, +)?; ChatDispatcher(ChatImpl).provide_on(&mut conn); conn.serve()?; // until the transport closes ``` +The package's `accept` also keeps what `comline@2` agreed in the connection's +extensions, which `negotiated`, `warnings` and `unavailable` read, and each +sender checks before it calls. Opened as above, a connection has nothing to +check against, and every call goes. On `datagram@2` and `comline@1` the +connection is simpler, and `Connection::accept(transport, Format::default(), +CONNECTION_IR_HASH)` is all of it. + `serve_one()` handles a single frame instead, returning `Ok(false)` once the transport has closed. Between frames, this side can call the client on its own: ```rust conn.serve_one()?; -EventsSender::new(&mut conn).message("pushed")?; +EventsSender::new(&mut conn).shown(7)?; ``` -The dialling side is `Connection::connect` with the same arguments. While a -call waits for its reply, the connection serves whatever the server sends -first, such as the `Events::message` call its handler makes. A request to a +The dialling side is `Connection::connect_with` with the same arguments. While +a call waits for its reply, the connection serves whatever the server sends +first, such as the `Events::shown` call its handler makes. A request to a protocol this side doesn't provide is answered with a fault. ## Over JSON-RPC A JSON-RPC protocol the client provides runs on a connection too, and then so do the package's other JSON-RPC protocols -([the rules](../../guides/idl/protocol.md#json-rpc-on-a-connection)). Open the -connection with `JsonRpcFraming`, which the package's `serve` and `connect` -do for you; the rest of this page is unchanged: +([the rules](../../guides/idl/protocol.md#json-rpc-on-a-connection)). The +package's `serve` and `connect` open the connection with `JsonRpcFraming` and +the `Json` format, and `connection.rs` names them: + +```rust +/// The framing the package's connection runs on (`jsonrpc`). +pub type Framing = comline_runtime::framing::JsonRpcFraming; + +/// The package's connection over the transport `T`: what [`accept`] and [`connect`] +/// return, written `Connection`: JSON over [`Framing`]. +pub type Connection = comline_runtime::connection::Connection; +``` + +By hand, the rest of this page is unchanged: ```rust +use comline_runtime::format::Json; use comline_runtime::framing::JsonRpcFraming; use comline_runtime::handshake::ComlineHandshake; -let mut conn = Connection::accept_with(transport, Json, JsonRpcFraming, &mut ComlineHandshake, CONNECTION_IR_HASH)?; +let mut conn = Connection::accept_with(transport, Json::default(), JsonRpcFraming, &mut ComlineHandshake, CONNECTION_IR_HASH)?; // The dialling side: -let mut conn = Connection::connect_with(transport, Json, JsonRpcFraming, &mut ComlineHandshake, CONNECTION_IR_HASH)?; +let mut conn = Connection::connect_with(transport, Json::default(), JsonRpcFraming, &mut ComlineHandshake, CONNECTION_IR_HASH)?; ``` An `AsyncConnection` opens with `AsyncConnection::handshake(transport, Json, JsonRpcFraming, CONNECTION_IR_HASH)`. -- **Each call table holds method names:** `["send", "count"]`, or under - `method_names = qualified`, `["chat.Events/message", "chat.Events/ping"]`. +- **Each call table holds method names:** `["send"]`, or under + `method_names = qualified`, `["chat.Events/shown", "chat.Events/ping"]`. A request is routed to the provided protocol whose table has its method. - **A one-way call is a notification,** sent with no `id`. A request without one gets no reply, even if its function returns a value. +A JSON-RPC protocol that stays off a connection keeps its `Client` and +`Server`: `RpcDispatcher(MyRpc).serve(&mut transport)` and +`RpcClient::connect(transport)`, which encode JSON. + ## A handler calling back ```rust -struct Sent(u64); +struct Sent(u32); impl Chat for ChatImpl { - fn send(&self, peer: &mut impl Peer, text: &str) -> Result> { - let shown = EventsSender::new(peer).message(text).map_err(|_| Fault::Internal)?; + fn send(&self, peer: &mut impl Peer, n: u32) -> Result> { + let shown = EventsSender::new(peer).shown(n).map_err(|_| Fault::Internal)?; let sent = peer.extensions().get_mut::().map(|s| { s.0 += 1; s.0 }); let sent = sent.unwrap_or_else(|| { peer.extensions().insert(Sent(1)); 1 }); Ok(sent) } - // … } ``` @@ -213,16 +333,19 @@ another task while the connection serves, generate for the async driver. With `async = true` in [`comline.toml`](../../reference/package/comline-toml.md#async), connection protocols are generated for the runtime's `AsyncConnection` -instead, on any executor: +instead, on any executor. `Connection` becomes `AsyncConnection` +(over [`Framing`](#what-codegen-emits), where there is one): ```rust pub trait Chat: Send + Sync + 'static { - fn send(&self, peer: &impl AsyncPeer, text: &str) - -> impl Future>> + Send; - // … + fn send(&self, peer: &impl AsyncPeer, n: u32) -> impl ::core::future::Future>> + Send; } +#[doc(hidden)] pub struct ChatAsyncDispatcher(pub S); // PROTOCOL, provide_on(&mut AsyncConnection) + +/// Calls protocol `Chat` on the other end of a connection: the peer an +/// `AsyncConnection`'s handle reaches, or the one a handler was given. pub struct ChatAsyncSender<'p, P: AsyncPeer>(pub &'p P); ``` @@ -230,8 +353,8 @@ A handler is written as an `async fn`, and awaits its calls back: ```rust impl Chat for ChatImpl { - async fn send(&self, peer: &impl AsyncPeer, text: &str) -> Result> { - let shown = EventsAsyncSender::new(peer).message(text).await.map_err(|_| Fault::Internal)?; + async fn send(&self, peer: &impl AsyncPeer, n: u32) -> Result> { + let shown = EventsAsyncSender::new(peer).shown(n).await.map_err(|_| Fault::Internal)?; // … } } @@ -252,11 +375,11 @@ let client = connect(dialler, ClientServices { events: EventsImpl::default() }). let to_server = client.handle(); tokio::spawn(client.run()); -let sent = ChatAsyncSender::new(&to_server).send("hi").await?; +let sent = ChatAsyncSender::new(&to_server).send(3).await?; ``` -Requests are handled in order, except that while every running handler -waits on a call to the peer, the next one starts: it may be that call's +Requests are handled in order, except while every running handler +waits on a call to the peer: the next one starts, as it may be that call's nested request. `conn.concurrent(n)` lets several run at once, and `conn.set_timer(…)` gives `@timeout_ms` a clock. The runtime's `tokio` feature adds TCP (`async_connection::tokio::Tcp`) and a timer. diff --git a/docs/docs/languages/rust/framing-and-wire-format.md b/docs/docs/languages/rust/framing-and-wire-format.md index c6505e1..1711b94 100644 --- a/docs/docs/languages/rust/framing-and-wire-format.md +++ b/docs/docs/languages/rust/framing-and-wire-format.md @@ -67,9 +67,14 @@ the schema's `IR_HASH`. The generated code names the package's format once: ```rust +/// The package's wire format (`wire.format`). pub type Format = comline_runtime::format::Packed; ``` +It's in `connection.rs` when the package has a [connection](connections.md); +each protocol file re-exports it as `#[doc(hidden)]`. A package of lockstep +protocols only has no `connection.rs`, and each protocol file defines it. + The package's `serve` / `accept` / `connect`, and each lockstep protocol's own `serve` and `connect`, use it, so there's no format argument to pass: diff --git a/docs/docs/languages/rust/index.md b/docs/docs/languages/rust/index.md index 36f2d0a..b8623cf 100644 --- a/docs/docs/languages/rust/index.md +++ b/docs/docs/languages/rust/index.md @@ -5,6 +5,53 @@ source files) and `lib` mode (a buildable crate) — see [Library generation](../../guides/codegen/library-generation.md) for what each mode produces. +## What you use + +Which generated items you use depends on the protocol's framing and on who +provides it. The names below are for protocols `Chat` (the server provides it) +and `Events` (the client does), and `Mail` and `Rpc` for the others. + +| Case | You implement | To serve | To dial | To call through | +|---|---|---|---|---| +| **The default connection**: every protocol on one [connection](connections.md), `datagram@3` | each protocol's trait: `Chat`, and `Events` for what the client provides. Handlers take the peer first | `serve(transport, Services { chat })`. `accept(transport, Services { chat })` takes the same and hands back the connection first | `connect(transport, ClientServices { events })`, or `connect(transport)` when the client provides nothing | `ChatSender::new(&mut conn)`, on what `connect` returns, what `accept` returns, or the peer a handler is given. With `async = true`, `ChatAsyncSender::new(&conn.handle())` | +| **The lockstep `datagram`**: one protocol per transport ([lockstep](client-and-server.md)) | the protocol's trait: `Mail` | `MailDispatcher(MyMail).serve(&mut transport)` | `MailClient::connect(transport)` | `MailClient`'s methods; it takes `&mut self` | +| **JSON-RPC**, a protocol the client provides | as the default connection | as the default: the package's `serve` opens the connection with `JsonRpcFraming` ([over JSON-RPC](connections.md#over-json-rpc)) | as the default | as the default | +| **JSON-RPC**, a server-only protocol | the protocol's trait: `Rpc` | `RpcDispatcher(MyRpc).serve(&mut transport)` | `RpcClient::connect(transport)`, encoding JSON | `RpcClient`'s methods | +| **By hand** | the same traits | `Connection::accept_with(transport, Format::default(), Datagram3Framing, &mut handshake(), CONNECTION_IR_HASH)?`, then `ChatDispatcher(chat).provide_on(&mut conn)` and `conn.serve()?` ([by hand](connections.md#by-hand)). Lockstep: `Server::new(MailDispatcher(mail), format).serve(transport, IR_HASH)` | `Connection::connect_with(…)`, the same way. Lockstep: `MailClient::connect_with_format(transport, format)` | the same senders and clients | + +A package whose protocols disagree on the framing or the handshake has no one +connection, so no `serve` or `connect`; each protocol keeps its own dispatcher +and sender ([when they're generated](connections.md#when-theyre-generated)). + +### What's in the generated files + +A package with a connection gets `connection.rs` (in `lib` mode, the crate +root). It opens with a `//!` header saying which of the above to use, for this +package's protocols, and holds `Services`, `ClientServices`, `accept`, `serve` +and `connect`, plus three names every protocol file shares: + +- **`Format`**, the package's wire format, and **`CONNECTION_IR_HASH`**, the + digest the handshake checks. They're defined once, here. Each protocol file + re-exports them as `#[doc(hidden)]`, so by hand `Format` and + `CONNECTION_IR_HASH` come from `connection.rs`. +- **`Connection`**, the connection over a transport `T` (`Connection`): + what `accept` and `connect` return. +- **`Framing`**, the framing the connection runs on, named when it isn't the + runtime's default (`datagram@2`). + +The plumbing stays `pub`, so it's there for by-hand use, and is +`#[doc(hidden)]`, so it isn't in `cargo doc`: the `…Params` structs, the +`…_CALLS` tables, the dispatchers of a connection (`ChatDispatcher`, whose +`provide_on` is what `Services` calls), each protocol's `PROTOCOL` number, and +what the `comline@2` handshake is built from (`HELLO`, `handshake()`). What's left in rustdoc is what the header +tells you to use: the traits, the senders, `Services`, `ClientServices`, +`accept`, `serve`, `connect`, `Connection` and `Format`. A lockstep protocol's own +file has no header: in `lib` mode the crate root's docs list it, with the +`…Dispatcher(provider).serve(&mut transport)` and `…Client::connect(transport)?` +to use, and its dispatcher and client are documented as they are. + +The pages below show each case as it's generated. + ## Adding runtime to dependencies Not published to crates.io yet. Pin it by git rev, the same way the rest @@ -24,12 +71,13 @@ to the GPL-3.0 generator that only runs at build time). ## Where to go next -- [Client & server](client-and-server.md) — connecting, serving, and the - shape codegen actually emits. -- [Framing & wire format](framing-and-wire-format.md) — `Packed`, `Json` - and `MsgPack`; `Datagram2Framing`, `DatagramFraming` and `JsonRpcFraming`; - and how the package's `wire` key picks both. - [Connections](connections.md) — the default: every protocol on one connection, calls in both directions, sync or async. +- [Lockstep `datagram`: client & server](client-and-server.md) — the lockstep + framing's `Client` and `Dispatcher`, and the shape + codegen emits for them. +- [Framing & wire format](framing-and-wire-format.md) — `Packed`, `Json` + and `MsgPack`; `Datagram3Framing`, `Datagram2Framing`, `DatagramFraming` and + `JsonRpcFraming`; and how the package's `wire` key picks both. - [Sync, async & concurrency](concurrency.md) — sharing a lockstep `Client` between threads, and calling it from async code. diff --git a/docs/docs/languages/typescript/client-and-server.md b/docs/docs/languages/typescript/client-and-server.md index 2deef35..50c4318 100644 --- a/docs/docs/languages/typescript/client-and-server.md +++ b/docs/docs/languages/typescript/client-and-server.md @@ -1,7 +1,9 @@ -# Client & server +# Lockstep `datagram`: client & server -A protocol on the lockstep `datagram` framing gets a client and a server; every -other protocol runs on a [connection](connections.md), the default. This page +A protocol on the lockstep `datagram` framing (`@framing = "datagram"`) gets a +client and a server. This page is only that case; every other protocol runs on a +[connection](connections.md), the default, with its own `serve` and `connect` +([What you use](index.md#what-you-use) says which is which). This page follows the runtime's own test fixture — a lockstep `Chat` protocol with a throwing call, a plain call, a `()` return, and a one-way call: @@ -27,13 +29,36 @@ protocol Chat { ## What codegen emits ```typescript -export interface Message { body: string; seq: bigint; } -export const Message: Shape = { fields: { seq: "bigint" } }; +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 0x222ffe8dc03c4d62n; + +/** The package's wire format (`wire.format`): what this file's helpers +* encode with, and what the peer has to speak too. */ +export const Format: Codec = new PackedCodec(); + +export interface Message { + body: string; + seq: bigint; +} + +export const MessageLayout: Layout = { struct: [["body", "string"], ["seq", "u64"]] }; + export class RejectedError extends Error { static readonly ordinal = 0; - constructor(readonly data: Rejected) { … } + readonly data: Rejected; + constructor(data: Rejected) { /* … */ } } +export interface ChatSendParams { + text: string; +} + +/** @internal */ +export const ChatSendParamsLayout: Layout = { struct: [["text", "string"]] }; + +// … ChatHistoryParams and ChatNoteParams, and their layouts, the same way. + export interface Chat { /** @throws {RejectedError} */ send(params: ChatSendParams): Promise; @@ -42,19 +67,40 @@ export interface Chat { note(params: ChatNoteParams): Promise; } -export class ChatDispatcher implements Dispatch { constructor(private readonly impl: Chat) {} … } -export class ChatClient { … } -export function serveChat(impl: Chat, transport: Transport, codec: Codec, framing?: Framing): Promise; +/** @internal */ +export const CHAT_CALLS = ["send", "history", "wipe", "note"] as const; -export const IR_HASH = 0x…n; // schema fingerprint, used in the handshake +export class ChatDispatcher implements Dispatch { + constructor(impl: Chat) { /* … */ } + // … +} + +export class ChatClient { + constructor(client: Client) { /* … */ } + + static async connect(transport: Transport, codec: Codec = Format, framing: Framing = new DatagramFraming()): Promise { + return new ChatClient(await Client.connect(transport, codec, IR_HASH, framing)); + } + + async send(params: ChatSendParams): Promise { /* … */ } + async history(params: ChatHistoryParams): Promise { /* … */ } + async wipe(): Promise { /* … */ } + async note(params: ChatNoteParams): Promise { /* … */ } +} + +export function serveChat(impl: Chat, transport: Transport, codec: Codec = Format, framing: Framing = new DatagramFraming()): Promise { + return new Server(new ChatDispatcher(impl), codec, framing).serve(transport, IR_HASH); +} ``` +A lockstep protocol's file has no entry-point comment; in `lib` mode the +package's `index.ts` lists its `serveChat` and `ChatClient.connect`. + - `seq` is a `u64`, so it's a `bigint`. `number` holds integers exactly only up to 2^53, so every 64- and 128-bit integer is a `bigint`, and a constant - of one is written `7n`. A type that holds one, anywhere inside, also gets a - `Shape` of the same name. The generated client and dispatcher pass it to - the codec, which reads those integers exactly. Types without one are just - interfaces. + of one is written `7n`. Every type gets a `Layout` of the same name plus + `Layout` (`MessageLayout`), which the generated client and dispatcher pass to + the codec: it reads a `u64` as a `bigint`, and says how wide each integer is. - `Chat` is the interface your implementation fills in — every method `async`/`Promise`-returning, a thrown `*Error` class per declared `!` (several, comma-separated, if the function lists several). @@ -65,6 +111,12 @@ export const IR_HASH = 0x…n; // schema fingerprint, used in the handshake `ChatDispatcher`, run the handshake, serve. There's no dispatcher "class method" for this — it's a standalone function alongside the classes. +- `Format` and `IR_HASH` are exported by this file. A package that also has a + [connection](connections.md) keeps `Format` in a `wire.ts`, and this file + imports it from there. +- What's marked `@internal` is wire plumbing: exported, so a `Client` and + `Server` can be wired by hand, and not what you call (`…ParamsLayout`, + `…_CALLS`). ## Transport today diff --git a/docs/docs/languages/typescript/connections.md b/docs/docs/languages/typescript/connections.md index f156430..887b36f 100644 --- a/docs/docs/languages/typescript/connections.md +++ b/docs/docs/languages/typescript/connections.md @@ -3,18 +3,17 @@ Every protocol runs on a [connection](../../guides/idl/protocol.md#calls-in-both-directions) unless it picks the lockstep `datagram` framing, in which case it gets a -[client and server](client-and-server.md) instead. This page uses this -schema: +[client and server](client-and-server.md) instead. This page is the default +case in [What you use](index.md#what-you-use), and uses this schema: ```ids protocol Chat { - function send(text: string) -> u64; - function count() -> u64; + function send(n: u32) -> u32; } @provider = Client protocol Events { - function message(text: string) -> bool; + function shown(n: u32) -> bool; function ping(); } ``` @@ -31,8 +30,8 @@ when the package has one connection to serve, and left out otherwise. They're left out when: - **No protocol is on a connection.** That includes a package with no - protocols at all. A protocol is on a connection when it uses `datagram@2` - (the default), or when the client provides it (`@provider = Client` or + protocols at all. A protocol is on a connection when it uses `datagram@3` + (the default) or `datagram@2`, or when the client provides it (`@provider = Client` or `Multiple`). A server-only protocol on `datagram@1` isn't, so a package of only those has no `serve`. The same goes for JSON-RPC protocols, which count only once one JSON-RPC protocol in the package is client-provided; then they @@ -50,7 +49,8 @@ When a package declares protocols but none is on a connection, They're in `connection.ts`. In `lib` mode the package's `index.ts` re-exports it, so import from the package; in `code` mode import from the -file, wherever you placed it. +file, wherever you placed it. `Format` and `CONNECTION_IR_HASH` are in +`wire.ts`, which `connection.ts` re-exports. ```ts // `lib` mode @@ -67,14 +67,14 @@ await serve(transport, { chat: chatImpl }); // The side that dials: handshake, provide the client's protocols, and call // the server's through their senders. const conn = await connect(transport, { events: eventsImpl }); -const sent = await new chat.ChatSender(conn).send({ text: "hi" }); +const sent = await new chat.ChatSender(conn).send({ n: 3 }); ``` - **`accept(transport, services)`** returns the connection, already serving, so the server can call the client through it. - **`ClientServices`** holds the protocols the dialling side provides - (`@provider = Client` or `Multiple`). With none, `connect` takes only the - transport. + (`@provider = Client` or `Multiple`). With none, there is no `ClientServices` + and `connect` takes only the transport. - **Field names** are the protocol's name in camelCase (`CharacterInventory` is `characterInventory`), prefixed with the namespace where two schemas declare a protocol of the same name. @@ -83,37 +83,133 @@ const sent = await new chat.ChatSender(conn).send({ text: "hi" }); handshake are the protocols'. When the protocols on connections disagree on either, no one connection carries them all, so these functions aren't generated and `comline generation` warns why. +- **A schema named `wire`** can't be used, since the package's `wire.ts` would + overwrite it. ## What codegen emits +The entry points are in `connection.ts`, which opens with a comment saying, for +this package's protocols, what to implement, serve, dial and call: + ```ts +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +/** + * Where to start: + * + * - Implement what you provide: `Chat`, `Events` (in `./conformance.js`). + * - Serve with `serve(transport, { chat })`; `accept(transport, { chat })` takes the same and hands back the connection. + * - Dial with `connect(transport, { events })`. + * - Call the other end with `new ChatSender(conn).send(…)`, on the connection `connect` returns or the peer a handler is given. + * + * What is marked internal is wire plumbing: exported for hand-written use, and not what + * a user calls. + */ + +import { CONNECTION_IR_HASH, Format } from "./wire.js"; + +/** The package's wire format and the digest of every schema in it, which every file of the package shares. */ +export { CONNECTION_IR_HASH, Format } from "./wire.js"; + +/** What the accepting side provides: one field per protocol, so leaving one out doesn't type-check. */ +export interface Services { + chat: ns_conformance.Chat; +} + +/** What the dialling side provides: one field per protocol, so leaving one out doesn't type-check. */ +export interface ClientServices { + events: ns_conformance.Events; +} + +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ +export function provideServices(conn: Connection, services: Services): void { /* … */ } + +// provideClientServices, the same for `ClientServices`, also `@internal`. + +export async function accept(transport: Transport, services: Services): Promise { + const agreed = handshake(); + const conn = await Connection.accept(transport, Format, CONNECTION_IR_HASH, new Datagram3Framing(), agreed); + conn.extensions.set(agreed.negotiated!); + provideServices(conn, services); + return conn; +} + +/** {@link accept}, then serve every call until the peer leaves. */ +export async function serve(transport: Transport, services: Services): Promise { + await (await accept(transport, services)).closed; +} + +export async function connect(transport: Transport, services: ClientServices): Promise { /* … */ } + +// Also here, for the `comline@2` handshake: `negotiated` and `warnings`, which +// read what it agreed, and `@internal` `HELLO` and `handshake()`. +``` + +`wire.ts` holds what every file of the package shares: + +```ts +/** The package's wire format (`wire.format`). */ +export const Format: Codec = new PackedCodec(); + +/** Digest of every schema in the package — what a connection's handshake +* checks, so both ends agree on each protocol's number. */ +export const CONNECTION_IR_HASH = 0x1ad273c98d4e98fbn; +``` + +Each protocol's file has its interface, its sender, and the plumbing: + +```ts +// conformance.ts +export interface ChatSendParams { + n: number; +} + +/** @internal */ +export const ChatSendParamsLayout: Layout = { struct: [["n", "u32"]] }; + export interface Chat { - send(peer: Peer, params: ChatSendParams): Promise; - count(peer: Peer): Promise; + send(peer: Peer, params: ChatSendParams): Promise; } +/** @internal */ +export const CHAT_CALLS = ["send"] as const; + +/** @internal */ export class ChatDispatcher implements Dispatch { - static readonly PROTOCOL = 0; - constructor(impl: Chat); - provideOn(conn: Connection): void; + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + constructor(impl: Chat) { /* … */ } + provideOn(conn: Connection): void { /* … */ } + // … } +/** Calls protocol `Chat` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ export class ChatSender { - constructor(peer: Peer); - send(params: ChatSendParams): Promise; - count(): Promise; -} + constructor(peer: Peer) { /* … */ } -// Events, EventsDispatcher (PROTOCOL = 1) and EventsSender, the same way. + async send(params: ChatSendParams): Promise { + checkCall(this.peer, ChatSender.PROTOCOL, 0, "conformance::Chat", "send"); + const env = await this.peer.call(ChatSender.PROTOCOL, { id: 0, name: "send" }, params, { layout: ChatSendParamsLayout }); + // … + } +} -// Once per package, in connection.ts: -export const Format: Codec = new PackedCodec(); -export const CONNECTION_IR_HASH = 0x…n; // checked by the handshake -export interface Services { chat: Chat } -export interface ClientServices { events: Events } -export async function accept(…); serve(…); connect(…); +// Events, EventsDispatcher (PROTOCOL = 1) and EventsSender, the same way; +// `ping` is one-way, so `EventsSender.ping()` resolves to `void`. ``` +`u32` is a `number`; a `u64` would be a `bigint`. The plumbing is exported, so +you can wire a connection [by hand](#by-hand), and `@internal`, so it isn't what +you call: the `…ParamsLayout` constants, the `…_CALLS` tables, and the +dispatchers (`provideServices` builds them, so you don't name one). With +`datagram@2` and `comline@1`, the comment is the same, `accept` and `connect` +call `Connection.accept(transport, Format, CONNECTION_IR_HASH)` without a +handshake of their own, and there is no `checkCall`. + It differs from a client and server in three ways: - **Handlers take the peer first:** the other end of the connection the call @@ -135,24 +231,36 @@ There's no `serveChat` helper: the package's `serve` serves them all. Protocols ## By hand The package's functions are a few lines over the runtime's `Connection`, -which is also how to pick another codec for one connection: +which is also how to pick another codec for one connection. For the default +`datagram@3` and `comline@2`, the package's `handshake()` is the handshake: ```ts -import { Connection } from "@comline/runtime"; +import { Connection, Datagram3Framing } from "@comline/runtime"; +import { CONNECTION_IR_HASH, Format } from "./generated/wire.js"; +import { handshake } from "./generated/connection.js"; // The side that accepts. -const server = await Connection.accept(transport, Format, CONNECTION_IR_HASH); +const agreed = handshake(); +const server = await Connection.accept(transport, Format, CONNECTION_IR_HASH, new Datagram3Framing(), agreed); +server.extensions.set(agreed.negotiated!); new ChatDispatcher(chatImpl).provideOn(server); // The side that dials. -const client = await Connection.connect(transport, Format, CONNECTION_IR_HASH); +const client = await Connection.connect(transport, Format, CONNECTION_IR_HASH, new Datagram3Framing(), handshake()); new EventsDispatcher(eventsImpl).provideOn(client); -const sent = await new ChatSender(client).send({ text: "hi" }); +const sent = await new ChatSender(client).send({ n: 3 }); // The server calls the client on its own. -await new EventsSender(server).message({ text: "pushed" }); +await new EventsSender(server).shown({ n: 7 }); ``` +The package's `accept` and `connect` keep what `comline@2` agreed in the +connection's extensions, as the `server.extensions.set(…)` line does, for +`negotiated` and `warnings` to read and for each sender to check before it +calls. A connection opened without it has nothing to check against, and every +call goes. On `datagram@2` and `comline@1` there's nothing to keep, and +`Connection.accept(transport, Format, CONNECTION_IR_HASH)` is all of it. + A connection starts reading as soon as it's made, and `closed` resolves when the transport closes. Calls still waiting then reject with a `transport` error. A request to a protocol this side doesn't provide is answered with a @@ -164,7 +272,7 @@ A JSON-RPC protocol the client provides runs on a connection too, and then so do the package's other JSON-RPC protocols ([the rules](../../guides/idl/protocol.md#json-rpc-on-a-connection)). Pass `JsonRpcConnectionFraming` to both ends (the package's `serve` and `connect` -do); the rest of this page is unchanged: +do, with a `JsonCodec`); the rest of this page is unchanged: ```ts import { Connection, JsonCodec, JsonRpcConnectionFraming } from "@comline/runtime"; @@ -173,30 +281,31 @@ const server = await Connection.accept(transport, new JsonCodec(), CONNECTION_IR const client = await Connection.connect(transport, new JsonCodec(), CONNECTION_IR_HASH, new JsonRpcConnectionFraming()); ``` -- **Each call table holds method names:** `["send", "count"]`, or under - `method_names = qualified`, `["chat.Events/message", "chat.Events/ping"]`. +- **Each call table holds method names:** `["send"]`, or under + `method_names = qualified`, `["chat.Events/shown", "chat.Events/ping"]`. A request is routed to the provided protocol whose table has its method. - **A one-way call is a notification,** sent with no `id`. A request without one gets no reply, even if its function returns a value. +A JSON-RPC protocol that stays off a connection keeps its client and server: +`serveRpc(impl, transport)` and `RpcClient.connect(transport)`, which encode +JSON over `JsonRpcFraming`. + ## A handler calling back ```ts class Sent { - constructor(public count: bigint) {} + constructor(public count: number) {} } const chatImpl: Chat = { - async send(peer, { text }) { - await new EventsSender(peer).message({ text }); - const sent = peer.extensions.get(Sent) ?? new Sent(0n); + async send(peer, { n }) { + await new EventsSender(peer).shown({ n }); + const sent = peer.extensions.get(Sent) ?? new Sent(0); sent.count++; peer.extensions.set(sent); return sent.count; }, - async count(peer) { - return peer.extensions.get(Sent)?.count ?? 0n; - }, }; ``` diff --git a/docs/docs/languages/typescript/framing-and-wire-format.md b/docs/docs/languages/typescript/framing-and-wire-format.md index 50a45c2..e7ccd66 100644 --- a/docs/docs/languages/typescript/framing-and-wire-format.md +++ b/docs/docs/languages/typescript/framing-and-wire-format.md @@ -30,9 +30,13 @@ const client = await Client.connect(transport, codec, IR_HASH, new JsonRpcFramin The generated code exports the package's format: ```typescript +/** The package's wire format (`wire.format`). */ export const Format: Codec = new PackedCodec(); ``` +It's in a `wire.ts` shared by the package's files when more than one needs it +(`connection.ts` re-exports it), and in the protocol's own file otherwise. + The package's `serve` / `accept` / `connect`, and each lockstep helper, use it by default; a lockstep helper takes another `Codec` as an optional argument. diff --git a/docs/docs/languages/typescript/index.md b/docs/docs/languages/typescript/index.md index 21211b8..49a5e12 100644 --- a/docs/docs/languages/typescript/index.md +++ b/docs/docs/languages/typescript/index.md @@ -10,6 +10,44 @@ reference until it is; `comline-codegen-typescript`'s own pin on the runtime (by git rev, like the rest of this toolchain) is the pattern to copy. +## What you use + +Which generated items you use depends on the protocol's framing and on who +provides it. The names below are for protocols `Chat` (the server provides it) +and `Events` (the client does), and `Mail` and `Rpc` for the others. + +| Case | You implement | To serve | To dial | To call through | +|---|---|---|---|---| +| **The default connection**: every protocol on one [connection](connections.md), `datagram@3` | each protocol's interface: `Chat`, and `Events` for what the client provides. Handlers take the peer first | `serve(transport, { chat })`. `accept(transport, { chat })` takes the same and hands back the connection | `connect(transport, { events })`, or `connect(transport)` when the client provides nothing | `new ChatSender(conn).send({ n })`, on what `connect` returns, what `accept` returns, or the peer a handler is given | +| **The lockstep `datagram`**: one protocol per transport ([lockstep](client-and-server.md)) | the protocol's interface: `Mail` | `serveMail(impl, transport)` | `MailClient.connect(transport)` | `MailClient`'s methods | +| **JSON-RPC**, a protocol the client provides | as the default connection | as the default: the package's `serve` opens the connection with `JsonCodec` and `JsonRpcConnectionFraming` ([over JSON-RPC](connections.md#over-json-rpc)) | as the default | as the default | +| **JSON-RPC**, a server-only protocol | the protocol's interface: `Rpc` | `serveRpc(impl, transport)` | `RpcClient.connect(transport)`, encoding JSON | `RpcClient`'s methods | +| **By hand** | the same interfaces | `Connection.accept(transport, Format, CONNECTION_IR_HASH, new Datagram3Framing(), handshake())`, then `new ChatDispatcher(chat).provideOn(conn)` ([by hand](connections.md#by-hand)). Lockstep: `new Server(new MailDispatcher(mail), codec, framing).serve(transport, IR_HASH)` | `Connection.connect(…)`, the same way. Lockstep: `Client.connect(transport, codec, IR_HASH, framing)` | the same senders and clients | + +A package whose protocols disagree on the framing or the handshake has no one +connection, so no `serve` or `connect`; each protocol keeps its own dispatcher +and sender ([when they're generated](connections.md#when-theyre-generated)). + +### What's in the generated files + +A package with a connection gets `connection.ts`. It opens with a comment +saying which of the above to use, for this package's protocols, and holds +`Services`, `ClientServices`, `accept`, `serve` and `connect`. In `lib` mode the +package's `index.ts` opens with a comment of the same kind, and lists each lockstep +protocol's `serve` and `Client.connect` too. A lockstep +protocol's own file has no such comment. + +The package's `Format` (its codec) and `CONNECTION_IR_HASH` (the digest the +handshake checks) are shared by every file of the package. When more than one +file needs them they're in a `wire.ts` of their own, which `connection.ts` +re-exports; a lone file keeps its own. + +What is marked `@internal` is wire plumbing: the `…ParamsLayout` constants, the +`…_CALLS` tables, the dispatchers of a connection, `provideServices` and +`provideClientServices`, and what the `comline@2` handshake is built from +(`HELLO`, `handshake()`). It stays exported, for by-hand use, and is not what you +call. + ## The mirror fact to Rust's Where the Rust runtime is sync and blocking by design, the TypeScript @@ -61,9 +99,10 @@ median of 5. They are not a CI gate; see ## Where to go next -- [Client & server](client-and-server.md) — connecting, serving, and the - shape codegen actually emits. - [Connections](connections.md) — the default: every protocol on one connection, calls in both directions. +- [Lockstep `datagram`: client & server](client-and-server.md) — the lockstep + framing's `Client`, dispatcher and `serve`, and the shape + codegen emits for them. - [Framing & wire format](framing-and-wire-format.md) — what's pluggable today and what isn't yet. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 0df5e41..a8e754c 100755 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -45,16 +45,16 @@ nav: - Rust: - 'languages/rust/index.md' - - Client & server: 'languages/rust/client-and-server.md' - - Framing & wire format: 'languages/rust/framing-and-wire-format.md' - Connections: 'languages/rust/connections.md' + - Lockstep datagram: 'languages/rust/client-and-server.md' + - Framing & wire format: 'languages/rust/framing-and-wire-format.md' - Sync, async & concurrency: 'languages/rust/concurrency.md' - TypeScript: - 'languages/typescript/index.md' - - Client & server: 'languages/typescript/client-and-server.md' - - Framing & wire format: 'languages/typescript/framing-and-wire-format.md' - Connections: 'languages/typescript/connections.md' + - Lockstep datagram: 'languages/typescript/client-and-server.md' + - Framing & wire format: 'languages/typescript/framing-and-wire-format.md' - C: 'languages/c/index.md'