diff --git a/conformance/Cargo.toml b/conformance/Cargo.toml index 2367b46..41a0ce9 100644 --- a/conformance/Cargo.toml +++ b/conformance/Cargo.toml @@ -19,5 +19,5 @@ comline-codegen = { path = "../codegen" } [dev-dependencies] eyre = "0.6.8" serde_json = "1.0" -comline-codegen-rust = { git = "https://github.com/ComlineProject/comline-rust", rev = "2d2c8853727929a7b350b3017c9ff86cb2ec8911" } -comline-codegen-typescript = { git = "https://github.com/ComlineProject/comline-typescript", rev = "c44b39d68035bd968cec0cd75afb6c6230c4ab76" } +comline-codegen-rust = { git = "https://github.com/ComlineProject/comline-rust", rev = "dd1c29e6560a0ffd7893c59715b31d43b88c585f" } +comline-codegen-typescript = { git = "https://github.com/ComlineProject/comline-typescript", rev = "d377fbf07cf6c0f004e9d5dd4fbd6fa15ea9d0bc" } diff --git a/conformance/tests/golden/connections/rust/conformance.rs b/conformance/tests/golden/connections/rust/conformance.rs index ab01861..b5e3fc2 100644 --- a/conformance/tests/golden/connections/rust/conformance.rs +++ b/conformance/tests/golden/connections/rust/conformance.rs @@ -12,14 +12,10 @@ use comline_runtime::transport::Transport; /// two ends of a connection must agree on it, and the handshake checks. pub const IR_HASH: u64 = 0xb97e34b203ec1425; -/// 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 = 0xb97e34b203ec1425; - -/// 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)] +pub use crate::connection::{CONNECTION_IR_HASH, Format}; +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct ChatSendParams { pub n: u32, @@ -33,8 +29,10 @@ pub trait Chat { 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 Dispatch for ChatDispatcher { @@ -89,6 +87,7 @@ impl Dispatch for ChatDispatcher { impl ChatDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -109,6 +108,7 @@ pub struct ChatSender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> ChatSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; pub fn new(peer: &'p mut P) -> Self { @@ -125,6 +125,7 @@ impl<'p, P: Peer> ChatSender<'p, P> { } } +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct EventsShownParams { pub n: u32, @@ -139,8 +140,10 @@ pub trait Events { fn ping(&self, peer: &mut impl Peer); } +#[doc(hidden)] pub const EVENTS_CALLS: &[&str] = &["shown", "ping"]; +#[doc(hidden)] pub struct EventsDispatcher(pub S); impl Dispatch for EventsDispatcher { @@ -203,6 +206,7 @@ impl Dispatch for EventsDispatcher { impl EventsDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 1; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -223,6 +227,7 @@ pub struct EventsSender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> EventsSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 1; pub fn new(peer: &'p mut P) -> Self { diff --git a/conformance/tests/golden/connections/rust/connection.rs b/conformance/tests/golden/connections/rust/connection.rs index 43d1fdb..071340b 100644 --- a/conformance/tests/golden/connections/rust/connection.rs +++ b/conformance/tests/golden/connections/rust/connection.rs @@ -1,5 +1,19 @@ // Generated by Comline // For Rust 1.85.0 or later; verified up to 1.99. +//! The package's protocols share one connection: `datagram@2` framing, the `comline@1` 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. + +use comline_runtime::contract::RuntimeError; +use comline_runtime::transport::Transport; + /// The package's wire format (`wire.format`). pub type Format = comline_runtime::format::Packed; @@ -7,6 +21,10 @@ pub type Format = comline_runtime::format::Packed; /// checks, so both ends agree on each protocol's number. pub const CONNECTION_IR_HASH: u64 = 0xb97e34b203ec1425; +/// The package's connection over the transport `T`: what [`accept`] and [`connect`] +/// return, written `Connection`: [`Format`] over the default framing. +pub type Connection = comline_runtime::connection::Connection; + /// What the accepting side provides: one field per protocol, so leaving one out /// doesn't compile. pub struct Services { @@ -15,7 +33,7 @@ pub struct Services { impl Services { /// Provide every protocol on `conn`: the peer's calls to them come here. - pub fn provide_on(self, conn: &mut comline_runtime::connection::Connection) { + pub fn provide_on(self, conn: &mut Connection) { crate::conformance::ChatDispatcher(self.chat).provide_on(conn); } } @@ -28,7 +46,7 @@ pub struct ClientServices { impl ClientServices { /// Provide every protocol on `conn`: the peer's calls to them come here. - pub fn provide_on(self, conn: &mut comline_runtime::connection::Connection) { + pub fn provide_on(self, conn: &mut Connection) { crate::conformance::EventsDispatcher(self.events).provide_on(conn); } } @@ -37,21 +55,21 @@ impl ClientServices { /// every protocol in `services` on it. The connection comes back not yet /// served, for a server that calls the client first, or serves one call at /// a time. -pub fn accept(transport: T, services: Services) -> Result, comline_runtime::contract::RuntimeError> { +pub fn accept(transport: T, services: Services) -> Result, RuntimeError> { let mut conn = comline_runtime::connection::Connection::accept(transport, Format::default(), CONNECTION_IR_HASH)?; services.provide_on(&mut conn); Ok(conn) } /// [`accept`], then serve every call until the peer leaves. -pub fn serve(transport: T, services: Services) -> Result<(), comline_runtime::contract::RuntimeError> { +pub fn serve(transport: T, services: Services) -> Result<(), RuntimeError> { accept(transport, services)?.serve() } /// Dial over `transport`: run the handshake, then provide every protocol in /// `services`, which the server calls. Call the server's protocols through /// their senders. -pub fn connect(transport: T, services: ClientServices) -> Result, comline_runtime::contract::RuntimeError> { +pub fn connect(transport: T, services: ClientServices) -> Result, RuntimeError> { let mut conn = comline_runtime::connection::Connection::connect(transport, Format::default(), CONNECTION_IR_HASH)?; services.provide_on(&mut conn); Ok(conn) diff --git a/conformance/tests/golden/connections/typescript/conformance.ts b/conformance/tests/golden/connections/typescript/conformance.ts index 89b6bdb..814c58c 100644 --- a/conformance/tests/golden/connections/typescript/conformance.ts +++ b/conformance/tests/golden/connections/typescript/conformance.ts @@ -4,7 +4,6 @@ import { RuntimeError, resolveKind, - PackedCodec, type Codec, type Connection, type Dispatch, @@ -18,26 +17,21 @@ import { * two ends of a connection must agree on it. */ export const IR_HASH = 0xb97e34b203ec1425n; -/** 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 = 0xb97e34b203ec1425n; - -/** 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 ChatSendParams { n: number; } +/** @internal */ export const ChatSendParamsLayout: Layout = { struct: [["n", "u32"]] }; export interface Chat { send(peer: Peer, params: ChatSendParams): Promise; } +/** @internal */ export const CHAT_CALLS = ["send"] as const; +/** @internal */ export class ChatDispatcher implements Dispatch { /** This protocol's number on a connection. */ static readonly PROTOCOL = 0; @@ -74,7 +68,7 @@ export class ChatDispatcher implements Dispatch { } } - /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)`, or let the package's `serve` / `connect` do it. */ + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)` (`Format` and `CONNECTION_IR_HASH` are in `./wire.js`), or let the package's `serve` / `connect` do it. */ provideOn(conn: Connection): void { conn.provide(ChatDispatcher.PROTOCOL, this); } @@ -103,6 +97,7 @@ export interface EventsShownParams { n: number; } +/** @internal */ export const EventsShownParamsLayout: Layout = { struct: [["n", "u32"]] }; export interface Events { @@ -110,8 +105,10 @@ export interface Events { ping(peer: Peer): Promise; } +/** @internal */ export const EVENTS_CALLS = ["shown", "ping"] as const; +/** @internal */ export class EventsDispatcher implements Dispatch { /** This protocol's number on a connection. */ static readonly PROTOCOL = 1; @@ -156,7 +153,7 @@ export class EventsDispatcher implements Dispatch { } } - /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.connect(transport, Format, CONNECTION_IR_HASH)`, or let the package's `serve` / `connect` do it. */ + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.connect(transport, Format, CONNECTION_IR_HASH)` (`Format` and `CONNECTION_IR_HASH` are in `./wire.js`), or let the package's `serve` / `connect` do it. */ provideOn(conn: Connection): void { conn.provide(EventsDispatcher.PROTOCOL, this); } diff --git a/conformance/tests/golden/connections/typescript/connection.ts b/conformance/tests/golden/connections/typescript/connection.ts index 1f2a462..18b3931 100644 --- a/conformance/tests/golden/connections/typescript/connection.ts +++ b/conformance/tests/golden/connections/typescript/connection.ts @@ -1,27 +1,37 @@ // 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, - PackedCodec, - type Codec, type Transport, } from "@comline/runtime"; import * as ns_conformance from "./conformance.js"; +import { CONNECTION_IR_HASH, Format } from "./wire.js"; -/** 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 = 0xb97e34b203ec1425n; +/** 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; } -/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ export function provideServices(conn: Connection, services: Services): void { new ns_conformance.ChatDispatcher(services.chat).provideOn(conn); } @@ -31,7 +41,10 @@ export interface ClientServices { events: ns_conformance.Events; } -/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ export function provideClientServices(conn: Connection, services: ClientServices): void { new ns_conformance.EventsDispatcher(services.events).provideOn(conn); } diff --git a/conformance/tests/golden/connections/typescript/wire.ts b/conformance/tests/golden/connections/typescript/wire.ts new file mode 100644 index 0000000..351fa7f --- /dev/null +++ b/conformance/tests/golden/connections/typescript/wire.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + PackedCodec, + type Codec, +} from "@comline/runtime"; + +/** 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 = 0xb97e34b203ec1425n; diff --git a/conformance/tests/golden/connections_async/rust/conformance.rs b/conformance/tests/golden/connections_async/rust/conformance.rs index 638304c..11b4f9b 100644 --- a/conformance/tests/golden/connections_async/rust/conformance.rs +++ b/conformance/tests/golden/connections_async/rust/conformance.rs @@ -12,14 +12,10 @@ use comline_runtime::contract::{ConnectionFraming, ProtocolNumber}; /// two ends of a connection must agree on it, and the handshake checks. pub const IR_HASH: u64 = 0xb97e34b203ec1425; -/// 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 = 0xb97e34b203ec1425; - -/// 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)] +pub use crate::connection::{CONNECTION_IR_HASH, Format}; +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct ChatSendParams { pub n: u32, @@ -33,8 +29,10 @@ pub trait Chat: Send + Sync + 'static { fn send(&self, peer: &impl AsyncPeer, n: u32) -> impl ::core::future::Future>> + Send; } +#[doc(hidden)] pub const CHAT_CALLS: &[&str] = &["send"]; +#[doc(hidden)] pub struct ChatAsyncDispatcher(pub S); impl AsyncDispatch for ChatAsyncDispatcher { @@ -71,6 +69,7 @@ impl AsyncDispatch for ChatAsyncDispatcher { impl ChatAsyncDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -91,6 +90,7 @@ pub struct ChatAsyncSender<'p, P: AsyncPeer>(pub &'p P); impl<'p, P: AsyncPeer> ChatAsyncSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; pub fn new(peer: &'p P) -> Self { @@ -108,6 +108,7 @@ impl<'p, P: AsyncPeer> ChatAsyncSender<'p, P> { } } +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct EventsShownParams { pub n: u32, @@ -122,8 +123,10 @@ pub trait Events: Send + Sync + 'static { fn ping(&self, peer: &impl AsyncPeer) -> impl ::core::future::Future + Send; } +#[doc(hidden)] pub const EVENTS_CALLS: &[&str] = &["shown", "ping"]; +#[doc(hidden)] pub struct EventsAsyncDispatcher(pub S); impl AsyncDispatch for EventsAsyncDispatcher { @@ -168,6 +171,7 @@ impl AsyncDispatch for EventsAsyncDispatcher { impl EventsAsyncDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 1; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -188,6 +192,7 @@ pub struct EventsAsyncSender<'p, P: AsyncPeer>(pub &'p P); impl<'p, P: AsyncPeer> EventsAsyncSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 1; pub fn new(peer: &'p P) -> Self { diff --git a/conformance/tests/golden/connections_async/rust/connection.rs b/conformance/tests/golden/connections_async/rust/connection.rs index 85bcd62..f130cbd 100644 --- a/conformance/tests/golden/connections_async/rust/connection.rs +++ b/conformance/tests/golden/connections_async/rust/connection.rs @@ -1,5 +1,19 @@ // Generated by Comline // For Rust 1.85.0 or later; verified up to 1.99. +//! The package's protocols share one connection: `datagram@2` framing, the `comline@1` 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: .. }).await`, which runs until the peer leaves. [`accept`] hands the connection back first, not yet running: take its `handle()` to call the client, then `run().await` it. +//! - Dial with [`connect`]`(transport, ClientServices { events: .. }).await`, then `run().await` the connection it returns. +//! - Call the server from the dialling side: `ChatAsyncSender::new(&conn.handle()).send(..).await`. +//! - Call the client from the accepting side, on the connection [`accept`] returns or the peer a handler is given: `EventsAsyncSender::new(&conn.handle()).shown(..).await`. +//! +//! [`Connection`](Connection) names the connection over a transport `T`, written `Connection`; [`Format`] is the package's wire format. + +use comline_runtime::contract::RuntimeError; +use comline_runtime::transport::AsyncTransport; + /// The package's wire format (`wire.format`). pub type Format = comline_runtime::format::Packed; @@ -7,6 +21,10 @@ pub type Format = comline_runtime::format::Packed; /// checks, so both ends agree on each protocol's number. pub const CONNECTION_IR_HASH: u64 = 0xb97e34b203ec1425; +/// The package's connection over the transport `T`: what [`accept`] and [`connect`] +/// return, written `Connection`: [`Format`] over the default framing. +pub type Connection = comline_runtime::connection::AsyncConnection; + /// What the accepting side provides: one field per protocol, so leaving one out /// doesn't compile. pub struct Services { @@ -15,7 +33,7 @@ pub struct Services { impl Services { /// Provide every protocol on `conn`: the peer's calls to them come here. - pub fn provide_on(self, conn: &mut comline_runtime::connection::AsyncConnection) { + pub fn provide_on(self, conn: &mut Connection) { crate::conformance::ChatAsyncDispatcher(self.chat).provide_on(conn); } } @@ -28,7 +46,7 @@ pub struct ClientServices { impl ClientServices { /// Provide every protocol on `conn`: the peer's calls to them come here. - pub fn provide_on(self, conn: &mut comline_runtime::connection::AsyncConnection) { + pub fn provide_on(self, conn: &mut Connection) { crate::conformance::EventsAsyncDispatcher(self.events).provide_on(conn); } } @@ -37,21 +55,21 @@ impl ClientServices { /// every protocol in `services` on it. The connection comes back not yet /// running, so the caller can take a `handle()` to call the client with /// before it runs. -pub async fn accept(transport: T, services: Services) -> Result, comline_runtime::contract::RuntimeError> { +pub async fn accept(transport: T, services: Services) -> Result, RuntimeError> { let mut conn = comline_runtime::connection::AsyncConnection::accept(transport, Format::default(), CONNECTION_IR_HASH).await?; services.provide_on(&mut conn); Ok(conn) } /// [`accept`], then serve every call until the peer leaves. -pub async fn serve(transport: T, services: Services) -> Result<(), comline_runtime::contract::RuntimeError> { +pub async fn serve(transport: T, services: Services) -> Result<(), RuntimeError> { accept(transport, services).await?.run().await } /// Dial over `transport`: run the handshake, then provide every protocol in /// `services`, which the server calls. Call the server's protocols through /// their senders. -pub async fn connect(transport: T, services: ClientServices) -> Result, comline_runtime::contract::RuntimeError> { +pub async fn connect(transport: T, services: ClientServices) -> Result, RuntimeError> { let mut conn = comline_runtime::connection::AsyncConnection::connect(transport, Format::default(), CONNECTION_IR_HASH).await?; services.provide_on(&mut conn); Ok(conn) diff --git a/conformance/tests/golden/connections_async/typescript/conformance.ts b/conformance/tests/golden/connections_async/typescript/conformance.ts index 89b6bdb..814c58c 100644 --- a/conformance/tests/golden/connections_async/typescript/conformance.ts +++ b/conformance/tests/golden/connections_async/typescript/conformance.ts @@ -4,7 +4,6 @@ import { RuntimeError, resolveKind, - PackedCodec, type Codec, type Connection, type Dispatch, @@ -18,26 +17,21 @@ import { * two ends of a connection must agree on it. */ export const IR_HASH = 0xb97e34b203ec1425n; -/** 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 = 0xb97e34b203ec1425n; - -/** 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 ChatSendParams { n: number; } +/** @internal */ export const ChatSendParamsLayout: Layout = { struct: [["n", "u32"]] }; export interface Chat { send(peer: Peer, params: ChatSendParams): Promise; } +/** @internal */ export const CHAT_CALLS = ["send"] as const; +/** @internal */ export class ChatDispatcher implements Dispatch { /** This protocol's number on a connection. */ static readonly PROTOCOL = 0; @@ -74,7 +68,7 @@ export class ChatDispatcher implements Dispatch { } } - /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)`, or let the package's `serve` / `connect` do it. */ + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)` (`Format` and `CONNECTION_IR_HASH` are in `./wire.js`), or let the package's `serve` / `connect` do it. */ provideOn(conn: Connection): void { conn.provide(ChatDispatcher.PROTOCOL, this); } @@ -103,6 +97,7 @@ export interface EventsShownParams { n: number; } +/** @internal */ export const EventsShownParamsLayout: Layout = { struct: [["n", "u32"]] }; export interface Events { @@ -110,8 +105,10 @@ export interface Events { ping(peer: Peer): Promise; } +/** @internal */ export const EVENTS_CALLS = ["shown", "ping"] as const; +/** @internal */ export class EventsDispatcher implements Dispatch { /** This protocol's number on a connection. */ static readonly PROTOCOL = 1; @@ -156,7 +153,7 @@ export class EventsDispatcher implements Dispatch { } } - /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.connect(transport, Format, CONNECTION_IR_HASH)`, or let the package's `serve` / `connect` do it. */ + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.connect(transport, Format, CONNECTION_IR_HASH)` (`Format` and `CONNECTION_IR_HASH` are in `./wire.js`), or let the package's `serve` / `connect` do it. */ provideOn(conn: Connection): void { conn.provide(EventsDispatcher.PROTOCOL, this); } diff --git a/conformance/tests/golden/connections_async/typescript/connection.ts b/conformance/tests/golden/connections_async/typescript/connection.ts index 1f2a462..18b3931 100644 --- a/conformance/tests/golden/connections_async/typescript/connection.ts +++ b/conformance/tests/golden/connections_async/typescript/connection.ts @@ -1,27 +1,37 @@ // 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, - PackedCodec, - type Codec, type Transport, } from "@comline/runtime"; import * as ns_conformance from "./conformance.js"; +import { CONNECTION_IR_HASH, Format } from "./wire.js"; -/** 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 = 0xb97e34b203ec1425n; +/** 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; } -/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ export function provideServices(conn: Connection, services: Services): void { new ns_conformance.ChatDispatcher(services.chat).provideOn(conn); } @@ -31,7 +41,10 @@ export interface ClientServices { events: ns_conformance.Events; } -/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ export function provideClientServices(conn: Connection, services: ClientServices): void { new ns_conformance.EventsDispatcher(services.events).provideOn(conn); } diff --git a/conformance/tests/golden/connections_async/typescript/wire.ts b/conformance/tests/golden/connections_async/typescript/wire.ts new file mode 100644 index 0000000..351fa7f --- /dev/null +++ b/conformance/tests/golden/connections_async/typescript/wire.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + PackedCodec, + type Codec, +} from "@comline/runtime"; + +/** 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 = 0xb97e34b203ec1425n; diff --git a/conformance/tests/golden/connections_jsonrpc/rust/conformance.rs b/conformance/tests/golden/connections_jsonrpc/rust/conformance.rs index 68035e5..a9f2e75 100644 --- a/conformance/tests/golden/connections_jsonrpc/rust/conformance.rs +++ b/conformance/tests/golden/connections_jsonrpc/rust/conformance.rs @@ -12,10 +12,10 @@ use comline_runtime::transport::Transport; /// two ends of a connection must agree on it, and the handshake checks. pub const IR_HASH: u64 = 0x30c29bde2ae397d9; -/// 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 = 0x30c29bde2ae397d9; +#[doc(hidden)] +pub use crate::connection::CONNECTION_IR_HASH; +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct ChatSendParams { pub n: u32, @@ -29,8 +29,10 @@ pub trait Chat { 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 Dispatch for ChatDispatcher { @@ -85,6 +87,7 @@ impl Dispatch for ChatDispatcher { impl ChatDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -105,6 +108,7 @@ pub struct ChatSender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> ChatSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; pub fn new(peer: &'p mut P) -> Self { @@ -121,6 +125,7 @@ impl<'p, P: Peer> ChatSender<'p, P> { } } +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct EventsShownParams { pub n: u32, @@ -135,8 +140,10 @@ pub trait Events { fn ping(&self, peer: &mut impl Peer); } +#[doc(hidden)] pub const EVENTS_CALLS: &[&str] = &["conformance.Events/shown", "conformance.Events/ping"]; +#[doc(hidden)] pub struct EventsDispatcher(pub S); impl Dispatch for EventsDispatcher { @@ -199,6 +206,7 @@ impl Dispatch for EventsDispatcher { impl EventsDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 1; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -219,6 +227,7 @@ pub struct EventsSender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> EventsSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 1; pub fn new(peer: &'p mut P) -> Self { diff --git a/conformance/tests/golden/connections_jsonrpc/rust/connection.rs b/conformance/tests/golden/connections_jsonrpc/rust/connection.rs index b8cb1bb..3c96bb7 100644 --- a/conformance/tests/golden/connections_jsonrpc/rust/connection.rs +++ b/conformance/tests/golden/connections_jsonrpc/rust/connection.rs @@ -1,5 +1,19 @@ // Generated by Comline // For Rust 1.85.0 or later; verified up to 1.99. +//! The package's protocols share one connection: `jsonrpc` framing, the `comline@1` 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. + +use comline_runtime::contract::RuntimeError; +use comline_runtime::transport::Transport; + /// The package's wire format (`wire.format`). pub type Format = comline_runtime::format::Packed; @@ -7,6 +21,13 @@ pub type Format = comline_runtime::format::Packed; /// checks, so both ends agree on each protocol's number. pub const CONNECTION_IR_HASH: u64 = 0x30c29bde2ae397d9; +/// 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; + /// What the accepting side provides: one field per protocol, so leaving one out /// doesn't compile. pub struct Services { @@ -15,7 +36,7 @@ pub struct Services { impl Services { /// Provide every protocol on `conn`: the peer's calls to them come here. - pub fn provide_on(self, conn: &mut comline_runtime::connection::Connection) { + pub fn provide_on(self, conn: &mut Connection) { crate::conformance::ChatDispatcher(self.chat).provide_on(conn); } } @@ -28,7 +49,7 @@ pub struct ClientServices { impl ClientServices { /// Provide every protocol on `conn`: the peer's calls to them come here. - pub fn provide_on(self, conn: &mut comline_runtime::connection::Connection) { + pub fn provide_on(self, conn: &mut Connection) { crate::conformance::EventsDispatcher(self.events).provide_on(conn); } } @@ -37,21 +58,21 @@ impl ClientServices { /// every protocol in `services` on it. The connection comes back not yet /// served, for a server that calls the client first, or serves one call at /// a time. -pub fn accept(transport: T, services: Services) -> Result, comline_runtime::contract::RuntimeError> { +pub fn accept(transport: T, services: Services) -> Result, RuntimeError> { let mut conn = comline_runtime::connection::Connection::accept_with(transport, comline_runtime::format::Json::default(), comline_runtime::framing::JsonRpcFraming, &mut comline_runtime::handshake::ComlineHandshake, CONNECTION_IR_HASH)?; services.provide_on(&mut conn); Ok(conn) } /// [`accept`], then serve every call until the peer leaves. -pub fn serve(transport: T, services: Services) -> Result<(), comline_runtime::contract::RuntimeError> { +pub fn serve(transport: T, services: Services) -> Result<(), RuntimeError> { accept(transport, services)?.serve() } /// Dial over `transport`: run the handshake, then provide every protocol in /// `services`, which the server calls. Call the server's protocols through /// their senders. -pub fn connect(transport: T, services: ClientServices) -> Result, comline_runtime::contract::RuntimeError> { +pub fn connect(transport: T, services: ClientServices) -> Result, RuntimeError> { let mut conn = comline_runtime::connection::Connection::connect_with(transport, comline_runtime::format::Json::default(), comline_runtime::framing::JsonRpcFraming, &mut comline_runtime::handshake::ComlineHandshake, CONNECTION_IR_HASH)?; services.provide_on(&mut conn); Ok(conn) diff --git a/conformance/tests/golden/connections_jsonrpc/typescript/conformance.ts b/conformance/tests/golden/connections_jsonrpc/typescript/conformance.ts index 4c83631..d68215a 100644 --- a/conformance/tests/golden/connections_jsonrpc/typescript/conformance.ts +++ b/conformance/tests/golden/connections_jsonrpc/typescript/conformance.ts @@ -17,22 +17,21 @@ import { * two ends of a connection must agree on it. */ export const IR_HASH = 0x30c29bde2ae397d9n; -/** 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 = 0x30c29bde2ae397d9n; - export interface ChatSendParams { n: number; } +/** @internal */ export const ChatSendParamsLayout: Layout = { struct: [["n", "u32"]] }; export interface Chat { send(peer: Peer, params: ChatSendParams): Promise; } +/** @internal */ export const CHAT_CALLS = ["send"] as const; +/** @internal */ export class ChatDispatcher implements Dispatch { /** This protocol's number on a connection. */ static readonly PROTOCOL = 0; @@ -69,7 +68,7 @@ export class ChatDispatcher implements Dispatch { } } - /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, new JsonCodec(), CONNECTION_IR_HASH, new JsonRpcConnectionFraming())`, or let the package's `serve` / `connect` do it. */ + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, new JsonCodec(), CONNECTION_IR_HASH, new JsonRpcConnectionFraming())` (`Format` and `CONNECTION_IR_HASH` are in `./wire.js`), or let the package's `serve` / `connect` do it. */ provideOn(conn: Connection): void { conn.provide(ChatDispatcher.PROTOCOL, this); } @@ -98,6 +97,7 @@ export interface EventsShownParams { n: number; } +/** @internal */ export const EventsShownParamsLayout: Layout = { struct: [["n", "u32"]] }; export interface Events { @@ -105,8 +105,10 @@ export interface Events { ping(peer: Peer): Promise; } +/** @internal */ export const EVENTS_CALLS = ["conformance.Events/shown", "conformance.Events/ping"] as const; +/** @internal */ export class EventsDispatcher implements Dispatch { /** This protocol's number on a connection. */ static readonly PROTOCOL = 1; @@ -151,7 +153,7 @@ export class EventsDispatcher implements Dispatch { } } - /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.connect(transport, new JsonCodec(), CONNECTION_IR_HASH, new JsonRpcConnectionFraming())`, or let the package's `serve` / `connect` do it. */ + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.connect(transport, new JsonCodec(), CONNECTION_IR_HASH, new JsonRpcConnectionFraming())` (`Format` and `CONNECTION_IR_HASH` are in `./wire.js`), or let the package's `serve` / `connect` do it. */ provideOn(conn: Connection): void { conn.provide(EventsDispatcher.PROTOCOL, this); } diff --git a/conformance/tests/golden/connections_jsonrpc/typescript/connection.ts b/conformance/tests/golden/connections_jsonrpc/typescript/connection.ts index 4f5b2f1..c6942d9 100644 --- a/conformance/tests/golden/connections_jsonrpc/typescript/connection.ts +++ b/conformance/tests/golden/connections_jsonrpc/typescript/connection.ts @@ -1,29 +1,39 @@ // 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, JsonCodec, JsonRpcConnectionFraming, - PackedCodec, - type Codec, type Transport, } from "@comline/runtime"; import * as ns_conformance from "./conformance.js"; +import { CONNECTION_IR_HASH } from "./wire.js"; -/** 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 = 0x30c29bde2ae397d9n; +/** 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; } -/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ export function provideServices(conn: Connection, services: Services): void { new ns_conformance.ChatDispatcher(services.chat).provideOn(conn); } @@ -33,7 +43,10 @@ export interface ClientServices { events: ns_conformance.Events; } -/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ export function provideClientServices(conn: Connection, services: ClientServices): void { new ns_conformance.EventsDispatcher(services.events).provideOn(conn); } diff --git a/conformance/tests/golden/connections_jsonrpc/typescript/wire.ts b/conformance/tests/golden/connections_jsonrpc/typescript/wire.ts new file mode 100644 index 0000000..4e964de --- /dev/null +++ b/conformance/tests/golden/connections_jsonrpc/typescript/wire.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + PackedCodec, + type Codec, +} from "@comline/runtime"; + +/** 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 = 0x30c29bde2ae397d9n; diff --git a/conformance/tests/golden/dependency_and_own_protocols/rust/api.rs b/conformance/tests/golden/dependency_and_own_protocols/rust/api.rs index ef5377e..80d4d08 100644 --- a/conformance/tests/golden/dependency_and_own_protocols/rust/api.rs +++ b/conformance/tests/golden/dependency_and_own_protocols/rust/api.rs @@ -12,19 +12,15 @@ use comline_runtime::transport::Transport; /// two ends of a connection must agree on it, and the handshake checks. pub const IR_HASH: u64 = 0x25f4c4d936e7aa90; -/// 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 = 0x55e3b94344a9c775; - -/// 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)] +pub use crate::connection::{CONNECTION_IR_HASH, Format}; #[derive(Debug, Clone, Serialize, Deserialize)] pub struct Message { pub greeting: crate::localdeps::greeting::Greeting, } +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct ChatGreetParams { pub n: u32, @@ -38,8 +34,10 @@ pub trait Chat { fn greet(&self, peer: &mut impl Peer, n: u32) -> Result>; } +#[doc(hidden)] pub const CHAT_CALLS: &[&str] = &["greet"]; +#[doc(hidden)] pub struct ChatDispatcher(pub S); impl Dispatch for ChatDispatcher { @@ -98,6 +96,7 @@ impl Dispatch for ChatDispatcher { impl ChatDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -118,6 +117,7 @@ pub struct ChatSender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> ChatSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; pub fn new(peer: &'p mut P) -> Self { diff --git a/conformance/tests/golden/dependency_and_own_protocols/rust/connection.rs b/conformance/tests/golden/dependency_and_own_protocols/rust/connection.rs index e598317..bbeb477 100644 --- a/conformance/tests/golden/dependency_and_own_protocols/rust/connection.rs +++ b/conformance/tests/golden/dependency_and_own_protocols/rust/connection.rs @@ -1,5 +1,18 @@ // 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: `api::Chat`. +//! - 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)`. +//! - Call the server from the dialling side: `ChatSender::new(&mut conn).greet(..)`. +//! +//! [`Connection`](Connection) names the connection over a transport `T`, written `Connection`; [`Format`] is the package's wire format. + +use comline_runtime::contract::{Peer, Reason, RuntimeError}; +use comline_runtime::handshake::comline2::{Comline2Handshake, Negotiated}; +use comline_runtime::transport::Transport; + /// The package's wire format (`wire.format`). pub type Format = comline_runtime::format::Packed; @@ -7,10 +20,18 @@ pub type Format = comline_runtime::format::Packed; /// checks, so both ends agree on each protocol's number. pub const CONNECTION_IR_HASH: u64 = 0x55e3b94344a9c775; +/// 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; + /// This end's `comline@2` Hello: version 0.1.0 of package `0123456789abcdef0123456789abcdef`, as its /// history records it. Its protocols, by wire number: /// /// - 0 `api::Chat`, line 0.1.0: `greet` 0 +#[doc(hidden)] pub const HELLO: &[u8] = &[ 0x43, 0x4f, 0x02, 0x01, 0x00, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x00, 0x01, 0x00, @@ -25,7 +46,8 @@ pub const HELLO: &[u8] = &[ /// The `comline@2` handshake, with [`HELLO`] and the parameters the package /// states: `scope = protocol`, `newer_consumer = degrade`, `same_version_differs = refuse`, `exchange = offer`. -pub fn handshake() -> comline_runtime::handshake::comline2::Comline2Handshake { +#[doc(hidden)] +pub fn handshake() -> Comline2Handshake { use comline_runtime::handshake::comline2 as c2; let hello = match c2::Message::decode(HELLO) { Ok(c2::Message::Hello(hello)) => hello, @@ -51,7 +73,7 @@ fn protocol_path(number: u16) -> &'static str { /// the connection's extensions. #[derive(Debug, Clone)] pub struct Negotiation { - pub negotiated: comline_runtime::handshake::comline2::Negotiated, + pub negotiated: Negotiated, /// The last call that wasn't made because the peer can't take it. pub unavailable: Option, } @@ -66,7 +88,7 @@ pub struct Unavailable { pub function: &'static str, /// Why the peer refused the protocol, or `None` when the peer lacks the /// function (`newer_consumer = degrade`). - pub refused: Option, + pub refused: Option, } impl ::core::fmt::Display for Unavailable { @@ -82,14 +104,14 @@ impl ::core::error::Error for Unavailable {} /// What the connection's `comline@2` handshake agreed, if `accept` / `connect` /// opened it. -pub fn negotiated(peer: &mut P) -> Option { +pub fn negotiated(peer: &mut P) -> Option { let extensions = peer.extensions(); extensions.get::().map(|n| n.negotiated.clone()) } /// The protocols that connected although their wire shape differs from the /// peer's at the same version (`same_version_differs = warn`), by path. -pub fn warnings(peer: &mut P) -> Vec<&'static str> { +pub fn warnings(peer: &mut P) -> Vec<&'static str> { let extensions = peer.extensions(); match extensions.get::() { Some(n) => n.negotiated.warnings.iter().map(|p| protocol_path(*p)).collect(), @@ -99,7 +121,7 @@ pub fn warnings(peer: &mut P) -> Vec<&'stati /// The last call on this connection that failed with `Unavailable`: which /// function, and why. -pub fn unavailable(peer: &mut P) -> Option { +pub fn unavailable(peer: &mut P) -> Option { let extensions = peer.extensions(); extensions.get::().and_then(|n| n.unavailable) } @@ -108,7 +130,7 @@ pub fn unavailable(peer: &mut P) -> Option(peer: &mut P, protocol: u16, function: u16, path: &'static str, name: &'static str) -> Result<(), comline_runtime::contract::RuntimeError> { +pub fn check_call(peer: &mut P, protocol: u16, function: u16, path: &'static str, name: &'static str) -> Result<(), RuntimeError> { let extensions = peer.extensions(); let Some(n) = extensions.get_mut::() else { return Ok(()); @@ -122,7 +144,7 @@ pub fn check_call(peer: &mut P, protocol: u1 _ => None, }); // A protocol this end doesn't have isn't refused by the peer: it's unknown. - let refused = refused.or_else(|| (!n.negotiated.protocols.iter().any(|p| p.number == protocol)).then_some(comline_runtime::contract::Reason::UnknownProtocol)); + let refused = refused.or_else(|| (!n.negotiated.protocols.iter().any(|p| p.number == protocol)).then_some(Reason::UnknownProtocol)); n.unavailable = Some(Unavailable { protocol: path, function: name, refused }); Err(error) } @@ -135,7 +157,7 @@ pub struct Services { impl Services { /// Provide every protocol on `conn`: the peer's calls to them come here. - pub fn provide_on(self, conn: &mut comline_runtime::connection::Connection) { + pub fn provide_on(self, conn: &mut Connection) { crate::api::ChatDispatcher(self.chat).provide_on(conn); } } @@ -144,25 +166,24 @@ impl Services { /// every protocol in `services` on it. The connection comes back not yet /// served, for a server that calls the client first, or serves one call at /// a time. -pub fn accept(transport: T, services: Services) -> Result, comline_runtime::contract::RuntimeError> { +pub fn accept(transport: T, services: Services) -> Result, RuntimeError> { let mut handshake = handshake(); let mut conn = comline_runtime::connection::Connection::accept_with(transport, Format::default(), comline_runtime::contract::Datagram3Framing, &mut handshake, CONNECTION_IR_HASH)?; - comline_runtime::contract::Peer::extensions(&mut conn).insert(Negotiation { negotiated: handshake.negotiated().cloned().unwrap_or_else(|| unreachable!("a handshake that succeeded agreed something")), unavailable: None }); + Peer::extensions(&mut conn).insert(Negotiation { negotiated: handshake.negotiated().cloned().unwrap_or_else(|| unreachable!("a handshake that succeeded agreed something")), unavailable: None }); services.provide_on(&mut conn); Ok(conn) } /// [`accept`], then serve every call until the peer leaves. -pub fn serve(transport: T, services: Services) -> Result<(), comline_runtime::contract::RuntimeError> { +pub fn serve(transport: T, services: Services) -> Result<(), RuntimeError> { accept(transport, services)?.serve() } -/// Dial over `transport`: run the handshake, then provide every protocol in -/// `services`, which the server calls. Call the server's protocols through -/// their senders. -pub fn connect(transport: T) -> Result, comline_runtime::contract::RuntimeError> { +/// Dial over `transport`: run the handshake. Call the server's protocols +/// through their senders. +pub fn connect(transport: T) -> Result, RuntimeError> { let mut handshake = handshake(); let mut conn = comline_runtime::connection::Connection::connect_with(transport, Format::default(), comline_runtime::contract::Datagram3Framing, &mut handshake, CONNECTION_IR_HASH)?; - comline_runtime::contract::Peer::extensions(&mut conn).insert(Negotiation { negotiated: handshake.negotiated().cloned().unwrap_or_else(|| unreachable!("a handshake that succeeded agreed something")), unavailable: None }); + Peer::extensions(&mut conn).insert(Negotiation { negotiated: handshake.negotiated().cloned().unwrap_or_else(|| unreachable!("a handshake that succeeded agreed something")), unavailable: None }); Ok(conn) } diff --git a/conformance/tests/golden/dependency_and_own_protocols/rust/localdeps/greeting.rs b/conformance/tests/golden/dependency_and_own_protocols/rust/localdeps/greeting.rs index 9084980..7a4d6a7 100644 --- a/conformance/tests/golden/dependency_and_own_protocols/rust/localdeps/greeting.rs +++ b/conformance/tests/golden/dependency_and_own_protocols/rust/localdeps/greeting.rs @@ -12,19 +12,15 @@ use comline_runtime::transport::Transport; /// two ends of a connection must agree on it, and the handshake checks. pub const IR_HASH: u64 = 0x653ed335b8ab7ba0; -/// 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 = 0x55e3b94344a9c775; - -/// 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)] +pub use crate::connection::{CONNECTION_IR_HASH, Format}; #[derive(Debug, Clone, Serialize, Deserialize)] pub struct Greeting { pub text: String, } +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct FooGreetParams { pub n: u32, @@ -38,6 +34,7 @@ pub trait Foo { fn greet(&self, peer: &mut impl Peer, n: u32) -> Result>; } +#[doc(hidden)] pub const FOO_CALLS: &[&str] = &["greet"]; pub struct FooDispatcher(pub S); @@ -98,6 +95,7 @@ impl Dispatch for FooDispatcher { impl FooDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -118,6 +116,7 @@ pub struct FooSender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> FooSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; pub fn new(peer: &'p mut P) -> Self { diff --git a/conformance/tests/golden/dependency_and_own_protocols/typescript/api.ts b/conformance/tests/golden/dependency_and_own_protocols/typescript/api.ts index 6b3e01f..2b606ed 100644 --- a/conformance/tests/golden/dependency_and_own_protocols/typescript/api.ts +++ b/conformance/tests/golden/dependency_and_own_protocols/typescript/api.ts @@ -5,7 +5,6 @@ import { RuntimeError, resolveKind, checkCall, - PackedCodec, type Codec, type Connection, type Dispatch, @@ -22,14 +21,6 @@ import type { Greeting } from "./localdeps/greeting.js"; * two ends of a connection must agree on it. */ export const IR_HASH = 0x25f4c4d936e7aa90n; -/** 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 = 0x55e3b94344a9c775n; - -/** 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 { greeting: Greeting; } @@ -40,14 +31,17 @@ export interface ChatGreetParams { n: number; } +/** @internal */ export const ChatGreetParamsLayout: Layout = { struct: [["n", "u32"]] }; export interface Chat { greet(peer: Peer, params: ChatGreetParams): Promise; } +/** @internal */ export const CHAT_CALLS = ["greet"] as const; +/** @internal */ export class ChatDispatcher implements Dispatch { /** This protocol's number on a connection. */ static readonly PROTOCOL = 0; diff --git a/conformance/tests/golden/dependency_and_own_protocols/typescript/connection.ts b/conformance/tests/golden/dependency_and_own_protocols/typescript/connection.ts index 282f9f3..7f6dd4c 100644 --- a/conformance/tests/golden/dependency_and_own_protocols/typescript/connection.ts +++ b/conformance/tests/golden/dependency_and_own_protocols/typescript/connection.ts @@ -1,30 +1,39 @@ // Generated by Comline // For TypeScript 5.0 or later; verified up to 5.9. +/** + * Where to start: + * + * - Implement what you provide: `Chat` (in `./api.js`). + * - Serve with `serve(transport, { chat })`; `accept(transport, { chat })` takes the same and hands back the connection. + * - Dial with `connect(transport)`. + * - Call the other end with `new ChatSender(conn).greet(…)`, 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, Datagram3Framing, - PackedCodec, Comline2Handshake, Negotiated, - type Codec, type Peer, type Transport, } from "@comline/runtime"; import * as ns_api from "./api.js"; +import { CONNECTION_IR_HASH, Format } from "./wire.js"; -/** 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 = 0x55e3b94344a9c775n; +/** 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"; /** * This end's `comline@2` Hello: version 0.1.0 of package `0123456789abcdef0123456789abcdef`, as its history * records it. Its protocols, by wire number: * * - 0 `api::Chat`, line 0.1.0: `greet` 0 + * + * @internal */ export const HELLO = new Uint8Array([ 0x43, 0x4f, 0x02, 0x01, 0x00, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, @@ -38,7 +47,10 @@ export const HELLO = new Uint8Array([ 0x5a, 0x5a, 0x01, 0x00, ]); -/** The `comline@2` handshake, with {@link HELLO} and the parameters the package states. */ +/** + * The `comline@2` handshake, with {@link HELLO} and the parameters the package states. + * @internal + */ export function handshake(): Comline2Handshake { return new Comline2Handshake(HELLO, { scope: "protocol", @@ -69,7 +81,10 @@ export interface Services { chat: ns_api.Chat; } -/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ export function provideServices(conn: Connection, services: Services): void { new ns_api.ChatDispatcher(services.chat).provideOn(conn); } @@ -93,9 +108,8 @@ export async function serve(transport: Transport, services: Services): Promise { const agreed = handshake(); diff --git a/conformance/tests/golden/dependency_and_own_protocols/typescript/localdeps/greeting.ts b/conformance/tests/golden/dependency_and_own_protocols/typescript/localdeps/greeting.ts index 5c0c403..66fc420 100644 --- a/conformance/tests/golden/dependency_and_own_protocols/typescript/localdeps/greeting.ts +++ b/conformance/tests/golden/dependency_and_own_protocols/typescript/localdeps/greeting.ts @@ -4,7 +4,6 @@ import { RuntimeError, resolveKind, - PackedCodec, type Codec, type Connection, type Dispatch, @@ -18,14 +17,6 @@ import { * two ends of a connection must agree on it. */ export const IR_HASH = 0x653ed335b8ab7ba0n; -/** 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 = 0x55e3b94344a9c775n; - -/** 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 Greeting { text: string; } @@ -36,12 +27,14 @@ export interface FooGreetParams { n: number; } +/** @internal */ export const FooGreetParamsLayout: Layout = { struct: [["n", "u32"]] }; export interface Foo { greet(peer: Peer, params: FooGreetParams): Promise; } +/** @internal */ export const FOO_CALLS = ["greet"] as const; export class FooDispatcher implements Dispatch { @@ -80,7 +73,7 @@ export class FooDispatcher implements Dispatch { } } - /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH, undefined, new Comline2Handshake())`, or let the package's `serve` / `connect` do it. */ + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH, undefined, new Comline2Handshake())` (`Format` and `CONNECTION_IR_HASH` are in `../wire.js`), or let the package's `serve` / `connect` do it. */ provideOn(conn: Connection): void { conn.provide(FooDispatcher.PROTOCOL, this); } diff --git a/conformance/tests/golden/dependency_and_own_protocols/typescript/wire.ts b/conformance/tests/golden/dependency_and_own_protocols/typescript/wire.ts new file mode 100644 index 0000000..bf972a3 --- /dev/null +++ b/conformance/tests/golden/dependency_and_own_protocols/typescript/wire.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + PackedCodec, + type Codec, +} from "@comline/runtime"; + +/** 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 = 0x55e3b94344a9c775n; diff --git a/conformance/tests/golden/dependency_protocol/rust/localdeps/greeting.rs b/conformance/tests/golden/dependency_protocol/rust/localdeps/greeting.rs index 0eb685a..3c3caae 100644 --- a/conformance/tests/golden/dependency_protocol/rust/localdeps/greeting.rs +++ b/conformance/tests/golden/dependency_protocol/rust/localdeps/greeting.rs @@ -25,6 +25,7 @@ pub struct Greeting { pub text: String, } +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct FooGreetParams { pub n: u32, @@ -38,6 +39,7 @@ pub trait Foo { fn greet(&self, peer: &mut impl Peer, n: u32) -> Result>; } +#[doc(hidden)] pub const FOO_CALLS: &[&str] = &["greet"]; pub struct FooDispatcher(pub S); @@ -98,6 +100,7 @@ impl Dispatch for FooDispatcher { impl FooDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -118,6 +121,7 @@ pub struct FooSender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> FooSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; pub fn new(peer: &'p mut P) -> Self { diff --git a/conformance/tests/golden/dependency_protocol/typescript/localdeps/greeting.ts b/conformance/tests/golden/dependency_protocol/typescript/localdeps/greeting.ts index c8fdef8..643f01d 100644 --- a/conformance/tests/golden/dependency_protocol/typescript/localdeps/greeting.ts +++ b/conformance/tests/golden/dependency_protocol/typescript/localdeps/greeting.ts @@ -36,12 +36,14 @@ export interface FooGreetParams { n: number; } +/** @internal */ export const FooGreetParamsLayout: Layout = { struct: [["n", "u32"]] }; export interface Foo { greet(peer: Peer, params: FooGreetParams): Promise; } +/** @internal */ export const FOO_CALLS = ["greet"] as const; export class FooDispatcher implements Dispatch { diff --git a/conformance/tests/golden/error_shapes/rust/conformance.rs b/conformance/tests/golden/error_shapes/rust/conformance.rs index 42435fe..6fe443c 100644 --- a/conformance/tests/golden/error_shapes/rust/conformance.rs +++ b/conformance/tests/golden/error_shapes/rust/conformance.rs @@ -12,13 +12,8 @@ use comline_runtime::transport::Transport; /// two ends of a connection must agree on it, and the handshake checks. pub const IR_HASH: u64 = 0x6fc29e1014b9b9c8; -/// 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 = 0x6fc29e1014b9b9c8; - -/// 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)] +pub use crate::connection::{CONNECTION_IR_HASH, Format}; #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub struct TooLong { @@ -45,6 +40,7 @@ impl core::fmt::Display for Denied { impl core::error::Error for Denied {} +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct MultiSendParams<'a> { #[serde(borrow)] @@ -98,8 +94,10 @@ pub trait Multi { fn send(&self, peer: &mut impl Peer, body: &str) -> Result>; } +#[doc(hidden)] pub const MULTI_CALLS: &[&str] = &["send"]; +#[doc(hidden)] pub struct MultiDispatcher(pub S); impl Dispatch for MultiDispatcher { @@ -163,6 +161,7 @@ impl Dispatch for MultiDispatcher { impl MultiDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -183,6 +182,7 @@ pub struct MultiSender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> MultiSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; pub fn new(peer: &'p mut P) -> Self { @@ -216,8 +216,10 @@ pub trait Quiet { fn hush(&self, peer: &mut impl Peer); } +#[doc(hidden)] pub const QUIET_CALLS: &[&str] = &["ping", "hush"]; +#[doc(hidden)] pub struct QuietDispatcher(pub S); impl Dispatch for QuietDispatcher { @@ -280,6 +282,7 @@ impl Dispatch for QuietDispatcher { impl QuietDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 1; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -300,6 +303,7 @@ pub struct QuietSender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> QuietSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 1; pub fn new(peer: &'p mut P) -> Self { diff --git a/conformance/tests/golden/error_shapes/rust/connection.rs b/conformance/tests/golden/error_shapes/rust/connection.rs index bf1d921..e8569c2 100644 --- a/conformance/tests/golden/error_shapes/rust/connection.rs +++ b/conformance/tests/golden/error_shapes/rust/connection.rs @@ -1,5 +1,17 @@ // Generated by Comline // For Rust 1.85.0 or later; verified up to 1.99. +//! The package's protocols share one connection: `datagram@2` framing, the `comline@1` handshake. To use it: +//! +//! - Implement the trait of each protocol the server provides: `conformance::Multi`, `conformance::Quiet`. +//! - Serve with [`serve`]`(transport, Services { multi: .., quiet: .. })`, 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)`. +//! - Call the server from the dialling side: `MultiSender::new(&mut conn).send(..)`. +//! +//! [`Connection`](Connection) names the connection over a transport `T`, written `Connection`; [`Format`] is the package's wire format. + +use comline_runtime::contract::RuntimeError; +use comline_runtime::transport::Transport; + /// The package's wire format (`wire.format`). pub type Format = comline_runtime::format::Packed; @@ -7,6 +19,10 @@ pub type Format = comline_runtime::format::Packed; /// checks, so both ends agree on each protocol's number. pub const CONNECTION_IR_HASH: u64 = 0x6fc29e1014b9b9c8; +/// The package's connection over the transport `T`: what [`accept`] and [`connect`] +/// return, written `Connection`: [`Format`] over the default framing. +pub type Connection = comline_runtime::connection::Connection; + /// What the accepting side provides: one field per protocol, so leaving one out /// doesn't compile. pub struct Services { @@ -16,7 +32,7 @@ pub struct Services { impl Services { /// Provide every protocol on `conn`: the peer's calls to them come here. - pub fn provide_on(self, conn: &mut comline_runtime::connection::Connection) { + pub fn provide_on(self, conn: &mut Connection) { crate::conformance::MultiDispatcher(self.multi).provide_on(conn); crate::conformance::QuietDispatcher(self.quiet).provide_on(conn); } @@ -26,21 +42,20 @@ impl(transport: T, services: Services) -> Result, comline_runtime::contract::RuntimeError> { +pub fn accept(transport: T, services: Services) -> Result, RuntimeError> { let mut conn = comline_runtime::connection::Connection::accept(transport, Format::default(), CONNECTION_IR_HASH)?; services.provide_on(&mut conn); Ok(conn) } /// [`accept`], then serve every call until the peer leaves. -pub fn serve(transport: T, services: Services) -> Result<(), comline_runtime::contract::RuntimeError> { +pub fn serve(transport: T, services: Services) -> Result<(), RuntimeError> { accept(transport, services)?.serve() } -/// Dial over `transport`: run the handshake, then provide every protocol in -/// `services`, which the server calls. Call the server's protocols through -/// their senders. -pub fn connect(transport: T) -> Result, comline_runtime::contract::RuntimeError> { +/// Dial over `transport`: run the handshake. Call the server's protocols +/// through their senders. +pub fn connect(transport: T) -> Result, RuntimeError> { let conn = comline_runtime::connection::Connection::connect(transport, Format::default(), CONNECTION_IR_HASH)?; Ok(conn) } diff --git a/conformance/tests/golden/error_shapes/typescript/conformance.ts b/conformance/tests/golden/error_shapes/typescript/conformance.ts index d411a67..3963fca 100644 --- a/conformance/tests/golden/error_shapes/typescript/conformance.ts +++ b/conformance/tests/golden/error_shapes/typescript/conformance.ts @@ -4,7 +4,6 @@ import { RuntimeError, resolveKind, - PackedCodec, type Codec, type Connection, type Dispatch, @@ -18,14 +17,6 @@ import { * two ends of a connection must agree on it. */ export const IR_HASH = 0x6fc29e1014b9b9c8n; -/** 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 = 0x6fc29e1014b9b9c8n; - -/** 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 TooLong { limit: number; } @@ -61,6 +52,7 @@ export interface MultiSendParams { body: string; } +/** @internal */ export const MultiSendParamsLayout: Layout = { struct: [["body", "string"]] }; export interface Multi { @@ -68,8 +60,10 @@ export interface Multi { send(peer: Peer, params: MultiSendParams): Promise; } +/** @internal */ export const MULTI_CALLS = ["send"] as const; +/** @internal */ export class MultiDispatcher implements Dispatch { /** This protocol's number on a connection. */ static readonly PROTOCOL = 0; @@ -108,7 +102,7 @@ export class MultiDispatcher implements Dispatch { } } - /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)`, or let the package's `serve` / `connect` do it. */ + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)` (`Format` and `CONNECTION_IR_HASH` are in `./wire.js`), or let the package's `serve` / `connect` do it. */ provideOn(conn: Connection): void { conn.provide(MultiDispatcher.PROTOCOL, this); } @@ -145,8 +139,10 @@ export interface Quiet { hush(peer: Peer): Promise; } +/** @internal */ export const QUIET_CALLS = ["ping", "hush"] as const; +/** @internal */ export class QuietDispatcher implements Dispatch { /** This protocol's number on a connection. */ static readonly PROTOCOL = 1; @@ -190,7 +186,7 @@ export class QuietDispatcher implements Dispatch { } } - /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)`, or let the package's `serve` / `connect` do it. */ + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)` (`Format` and `CONNECTION_IR_HASH` are in `./wire.js`), or let the package's `serve` / `connect` do it. */ provideOn(conn: Connection): void { conn.provide(QuietDispatcher.PROTOCOL, this); } diff --git a/conformance/tests/golden/error_shapes/typescript/connection.ts b/conformance/tests/golden/error_shapes/typescript/connection.ts index 5f00a64..7fb3179 100644 --- a/conformance/tests/golden/error_shapes/typescript/connection.ts +++ b/conformance/tests/golden/error_shapes/typescript/connection.ts @@ -1,20 +1,27 @@ // Generated by Comline // For TypeScript 5.0 or later; verified up to 5.9. +/** + * Where to start: + * + * - Implement what you provide: `Multi`, `Quiet` (in `./conformance.js`). + * - Serve with `serve(transport, { multi, quiet })`; `accept(transport, { multi, quiet })` takes the same and hands back the connection. + * - Dial with `connect(transport)`. + * - Call the other end with `new MultiSender(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, - PackedCodec, - type Codec, type Transport, } from "@comline/runtime"; import * as ns_conformance from "./conformance.js"; +import { CONNECTION_IR_HASH, Format } from "./wire.js"; -/** 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 = 0x6fc29e1014b9b9c8n; +/** 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 { @@ -22,7 +29,10 @@ export interface Services { quiet: ns_conformance.Quiet; } -/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ export function provideServices(conn: Connection, services: Services): void { new ns_conformance.MultiDispatcher(services.multi).provideOn(conn); new ns_conformance.QuietDispatcher(services.quiet).provideOn(conn); @@ -45,9 +55,8 @@ export async function serve(transport: Transport, services: Services): Promise { const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH); diff --git a/conformance/tests/golden/error_shapes/typescript/wire.ts b/conformance/tests/golden/error_shapes/typescript/wire.ts new file mode 100644 index 0000000..a7aab5f --- /dev/null +++ b/conformance/tests/golden/error_shapes/typescript/wire.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + PackedCodec, + type Codec, +} from "@comline/runtime"; + +/** 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 = 0x6fc29e1014b9b9c8n; diff --git a/conformance/tests/golden/external_std/rust/Cargo.toml b/conformance/tests/golden/external_std/rust/Cargo.toml index fa743aa..9957879 100644 --- a/conformance/tests/golden/external_std/rust/Cargo.toml +++ b/conformance/tests/golden/external_std/rust/Cargo.toml @@ -12,4 +12,4 @@ autobins = false [dependencies] serde = { version = "1", features = ["derive"] } -comline_std = { git = "https://github.com/ComlineProject/comline-rust", rev = "8b36b5a9ebb555f6e9760969be0a119e99b87aaa" } +comline_std = { git = "https://github.com/ComlineProject/comline-rust", rev = "fa2b4cc65cbd1b91443fd694d0df9c816f55fb51" } diff --git a/conformance/tests/golden/external_std/rust/src/lib.rs b/conformance/tests/golden/external_std/rust/src/lib.rs index cfae1e0..45b4e44 100644 --- a/conformance/tests/golden/external_std/rust/src/lib.rs +++ b/conformance/tests/golden/external_std/rust/src/lib.rs @@ -1,3 +1,5 @@ // Generated by Comline +//! This package declares no protocols: it holds types, so there is nothing to serve or dial. + pub mod api; diff --git a/conformance/tests/golden/format_json/rust/conformance.rs b/conformance/tests/golden/format_json/rust/conformance.rs index d78d81d..ace4801 100644 --- a/conformance/tests/golden/format_json/rust/conformance.rs +++ b/conformance/tests/golden/format_json/rust/conformance.rs @@ -12,13 +12,8 @@ use comline_runtime::transport::Transport; /// two ends of a connection must agree on it, and the handshake checks. pub const IR_HASH: u64 = 0x8ee00745c73a32b2; -/// 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 = 0x8ee00745c73a32b2; - -/// 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::Json; +#[doc(hidden)] +pub use crate::connection::{CONNECTION_IR_HASH, Format}; #[derive(Debug, Clone, Serialize, Deserialize)] pub struct Record { @@ -38,11 +33,13 @@ impl core::fmt::Display for NotFound { impl core::error::Error for NotFound {} +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct ServiceLookupParams { pub id: i32, } +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct ServiceNotifyParams { pub code: u16, @@ -94,8 +91,10 @@ pub trait Service { fn notify(&self, peer: &mut impl Peer, code: u16); } +#[doc(hidden)] pub const SERVICE_CALLS: &[&str] = &["lookup", "count", "notify"]; +#[doc(hidden)] pub struct ServiceDispatcher(pub S); impl Dispatch for ServiceDispatcher { @@ -181,6 +180,7 @@ impl Dispatch for ServiceDispatcher { impl ServiceDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -201,6 +201,7 @@ pub struct ServiceSender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> ServiceSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; pub fn new(peer: &'p mut P) -> Self { diff --git a/conformance/tests/golden/format_json/rust/connection.rs b/conformance/tests/golden/format_json/rust/connection.rs index a2dd1e9..327827b 100644 --- a/conformance/tests/golden/format_json/rust/connection.rs +++ b/conformance/tests/golden/format_json/rust/connection.rs @@ -1,5 +1,17 @@ // Generated by Comline // For Rust 1.85.0 or later; verified up to 1.99. +//! The package's protocols share one connection: `datagram@2` framing, the `comline@1` handshake. To use it: +//! +//! - Implement the trait of each protocol the server provides: `conformance::Service`. +//! - Serve with [`serve`]`(transport, Services { service: .. })`, 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)`. +//! - Call the server from the dialling side: `ServiceSender::new(&mut conn).lookup(..)`. +//! +//! [`Connection`](Connection) names the connection over a transport `T`, written `Connection`; [`Format`] is the package's wire format. + +use comline_runtime::contract::RuntimeError; +use comline_runtime::transport::Transport; + /// The package's wire format (`wire.format`). pub type Format = comline_runtime::format::Json; @@ -7,6 +19,10 @@ pub type Format = comline_runtime::format::Json; /// checks, so both ends agree on each protocol's number. pub const CONNECTION_IR_HASH: u64 = 0x8ee00745c73a32b2; +/// The package's connection over the transport `T`: what [`accept`] and [`connect`] +/// return, written `Connection`: [`Format`] over the default framing. +pub type Connection = comline_runtime::connection::Connection; + /// What the accepting side provides: one field per protocol, so leaving one out /// doesn't compile. pub struct Services { @@ -15,7 +31,7 @@ pub struct Services { impl Services { /// Provide every protocol on `conn`: the peer's calls to them come here. - pub fn provide_on(self, conn: &mut comline_runtime::connection::Connection) { + pub fn provide_on(self, conn: &mut Connection) { crate::conformance::ServiceDispatcher(self.service).provide_on(conn); } } @@ -24,21 +40,20 @@ impl Services { /// every protocol in `services` on it. The connection comes back not yet /// served, for a server that calls the client first, or serves one call at /// a time. -pub fn accept(transport: T, services: Services) -> Result, comline_runtime::contract::RuntimeError> { +pub fn accept(transport: T, services: Services) -> Result, RuntimeError> { let mut conn = comline_runtime::connection::Connection::accept(transport, Format::default(), CONNECTION_IR_HASH)?; services.provide_on(&mut conn); Ok(conn) } /// [`accept`], then serve every call until the peer leaves. -pub fn serve(transport: T, services: Services) -> Result<(), comline_runtime::contract::RuntimeError> { +pub fn serve(transport: T, services: Services) -> Result<(), RuntimeError> { accept(transport, services)?.serve() } -/// Dial over `transport`: run the handshake, then provide every protocol in -/// `services`, which the server calls. Call the server's protocols through -/// their senders. -pub fn connect(transport: T) -> Result, comline_runtime::contract::RuntimeError> { +/// Dial over `transport`: run the handshake. Call the server's protocols +/// through their senders. +pub fn connect(transport: T) -> Result, RuntimeError> { let conn = comline_runtime::connection::Connection::connect(transport, Format::default(), CONNECTION_IR_HASH)?; Ok(conn) } diff --git a/conformance/tests/golden/format_json/typescript/conformance.ts b/conformance/tests/golden/format_json/typescript/conformance.ts index 4a12c64..cd34d80 100644 --- a/conformance/tests/golden/format_json/typescript/conformance.ts +++ b/conformance/tests/golden/format_json/typescript/conformance.ts @@ -4,7 +4,6 @@ import { RuntimeError, resolveKind, - JsonCodec, type Codec, type Connection, type Dispatch, @@ -18,14 +17,6 @@ import { * two ends of a connection must agree on it. */ export const IR_HASH = 0x8ee00745c73a32b2n; -/** 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 = 0x8ee00745c73a32b2n; - -/** 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 JsonCodec(); - export interface Record { id: number; name: string; @@ -52,12 +43,14 @@ export interface ServiceLookupParams { id: number; } +/** @internal */ export const ServiceLookupParamsLayout: Layout = { struct: [["id", "s32"]] }; export interface ServiceNotifyParams { code: number; } +/** @internal */ export const ServiceNotifyParamsLayout: Layout = { struct: [["code", "u16"]] }; export interface Service { @@ -67,8 +60,10 @@ export interface Service { notify(peer: Peer, params: ServiceNotifyParams): Promise; } +/** @internal */ export const SERVICE_CALLS = ["lookup", "count", "notify"] as const; +/** @internal */ export class ServiceDispatcher implements Dispatch { /** This protocol's number on a connection. */ static readonly PROTOCOL = 0; @@ -123,7 +118,7 @@ export class ServiceDispatcher implements Dispatch { } } - /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)`, or let the package's `serve` / `connect` do it. */ + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)` (`Format` and `CONNECTION_IR_HASH` are in `./wire.js`), or let the package's `serve` / `connect` do it. */ provideOn(conn: Connection): void { conn.provide(ServiceDispatcher.PROTOCOL, this); } diff --git a/conformance/tests/golden/format_json/typescript/connection.ts b/conformance/tests/golden/format_json/typescript/connection.ts index 53a5c0b..1a1cedb 100644 --- a/conformance/tests/golden/format_json/typescript/connection.ts +++ b/conformance/tests/golden/format_json/typescript/connection.ts @@ -1,27 +1,37 @@ // Generated by Comline // For TypeScript 5.0 or later; verified up to 5.9. +/** + * Where to start: + * + * - Implement what you provide: `Service` (in `./conformance.js`). + * - Serve with `serve(transport, { service })`; `accept(transport, { service })` takes the same and hands back the connection. + * - Dial with `connect(transport)`. + * - Call the other end with `new ServiceSender(conn).lookup(…)`, 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, - JsonCodec, - type Codec, type Transport, } from "@comline/runtime"; import * as ns_conformance from "./conformance.js"; +import { CONNECTION_IR_HASH, Format } from "./wire.js"; -/** The package's wire format (`wire.format`). */ -export const Format: Codec = new JsonCodec(); - -/** 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 = 0x8ee00745c73a32b2n; +/** 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 { service: ns_conformance.Service; } -/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ export function provideServices(conn: Connection, services: Services): void { new ns_conformance.ServiceDispatcher(services.service).provideOn(conn); } @@ -43,9 +53,8 @@ export async function serve(transport: Transport, services: Services): Promise { const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH); diff --git a/conformance/tests/golden/format_json/typescript/wire.ts b/conformance/tests/golden/format_json/typescript/wire.ts new file mode 100644 index 0000000..409baeb --- /dev/null +++ b/conformance/tests/golden/format_json/typescript/wire.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + JsonCodec, + type Codec, +} from "@comline/runtime"; + +/** The package's wire format (`wire.format`). */ +export const Format: Codec = new JsonCodec(); + +/** 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 = 0x8ee00745c73a32b2n; diff --git a/conformance/tests/golden/format_msgpack/rust/conformance.rs b/conformance/tests/golden/format_msgpack/rust/conformance.rs index cb8546c..ace4801 100644 --- a/conformance/tests/golden/format_msgpack/rust/conformance.rs +++ b/conformance/tests/golden/format_msgpack/rust/conformance.rs @@ -12,13 +12,8 @@ use comline_runtime::transport::Transport; /// two ends of a connection must agree on it, and the handshake checks. pub const IR_HASH: u64 = 0x8ee00745c73a32b2; -/// 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 = 0x8ee00745c73a32b2; - -/// 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::MsgPack; +#[doc(hidden)] +pub use crate::connection::{CONNECTION_IR_HASH, Format}; #[derive(Debug, Clone, Serialize, Deserialize)] pub struct Record { @@ -38,11 +33,13 @@ impl core::fmt::Display for NotFound { impl core::error::Error for NotFound {} +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct ServiceLookupParams { pub id: i32, } +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct ServiceNotifyParams { pub code: u16, @@ -94,8 +91,10 @@ pub trait Service { fn notify(&self, peer: &mut impl Peer, code: u16); } +#[doc(hidden)] pub const SERVICE_CALLS: &[&str] = &["lookup", "count", "notify"]; +#[doc(hidden)] pub struct ServiceDispatcher(pub S); impl Dispatch for ServiceDispatcher { @@ -181,6 +180,7 @@ impl Dispatch for ServiceDispatcher { impl ServiceDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -201,6 +201,7 @@ pub struct ServiceSender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> ServiceSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; pub fn new(peer: &'p mut P) -> Self { diff --git a/conformance/tests/golden/format_msgpack/rust/connection.rs b/conformance/tests/golden/format_msgpack/rust/connection.rs index 5eed300..9c2f825 100644 --- a/conformance/tests/golden/format_msgpack/rust/connection.rs +++ b/conformance/tests/golden/format_msgpack/rust/connection.rs @@ -1,5 +1,17 @@ // Generated by Comline // For Rust 1.85.0 or later; verified up to 1.99. +//! The package's protocols share one connection: `datagram@2` framing, the `comline@1` handshake. To use it: +//! +//! - Implement the trait of each protocol the server provides: `conformance::Service`. +//! - Serve with [`serve`]`(transport, Services { service: .. })`, 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)`. +//! - Call the server from the dialling side: `ServiceSender::new(&mut conn).lookup(..)`. +//! +//! [`Connection`](Connection) names the connection over a transport `T`, written `Connection`; [`Format`] is the package's wire format. + +use comline_runtime::contract::RuntimeError; +use comline_runtime::transport::Transport; + /// The package's wire format (`wire.format`). pub type Format = comline_runtime::format::MsgPack; @@ -7,6 +19,10 @@ pub type Format = comline_runtime::format::MsgPack; /// checks, so both ends agree on each protocol's number. pub const CONNECTION_IR_HASH: u64 = 0x8ee00745c73a32b2; +/// The package's connection over the transport `T`: what [`accept`] and [`connect`] +/// return, written `Connection`: [`Format`] over the default framing. +pub type Connection = comline_runtime::connection::Connection; + /// What the accepting side provides: one field per protocol, so leaving one out /// doesn't compile. pub struct Services { @@ -15,7 +31,7 @@ pub struct Services { impl Services { /// Provide every protocol on `conn`: the peer's calls to them come here. - pub fn provide_on(self, conn: &mut comline_runtime::connection::Connection) { + pub fn provide_on(self, conn: &mut Connection) { crate::conformance::ServiceDispatcher(self.service).provide_on(conn); } } @@ -24,21 +40,20 @@ impl Services { /// every protocol in `services` on it. The connection comes back not yet /// served, for a server that calls the client first, or serves one call at /// a time. -pub fn accept(transport: T, services: Services) -> Result, comline_runtime::contract::RuntimeError> { +pub fn accept(transport: T, services: Services) -> Result, RuntimeError> { let mut conn = comline_runtime::connection::Connection::accept(transport, Format::default(), CONNECTION_IR_HASH)?; services.provide_on(&mut conn); Ok(conn) } /// [`accept`], then serve every call until the peer leaves. -pub fn serve(transport: T, services: Services) -> Result<(), comline_runtime::contract::RuntimeError> { +pub fn serve(transport: T, services: Services) -> Result<(), RuntimeError> { accept(transport, services)?.serve() } -/// Dial over `transport`: run the handshake, then provide every protocol in -/// `services`, which the server calls. Call the server's protocols through -/// their senders. -pub fn connect(transport: T) -> Result, comline_runtime::contract::RuntimeError> { +/// Dial over `transport`: run the handshake. Call the server's protocols +/// through their senders. +pub fn connect(transport: T) -> Result, RuntimeError> { let conn = comline_runtime::connection::Connection::connect(transport, Format::default(), CONNECTION_IR_HASH)?; Ok(conn) } diff --git a/conformance/tests/golden/framing_datagram3/rust/conformance.rs b/conformance/tests/golden/framing_datagram3/rust/conformance.rs index 7fb4699..3094b8a 100644 --- a/conformance/tests/golden/framing_datagram3/rust/conformance.rs +++ b/conformance/tests/golden/framing_datagram3/rust/conformance.rs @@ -12,14 +12,10 @@ use comline_runtime::transport::Transport; /// two ends of a connection must agree on it, and the handshake checks. pub const IR_HASH: u64 = 0xbb9f4216f7365478; -/// 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 = 0xbb9f4216f7365478; - -/// 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)] +pub use crate::connection::{CONNECTION_IR_HASH, Format}; +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct CounterAddParams { pub n: u32, @@ -34,8 +30,10 @@ pub trait Counter { fn reset(&self, peer: &mut impl Peer); } +#[doc(hidden)] pub const COUNTER_CALLS: &[&str] = &["add", "reset"]; +#[doc(hidden)] pub struct CounterDispatcher(pub S); impl Dispatch for CounterDispatcher { @@ -102,6 +100,7 @@ impl Dispatch for CounterDispatcher { impl CounterDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -122,6 +121,7 @@ pub struct CounterSender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> CounterSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; pub fn new(peer: &'p mut P) -> Self { diff --git a/conformance/tests/golden/framing_datagram3/rust/connection.rs b/conformance/tests/golden/framing_datagram3/rust/connection.rs index 04b31bd..a73dbda 100644 --- a/conformance/tests/golden/framing_datagram3/rust/connection.rs +++ b/conformance/tests/golden/framing_datagram3/rust/connection.rs @@ -1,5 +1,17 @@ // 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@1` handshake. To use it: +//! +//! - Implement the trait of each protocol the server provides: `conformance::Counter`. +//! - Serve with [`serve`]`(transport, Services { counter: .. })`, 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)`. +//! - Call the server from the dialling side: `CounterSender::new(&mut conn).add(..)`. +//! +//! [`Connection`](Connection) names the connection over a transport `T`, written `Connection`; [`Format`] is the package's wire format. + +use comline_runtime::contract::RuntimeError; +use comline_runtime::transport::Transport; + /// The package's wire format (`wire.format`). pub type Format = comline_runtime::format::Packed; @@ -7,6 +19,13 @@ pub type Format = comline_runtime::format::Packed; /// checks, so both ends agree on each protocol's number. pub const CONNECTION_IR_HASH: u64 = 0xbb9f4216f7365478; +/// 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; + /// What the accepting side provides: one field per protocol, so leaving one out /// doesn't compile. pub struct Services { @@ -15,7 +34,7 @@ pub struct Services { impl Services { /// Provide every protocol on `conn`: the peer's calls to them come here. - pub fn provide_on(self, conn: &mut comline_runtime::connection::Connection) { + pub fn provide_on(self, conn: &mut Connection) { crate::conformance::CounterDispatcher(self.counter).provide_on(conn); } } @@ -24,21 +43,20 @@ impl Services { /// every protocol in `services` on it. The connection comes back not yet /// served, for a server that calls the client first, or serves one call at /// a time. -pub fn accept(transport: T, services: Services) -> Result, comline_runtime::contract::RuntimeError> { +pub fn accept(transport: T, services: Services) -> Result, RuntimeError> { let mut conn = comline_runtime::connection::Connection::accept_with(transport, Format::default(), comline_runtime::contract::Datagram3Framing, &mut comline_runtime::handshake::ComlineHandshake, CONNECTION_IR_HASH)?; services.provide_on(&mut conn); Ok(conn) } /// [`accept`], then serve every call until the peer leaves. -pub fn serve(transport: T, services: Services) -> Result<(), comline_runtime::contract::RuntimeError> { +pub fn serve(transport: T, services: Services) -> Result<(), RuntimeError> { accept(transport, services)?.serve() } -/// Dial over `transport`: run the handshake, then provide every protocol in -/// `services`, which the server calls. Call the server's protocols through -/// their senders. -pub fn connect(transport: T) -> Result, comline_runtime::contract::RuntimeError> { +/// Dial over `transport`: run the handshake. Call the server's protocols +/// through their senders. +pub fn connect(transport: T) -> Result, RuntimeError> { let conn = comline_runtime::connection::Connection::connect_with(transport, Format::default(), comline_runtime::contract::Datagram3Framing, &mut comline_runtime::handshake::ComlineHandshake, CONNECTION_IR_HASH)?; Ok(conn) } diff --git a/conformance/tests/golden/framing_datagram3/typescript/conformance.ts b/conformance/tests/golden/framing_datagram3/typescript/conformance.ts index 0042c90..88ac190 100644 --- a/conformance/tests/golden/framing_datagram3/typescript/conformance.ts +++ b/conformance/tests/golden/framing_datagram3/typescript/conformance.ts @@ -4,7 +4,6 @@ import { RuntimeError, resolveKind, - PackedCodec, type Codec, type Connection, type Dispatch, @@ -18,18 +17,11 @@ import { * two ends of a connection must agree on it. */ export const IR_HASH = 0xbb9f4216f7365478n; -/** 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 = 0xbb9f4216f7365478n; - -/** 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 CounterAddParams { n: number; } +/** @internal */ export const CounterAddParamsLayout: Layout = { struct: [["n", "u32"]] }; export interface Counter { @@ -37,8 +29,10 @@ export interface Counter { reset(peer: Peer): Promise; } +/** @internal */ export const COUNTER_CALLS = ["add", "reset"] as const; +/** @internal */ export class CounterDispatcher implements Dispatch { /** This protocol's number on a connection. */ static readonly PROTOCOL = 0; @@ -83,7 +77,7 @@ export class CounterDispatcher implements Dispatch { } } - /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)`, or let the package's `serve` / `connect` do it. */ + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)` (`Format` and `CONNECTION_IR_HASH` are in `./wire.js`), or let the package's `serve` / `connect` do it. */ provideOn(conn: Connection): void { conn.provide(CounterDispatcher.PROTOCOL, this); } diff --git a/conformance/tests/golden/framing_datagram3/typescript/connection.ts b/conformance/tests/golden/framing_datagram3/typescript/connection.ts index a21c675..0d1f323 100644 --- a/conformance/tests/golden/framing_datagram3/typescript/connection.ts +++ b/conformance/tests/golden/framing_datagram3/typescript/connection.ts @@ -1,28 +1,38 @@ // Generated by Comline // For TypeScript 5.0 or later; verified up to 5.9. +/** + * Where to start: + * + * - Implement what you provide: `Counter` (in `./conformance.js`). + * - Serve with `serve(transport, { counter })`; `accept(transport, { counter })` takes the same and hands back the connection. + * - Dial with `connect(transport)`. + * - Call the other end with `new CounterSender(conn).add(…)`, 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, Datagram3Framing, - PackedCodec, - type Codec, type Transport, } from "@comline/runtime"; import * as ns_conformance from "./conformance.js"; +import { CONNECTION_IR_HASH, Format } from "./wire.js"; -/** 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 = 0xbb9f4216f7365478n; +/** 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 { counter: ns_conformance.Counter; } -/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ export function provideServices(conn: Connection, services: Services): void { new ns_conformance.CounterDispatcher(services.counter).provideOn(conn); } @@ -44,9 +54,8 @@ export async function serve(transport: Transport, services: Services): Promise { const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH, new Datagram3Framing()); diff --git a/conformance/tests/golden/framing_datagram3/typescript/wire.ts b/conformance/tests/golden/framing_datagram3/typescript/wire.ts new file mode 100644 index 0000000..b536004 --- /dev/null +++ b/conformance/tests/golden/framing_datagram3/typescript/wire.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + PackedCodec, + type Codec, +} from "@comline/runtime"; + +/** 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 = 0xbb9f4216f7365478n; diff --git a/conformance/tests/golden/framing_jsonrpc/rust/conformance.rs b/conformance/tests/golden/framing_jsonrpc/rust/conformance.rs index 8809d0e..55c8e66 100644 --- a/conformance/tests/golden/framing_jsonrpc/rust/conformance.rs +++ b/conformance/tests/golden/framing_jsonrpc/rust/conformance.rs @@ -7,11 +7,14 @@ use comline_runtime::contract::{ }; use comline_runtime::serve::Server; use comline_runtime::transport::Transport; +use comline_runtime::format::Json; +use comline_runtime::framing::JsonRpcFraming; /// 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 = 0x1a95418a1177cd91; +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct RpcPingParams { pub n: u32, @@ -25,6 +28,7 @@ pub trait Rpc { fn ping(&self, n: u32) -> Result>; } +#[doc(hidden)] pub const RPC_CALLS: &[&str] = &["ping"]; pub struct RpcDispatcher(pub S); @@ -72,28 +76,28 @@ impl RpcDispatcher { /// the peer first. /// Encodes with `Json`. pub fn serve(self, transport: &mut T) -> Result<(), RuntimeError> { - self.serve_with_format(transport, comline_runtime::format::Json::default()) + self.serve_with_format(transport, Json::default()) } /// [`serve`](Self::serve), encoding with `format` instead. pub fn serve_with_format(self, transport: &mut T, format: W) -> Result<(), RuntimeError> { - let framing = comline_runtime::framing::JsonRpcFraming; + let framing = JsonRpcFraming; Server::with_framing(self, format, framing).serve(transport, IR_HASH) } } -pub struct RpcClient(pub Client); +pub struct RpcClient(pub Client); impl RpcClient { - pub fn new(client: Client) -> Self { + pub fn new(client: Client) -> Self { Self(client) } /// Bind + run the connection handshake against the provider. /// [`connect`](Self::connect), encoding with `format`. pub fn connect_with_format(transport: T, format: W) -> Result { - let framing = comline_runtime::framing::JsonRpcFraming; + let framing = JsonRpcFraming; Ok(Self(Client::connect_with_framing(transport, format, framing, IR_HASH)?)) } @@ -107,11 +111,11 @@ impl RpcClient { } } -impl RpcClient { +impl RpcClient { /// Bind + run the connection handshake against the provider. /// Encodes with `Json`. pub fn connect(transport: T) -> Result { - Self::connect_with_format(transport, comline_runtime::format::Json::default()) + Self::connect_with_format(transport, Json::default()) } } diff --git a/conformance/tests/golden/framing_jsonrpc/typescript/conformance.ts b/conformance/tests/golden/framing_jsonrpc/typescript/conformance.ts index a4d3928..5fb7fe1 100644 --- a/conformance/tests/golden/framing_jsonrpc/typescript/conformance.ts +++ b/conformance/tests/golden/framing_jsonrpc/typescript/conformance.ts @@ -25,12 +25,14 @@ export interface RpcPingParams { n: number; } +/** @internal */ export const RpcPingParamsLayout: Layout = { struct: [["n", "u32"]] }; export interface Rpc { ping(params: RpcPingParams): Promise; } +/** @internal */ export const RPC_CALLS = ["ping"] as const; export class RpcDispatcher implements Dispatch { diff --git a/conformance/tests/golden/handshake_comline2/rust/conformance.rs b/conformance/tests/golden/handshake_comline2/rust/conformance.rs index e04f9d0..81c80c2 100644 --- a/conformance/tests/golden/handshake_comline2/rust/conformance.rs +++ b/conformance/tests/golden/handshake_comline2/rust/conformance.rs @@ -12,14 +12,10 @@ use comline_runtime::transport::Transport; /// two ends of a connection must agree on it, and the handshake checks. pub const IR_HASH: u64 = 0x9328a48fb76a93df; -/// 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 = 0x9328a48fb76a93df; - -/// 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)] +pub use crate::connection::{CONNECTION_IR_HASH, Format}; +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct ChatSendParams { pub text: u32, @@ -34,8 +30,10 @@ pub trait Chat { fn leave(&self, peer: &mut impl Peer); } +#[doc(hidden)] pub const CHAT_CALLS: &[&str] = &["send", "leave"]; +#[doc(hidden)] pub struct ChatDispatcher(pub S); impl Dispatch for ChatDispatcher { @@ -102,6 +100,7 @@ impl Dispatch for ChatDispatcher { impl ChatDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -122,6 +121,7 @@ pub struct ChatSender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> ChatSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; pub fn new(peer: &'p mut P) -> Self { diff --git a/conformance/tests/golden/handshake_comline2/rust/connection.rs b/conformance/tests/golden/handshake_comline2/rust/connection.rs index 66e5d90..9971097 100644 --- a/conformance/tests/golden/handshake_comline2/rust/connection.rs +++ b/conformance/tests/golden/handshake_comline2/rust/connection.rs @@ -1,5 +1,18 @@ // 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`. +//! - 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)`. +//! - Call the server from the dialling side: `ChatSender::new(&mut conn).send(..)`. +//! +//! [`Connection`](Connection) names the connection over a transport `T`, written `Connection`; [`Format`] is the package's wire format. + +use comline_runtime::contract::{Peer, Reason, RuntimeError}; +use comline_runtime::handshake::comline2::{Comline2Handshake, Negotiated}; +use comline_runtime::transport::Transport; + /// The package's wire format (`wire.format`). pub type Format = comline_runtime::format::Packed; @@ -7,10 +20,18 @@ pub type Format = comline_runtime::format::Packed; /// checks, so both ends agree on each protocol's number. pub const CONNECTION_IR_HASH: u64 = 0x9328a48fb76a93df; +/// 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; + /// This end's `comline@2` Hello: version 0.1.0 of package `0123456789abcdef0123456789abcdef`, as its /// history records it. Its protocols, by wire number: /// /// - 0 `conformance::Chat`, line 0.1.0: `send` 1, `leave` 0 +#[doc(hidden)] pub const HELLO: &[u8] = &[ 0x43, 0x4f, 0x02, 0x01, 0x00, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x00, 0x01, 0x00, @@ -25,7 +46,8 @@ pub const HELLO: &[u8] = &[ /// The `comline@2` handshake, with [`HELLO`] and the parameters the package /// states: `scope = protocol`, `newer_consumer = refuse`, `same_version_differs = refuse`, `exchange = offer`. -pub fn handshake() -> comline_runtime::handshake::comline2::Comline2Handshake { +#[doc(hidden)] +pub fn handshake() -> Comline2Handshake { use comline_runtime::handshake::comline2 as c2; let hello = match c2::Message::decode(HELLO) { Ok(c2::Message::Hello(hello)) => hello, @@ -51,7 +73,7 @@ fn protocol_path(number: u16) -> &'static str { /// the connection's extensions. #[derive(Debug, Clone)] pub struct Negotiation { - pub negotiated: comline_runtime::handshake::comline2::Negotiated, + pub negotiated: Negotiated, /// The last call that wasn't made because the peer can't take it. pub unavailable: Option, } @@ -66,7 +88,7 @@ pub struct Unavailable { pub function: &'static str, /// Why the peer refused the protocol, or `None` when the peer lacks the /// function (`newer_consumer = degrade`). - pub refused: Option, + pub refused: Option, } impl ::core::fmt::Display for Unavailable { @@ -82,14 +104,14 @@ impl ::core::error::Error for Unavailable {} /// What the connection's `comline@2` handshake agreed, if `accept` / `connect` /// opened it. -pub fn negotiated(peer: &mut P) -> Option { +pub fn negotiated(peer: &mut P) -> Option { let extensions = peer.extensions(); extensions.get::().map(|n| n.negotiated.clone()) } /// The protocols that connected although their wire shape differs from the /// peer's at the same version (`same_version_differs = warn`), by path. -pub fn warnings(peer: &mut P) -> Vec<&'static str> { +pub fn warnings(peer: &mut P) -> Vec<&'static str> { let extensions = peer.extensions(); match extensions.get::() { Some(n) => n.negotiated.warnings.iter().map(|p| protocol_path(*p)).collect(), @@ -99,7 +121,7 @@ pub fn warnings(peer: &mut P) -> Vec<&'stati /// The last call on this connection that failed with `Unavailable`: which /// function, and why. -pub fn unavailable(peer: &mut P) -> Option { +pub fn unavailable(peer: &mut P) -> Option { let extensions = peer.extensions(); extensions.get::().and_then(|n| n.unavailable) } @@ -108,7 +130,7 @@ pub fn unavailable(peer: &mut P) -> Option(peer: &mut P, protocol: u16, function: u16, path: &'static str, name: &'static str) -> Result<(), comline_runtime::contract::RuntimeError> { +pub fn check_call(peer: &mut P, protocol: u16, function: u16, path: &'static str, name: &'static str) -> Result<(), RuntimeError> { let extensions = peer.extensions(); let Some(n) = extensions.get_mut::() else { return Ok(()); @@ -122,7 +144,7 @@ pub fn check_call(peer: &mut P, protocol: u1 _ => None, }); // A protocol this end doesn't have isn't refused by the peer: it's unknown. - let refused = refused.or_else(|| (!n.negotiated.protocols.iter().any(|p| p.number == protocol)).then_some(comline_runtime::contract::Reason::UnknownProtocol)); + let refused = refused.or_else(|| (!n.negotiated.protocols.iter().any(|p| p.number == protocol)).then_some(Reason::UnknownProtocol)); n.unavailable = Some(Unavailable { protocol: path, function: name, refused }); Err(error) } @@ -135,7 +157,7 @@ pub struct Services { impl Services { /// Provide every protocol on `conn`: the peer's calls to them come here. - pub fn provide_on(self, conn: &mut comline_runtime::connection::Connection) { + pub fn provide_on(self, conn: &mut Connection) { crate::conformance::ChatDispatcher(self.chat).provide_on(conn); } } @@ -144,25 +166,24 @@ impl Services { /// every protocol in `services` on it. The connection comes back not yet /// served, for a server that calls the client first, or serves one call at /// a time. -pub fn accept(transport: T, services: Services) -> Result, comline_runtime::contract::RuntimeError> { +pub fn accept(transport: T, services: Services) -> Result, RuntimeError> { let mut handshake = handshake(); let mut conn = comline_runtime::connection::Connection::accept_with(transport, Format::default(), comline_runtime::contract::Datagram3Framing, &mut handshake, CONNECTION_IR_HASH)?; - comline_runtime::contract::Peer::extensions(&mut conn).insert(Negotiation { negotiated: handshake.negotiated().cloned().unwrap_or_else(|| unreachable!("a handshake that succeeded agreed something")), unavailable: None }); + Peer::extensions(&mut conn).insert(Negotiation { negotiated: handshake.negotiated().cloned().unwrap_or_else(|| unreachable!("a handshake that succeeded agreed something")), unavailable: None }); services.provide_on(&mut conn); Ok(conn) } /// [`accept`], then serve every call until the peer leaves. -pub fn serve(transport: T, services: Services) -> Result<(), comline_runtime::contract::RuntimeError> { +pub fn serve(transport: T, services: Services) -> Result<(), RuntimeError> { accept(transport, services)?.serve() } -/// Dial over `transport`: run the handshake, then provide every protocol in -/// `services`, which the server calls. Call the server's protocols through -/// their senders. -pub fn connect(transport: T) -> Result, comline_runtime::contract::RuntimeError> { +/// Dial over `transport`: run the handshake. Call the server's protocols +/// through their senders. +pub fn connect(transport: T) -> Result, RuntimeError> { let mut handshake = handshake(); let mut conn = comline_runtime::connection::Connection::connect_with(transport, Format::default(), comline_runtime::contract::Datagram3Framing, &mut handshake, CONNECTION_IR_HASH)?; - comline_runtime::contract::Peer::extensions(&mut conn).insert(Negotiation { negotiated: handshake.negotiated().cloned().unwrap_or_else(|| unreachable!("a handshake that succeeded agreed something")), unavailable: None }); + Peer::extensions(&mut conn).insert(Negotiation { negotiated: handshake.negotiated().cloned().unwrap_or_else(|| unreachable!("a handshake that succeeded agreed something")), unavailable: None }); Ok(conn) } diff --git a/conformance/tests/golden/handshake_comline2/typescript/conformance.ts b/conformance/tests/golden/handshake_comline2/typescript/conformance.ts index 29bc497..cd8ba98 100644 --- a/conformance/tests/golden/handshake_comline2/typescript/conformance.ts +++ b/conformance/tests/golden/handshake_comline2/typescript/conformance.ts @@ -5,7 +5,6 @@ import { RuntimeError, resolveKind, checkCall, - PackedCodec, type Codec, type Connection, type Dispatch, @@ -19,18 +18,11 @@ import { * two ends of a connection must agree on it. */ export const IR_HASH = 0x9328a48fb76a93dfn; -/** 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 = 0x9328a48fb76a93dfn; - -/** 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 ChatSendParams { text: number; } +/** @internal */ export const ChatSendParamsLayout: Layout = { struct: [["text", "u32"]] }; export interface Chat { @@ -38,8 +30,10 @@ export interface Chat { leave(peer: Peer): Promise; } +/** @internal */ export const CHAT_CALLS = ["send", "leave"] as const; +/** @internal */ export class ChatDispatcher implements Dispatch { /** This protocol's number on a connection. */ static readonly PROTOCOL = 0; diff --git a/conformance/tests/golden/handshake_comline2/typescript/connection.ts b/conformance/tests/golden/handshake_comline2/typescript/connection.ts index 43ac105..23e9a02 100644 --- a/conformance/tests/golden/handshake_comline2/typescript/connection.ts +++ b/conformance/tests/golden/handshake_comline2/typescript/connection.ts @@ -1,30 +1,39 @@ // Generated by Comline // For TypeScript 5.0 or later; verified up to 5.9. +/** + * Where to start: + * + * - Implement what you provide: `Chat` (in `./conformance.js`). + * - Serve with `serve(transport, { chat })`; `accept(transport, { chat })` takes the same and hands back the connection. + * - Dial with `connect(transport)`. + * - 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, Datagram3Framing, - PackedCodec, Comline2Handshake, Negotiated, - type Codec, type Peer, type Transport, } from "@comline/runtime"; import * as ns_conformance from "./conformance.js"; +import { CONNECTION_IR_HASH, Format } from "./wire.js"; -/** 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 = 0x9328a48fb76a93dfn; +/** 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"; /** * This end's `comline@2` Hello: version 0.1.0 of package `0123456789abcdef0123456789abcdef`, as its history * records it. Its protocols, by wire number: * * - 0 `conformance::Chat`, line 0.1.0: `send` 1, `leave` 0 + * + * @internal */ export const HELLO = new Uint8Array([ 0x43, 0x4f, 0x02, 0x01, 0x00, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, @@ -38,7 +47,10 @@ export const HELLO = new Uint8Array([ 0x5a, 0x5a, 0x02, 0x00, 0x01, ]); -/** The `comline@2` handshake, with {@link HELLO} and the parameters the package states. */ +/** + * The `comline@2` handshake, with {@link HELLO} and the parameters the package states. + * @internal + */ export function handshake(): Comline2Handshake { return new Comline2Handshake(HELLO, { scope: "protocol", @@ -69,7 +81,10 @@ export interface Services { chat: ns_conformance.Chat; } -/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ export function provideServices(conn: Connection, services: Services): void { new ns_conformance.ChatDispatcher(services.chat).provideOn(conn); } @@ -93,9 +108,8 @@ export async function serve(transport: Transport, services: Services): Promise { const agreed = handshake(); diff --git a/conformance/tests/golden/handshake_comline2/typescript/wire.ts b/conformance/tests/golden/handshake_comline2/typescript/wire.ts new file mode 100644 index 0000000..d24e55e --- /dev/null +++ b/conformance/tests/golden/handshake_comline2/typescript/wire.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + PackedCodec, + type Codec, +} from "@comline/runtime"; + +/** 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 = 0x9328a48fb76a93dfn; diff --git a/conformance/tests/golden/handshake_none/rust/conformance.rs b/conformance/tests/golden/handshake_none/rust/conformance.rs index 19b6f1e..7eb2cb6 100644 --- a/conformance/tests/golden/handshake_none/rust/conformance.rs +++ b/conformance/tests/golden/handshake_none/rust/conformance.rs @@ -12,14 +12,10 @@ use comline_runtime::transport::Transport; /// two ends of a connection must agree on it, and the handshake checks. pub const IR_HASH: u64 = 0xb7e7d5c80c4d8287; -/// 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 = 0xb7e7d5c80c4d8287; - -/// 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)] +pub use crate::connection::{CONNECTION_IR_HASH, Format}; +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct GatewayPingParams { pub n: u32, @@ -33,10 +29,12 @@ pub trait Gateway { fn ping(&self, peer: &mut impl Peer, n: u32) -> Result>; } +#[doc(hidden)] pub const GATEWAY_CALLS: &[&str] = &["ping"]; /// **Unverified:** gives up schema agreement and encoding agreement. /// Reason given: the gateway predates Comline +#[doc(hidden)] pub struct GatewayDispatcher(pub S); impl Dispatch for GatewayDispatcher { @@ -91,6 +89,7 @@ impl Dispatch for GatewayDispatcher { impl GatewayDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -113,6 +112,7 @@ pub struct GatewaySender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> GatewaySender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; pub fn new(peer: &'p mut P) -> Self { diff --git a/conformance/tests/golden/handshake_none/rust/connection.rs b/conformance/tests/golden/handshake_none/rust/connection.rs index d146722..641f30c 100644 --- a/conformance/tests/golden/handshake_none/rust/connection.rs +++ b/conformance/tests/golden/handshake_none/rust/connection.rs @@ -1,5 +1,17 @@ // Generated by Comline // For Rust 1.85.0 or later; verified up to 1.99. +//! The package's protocols share one connection: `datagram@2` framing, the `none` handshake. To use it: +//! +//! - Implement the trait of each protocol the server provides: `conformance::Gateway`. +//! - Serve with [`serve`]`(transport, Services { gateway: .. })`, 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)`. +//! - Call the server from the dialling side: `GatewaySender::new(&mut conn).ping(..)`. +//! +//! [`Connection`](Connection) names the connection over a transport `T`, written `Connection`; [`Format`] is the package's wire format. + +use comline_runtime::contract::RuntimeError; +use comline_runtime::transport::Transport; + /// The package's wire format (`wire.format`). pub type Format = comline_runtime::format::Packed; @@ -7,6 +19,10 @@ pub type Format = comline_runtime::format::Packed; /// checks, so both ends agree on each protocol's number. pub const CONNECTION_IR_HASH: u64 = 0xb7e7d5c80c4d8287; +/// The package's connection over the transport `T`: what [`accept`] and [`connect`] +/// return, written `Connection`: [`Format`] over the default framing. +pub type Connection = comline_runtime::connection::Connection; + /// What the accepting side provides: one field per protocol, so leaving one out /// doesn't compile. pub struct Services { @@ -15,7 +31,7 @@ pub struct Services { impl Services { /// Provide every protocol on `conn`: the peer's calls to them come here. - pub fn provide_on(self, conn: &mut comline_runtime::connection::Connection) { + pub fn provide_on(self, conn: &mut Connection) { crate::conformance::GatewayDispatcher(self.gateway).provide_on(conn); } } @@ -24,21 +40,20 @@ impl Services { /// every protocol in `services` on it. The connection comes back not yet /// served, for a server that calls the client first, or serves one call at /// a time. -pub fn accept(transport: T, services: Services) -> Result, comline_runtime::contract::RuntimeError> { +pub fn accept(transport: T, services: Services) -> Result, RuntimeError> { let mut conn = comline_runtime::connection::Connection::new_unverified(transport, Format::default()); services.provide_on(&mut conn); Ok(conn) } /// [`accept`], then serve every call until the peer leaves. -pub fn serve(transport: T, services: Services) -> Result<(), comline_runtime::contract::RuntimeError> { +pub fn serve(transport: T, services: Services) -> Result<(), RuntimeError> { accept(transport, services)?.serve() } -/// Dial over `transport`: run the handshake, then provide every protocol in -/// `services`, which the server calls. Call the server's protocols through -/// their senders. -pub fn connect(transport: T) -> Result, comline_runtime::contract::RuntimeError> { +/// Dial over `transport`: run the handshake. Call the server's protocols +/// through their senders. +pub fn connect(transport: T) -> Result, RuntimeError> { let conn = comline_runtime::connection::Connection::new_unverified(transport, Format::default()); Ok(conn) } diff --git a/conformance/tests/golden/handshake_none/typescript/conformance.ts b/conformance/tests/golden/handshake_none/typescript/conformance.ts index 199024f..a76c689 100644 --- a/conformance/tests/golden/handshake_none/typescript/conformance.ts +++ b/conformance/tests/golden/handshake_none/typescript/conformance.ts @@ -4,7 +4,6 @@ import { RuntimeError, resolveKind, - PackedCodec, type Codec, type Connection, type Dispatch, @@ -18,29 +17,25 @@ import { * two ends of a connection must agree on it. */ export const IR_HASH = 0xb7e7d5c80c4d8287n; -/** 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 = 0xb7e7d5c80c4d8287n; - -/** 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 GatewayPingParams { n: number; } +/** @internal */ export const GatewayPingParamsLayout: Layout = { struct: [["n", "u32"]] }; export interface Gateway { ping(peer: Peer, params: GatewayPingParams): Promise; } +/** @internal */ export const GATEWAY_CALLS = ["ping"] as const; /** * **Unverified:** gives up schema agreement and encoding agreement. * Reason given: the gateway predates Comline + * + * @internal */ export class GatewayDispatcher implements Dispatch { /** This protocol's number on a connection. */ @@ -78,7 +73,7 @@ export class GatewayDispatcher implements Dispatch { } } - /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH, framing, new NoHandshake())`, or let the package's `serve` / `connect` do it. */ + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH, framing, new NoHandshake())` (`Format` and `CONNECTION_IR_HASH` are in `./wire.js`), or let the package's `serve` / `connect` do it. */ provideOn(conn: Connection): void { conn.provide(GatewayDispatcher.PROTOCOL, this); } diff --git a/conformance/tests/golden/handshake_none/typescript/connection.ts b/conformance/tests/golden/handshake_none/typescript/connection.ts index fcc5217..91d1b57 100644 --- a/conformance/tests/golden/handshake_none/typescript/connection.ts +++ b/conformance/tests/golden/handshake_none/typescript/connection.ts @@ -1,28 +1,38 @@ // Generated by Comline // For TypeScript 5.0 or later; verified up to 5.9. +/** + * Where to start: + * + * - Implement what you provide: `Gateway` (in `./conformance.js`). + * - Serve with `serve(transport, { gateway })`; `accept(transport, { gateway })` takes the same and hands back the connection. + * - Dial with `connect(transport)`. + * - Call the other end with `new GatewaySender(conn).ping(…)`, 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, - PackedCodec, NoHandshake, - type Codec, type Transport, } from "@comline/runtime"; import * as ns_conformance from "./conformance.js"; +import { CONNECTION_IR_HASH, Format } from "./wire.js"; -/** 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 = 0xb7e7d5c80c4d8287n; +/** 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 { gateway: ns_conformance.Gateway; } -/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ export function provideServices(conn: Connection, services: Services): void { new ns_conformance.GatewayDispatcher(services.gateway).provideOn(conn); } @@ -44,9 +54,8 @@ export async function serve(transport: Transport, services: Services): Promise { const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH, undefined, new NoHandshake()); diff --git a/conformance/tests/golden/handshake_none/typescript/wire.ts b/conformance/tests/golden/handshake_none/typescript/wire.ts new file mode 100644 index 0000000..1290676 --- /dev/null +++ b/conformance/tests/golden/handshake_none/typescript/wire.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + PackedCodec, + type Codec, +} from "@comline/runtime"; + +/** 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 = 0xb7e7d5c80c4d8287n; diff --git a/conformance/tests/golden/nested_namespace/rust/src/lib.rs b/conformance/tests/golden/nested_namespace/rust/src/lib.rs index c06bcc1..76d0aa5 100644 --- a/conformance/tests/golden/nested_namespace/rust/src/lib.rs +++ b/conformance/tests/golden/nested_namespace/rust/src/lib.rs @@ -1,4 +1,6 @@ // Generated by Comline +//! This package declares no protocols: it holds types, so there is nothing to serve or dial. + pub mod group; pub mod top; diff --git a/conformance/tests/golden/nested_protocol/rust/chat/admin.rs b/conformance/tests/golden/nested_protocol/rust/chat/admin.rs index 19da5de..7e3beac 100644 --- a/conformance/tests/golden/nested_protocol/rust/chat/admin.rs +++ b/conformance/tests/golden/nested_protocol/rust/chat/admin.rs @@ -12,19 +12,15 @@ use comline_runtime::transport::Transport; /// two ends of a connection must agree on it, and the handshake checks. pub const IR_HASH: u64 = 0xa6f61afefe65d74a; -/// 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 = 0xa6f61afefe65d74a; - -/// 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)] +pub use crate::connection::{CONNECTION_IR_HASH, Format}; #[derive(Debug, Clone, Serialize, Deserialize)] pub struct Notice { pub text: String, } +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct AdminGreetParams { pub n: u32, @@ -38,8 +34,10 @@ pub trait Admin { fn greet(&self, peer: &mut impl Peer, n: u32) -> Result>; } +#[doc(hidden)] pub const ADMIN_CALLS: &[&str] = &["greet"]; +#[doc(hidden)] pub struct AdminDispatcher(pub S); impl Dispatch for AdminDispatcher { @@ -98,6 +96,7 @@ impl Dispatch for AdminDispatcher { impl AdminDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -118,6 +117,7 @@ pub struct AdminSender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> AdminSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; pub fn new(peer: &'p mut P) -> Self { diff --git a/conformance/tests/golden/nested_protocol/rust/connection.rs b/conformance/tests/golden/nested_protocol/rust/connection.rs index 585a777..2e6af9c 100644 --- a/conformance/tests/golden/nested_protocol/rust/connection.rs +++ b/conformance/tests/golden/nested_protocol/rust/connection.rs @@ -1,5 +1,18 @@ // 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: `chat::admin::Admin`. +//! - Serve with [`serve`]`(transport, Services { admin: .. })`, 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)`. +//! - Call the server from the dialling side: `AdminSender::new(&mut conn).greet(..)`. +//! +//! [`Connection`](Connection) names the connection over a transport `T`, written `Connection`; [`Format`] is the package's wire format. + +use comline_runtime::contract::{Peer, Reason, RuntimeError}; +use comline_runtime::handshake::comline2::{Comline2Handshake, Negotiated}; +use comline_runtime::transport::Transport; + /// The package's wire format (`wire.format`). pub type Format = comline_runtime::format::Packed; @@ -7,10 +20,18 @@ pub type Format = comline_runtime::format::Packed; /// checks, so both ends agree on each protocol's number. pub const CONNECTION_IR_HASH: u64 = 0xa6f61afefe65d74a; +/// 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; + /// This end's `comline@2` Hello: version 0.1.0 of package `0123456789abcdef0123456789abcdef`, as its /// history records it. Its protocols, by wire number: /// /// - 0 `chat::admin::Admin`, line 0.1.0: `greet` 0 +#[doc(hidden)] pub const HELLO: &[u8] = &[ 0x43, 0x4f, 0x02, 0x01, 0x00, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x00, 0x01, 0x00, @@ -25,7 +46,8 @@ pub const HELLO: &[u8] = &[ /// The `comline@2` handshake, with [`HELLO`] and the parameters the package /// states: `scope = protocol`, `newer_consumer = degrade`, `same_version_differs = refuse`, `exchange = offer`. -pub fn handshake() -> comline_runtime::handshake::comline2::Comline2Handshake { +#[doc(hidden)] +pub fn handshake() -> Comline2Handshake { use comline_runtime::handshake::comline2 as c2; let hello = match c2::Message::decode(HELLO) { Ok(c2::Message::Hello(hello)) => hello, @@ -51,7 +73,7 @@ fn protocol_path(number: u16) -> &'static str { /// the connection's extensions. #[derive(Debug, Clone)] pub struct Negotiation { - pub negotiated: comline_runtime::handshake::comline2::Negotiated, + pub negotiated: Negotiated, /// The last call that wasn't made because the peer can't take it. pub unavailable: Option, } @@ -66,7 +88,7 @@ pub struct Unavailable { pub function: &'static str, /// Why the peer refused the protocol, or `None` when the peer lacks the /// function (`newer_consumer = degrade`). - pub refused: Option, + pub refused: Option, } impl ::core::fmt::Display for Unavailable { @@ -82,14 +104,14 @@ impl ::core::error::Error for Unavailable {} /// What the connection's `comline@2` handshake agreed, if `accept` / `connect` /// opened it. -pub fn negotiated(peer: &mut P) -> Option { +pub fn negotiated(peer: &mut P) -> Option { let extensions = peer.extensions(); extensions.get::().map(|n| n.negotiated.clone()) } /// The protocols that connected although their wire shape differs from the /// peer's at the same version (`same_version_differs = warn`), by path. -pub fn warnings(peer: &mut P) -> Vec<&'static str> { +pub fn warnings(peer: &mut P) -> Vec<&'static str> { let extensions = peer.extensions(); match extensions.get::() { Some(n) => n.negotiated.warnings.iter().map(|p| protocol_path(*p)).collect(), @@ -99,7 +121,7 @@ pub fn warnings(peer: &mut P) -> Vec<&'stati /// The last call on this connection that failed with `Unavailable`: which /// function, and why. -pub fn unavailable(peer: &mut P) -> Option { +pub fn unavailable(peer: &mut P) -> Option { let extensions = peer.extensions(); extensions.get::().and_then(|n| n.unavailable) } @@ -108,7 +130,7 @@ pub fn unavailable(peer: &mut P) -> Option(peer: &mut P, protocol: u16, function: u16, path: &'static str, name: &'static str) -> Result<(), comline_runtime::contract::RuntimeError> { +pub fn check_call(peer: &mut P, protocol: u16, function: u16, path: &'static str, name: &'static str) -> Result<(), RuntimeError> { let extensions = peer.extensions(); let Some(n) = extensions.get_mut::() else { return Ok(()); @@ -122,7 +144,7 @@ pub fn check_call(peer: &mut P, protocol: u1 _ => None, }); // A protocol this end doesn't have isn't refused by the peer: it's unknown. - let refused = refused.or_else(|| (!n.negotiated.protocols.iter().any(|p| p.number == protocol)).then_some(comline_runtime::contract::Reason::UnknownProtocol)); + let refused = refused.or_else(|| (!n.negotiated.protocols.iter().any(|p| p.number == protocol)).then_some(Reason::UnknownProtocol)); n.unavailable = Some(Unavailable { protocol: path, function: name, refused }); Err(error) } @@ -135,7 +157,7 @@ pub struct Services { impl Services { /// Provide every protocol on `conn`: the peer's calls to them come here. - pub fn provide_on(self, conn: &mut comline_runtime::connection::Connection) { + pub fn provide_on(self, conn: &mut Connection) { crate::chat::admin::AdminDispatcher(self.admin).provide_on(conn); } } @@ -144,25 +166,24 @@ impl Services { /// every protocol in `services` on it. The connection comes back not yet /// served, for a server that calls the client first, or serves one call at /// a time. -pub fn accept(transport: T, services: Services) -> Result, comline_runtime::contract::RuntimeError> { +pub fn accept(transport: T, services: Services) -> Result, RuntimeError> { let mut handshake = handshake(); let mut conn = comline_runtime::connection::Connection::accept_with(transport, Format::default(), comline_runtime::contract::Datagram3Framing, &mut handshake, CONNECTION_IR_HASH)?; - comline_runtime::contract::Peer::extensions(&mut conn).insert(Negotiation { negotiated: handshake.negotiated().cloned().unwrap_or_else(|| unreachable!("a handshake that succeeded agreed something")), unavailable: None }); + Peer::extensions(&mut conn).insert(Negotiation { negotiated: handshake.negotiated().cloned().unwrap_or_else(|| unreachable!("a handshake that succeeded agreed something")), unavailable: None }); services.provide_on(&mut conn); Ok(conn) } /// [`accept`], then serve every call until the peer leaves. -pub fn serve(transport: T, services: Services) -> Result<(), comline_runtime::contract::RuntimeError> { +pub fn serve(transport: T, services: Services) -> Result<(), RuntimeError> { accept(transport, services)?.serve() } -/// Dial over `transport`: run the handshake, then provide every protocol in -/// `services`, which the server calls. Call the server's protocols through -/// their senders. -pub fn connect(transport: T) -> Result, comline_runtime::contract::RuntimeError> { +/// Dial over `transport`: run the handshake. Call the server's protocols +/// through their senders. +pub fn connect(transport: T) -> Result, RuntimeError> { let mut handshake = handshake(); let mut conn = comline_runtime::connection::Connection::connect_with(transport, Format::default(), comline_runtime::contract::Datagram3Framing, &mut handshake, CONNECTION_IR_HASH)?; - comline_runtime::contract::Peer::extensions(&mut conn).insert(Negotiation { negotiated: handshake.negotiated().cloned().unwrap_or_else(|| unreachable!("a handshake that succeeded agreed something")), unavailable: None }); + Peer::extensions(&mut conn).insert(Negotiation { negotiated: handshake.negotiated().cloned().unwrap_or_else(|| unreachable!("a handshake that succeeded agreed something")), unavailable: None }); Ok(conn) } diff --git a/conformance/tests/golden/nested_protocol/typescript/chat/admin.ts b/conformance/tests/golden/nested_protocol/typescript/chat/admin.ts index eb84a27..02baaeb 100644 --- a/conformance/tests/golden/nested_protocol/typescript/chat/admin.ts +++ b/conformance/tests/golden/nested_protocol/typescript/chat/admin.ts @@ -5,7 +5,6 @@ import { RuntimeError, resolveKind, checkCall, - PackedCodec, type Codec, type Connection, type Dispatch, @@ -19,14 +18,6 @@ import { * two ends of a connection must agree on it. */ export const IR_HASH = 0xa6f61afefe65d74an; -/** 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 = 0xa6f61afefe65d74an; - -/** 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 Notice { text: string; } @@ -37,14 +28,17 @@ export interface AdminGreetParams { n: number; } +/** @internal */ export const AdminGreetParamsLayout: Layout = { struct: [["n", "u32"]] }; export interface Admin { greet(peer: Peer, params: AdminGreetParams): Promise; } +/** @internal */ export const ADMIN_CALLS = ["greet"] as const; +/** @internal */ export class AdminDispatcher implements Dispatch { /** This protocol's number on a connection. */ static readonly PROTOCOL = 0; diff --git a/conformance/tests/golden/nested_protocol/typescript/connection.ts b/conformance/tests/golden/nested_protocol/typescript/connection.ts index dc47823..82a2972 100644 --- a/conformance/tests/golden/nested_protocol/typescript/connection.ts +++ b/conformance/tests/golden/nested_protocol/typescript/connection.ts @@ -1,30 +1,39 @@ // Generated by Comline // For TypeScript 5.0 or later; verified up to 5.9. +/** + * Where to start: + * + * - Implement what you provide: `Admin` (in `./chat/admin.js`). + * - Serve with `serve(transport, { admin })`; `accept(transport, { admin })` takes the same and hands back the connection. + * - Dial with `connect(transport)`. + * - Call the other end with `new AdminSender(conn).greet(…)`, 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, Datagram3Framing, - PackedCodec, Comline2Handshake, Negotiated, - type Codec, type Peer, type Transport, } from "@comline/runtime"; import * as ns_chat_admin from "./chat/admin.js"; +import { CONNECTION_IR_HASH, Format } from "./wire.js"; -/** 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 = 0xa6f61afefe65d74an; +/** 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"; /** * This end's `comline@2` Hello: version 0.1.0 of package `0123456789abcdef0123456789abcdef`, as its history * records it. Its protocols, by wire number: * * - 0 `chat::admin::Admin`, line 0.1.0: `greet` 0 + * + * @internal */ export const HELLO = new Uint8Array([ 0x43, 0x4f, 0x02, 0x01, 0x00, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, @@ -38,7 +47,10 @@ export const HELLO = new Uint8Array([ 0x5a, 0x5a, 0x01, 0x00, ]); -/** The `comline@2` handshake, with {@link HELLO} and the parameters the package states. */ +/** + * The `comline@2` handshake, with {@link HELLO} and the parameters the package states. + * @internal + */ export function handshake(): Comline2Handshake { return new Comline2Handshake(HELLO, { scope: "protocol", @@ -69,7 +81,10 @@ export interface Services { admin: ns_chat_admin.Admin; } -/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ export function provideServices(conn: Connection, services: Services): void { new ns_chat_admin.AdminDispatcher(services.admin).provideOn(conn); } @@ -93,9 +108,8 @@ export async function serve(transport: Transport, services: Services): Promise { const agreed = handshake(); diff --git a/conformance/tests/golden/nested_protocol/typescript/wire.ts b/conformance/tests/golden/nested_protocol/typescript/wire.ts new file mode 100644 index 0000000..cf9accb --- /dev/null +++ b/conformance/tests/golden/nested_protocol/typescript/wire.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + PackedCodec, + type Codec, +} from "@comline/runtime"; + +/** 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 = 0xa6f61afefe65d74an; diff --git a/conformance/tests/golden/protocol/rust/conformance.rs b/conformance/tests/golden/protocol/rust/conformance.rs index a135cbe..ace4801 100644 --- a/conformance/tests/golden/protocol/rust/conformance.rs +++ b/conformance/tests/golden/protocol/rust/conformance.rs @@ -12,13 +12,8 @@ use comline_runtime::transport::Transport; /// two ends of a connection must agree on it, and the handshake checks. pub const IR_HASH: u64 = 0x8ee00745c73a32b2; -/// 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 = 0x8ee00745c73a32b2; - -/// 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)] +pub use crate::connection::{CONNECTION_IR_HASH, Format}; #[derive(Debug, Clone, Serialize, Deserialize)] pub struct Record { @@ -38,11 +33,13 @@ impl core::fmt::Display for NotFound { impl core::error::Error for NotFound {} +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct ServiceLookupParams { pub id: i32, } +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct ServiceNotifyParams { pub code: u16, @@ -94,8 +91,10 @@ pub trait Service { fn notify(&self, peer: &mut impl Peer, code: u16); } +#[doc(hidden)] pub const SERVICE_CALLS: &[&str] = &["lookup", "count", "notify"]; +#[doc(hidden)] pub struct ServiceDispatcher(pub S); impl Dispatch for ServiceDispatcher { @@ -181,6 +180,7 @@ impl Dispatch for ServiceDispatcher { impl ServiceDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -201,6 +201,7 @@ pub struct ServiceSender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> ServiceSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; pub fn new(peer: &'p mut P) -> Self { diff --git a/conformance/tests/golden/protocol/rust/connection.rs b/conformance/tests/golden/protocol/rust/connection.rs index d6ae55c..db67fce 100644 --- a/conformance/tests/golden/protocol/rust/connection.rs +++ b/conformance/tests/golden/protocol/rust/connection.rs @@ -1,5 +1,17 @@ // Generated by Comline // For Rust 1.85.0 or later; verified up to 1.99. +//! The package's protocols share one connection: `datagram@2` framing, the `comline@1` handshake. To use it: +//! +//! - Implement the trait of each protocol the server provides: `conformance::Service`. +//! - Serve with [`serve`]`(transport, Services { service: .. })`, 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)`. +//! - Call the server from the dialling side: `ServiceSender::new(&mut conn).lookup(..)`. +//! +//! [`Connection`](Connection) names the connection over a transport `T`, written `Connection`; [`Format`] is the package's wire format. + +use comline_runtime::contract::RuntimeError; +use comline_runtime::transport::Transport; + /// The package's wire format (`wire.format`). pub type Format = comline_runtime::format::Packed; @@ -7,6 +19,10 @@ pub type Format = comline_runtime::format::Packed; /// checks, so both ends agree on each protocol's number. pub const CONNECTION_IR_HASH: u64 = 0x8ee00745c73a32b2; +/// The package's connection over the transport `T`: what [`accept`] and [`connect`] +/// return, written `Connection`: [`Format`] over the default framing. +pub type Connection = comline_runtime::connection::Connection; + /// What the accepting side provides: one field per protocol, so leaving one out /// doesn't compile. pub struct Services { @@ -15,7 +31,7 @@ pub struct Services { impl Services { /// Provide every protocol on `conn`: the peer's calls to them come here. - pub fn provide_on(self, conn: &mut comline_runtime::connection::Connection) { + pub fn provide_on(self, conn: &mut Connection) { crate::conformance::ServiceDispatcher(self.service).provide_on(conn); } } @@ -24,21 +40,20 @@ impl Services { /// every protocol in `services` on it. The connection comes back not yet /// served, for a server that calls the client first, or serves one call at /// a time. -pub fn accept(transport: T, services: Services) -> Result, comline_runtime::contract::RuntimeError> { +pub fn accept(transport: T, services: Services) -> Result, RuntimeError> { let mut conn = comline_runtime::connection::Connection::accept(transport, Format::default(), CONNECTION_IR_HASH)?; services.provide_on(&mut conn); Ok(conn) } /// [`accept`], then serve every call until the peer leaves. -pub fn serve(transport: T, services: Services) -> Result<(), comline_runtime::contract::RuntimeError> { +pub fn serve(transport: T, services: Services) -> Result<(), RuntimeError> { accept(transport, services)?.serve() } -/// Dial over `transport`: run the handshake, then provide every protocol in -/// `services`, which the server calls. Call the server's protocols through -/// their senders. -pub fn connect(transport: T) -> Result, comline_runtime::contract::RuntimeError> { +/// Dial over `transport`: run the handshake. Call the server's protocols +/// through their senders. +pub fn connect(transport: T) -> Result, RuntimeError> { let conn = comline_runtime::connection::Connection::connect(transport, Format::default(), CONNECTION_IR_HASH)?; Ok(conn) } diff --git a/conformance/tests/golden/protocol/typescript/conformance.ts b/conformance/tests/golden/protocol/typescript/conformance.ts index 385b861..cd34d80 100644 --- a/conformance/tests/golden/protocol/typescript/conformance.ts +++ b/conformance/tests/golden/protocol/typescript/conformance.ts @@ -4,7 +4,6 @@ import { RuntimeError, resolveKind, - PackedCodec, type Codec, type Connection, type Dispatch, @@ -18,14 +17,6 @@ import { * two ends of a connection must agree on it. */ export const IR_HASH = 0x8ee00745c73a32b2n; -/** 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 = 0x8ee00745c73a32b2n; - -/** 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 Record { id: number; name: string; @@ -52,12 +43,14 @@ export interface ServiceLookupParams { id: number; } +/** @internal */ export const ServiceLookupParamsLayout: Layout = { struct: [["id", "s32"]] }; export interface ServiceNotifyParams { code: number; } +/** @internal */ export const ServiceNotifyParamsLayout: Layout = { struct: [["code", "u16"]] }; export interface Service { @@ -67,8 +60,10 @@ export interface Service { notify(peer: Peer, params: ServiceNotifyParams): Promise; } +/** @internal */ export const SERVICE_CALLS = ["lookup", "count", "notify"] as const; +/** @internal */ export class ServiceDispatcher implements Dispatch { /** This protocol's number on a connection. */ static readonly PROTOCOL = 0; @@ -123,7 +118,7 @@ export class ServiceDispatcher implements Dispatch { } } - /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)`, or let the package's `serve` / `connect` do it. */ + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)` (`Format` and `CONNECTION_IR_HASH` are in `./wire.js`), or let the package's `serve` / `connect` do it. */ provideOn(conn: Connection): void { conn.provide(ServiceDispatcher.PROTOCOL, this); } diff --git a/conformance/tests/golden/protocol/typescript/connection.ts b/conformance/tests/golden/protocol/typescript/connection.ts index ff807c4..1a1cedb 100644 --- a/conformance/tests/golden/protocol/typescript/connection.ts +++ b/conformance/tests/golden/protocol/typescript/connection.ts @@ -1,27 +1,37 @@ // Generated by Comline // For TypeScript 5.0 or later; verified up to 5.9. +/** + * Where to start: + * + * - Implement what you provide: `Service` (in `./conformance.js`). + * - Serve with `serve(transport, { service })`; `accept(transport, { service })` takes the same and hands back the connection. + * - Dial with `connect(transport)`. + * - Call the other end with `new ServiceSender(conn).lookup(…)`, 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, - PackedCodec, - type Codec, type Transport, } from "@comline/runtime"; import * as ns_conformance from "./conformance.js"; +import { CONNECTION_IR_HASH, Format } from "./wire.js"; -/** 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 = 0x8ee00745c73a32b2n; +/** 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 { service: ns_conformance.Service; } -/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ export function provideServices(conn: Connection, services: Services): void { new ns_conformance.ServiceDispatcher(services.service).provideOn(conn); } @@ -43,9 +53,8 @@ export async function serve(transport: Transport, services: Services): Promise { const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH); diff --git a/conformance/tests/golden/protocol/typescript/wire.ts b/conformance/tests/golden/protocol/typescript/wire.ts new file mode 100644 index 0000000..b656979 --- /dev/null +++ b/conformance/tests/golden/protocol/typescript/wire.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + PackedCodec, + type Codec, +} from "@comline/runtime"; + +/** 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 = 0x8ee00745c73a32b2n; diff --git a/conformance/tests/golden/validators/rust/conformance.rs b/conformance/tests/golden/validators/rust/conformance.rs index b3a3676..d4ff3c3 100644 --- a/conformance/tests/golden/validators/rust/conformance.rs +++ b/conformance/tests/golden/validators/rust/conformance.rs @@ -12,13 +12,8 @@ use comline_runtime::transport::Transport; /// two ends of a connection must agree on it, and the handshake checks. pub const IR_HASH: u64 = 0xeab4408b940579fb; -/// 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 = 0xf9d255a977b3b030; - -/// 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)] +pub use crate::connection::{CONNECTION_IR_HASH, Format}; pub const MIN_HANDLE: u32 = 2; @@ -165,6 +160,7 @@ impl comline_runtime::validation::Validate for Post { } } +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct SocialRenameParams { pub to: Handle, @@ -207,8 +203,10 @@ pub trait Social { fn rename(&self, peer: &mut impl Peer, to: Handle) -> Result>; } +#[doc(hidden)] pub const SOCIAL_CALLS: &[&str] = &["rename"]; +#[doc(hidden)] pub struct SocialDispatcher(pub S); impl Dispatch for SocialDispatcher { @@ -263,6 +261,7 @@ impl Dispatch for SocialDispatcher { impl SocialDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -283,6 +282,7 @@ pub struct SocialSender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> SocialSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; pub fn new(peer: &'p mut P) -> Self { diff --git a/conformance/tests/golden/validators/rust/connection.rs b/conformance/tests/golden/validators/rust/connection.rs index 6a5688c..fb3ce3a 100644 --- a/conformance/tests/golden/validators/rust/connection.rs +++ b/conformance/tests/golden/validators/rust/connection.rs @@ -1,5 +1,17 @@ // Generated by Comline // For Rust 1.85.0 or later; verified up to 1.99. +//! The package's protocols share one connection: `datagram@2` framing, the `comline@1` handshake. To use it: +//! +//! - Implement the trait of each protocol the server provides: `conformance::Social`. +//! - Serve with [`serve`]`(transport, Services { social: .. })`, 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)`. +//! - Call the server from the dialling side: `SocialSender::new(&mut conn).rename(..)`. +//! +//! [`Connection`](Connection) names the connection over a transport `T`, written `Connection`; [`Format`] is the package's wire format. + +use comline_runtime::contract::RuntimeError; +use comline_runtime::transport::Transport; + /// The package's wire format (`wire.format`). pub type Format = comline_runtime::format::Packed; @@ -7,6 +19,10 @@ pub type Format = comline_runtime::format::Packed; /// checks, so both ends agree on each protocol's number. pub const CONNECTION_IR_HASH: u64 = 0xf9d255a977b3b030; +/// The package's connection over the transport `T`: what [`accept`] and [`connect`] +/// return, written `Connection`: [`Format`] over the default framing. +pub type Connection = comline_runtime::connection::Connection; + /// What the accepting side provides: one field per protocol, so leaving one out /// doesn't compile. pub struct Services { @@ -15,7 +31,7 @@ pub struct Services { impl Services { /// Provide every protocol on `conn`: the peer's calls to them come here. - pub fn provide_on(self, conn: &mut comline_runtime::connection::Connection) { + pub fn provide_on(self, conn: &mut Connection) { crate::conformance::SocialDispatcher(self.social).provide_on(conn); } } @@ -24,21 +40,20 @@ impl Services { /// every protocol in `services` on it. The connection comes back not yet /// served, for a server that calls the client first, or serves one call at /// a time. -pub fn accept(transport: T, services: Services) -> Result, comline_runtime::contract::RuntimeError> { +pub fn accept(transport: T, services: Services) -> Result, RuntimeError> { let mut conn = comline_runtime::connection::Connection::accept(transport, Format::default(), CONNECTION_IR_HASH)?; services.provide_on(&mut conn); Ok(conn) } /// [`accept`], then serve every call until the peer leaves. -pub fn serve(transport: T, services: Services) -> Result<(), comline_runtime::contract::RuntimeError> { +pub fn serve(transport: T, services: Services) -> Result<(), RuntimeError> { accept(transport, services)?.serve() } -/// Dial over `transport`: run the handshake, then provide every protocol in -/// `services`, which the server calls. Call the server's protocols through -/// their senders. -pub fn connect(transport: T) -> Result, comline_runtime::contract::RuntimeError> { +/// Dial over `transport`: run the handshake. Call the server's protocols +/// through their senders. +pub fn connect(transport: T) -> Result, RuntimeError> { let conn = comline_runtime::connection::Connection::connect(transport, Format::default(), CONNECTION_IR_HASH)?; Ok(conn) } diff --git a/conformance/tests/golden/validators/typescript/conformance.ts b/conformance/tests/golden/validators/typescript/conformance.ts index 40ce6fb..c72d455 100644 --- a/conformance/tests/golden/validators/typescript/conformance.ts +++ b/conformance/tests/golden/validators/typescript/conformance.ts @@ -4,7 +4,6 @@ import { RuntimeError, resolveKind, - PackedCodec, type Codec, type Connection, type Dispatch, @@ -18,14 +17,6 @@ import { * two ends of a connection must agree on it. */ export const IR_HASH = 0xeab4408b940579fbn; -/** 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 = 0xf9d255a977b3b030n; - -/** 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 const MIN_HANDLE = 2; export type Handle = string; @@ -52,14 +43,17 @@ export interface SocialRenameParams { to: Handle; } +/** @internal */ export const SocialRenameParamsLayout: Layout = { struct: [["to", () => HandleLayout]] }; export interface Social { rename(peer: Peer, params: SocialRenameParams): Promise; } +/** @internal */ export const SOCIAL_CALLS = ["rename"] as const; +/** @internal */ export class SocialDispatcher implements Dispatch { /** This protocol's number on a connection. */ static readonly PROTOCOL = 0; @@ -96,7 +90,7 @@ export class SocialDispatcher implements Dispatch { } } - /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)`, or let the package's `serve` / `connect` do it. */ + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)` (`Format` and `CONNECTION_IR_HASH` are in `./wire.js`), or let the package's `serve` / `connect` do it. */ provideOn(conn: Connection): void { conn.provide(SocialDispatcher.PROTOCOL, this); } diff --git a/conformance/tests/golden/validators/typescript/connection.ts b/conformance/tests/golden/validators/typescript/connection.ts index 1b9512d..abe85a9 100644 --- a/conformance/tests/golden/validators/typescript/connection.ts +++ b/conformance/tests/golden/validators/typescript/connection.ts @@ -1,27 +1,37 @@ // Generated by Comline // For TypeScript 5.0 or later; verified up to 5.9. +/** + * Where to start: + * + * - Implement what you provide: `Social` (in `./conformance.js`). + * - Serve with `serve(transport, { social })`; `accept(transport, { social })` takes the same and hands back the connection. + * - Dial with `connect(transport)`. + * - Call the other end with `new SocialSender(conn).rename(…)`, 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, - PackedCodec, - type Codec, type Transport, } from "@comline/runtime"; import * as ns_conformance from "./conformance.js"; +import { CONNECTION_IR_HASH, Format } from "./wire.js"; -/** 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 = 0xf9d255a977b3b030n; +/** 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 { social: ns_conformance.Social; } -/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ export function provideServices(conn: Connection, services: Services): void { new ns_conformance.SocialDispatcher(services.social).provideOn(conn); } @@ -43,9 +53,8 @@ export async function serve(transport: Transport, services: Services): Promise { const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH); diff --git a/conformance/tests/golden/validators/typescript/wire.ts b/conformance/tests/golden/validators/typescript/wire.ts new file mode 100644 index 0000000..71c56b7 --- /dev/null +++ b/conformance/tests/golden/validators/typescript/wire.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + PackedCodec, + type Codec, +} from "@comline/runtime"; + +/** 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 = 0xf9d255a977b3b030n; diff --git a/conformance/tests/golden/validators_on_decode/rust/conformance.rs b/conformance/tests/golden/validators_on_decode/rust/conformance.rs index f26a9a0..0b4bf93 100644 --- a/conformance/tests/golden/validators_on_decode/rust/conformance.rs +++ b/conformance/tests/golden/validators_on_decode/rust/conformance.rs @@ -12,13 +12,8 @@ use comline_runtime::transport::Transport; /// two ends of a connection must agree on it, and the handshake checks. pub const IR_HASH: u64 = 0xeab4408b940579fb; -/// 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 = 0xf9d255a977b3b030; - -/// 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)] +pub use crate::connection::{CONNECTION_IR_HASH, Format}; pub const MIN_HANDLE: u32 = 2; @@ -215,6 +210,7 @@ impl TryFrom<__PostUnchecked> for Post { } } +#[doc(hidden)] #[derive(Debug, Clone, Serialize, Deserialize)] pub struct SocialRenameParams { pub to: Handle, @@ -257,8 +253,10 @@ pub trait Social { fn rename(&self, peer: &mut impl Peer, to: Handle) -> Result>; } +#[doc(hidden)] pub const SOCIAL_CALLS: &[&str] = &["rename"]; +#[doc(hidden)] pub struct SocialDispatcher(pub S); impl Dispatch for SocialDispatcher { @@ -317,6 +315,7 @@ impl Dispatch for SocialDispatcher { impl SocialDispatcher { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; /// Provide this protocol on `conn`: the peer's calls to it come here. @@ -337,6 +336,7 @@ pub struct SocialSender<'p, P: Peer>(pub &'p mut P); impl<'p, P: Peer> SocialSender<'p, P> { /// This protocol's number on a connection. + #[doc(hidden)] pub const PROTOCOL: ProtocolNumber = 0; pub fn new(peer: &'p mut P) -> Self { diff --git a/conformance/tests/golden/validators_on_decode/rust/connection.rs b/conformance/tests/golden/validators_on_decode/rust/connection.rs index 6a5688c..fb3ce3a 100644 --- a/conformance/tests/golden/validators_on_decode/rust/connection.rs +++ b/conformance/tests/golden/validators_on_decode/rust/connection.rs @@ -1,5 +1,17 @@ // Generated by Comline // For Rust 1.85.0 or later; verified up to 1.99. +//! The package's protocols share one connection: `datagram@2` framing, the `comline@1` handshake. To use it: +//! +//! - Implement the trait of each protocol the server provides: `conformance::Social`. +//! - Serve with [`serve`]`(transport, Services { social: .. })`, 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)`. +//! - Call the server from the dialling side: `SocialSender::new(&mut conn).rename(..)`. +//! +//! [`Connection`](Connection) names the connection over a transport `T`, written `Connection`; [`Format`] is the package's wire format. + +use comline_runtime::contract::RuntimeError; +use comline_runtime::transport::Transport; + /// The package's wire format (`wire.format`). pub type Format = comline_runtime::format::Packed; @@ -7,6 +19,10 @@ pub type Format = comline_runtime::format::Packed; /// checks, so both ends agree on each protocol's number. pub const CONNECTION_IR_HASH: u64 = 0xf9d255a977b3b030; +/// The package's connection over the transport `T`: what [`accept`] and [`connect`] +/// return, written `Connection`: [`Format`] over the default framing. +pub type Connection = comline_runtime::connection::Connection; + /// What the accepting side provides: one field per protocol, so leaving one out /// doesn't compile. pub struct Services { @@ -15,7 +31,7 @@ pub struct Services { impl Services { /// Provide every protocol on `conn`: the peer's calls to them come here. - pub fn provide_on(self, conn: &mut comline_runtime::connection::Connection) { + pub fn provide_on(self, conn: &mut Connection) { crate::conformance::SocialDispatcher(self.social).provide_on(conn); } } @@ -24,21 +40,20 @@ impl Services { /// every protocol in `services` on it. The connection comes back not yet /// served, for a server that calls the client first, or serves one call at /// a time. -pub fn accept(transport: T, services: Services) -> Result, comline_runtime::contract::RuntimeError> { +pub fn accept(transport: T, services: Services) -> Result, RuntimeError> { let mut conn = comline_runtime::connection::Connection::accept(transport, Format::default(), CONNECTION_IR_HASH)?; services.provide_on(&mut conn); Ok(conn) } /// [`accept`], then serve every call until the peer leaves. -pub fn serve(transport: T, services: Services) -> Result<(), comline_runtime::contract::RuntimeError> { +pub fn serve(transport: T, services: Services) -> Result<(), RuntimeError> { accept(transport, services)?.serve() } -/// Dial over `transport`: run the handshake, then provide every protocol in -/// `services`, which the server calls. Call the server's protocols through -/// their senders. -pub fn connect(transport: T) -> Result, comline_runtime::contract::RuntimeError> { +/// Dial over `transport`: run the handshake. Call the server's protocols +/// through their senders. +pub fn connect(transport: T) -> Result, RuntimeError> { let conn = comline_runtime::connection::Connection::connect(transport, Format::default(), CONNECTION_IR_HASH)?; Ok(conn) } diff --git a/conformance/tests/golden/validators_on_decode/typescript/conformance.ts b/conformance/tests/golden/validators_on_decode/typescript/conformance.ts index 40ce6fb..c72d455 100644 --- a/conformance/tests/golden/validators_on_decode/typescript/conformance.ts +++ b/conformance/tests/golden/validators_on_decode/typescript/conformance.ts @@ -4,7 +4,6 @@ import { RuntimeError, resolveKind, - PackedCodec, type Codec, type Connection, type Dispatch, @@ -18,14 +17,6 @@ import { * two ends of a connection must agree on it. */ export const IR_HASH = 0xeab4408b940579fbn; -/** 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 = 0xf9d255a977b3b030n; - -/** 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 const MIN_HANDLE = 2; export type Handle = string; @@ -52,14 +43,17 @@ export interface SocialRenameParams { to: Handle; } +/** @internal */ export const SocialRenameParamsLayout: Layout = { struct: [["to", () => HandleLayout]] }; export interface Social { rename(peer: Peer, params: SocialRenameParams): Promise; } +/** @internal */ export const SOCIAL_CALLS = ["rename"] as const; +/** @internal */ export class SocialDispatcher implements Dispatch { /** This protocol's number on a connection. */ static readonly PROTOCOL = 0; @@ -96,7 +90,7 @@ export class SocialDispatcher implements Dispatch { } } - /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)`, or let the package's `serve` / `connect` do it. */ + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with `Connection.accept(transport, Format, CONNECTION_IR_HASH)` (`Format` and `CONNECTION_IR_HASH` are in `./wire.js`), or let the package's `serve` / `connect` do it. */ provideOn(conn: Connection): void { conn.provide(SocialDispatcher.PROTOCOL, this); } diff --git a/conformance/tests/golden/validators_on_decode/typescript/connection.ts b/conformance/tests/golden/validators_on_decode/typescript/connection.ts index 1b9512d..abe85a9 100644 --- a/conformance/tests/golden/validators_on_decode/typescript/connection.ts +++ b/conformance/tests/golden/validators_on_decode/typescript/connection.ts @@ -1,27 +1,37 @@ // Generated by Comline // For TypeScript 5.0 or later; verified up to 5.9. +/** + * Where to start: + * + * - Implement what you provide: `Social` (in `./conformance.js`). + * - Serve with `serve(transport, { social })`; `accept(transport, { social })` takes the same and hands back the connection. + * - Dial with `connect(transport)`. + * - Call the other end with `new SocialSender(conn).rename(…)`, 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, - PackedCodec, - type Codec, type Transport, } from "@comline/runtime"; import * as ns_conformance from "./conformance.js"; +import { CONNECTION_IR_HASH, Format } from "./wire.js"; -/** 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 = 0xf9d255a977b3b030n; +/** 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 { social: ns_conformance.Social; } -/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ export function provideServices(conn: Connection, services: Services): void { new ns_conformance.SocialDispatcher(services.social).provideOn(conn); } @@ -43,9 +53,8 @@ export async function serve(transport: Transport, services: Services): Promise { const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH); diff --git a/conformance/tests/golden/validators_on_decode/typescript/wire.ts b/conformance/tests/golden/validators_on_decode/typescript/wire.ts new file mode 100644 index 0000000..71c56b7 --- /dev/null +++ b/conformance/tests/golden/validators_on_decode/typescript/wire.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + PackedCodec, + type Codec, +} from "@comline/runtime"; + +/** 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 = 0xf9d255a977b3b030n;