diff --git a/FEATURES.md b/FEATURES.md new file mode 100644 index 0000000..e859d24 --- /dev/null +++ b/FEATURES.md @@ -0,0 +1,37 @@ +# Generator features + + + +What the typescript generator implements, and the conformance fixtures that prove it. A claim is checked, not trusted: a supported feature has a fixture that generates and matches its golden, an ignored one generates exactly what it would without the feature, and an unsupported one is refused with an error naming every use. + +| Feature | typescript ≥ 5.0 | +|---|---| +| structs
`structs` | ✅ supported
proven by `primitives`, `optional_and_arrays`, `type_refs` +18 more | +| enums
`enums` | ✅ supported
proven by `enum_basic` | +| optional fields
`optional-fields` | ✅ supported
proven by `optional_and_arrays`, `type_refs`, `shapes` +5 more | +| arrays
`arrays` | ✅ supported
proven by `optional_and_arrays`, `type_refs`, `shapes` +6 more | +| fixed-length arrays
`fixed-arrays` | 🟡 partial: rendered as `T[]`: the length isn't part of the type
proven by `shapes`, `large_fixed_arrays_nested` | +| fixed arrays over 32 elements, nested
`large-fixed-arrays-nested` | 🟡 partial: rendered as `T[]`: the length isn't part of the type
proven by `large_fixed_arrays_nested` | +| unions
`unions` | ✅ supported
proven by `unions` | +| type aliases
`type-aliases` | ✅ supported
proven by `validators`, `validators_on_decode`, `unions` +1 more | +| constants
`constants` | ✅ supported
proven by `constant`, `shapes`, `validators` +1 more | +| protocols
`protocols` | ✅ supported
proven by `protocol`, `error_shapes`, `validators` +14 more | +| errors
`errors` | ✅ supported
proven by `protocol`, `error_shapes`, `lockstep` +1 more | +| functions that throw
`throws` | ✅ supported
proven by `protocol`, `error_shapes`, `lockstep` +1 more | +| validators
`validators` | ⚪ ignored: the types are generated; the checks aren't run yet (core#96)
proven by `validators`, `validators_on_decode` | +| imports between schemas
`imports` | ✅ supported
proven by `cross_schema`, `import_alias`, `import_glob` +6 more | +| nested namespaces
`nested-namespaces` | ✅ supported
proven by `nested_namespace`, `external_std`, `validators` +4 more | +| `lib` mode
`lib-mode` | ✅ supported
proven by `nested_namespace`, `external_std` | +| `external_std`
`external-std` | ✅ supported
proven by `external_std` | +| `validate_on_decode`
`validate-on-decode` | ⚪ ignored: no checks are generated to run on decode yet (core#96)
proven by `validators_on_decode` | +| JSON-RPC framing
`framing-jsonrpc` | ✅ supported
proven by `framing_jsonrpc`, `connections_jsonrpc` | +| no handshake
`handshake-none` | ✅ supported
proven by `handshake_none` | +| `datagram@3` framing
`framing-datagram3` | ✅ supported
proven by `framing_datagram3`, `handshake_comline2`, `connections_default` +3 more | +| `comline@2` handshake
`handshake-comline2` | ✅ supported
proven by `handshake_comline2`, `connections_default`, `dependency_protocol` +2 more | +| connections
`connections` | ✅ supported
proven by `protocol`, `error_shapes`, `validators` +12 more | +| `async`
`async` | ⚪ ignored: handlers and senders always return Promises: the output is async either way
proven by `connections_async` | +| the `packed@1` format
`format-packed` | ✅ supported
proven by `protocol`, `error_shapes`, `validators` +11 more | +| the `json@1` format
`format-json` | ✅ supported
proven by `format_json` | +| the `msgpack@1` format
`format-msgpack` | ❌ unsupported: `@comline/runtime` has no MessagePack codec yet
proven by `format_msgpack` | +| bounds
`bounds` | ✅ supported
proven by `bounds` | +| single characters
`chars` | ✅ supported
proven by `chars` | diff --git a/README.md b/README.md index 20c252a..f75e0bf 100644 --- a/README.md +++ b/README.md @@ -55,12 +55,14 @@ cd runtime && npm ci && npm test ## Features What this generator implements, feature by feature. Each claim is checked by -the conformance suite in [`ComlineProject/generation`](https://github.com/ComlineProject/generation): +`codegen/tests/conformance.rs`, which runs the conformance corpus of +[`ComlineProject/generation`](https://github.com/ComlineProject/generation) +over this generator, against the goldens in `codegen/tests/golden/`: a supported feature has a fixture that generates and matches its golden output, an ignored one generates exactly what it would without the feature, and an unsupported one is refused with an error naming every use. The full matrix, -with the fixtures that prove each claim, is in -[`FEATURES.md`](https://github.com/ComlineProject/generation/blob/master/FEATURES.md). +with the fixtures that prove each claim, is in [`FEATURES.md`](FEATURES.md) +(also as [`features.json`](features.json)), which that run writes. diff --git a/codegen/Cargo.toml b/codegen/Cargo.toml index 84290c1..662a7b9 100644 --- a/codegen/Cargo.toml +++ b/codegen/Cargo.toml @@ -8,7 +8,7 @@ license = "GPL-3.0-only" # Consumed by git rev (see ComlineProject/docs → Design → Runtime & generation # repository structure — no crates.io publishing at this stage). Local # iteration: add a `[patch]` onto a sibling checkout. -comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "e900919375429591d73c906380f1d354d636ab22" } +comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "31e808ff05632acbfa4f48d208b8d5a2fbca3b0e" } comline-core = { git = "https://github.com/ComlineProject/core", rev = "69039e7ab05953760bb7a6818f61e98c14b43922", default-features = false } eyre = "0.6.8" @@ -18,9 +18,10 @@ name = "comline-gen-typescript" path = "src/bin/comline-gen-typescript.rs" [dev-dependencies] -# The conformance corpus: every fixture is a whole package. Same generation -# rev as `comline-codegen` above, so the corpus and the generator share one -# `comline-codegen`. -comline-conformance = { git = "https://github.com/ComlineProject/generation", rev = "e900919375429591d73c906380f1d354d636ab22" } +# The conformance corpus and the harness that runs this generator over it +# (`tests/conformance.rs`, against `tests/golden/`): every fixture is a whole +# package. Same generation rev as `comline-codegen` above, so the corpus and +# the generator share one `comline-codegen`. +comline-conformance = { git = "https://github.com/ComlineProject/generation", rev = "31e808ff05632acbfa4f48d208b8d5a2fbca3b0e" } # The tests compile schemas, so they need core's compiler. comline-core = { git = "https://github.com/ComlineProject/core", rev = "69039e7ab05953760bb7a6818f61e98c14b43922" } diff --git a/codegen/tests/conformance.rs b/codegen/tests/conformance.rs new file mode 100644 index 0000000..b90bffe --- /dev/null +++ b/codegen/tests/conformance.rs @@ -0,0 +1,46 @@ +//! The conformance corpus (`comline-conformance`, in ComlineProject/generation) +//! run over this generator: its output for every fixture, at each of its +//! version boundaries, against the goldens under `tests/golden/`; the +//! generator protocol round trip; and the proof of every claim in `SUPPORT`, +//! with the report `FEATURES.md` and `features.json` at the repository root. +//! Regenerate the goldens and the report with: +//! +//! ```text +//! CONFORMANCE_BLESS=1 cargo test -p comline-codegen-typescript --test conformance +//! ``` +//! +//! A blessed golden is a snapshot of what the generator does now: a diff in +//! one is a change to what it emits, to be read as one. + +use std::path::Path; + +use comline_conformance::harness::{self, Generator}; + +const GENERATOR: Generator = Generator { + language: "typescript", + generate: comline_codegen_typescript::generate_typescript, + register: comline_codegen_typescript::register, + support: comline_codegen_typescript::SUPPORT, + versions: comline_codegen_typescript::VERSIONS, +}; + +#[test] +fn the_protocol_generates_what_the_generator_does() { + harness::the_protocol_generates_what_the_generator_does(&GENERATOR); +} + +#[test] +fn corpus_matches_golden() { + harness::corpus_matches_golden( + &GENERATOR, + &Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/golden"), + ); +} + +#[test] +fn support_is_proven() { + harness::support_is_proven( + &GENERATOR, + &Path::new(env!("CARGO_MANIFEST_DIR")).join(".."), + ); +} diff --git a/codegen/tests/golden/bounds/typescript/conformance.ts b/codegen/tests/golden/bounds/typescript/conformance.ts new file mode 100644 index 0000000..b657373 --- /dev/null +++ b/codegen/tests/golden/bounds/typescript/conformance.ts @@ -0,0 +1,35 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { checkChars, type Layout } from "@comline/runtime"; + +/** A string of at most 32 characters: make one with `Name.from`. */ +export type Name = string & { readonly __brand: "Name" }; + +export const NameLayout: Layout = { chars: { max: 32 } }; + +export const Name = { + /** `value` as a `Name`; throws a `RuntimeError` unless it holds at most 32 characters. */ + from(value: string): Name { + checkChars(value, 32); + return value as Name; + }, +}; + +export interface Customer { + name: Name; + country: string; + email?: string; + tags: string[]; + scores: number[]; +} + +export const CustomerLayout: Layout = { struct: [["name", () => NameLayout], ["country", { chars: { length: 2 } }], ["email", { option: { chars: { max: 254 } } }], ["tags", { array: { chars: { max: 16 } }, max: 8 }], ["scores", { array: "u32", max: 10 }]] }; + +export interface Node { + label: string; + children: Node[]; +} + +export const NodeLayout: Layout = { depth: 16, of: { struct: [["label", { chars: { max: 64 } }], ["children", { array: () => NodeLayout, max: 4 }]] } }; + diff --git a/codegen/tests/golden/chars/typescript/conformance.ts b/codegen/tests/golden/chars/typescript/conformance.ts new file mode 100644 index 0000000..d81dea9 --- /dev/null +++ b/codegen/tests/golden/chars/typescript/conformance.ts @@ -0,0 +1,11 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +export interface Grade { + letter: string; +} + +export const GradeLayout: Layout = { struct: [["letter", "char"]] }; + diff --git a/codegen/tests/golden/connections/typescript/conformance.ts b/codegen/tests/golden/connections/typescript/conformance.ts new file mode 100644 index 0000000..814c58c --- /dev/null +++ b/codegen/tests/golden/connections/typescript/conformance.ts @@ -0,0 +1,184 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + RuntimeError, + resolveKind, + type Codec, + type Connection, + type Dispatch, + type Kind, + type Layout, + type Peer, + type Reply, +} from "@comline/runtime"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 0xb97e34b203ec1425n; + +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; + + private readonly impl: Chat; + + constructor(impl: Chat) { + this.impl = impl; + } + + calls(): readonly string[] { + return CHAT_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch (resolveKind(call, CHAT_CALLS)) { + case 0: { + try { + const p = codec.decode(params, ChatSendParamsLayout); + reply.ok(codec.encode((await this.impl.send(peer, p)) ?? null, "u32")); + } catch { + reply.fault(); + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** 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); + } +} + +/** Calls protocol `Chat` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class ChatSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async send(params: ChatSendParams): Promise { + const env = await this.peer.call(ChatSender.PROTOCOL, { id: 0, name: "send" }, params, { layout: ChatSendParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "u32"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } +} + +export interface EventsShownParams { + n: number; +} + +/** @internal */ +export const EventsShownParamsLayout: Layout = { struct: [["n", "u32"]] }; + +export interface Events { + shown(peer: Peer, params: EventsShownParams): Promise; + 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; + + private readonly impl: Events; + + constructor(impl: Events) { + this.impl = impl; + } + + calls(): readonly string[] { + return EVENTS_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch (resolveKind(call, EVENTS_CALLS)) { + case 0: { + try { + const p = codec.decode(params, EventsShownParamsLayout); + reply.ok(codec.encode((await this.impl.shown(peer, p)) ?? null, "bool")); + } catch { + reply.fault(); + } + return; + } + case 1: { + try { + await this.impl.ping(peer); + } catch { + /* one-way: nowhere to report this */ + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** 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); + } +} + +/** Calls protocol `Events` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class EventsSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 1; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async shown(params: EventsShownParams): Promise { + const env = await this.peer.call(EventsSender.PROTOCOL, { id: 0, name: "shown" }, params, { layout: EventsShownParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "bool"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } + + async ping(): Promise { + await this.peer.notify(EventsSender.PROTOCOL, { id: 1, name: "ping" }, null, { layout: "unit" }); + } +} + diff --git a/codegen/tests/golden/connections/typescript/connection.ts b/codegen/tests/golden/connections/typescript/connection.ts new file mode 100644 index 0000000..18b3931 --- /dev/null +++ b/codegen/tests/golden/connections/typescript/connection.ts @@ -0,0 +1,77 @@ +// 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, + 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 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. + * @internal + */ +export function provideServices(conn: Connection, services: Services): void { + new ns_conformance.ChatDispatcher(services.chat).provideOn(conn); +} + +/** What the dialling side provides: one field per protocol, so leaving one out doesn't type-check. */ +export interface ClientServices { + events: ns_conformance.Events; +} + +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ +export function provideClientServices(conn: Connection, services: ClientServices): void { + new ns_conformance.EventsDispatcher(services.events).provideOn(conn); +} + +/** +* Accept a connection over `transport`: run the handshake, then provide +* every protocol in `services` on it. The connection comes back serving, +* so the server can call the client through it. +*/ +export async function accept(transport: Transport, services: Services): Promise { + const conn = await Connection.accept(transport, Format, CONNECTION_IR_HASH); + provideServices(conn, services); + return conn; +} + +/** {@link accept}, then serve every call until the peer leaves. */ +export async function serve(transport: Transport, services: Services): Promise { + await (await accept(transport, services)).closed; +} + +/** +* Dial over `transport`: run the handshake, then provide every protocol in +* `services`, which the server calls. Call the server's protocols through +* their senders. +*/ +export async function connect(transport: Transport, services: ClientServices): Promise { + const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH); + provideClientServices(conn, services); + return conn; +} diff --git a/codegen/tests/golden/connections/typescript/wire.ts b/codegen/tests/golden/connections/typescript/wire.ts new file mode 100644 index 0000000..351fa7f --- /dev/null +++ b/codegen/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/codegen/tests/golden/connections_async/typescript/conformance.ts b/codegen/tests/golden/connections_async/typescript/conformance.ts new file mode 100644 index 0000000..814c58c --- /dev/null +++ b/codegen/tests/golden/connections_async/typescript/conformance.ts @@ -0,0 +1,184 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + RuntimeError, + resolveKind, + type Codec, + type Connection, + type Dispatch, + type Kind, + type Layout, + type Peer, + type Reply, +} from "@comline/runtime"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 0xb97e34b203ec1425n; + +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; + + private readonly impl: Chat; + + constructor(impl: Chat) { + this.impl = impl; + } + + calls(): readonly string[] { + return CHAT_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch (resolveKind(call, CHAT_CALLS)) { + case 0: { + try { + const p = codec.decode(params, ChatSendParamsLayout); + reply.ok(codec.encode((await this.impl.send(peer, p)) ?? null, "u32")); + } catch { + reply.fault(); + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** 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); + } +} + +/** Calls protocol `Chat` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class ChatSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async send(params: ChatSendParams): Promise { + const env = await this.peer.call(ChatSender.PROTOCOL, { id: 0, name: "send" }, params, { layout: ChatSendParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "u32"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } +} + +export interface EventsShownParams { + n: number; +} + +/** @internal */ +export const EventsShownParamsLayout: Layout = { struct: [["n", "u32"]] }; + +export interface Events { + shown(peer: Peer, params: EventsShownParams): Promise; + 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; + + private readonly impl: Events; + + constructor(impl: Events) { + this.impl = impl; + } + + calls(): readonly string[] { + return EVENTS_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch (resolveKind(call, EVENTS_CALLS)) { + case 0: { + try { + const p = codec.decode(params, EventsShownParamsLayout); + reply.ok(codec.encode((await this.impl.shown(peer, p)) ?? null, "bool")); + } catch { + reply.fault(); + } + return; + } + case 1: { + try { + await this.impl.ping(peer); + } catch { + /* one-way: nowhere to report this */ + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** 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); + } +} + +/** Calls protocol `Events` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class EventsSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 1; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async shown(params: EventsShownParams): Promise { + const env = await this.peer.call(EventsSender.PROTOCOL, { id: 0, name: "shown" }, params, { layout: EventsShownParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "bool"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } + + async ping(): Promise { + await this.peer.notify(EventsSender.PROTOCOL, { id: 1, name: "ping" }, null, { layout: "unit" }); + } +} + diff --git a/codegen/tests/golden/connections_async/typescript/connection.ts b/codegen/tests/golden/connections_async/typescript/connection.ts new file mode 100644 index 0000000..18b3931 --- /dev/null +++ b/codegen/tests/golden/connections_async/typescript/connection.ts @@ -0,0 +1,77 @@ +// 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, + 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 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. + * @internal + */ +export function provideServices(conn: Connection, services: Services): void { + new ns_conformance.ChatDispatcher(services.chat).provideOn(conn); +} + +/** What the dialling side provides: one field per protocol, so leaving one out doesn't type-check. */ +export interface ClientServices { + events: ns_conformance.Events; +} + +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ +export function provideClientServices(conn: Connection, services: ClientServices): void { + new ns_conformance.EventsDispatcher(services.events).provideOn(conn); +} + +/** +* Accept a connection over `transport`: run the handshake, then provide +* every protocol in `services` on it. The connection comes back serving, +* so the server can call the client through it. +*/ +export async function accept(transport: Transport, services: Services): Promise { + const conn = await Connection.accept(transport, Format, CONNECTION_IR_HASH); + provideServices(conn, services); + return conn; +} + +/** {@link accept}, then serve every call until the peer leaves. */ +export async function serve(transport: Transport, services: Services): Promise { + await (await accept(transport, services)).closed; +} + +/** +* Dial over `transport`: run the handshake, then provide every protocol in +* `services`, which the server calls. Call the server's protocols through +* their senders. +*/ +export async function connect(transport: Transport, services: ClientServices): Promise { + const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH); + provideClientServices(conn, services); + return conn; +} diff --git a/codegen/tests/golden/connections_async/typescript/wire.ts b/codegen/tests/golden/connections_async/typescript/wire.ts new file mode 100644 index 0000000..351fa7f --- /dev/null +++ b/codegen/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/codegen/tests/golden/connections_default/typescript/conformance.ts b/codegen/tests/golden/connections_default/typescript/conformance.ts new file mode 100644 index 0000000..6e963a2 --- /dev/null +++ b/codegen/tests/golden/connections_default/typescript/conformance.ts @@ -0,0 +1,188 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + RuntimeError, + resolveKind, + checkCall, + type Codec, + type Connection, + type Dispatch, + type Kind, + type Layout, + type Peer, + type Reply, +} from "@comline/runtime"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 0x1ad273c98d4e98fbn; + +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; + + private readonly impl: Chat; + + constructor(impl: Chat) { + this.impl = impl; + } + + calls(): readonly string[] { + return CHAT_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch ("id" in call ? call.id : -1) { + case 0: { + try { + const p = codec.decode(params, ChatSendParamsLayout); + reply.ok(codec.encode((await this.impl.send(peer, p)) ?? null, "u32")); + } catch { + reply.fault(); + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with the package's `accept` / `connect`, which run `comline@2` with this package's facts, or let the package's `serve` / `connect` do it. */ + provideOn(conn: Connection): void { + conn.provide(ChatDispatcher.PROTOCOL, this); + } +} + +/** Calls protocol `Chat` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class ChatSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async send(params: ChatSendParams): Promise { + checkCall(this.peer, ChatSender.PROTOCOL, 0, "conformance::Chat", "send"); + const env = await this.peer.call(ChatSender.PROTOCOL, { id: 0, name: "send" }, params, { layout: ChatSendParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "u32"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } +} + +export interface EventsShownParams { + n: number; +} + +/** @internal */ +export const EventsShownParamsLayout: Layout = { struct: [["n", "u32"]] }; + +export interface Events { + shown(peer: Peer, params: EventsShownParams): Promise; + 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; + + private readonly impl: Events; + + constructor(impl: Events) { + this.impl = impl; + } + + calls(): readonly string[] { + return EVENTS_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch ("id" in call ? call.id : -1) { + case 1: { + try { + const p = codec.decode(params, EventsShownParamsLayout); + reply.ok(codec.encode((await this.impl.shown(peer, p)) ?? null, "bool")); + } catch { + reply.fault(); + } + return; + } + case 0: { + try { + await this.impl.ping(peer); + } catch { + /* one-way: nowhere to report this */ + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with the package's `accept` / `connect`, which run `comline@2` with this package's facts, or let the package's `serve` / `connect` do it. */ + provideOn(conn: Connection): void { + conn.provide(EventsDispatcher.PROTOCOL, this); + } +} + +/** Calls protocol `Events` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class EventsSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 1; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async shown(params: EventsShownParams): Promise { + checkCall(this.peer, EventsSender.PROTOCOL, 1, "conformance::Events", "shown"); + const env = await this.peer.call(EventsSender.PROTOCOL, { id: 1, name: "shown" }, params, { layout: EventsShownParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "bool"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } + + async ping(): Promise { + checkCall(this.peer, EventsSender.PROTOCOL, 0, "conformance::Events", "ping"); + await this.peer.notify(EventsSender.PROTOCOL, { id: 0, name: "ping" }, null, { layout: "unit" }); + } +} + diff --git a/codegen/tests/golden/connections_default/typescript/connection.ts b/codegen/tests/golden/connections_default/typescript/connection.ts new file mode 100644 index 0000000..64218a9 --- /dev/null +++ b/codegen/tests/golden/connections_default/typescript/connection.ts @@ -0,0 +1,137 @@ +// 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, + Datagram3Framing, + Comline2Handshake, + Negotiated, + 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 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` 0 + * - 1 `conformance::Events`, line 0.1.0: `shown` 1, `ping` 0 + * + * @internal + */ +export const HELLO = new Uint8Array([ + 0x43, 0x4f, 0x02, 0x01, 0x00, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, + 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x00, 0x01, 0x00, + 0x00, 0x03, 0x00, 0x52, 0x18, 0x5f, 0xd6, 0x09, 0x92, 0xad, 0x43, 0x02, + 0x9c, 0xc2, 0x99, 0x62, 0xb3, 0xaf, 0xb4, 0x01, 0x4e, 0x6e, 0xde, 0x7c, + 0xc8, 0xf5, 0xaa, 0x52, 0xce, 0x16, 0x9f, 0x9e, 0x65, 0x67, 0x40, 0xe2, + 0x02, 0x58, 0x80, 0x9a, 0xaf, 0x4b, 0x47, 0xd5, 0x6c, 0x69, 0xb2, 0xc1, + 0xfc, 0x9d, 0x43, 0x30, 0xc1, 0x02, 0x00, 0x00, 0x01, 0x00, 0x5a, 0x5a, + 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, + 0x5a, 0x5a, 0x01, 0x00, 0x01, 0x00, 0x01, 0x00, 0x5a, 0x5a, 0x5a, 0x5a, + 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, + 0x02, 0x00, 0x01, +]); + +/** + * The `comline@2` handshake, with {@link HELLO} and the parameters the package states. + * @internal + */ +export function handshake(): Comline2Handshake { + return new Comline2Handshake(HELLO, { + scope: "protocol", + newerConsumer: "degrade", + sameVersionDiffers: "refuse", + exchange: "offer", + }); +} + +/** The package's protocols on the connection, by wire number. */ +const PROTOCOLS = new Map([[0, "conformance::Chat"], [1, "conformance::Events"]]); + +/** What the connection's `comline@2` handshake agreed, if `accept` / `connect` opened it. */ +export function negotiated(conn: Peer): Negotiated | undefined { + return conn.extensions.get(Negotiated); +} + +/** + * The protocols that connected although their wire shape differs from the + * peer's at the same version (`same_version_differs = warn`), by path. + */ +export function warnings(conn: Peer): string[] { + return (negotiated(conn)?.warnings ?? []).map((n) => PROTOCOLS.get(n) ?? `#${n}`); +} + +/** 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. + * @internal + */ +export function provideServices(conn: Connection, services: Services): void { + new ns_conformance.ChatDispatcher(services.chat).provideOn(conn); +} + +/** What the dialling side provides: one field per protocol, so leaving one out doesn't type-check. */ +export interface ClientServices { + events: ns_conformance.Events; +} + +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ +export function provideClientServices(conn: Connection, services: ClientServices): void { + new ns_conformance.EventsDispatcher(services.events).provideOn(conn); +} + +/** +* Accept a connection over `transport`: run the handshake, then provide +* every protocol in `services` on it. The connection comes back serving, +* so the server can call the client through it. +*/ +export async function accept(transport: Transport, services: Services): Promise { + const agreed = handshake(); + const conn = await Connection.accept(transport, Format, CONNECTION_IR_HASH, new Datagram3Framing(), agreed); + conn.extensions.set(agreed.negotiated!); + provideServices(conn, services); + return conn; +} + +/** {@link accept}, then serve every call until the peer leaves. */ +export async function serve(transport: Transport, services: Services): Promise { + await (await accept(transport, services)).closed; +} + +/** +* Dial over `transport`: run the handshake, then provide every protocol in +* `services`, which the server calls. Call the server's protocols through +* their senders. +*/ +export async function connect(transport: Transport, services: ClientServices): Promise { + const agreed = handshake(); + const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH, new Datagram3Framing(), agreed); + conn.extensions.set(agreed.negotiated!); + provideClientServices(conn, services); + return conn; +} diff --git a/codegen/tests/golden/connections_default/typescript/wire.ts b/codegen/tests/golden/connections_default/typescript/wire.ts new file mode 100644 index 0000000..7629bc6 --- /dev/null +++ b/codegen/tests/golden/connections_default/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 = 0x1ad273c98d4e98fbn; diff --git a/codegen/tests/golden/connections_jsonrpc/typescript/conformance.ts b/codegen/tests/golden/connections_jsonrpc/typescript/conformance.ts new file mode 100644 index 0000000..d68215a --- /dev/null +++ b/codegen/tests/golden/connections_jsonrpc/typescript/conformance.ts @@ -0,0 +1,184 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + RuntimeError, + resolveKind, + type Codec, + type Connection, + type Dispatch, + type Kind, + type Layout, + type Peer, + type Reply, +} from "@comline/runtime"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 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; + + private readonly impl: Chat; + + constructor(impl: Chat) { + this.impl = impl; + } + + calls(): readonly string[] { + return CHAT_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch (resolveKind(call, CHAT_CALLS)) { + case 0: { + try { + const p = codec.decode(params, ChatSendParamsLayout); + reply.ok(codec.encode((await this.impl.send(peer, p)) ?? null, "u32")); + } catch { + reply.fault(); + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** 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); + } +} + +/** Calls protocol `Chat` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class ChatSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async send(params: ChatSendParams): Promise { + const env = await this.peer.call(ChatSender.PROTOCOL, { id: 0, name: "send" }, params, { layout: ChatSendParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "u32"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } +} + +export interface EventsShownParams { + n: number; +} + +/** @internal */ +export const EventsShownParamsLayout: Layout = { struct: [["n", "u32"]] }; + +export interface Events { + shown(peer: Peer, params: EventsShownParams): Promise; + 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; + + private readonly impl: Events; + + constructor(impl: Events) { + this.impl = impl; + } + + calls(): readonly string[] { + return EVENTS_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch (resolveKind(call, EVENTS_CALLS)) { + case 0: { + try { + const p = codec.decode(params, EventsShownParamsLayout); + reply.ok(codec.encode((await this.impl.shown(peer, p)) ?? null, "bool")); + } catch { + reply.fault(); + } + return; + } + case 1: { + try { + await this.impl.ping(peer); + } catch { + /* one-way: nowhere to report this */ + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** 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); + } +} + +/** Calls protocol `Events` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class EventsSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 1; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async shown(params: EventsShownParams): Promise { + const env = await this.peer.call(EventsSender.PROTOCOL, { id: 0, name: "conformance.Events/shown" }, params, { layout: EventsShownParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "bool"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } + + async ping(): Promise { + await this.peer.notify(EventsSender.PROTOCOL, { id: 1, name: "conformance.Events/ping" }, null, { layout: "unit" }); + } +} + diff --git a/codegen/tests/golden/connections_jsonrpc/typescript/connection.ts b/codegen/tests/golden/connections_jsonrpc/typescript/connection.ts new file mode 100644 index 0000000..c6942d9 --- /dev/null +++ b/codegen/tests/golden/connections_jsonrpc/typescript/connection.ts @@ -0,0 +1,79 @@ +// 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, + type Transport, +} from "@comline/runtime"; +import * as ns_conformance from "./conformance.js"; +import { CONNECTION_IR_HASH } from "./wire.js"; + +/** The package's wire format and the digest of every schema in it, which every file of the package shares. */ +export { CONNECTION_IR_HASH, Format } from "./wire.js"; + +/** What the accepting side provides: one field per protocol, so leaving one out doesn't type-check. */ +export interface Services { + chat: ns_conformance.Chat; +} + +/** + * 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); +} + +/** What the dialling side provides: one field per protocol, so leaving one out doesn't type-check. */ +export interface ClientServices { + events: ns_conformance.Events; +} + +/** + * Provide every protocol in `services` on `conn`: the peer's calls to them come here. + * @internal + */ +export function provideClientServices(conn: Connection, services: ClientServices): void { + new ns_conformance.EventsDispatcher(services.events).provideOn(conn); +} + +/** +* Accept a connection over `transport`: run the handshake, then provide +* every protocol in `services` on it. The connection comes back serving, +* so the server can call the client through it. +*/ +export async function accept(transport: Transport, services: Services): Promise { + const conn = await Connection.accept(transport, new JsonCodec(), CONNECTION_IR_HASH, new JsonRpcConnectionFraming()); + provideServices(conn, services); + return conn; +} + +/** {@link accept}, then serve every call until the peer leaves. */ +export async function serve(transport: Transport, services: Services): Promise { + await (await accept(transport, services)).closed; +} + +/** +* Dial over `transport`: run the handshake, then provide every protocol in +* `services`, which the server calls. Call the server's protocols through +* their senders. +*/ +export async function connect(transport: Transport, services: ClientServices): Promise { + const conn = await Connection.connect(transport, new JsonCodec(), CONNECTION_IR_HASH, new JsonRpcConnectionFraming()); + provideClientServices(conn, services); + return conn; +} diff --git a/codegen/tests/golden/connections_jsonrpc/typescript/wire.ts b/codegen/tests/golden/connections_jsonrpc/typescript/wire.ts new file mode 100644 index 0000000..4e964de --- /dev/null +++ b/codegen/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/codegen/tests/golden/constant/typescript/conformance.ts b/codegen/tests/golden/constant/typescript/conformance.ts new file mode 100644 index 0000000..649c7df --- /dev/null +++ b/codegen/tests/golden/constant/typescript/conformance.ts @@ -0,0 +1,5 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +export const MAX_RETRIES = 5; + diff --git a/codegen/tests/golden/cross_schema/typescript/api.ts b/codegen/tests/golden/cross_schema/typescript/api.ts new file mode 100644 index 0000000..c829ad2 --- /dev/null +++ b/codegen/tests/golden/cross_schema/typescript/api.ts @@ -0,0 +1,16 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +import { SharedLayout } from "./shared.js"; +import type { Shared } from "./shared.js"; + +export interface Holder { + one: Shared; + maybe?: Shared; + list: Shared[]; +} + +export const HolderLayout: Layout = { struct: [["one", () => SharedLayout], ["maybe", { option: () => SharedLayout }], ["list", { array: () => SharedLayout }]] }; + diff --git a/codegen/tests/golden/cross_schema/typescript/shared.ts b/codegen/tests/golden/cross_schema/typescript/shared.ts new file mode 100644 index 0000000..362c34d --- /dev/null +++ b/codegen/tests/golden/cross_schema/typescript/shared.ts @@ -0,0 +1,11 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +export interface Shared { + value: number; +} + +export const SharedLayout: Layout = { struct: [["value", "s32"]] }; + diff --git a/codegen/tests/golden/dependency_and_own_protocols/typescript/api.ts b/codegen/tests/golden/dependency_and_own_protocols/typescript/api.ts new file mode 100644 index 0000000..2b606ed --- /dev/null +++ b/codegen/tests/golden/dependency_and_own_protocols/typescript/api.ts @@ -0,0 +1,106 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + RuntimeError, + resolveKind, + checkCall, + type Codec, + type Connection, + type Dispatch, + type Kind, + type Layout, + type Peer, + type Reply, +} from "@comline/runtime"; + +import { GreetingLayout } from "./localdeps/greeting.js"; +import type { Greeting } from "./localdeps/greeting.js"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 0x25f4c4d936e7aa90n; + +export interface Message { + greeting: Greeting; +} + +export const MessageLayout: Layout = { struct: [["greeting", () => GreetingLayout]] }; + +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; + + private readonly impl: Chat; + + constructor(impl: Chat) { + this.impl = impl; + } + + calls(): readonly string[] { + return CHAT_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch ("id" in call ? call.id : -1) { + case 0: { + try { + const p = codec.decode(params, ChatGreetParamsLayout); + reply.ok(codec.encode((await this.impl.greet(peer, p)) ?? null, "u32")); + } catch { + reply.fault(); + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with the package's `accept` / `connect`, which run `comline@2` with this package's facts, or let the package's `serve` / `connect` do it. */ + provideOn(conn: Connection): void { + conn.provide(ChatDispatcher.PROTOCOL, this); + } +} + +/** Calls protocol `Chat` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class ChatSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async greet(params: ChatGreetParams): Promise { + checkCall(this.peer, ChatSender.PROTOCOL, 0, "api::Chat", "greet"); + const env = await this.peer.call(ChatSender.PROTOCOL, { id: 0, name: "greet" }, params, { layout: ChatGreetParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "u32"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } +} + diff --git a/codegen/tests/golden/dependency_and_own_protocols/typescript/connection.ts b/codegen/tests/golden/dependency_and_own_protocols/typescript/connection.ts new file mode 100644 index 0000000..7f6dd4c --- /dev/null +++ b/codegen/tests/golden/dependency_and_own_protocols/typescript/connection.ts @@ -0,0 +1,119 @@ +// 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, + Comline2Handshake, + Negotiated, + 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 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, + 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x00, 0x01, 0x00, + 0x00, 0x03, 0x00, 0x52, 0x18, 0x5f, 0xd6, 0x09, 0x92, 0xad, 0x43, 0x02, + 0x9c, 0xc2, 0x99, 0x62, 0xb3, 0xaf, 0xb4, 0x01, 0x4e, 0x6e, 0xde, 0x7c, + 0xc8, 0xf5, 0xaa, 0x52, 0xce, 0x16, 0x9f, 0x9e, 0x65, 0x67, 0x40, 0xe2, + 0x02, 0x58, 0x80, 0x9a, 0xaf, 0x4b, 0x47, 0xd5, 0x6c, 0x69, 0xb2, 0xc1, + 0xfc, 0x9d, 0x43, 0x30, 0xc1, 0x01, 0x00, 0x00, 0x01, 0x00, 0x5a, 0x5a, + 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, + 0x5a, 0x5a, 0x01, 0x00, +]); + +/** + * The `comline@2` handshake, with {@link HELLO} and the parameters the package states. + * @internal + */ +export function handshake(): Comline2Handshake { + return new Comline2Handshake(HELLO, { + scope: "protocol", + newerConsumer: "degrade", + sameVersionDiffers: "refuse", + exchange: "offer", + }); +} + +/** The package's protocols on the connection, by wire number. */ +const PROTOCOLS = new Map([[0, "api::Chat"]]); + +/** What the connection's `comline@2` handshake agreed, if `accept` / `connect` opened it. */ +export function negotiated(conn: Peer): Negotiated | undefined { + return conn.extensions.get(Negotiated); +} + +/** + * The protocols that connected although their wire shape differs from the + * peer's at the same version (`same_version_differs = warn`), by path. + */ +export function warnings(conn: Peer): string[] { + return (negotiated(conn)?.warnings ?? []).map((n) => PROTOCOLS.get(n) ?? `#${n}`); +} + +/** What the accepting side provides: one field per protocol, so leaving one out doesn't type-check. */ +export interface Services { + chat: ns_api.Chat; +} + +/** + * 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); +} + +/** +* Accept a connection over `transport`: run the handshake, then provide +* every protocol in `services` on it. The connection comes back serving, +* so the server can call the client through it. +*/ +export async function accept(transport: Transport, services: Services): Promise { + const agreed = handshake(); + const conn = await Connection.accept(transport, Format, CONNECTION_IR_HASH, new Datagram3Framing(), agreed); + conn.extensions.set(agreed.negotiated!); + provideServices(conn, services); + return conn; +} + +/** {@link accept}, then serve every call until the peer leaves. */ +export async function serve(transport: Transport, services: Services): Promise { + await (await accept(transport, services)).closed; +} + +/** +* Dial over `transport`: run the handshake. Call the server's protocols +* through their senders. +*/ +export async function connect(transport: Transport): Promise { + const agreed = handshake(); + const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH, new Datagram3Framing(), agreed); + conn.extensions.set(agreed.negotiated!); + return conn; +} diff --git a/codegen/tests/golden/dependency_and_own_protocols/typescript/localdeps/greeting.ts b/codegen/tests/golden/dependency_and_own_protocols/typescript/localdeps/greeting.ts new file mode 100644 index 0000000..66fc420 --- /dev/null +++ b/codegen/tests/golden/dependency_and_own_protocols/typescript/localdeps/greeting.ts @@ -0,0 +1,100 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + RuntimeError, + resolveKind, + type Codec, + type Connection, + type Dispatch, + type Kind, + type Layout, + type Peer, + type Reply, +} from "@comline/runtime"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 0x653ed335b8ab7ba0n; + +export interface Greeting { + text: string; +} + +export const GreetingLayout: Layout = { struct: [["text", "string"]] }; + +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 { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly impl: Foo; + + constructor(impl: Foo) { + this.impl = impl; + } + + calls(): readonly string[] { + return FOO_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch ("id" in call ? call.id : -1) { + case 0: { + try { + const p = codec.decode(params, FooGreetParamsLayout); + reply.ok(codec.encode((await this.impl.greet(peer, p)) ?? null, "u32")); + } catch { + reply.fault(); + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** 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); + } +} + +/** Calls protocol `Foo` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class FooSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async greet(params: FooGreetParams): Promise { + const env = await this.peer.call(FooSender.PROTOCOL, { id: 0, name: "greet" }, params, { layout: FooGreetParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "u32"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } +} + diff --git a/codegen/tests/golden/dependency_and_own_protocols/typescript/wire.ts b/codegen/tests/golden/dependency_and_own_protocols/typescript/wire.ts new file mode 100644 index 0000000..bf972a3 --- /dev/null +++ b/codegen/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/codegen/tests/golden/dependency_protocol/typescript/api.ts b/codegen/tests/golden/dependency_protocol/typescript/api.ts new file mode 100644 index 0000000..35d787a --- /dev/null +++ b/codegen/tests/golden/dependency_protocol/typescript/api.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +import { GreetingLayout } from "./localdeps/greeting.js"; +import type { Greeting } from "./localdeps/greeting.js"; + +export interface Message { + greeting: Greeting; +} + +export const MessageLayout: Layout = { struct: [["greeting", () => GreetingLayout]] }; + diff --git a/codegen/tests/golden/dependency_protocol/typescript/localdeps/greeting.ts b/codegen/tests/golden/dependency_protocol/typescript/localdeps/greeting.ts new file mode 100644 index 0000000..643f01d --- /dev/null +++ b/codegen/tests/golden/dependency_protocol/typescript/localdeps/greeting.ts @@ -0,0 +1,109 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + RuntimeError, + resolveKind, + PackedCodec, + type Codec, + type Connection, + type Dispatch, + type Kind, + type Layout, + type Peer, + type Reply, +} from "@comline/runtime"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 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 = 0xc1fed94bf808faean; + +/** 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; +} + +export const GreetingLayout: Layout = { struct: [["text", "string"]] }; + +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 { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly impl: Foo; + + constructor(impl: Foo) { + this.impl = impl; + } + + calls(): readonly string[] { + return FOO_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch ("id" in call ? call.id : -1) { + case 0: { + try { + const p = codec.decode(params, FooGreetParamsLayout); + reply.ok(codec.encode((await this.impl.greet(peer, p)) ?? null, "u32")); + } catch { + reply.fault(); + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** 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. */ + provideOn(conn: Connection): void { + conn.provide(FooDispatcher.PROTOCOL, this); + } +} + +/** Calls protocol `Foo` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class FooSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async greet(params: FooGreetParams): Promise { + const env = await this.peer.call(FooSender.PROTOCOL, { id: 0, name: "greet" }, params, { layout: FooGreetParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "u32"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } +} + diff --git a/codegen/tests/golden/enum_basic/typescript/conformance.ts b/codegen/tests/golden/enum_basic/typescript/conformance.ts new file mode 100644 index 0000000..3a104f0 --- /dev/null +++ b/codegen/tests/golden/enum_basic/typescript/conformance.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +export const State = { + Pending: "Pending", + Active: "Active", + Closed: "Closed", +} as const; +export type State = (typeof State)[keyof typeof State]; + +export const StateLayout: Layout = { enum: ["Pending", "Active", "Closed"] }; + diff --git a/codegen/tests/golden/error_shapes/typescript/conformance.ts b/codegen/tests/golden/error_shapes/typescript/conformance.ts new file mode 100644 index 0000000..3963fca --- /dev/null +++ b/codegen/tests/golden/error_shapes/typescript/conformance.ts @@ -0,0 +1,217 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + RuntimeError, + resolveKind, + type Codec, + type Connection, + type Dispatch, + type Kind, + type Layout, + type Peer, + type Reply, +} from "@comline/runtime"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 0x6fc29e1014b9b9c8n; + +export interface TooLong { + limit: number; +} + +export const TooLongLayout: Layout = { struct: [["limit", "u32"]] }; + +export class TooLongError extends Error { + static readonly ordinal = 1; + readonly data: TooLong; + constructor(data: TooLong) { + super("TooLong"); + this.data = data; + this.name = "TooLongError"; + } +} + +export interface Denied { +} + +export const DeniedLayout: Layout = { struct: [] }; + +export class DeniedError extends Error { + static readonly ordinal = 2; + readonly data: Denied; + constructor(data: Denied) { + super("Denied"); + this.data = data; + this.name = "DeniedError"; + } +} + +export interface MultiSendParams { + body: string; +} + +/** @internal */ +export const MultiSendParamsLayout: Layout = { struct: [["body", "string"]] }; + +export interface Multi { + /** @throws {DeniedError | TooLongError} */ + 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; + + private readonly impl: Multi; + + constructor(impl: Multi) { + this.impl = impl; + } + + calls(): readonly string[] { + return MULTI_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch (resolveKind(call, MULTI_CALLS)) { + case 0: { + try { + const p = codec.decode(params, MultiSendParamsLayout); + reply.ok(codec.encode((await this.impl.send(peer, p)) ?? null, "u64")); + } catch (e) { + if (e instanceof DeniedError) { reply.err(DeniedError.ordinal, codec.encode(e.data, DeniedLayout)); return; } + if (e instanceof TooLongError) { reply.err(TooLongError.ordinal, codec.encode(e.data, TooLongLayout)); return; } + reply.fault(); + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** 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); + } +} + +/** Calls protocol `Multi` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class MultiSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async send(params: MultiSendParams): Promise { + const env = await this.peer.call(MultiSender.PROTOCOL, { id: 0, name: "send" }, params, { layout: MultiSendParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "u64"); + if ("fault" in env) throw RuntimeError.provider(); + switch (env.err.id) { + case DeniedError.ordinal: + throw new DeniedError(this.peer.codec.decode(env.err.body, DeniedLayout)); + case TooLongError.ordinal: + throw new TooLongError(this.peer.codec.decode(env.err.body, TooLongLayout)); + default: + throw RuntimeError.remote(env.err.id); + } + } +} + +export interface Quiet { + ping(peer: Peer): Promise; + 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; + + private readonly impl: Quiet; + + constructor(impl: Quiet) { + this.impl = impl; + } + + calls(): readonly string[] { + return QUIET_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch (resolveKind(call, QUIET_CALLS)) { + case 0: { + try { + reply.ok(codec.encode((await this.impl.ping(peer)) ?? null, "u64")); + } catch { + reply.fault(); + } + return; + } + case 1: { + try { + await this.impl.hush(peer); + } catch { + /* one-way: nowhere to report this */ + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** 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); + } +} + +/** Calls protocol `Quiet` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class QuietSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 1; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async ping(): Promise { + const env = await this.peer.call(QuietSender.PROTOCOL, { id: 0, name: "ping" }, null, { layout: "unit" }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "u64"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } + + async hush(): Promise { + await this.peer.notify(QuietSender.PROTOCOL, { id: 1, name: "hush" }, null, { layout: "unit" }); + } +} + diff --git a/codegen/tests/golden/error_shapes/typescript/connection.ts b/codegen/tests/golden/error_shapes/typescript/connection.ts new file mode 100644 index 0000000..7fb3179 --- /dev/null +++ b/codegen/tests/golden/error_shapes/typescript/connection.ts @@ -0,0 +1,64 @@ +// 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, + 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 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 { + multi: ns_conformance.Multi; + quiet: ns_conformance.Quiet; +} + +/** + * 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); +} + +/** +* Accept a connection over `transport`: run the handshake, then provide +* every protocol in `services` on it. The connection comes back serving, +* so the server can call the client through it. +*/ +export async function accept(transport: Transport, services: Services): Promise { + const conn = await Connection.accept(transport, Format, CONNECTION_IR_HASH); + provideServices(conn, services); + return conn; +} + +/** {@link accept}, then serve every call until the peer leaves. */ +export async function serve(transport: Transport, services: Services): Promise { + await (await accept(transport, services)).closed; +} + +/** +* Dial over `transport`: run the handshake. Call the server's protocols +* through their senders. +*/ +export async function connect(transport: Transport): Promise { + const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH); + return conn; +} diff --git a/codegen/tests/golden/error_shapes/typescript/wire.ts b/codegen/tests/golden/error_shapes/typescript/wire.ts new file mode 100644 index 0000000..a7aab5f --- /dev/null +++ b/codegen/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/codegen/tests/golden/external_std/typescript/package.json b/codegen/tests/golden/external_std/typescript/package.json new file mode 100644 index 0000000..1f36da5 --- /dev/null +++ b/codegen/tests/golden/external_std/typescript/package.json @@ -0,0 +1,33 @@ +{ + "name": "conformance", + "version": "0.0.0", + "type": "module", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + }, + "./*": { + "types": "./dist/*.d.ts", + "import": "./dist/*.js" + } + }, + "files": ["dist", "src"], + "scripts": { + "build": "tsc" + }, + "dependencies": { + "@comline/std": "^0.1.0" + }, + "peerDependencies": { + "@comline/runtime": "^0.1.0", + "typescript": ">=5.0" + }, + "peerDependenciesMeta": { + "@comline/runtime": { "optional": true }, + "typescript": { "optional": true } + }, + "devDependencies": { + "typescript": "^5.6.0" + } +} diff --git a/codegen/tests/golden/external_std/typescript/src/api.ts b/codegen/tests/golden/external_std/typescript/src/api.ts new file mode 100644 index 0000000..da338fa --- /dev/null +++ b/codegen/tests/golden/external_std/typescript/src/api.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +import { RequestLayout } from "@comline/std/http"; +import type { Request } from "@comline/std/http"; + +export interface Call { + request: Request; +} + +export const CallLayout: Layout = { struct: [["request", () => RequestLayout]] }; + diff --git a/codegen/tests/golden/external_std/typescript/src/index.ts b/codegen/tests/golden/external_std/typescript/src/index.ts new file mode 100644 index 0000000..da04339 --- /dev/null +++ b/codegen/tests/golden/external_std/typescript/src/index.ts @@ -0,0 +1,3 @@ +// Generated by Comline + +export * as api from "./api.js"; diff --git a/codegen/tests/golden/external_std/typescript/tsconfig.json b/codegen/tests/golden/external_std/typescript/tsconfig.json new file mode 100644 index 0000000..931f802 --- /dev/null +++ b/codegen/tests/golden/external_std/typescript/tsconfig.json @@ -0,0 +1,16 @@ +{ + "compilerOptions": { + "target": "ES2020", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "outDir": "dist", + "rootDir": "src", + "declaration": true, + "strict": true, + "exactOptionalPropertyTypes": true, + "noUncheckedIndexedAccess": true, + "verbatimModuleSyntax": true, + "skipLibCheck": true + }, + "include": ["src/**/*.ts"] +} diff --git a/codegen/tests/golden/format_json/typescript/conformance.ts b/codegen/tests/golden/format_json/typescript/conformance.ts new file mode 100644 index 0000000..cd34d80 --- /dev/null +++ b/codegen/tests/golden/format_json/typescript/conformance.ts @@ -0,0 +1,161 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + RuntimeError, + resolveKind, + type Codec, + type Connection, + type Dispatch, + type Kind, + type Layout, + type Peer, + type Reply, +} from "@comline/runtime"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 0x8ee00745c73a32b2n; + +export interface Record { + id: number; + name: string; +} + +export const RecordLayout: Layout = { struct: [["id", "s32"], ["name", "string"]] }; + +export interface NotFound { +} + +export const NotFoundLayout: Layout = { struct: [] }; + +export class NotFoundError extends Error { + static readonly ordinal = 0; + readonly data: NotFound; + constructor(data: NotFound) { + super("NotFound"); + this.data = data; + this.name = "NotFoundError"; + } +} + +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 { + /** @throws {NotFoundError} */ + lookup(peer: Peer, params: ServiceLookupParams): Promise; + count(peer: Peer): Promise; + 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; + + private readonly impl: Service; + + constructor(impl: Service) { + this.impl = impl; + } + + calls(): readonly string[] { + return SERVICE_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch (resolveKind(call, SERVICE_CALLS)) { + case 0: { + try { + const p = codec.decode(params, ServiceLookupParamsLayout); + reply.ok(codec.encode((await this.impl.lookup(peer, p)) ?? null, RecordLayout)); + } catch (e) { + if (e instanceof NotFoundError) { reply.err(NotFoundError.ordinal, codec.encode(e.data, NotFoundLayout)); return; } + reply.fault(); + } + return; + } + case 1: { + try { + reply.ok(codec.encode((await this.impl.count(peer)) ?? null, "u64")); + } catch { + reply.fault(); + } + return; + } + case 2: { + try { + const p = codec.decode(params, ServiceNotifyParamsLayout); + await this.impl.notify(peer, p); + } catch { + /* one-way: nowhere to report this */ + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** 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); + } +} + +/** Calls protocol `Service` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class ServiceSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async lookup(params: ServiceLookupParams): Promise { + const env = await this.peer.call(ServiceSender.PROTOCOL, { id: 0, name: "lookup" }, params, { layout: ServiceLookupParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, RecordLayout); + if ("fault" in env) throw RuntimeError.provider(); + switch (env.err.id) { + case NotFoundError.ordinal: + throw new NotFoundError(this.peer.codec.decode(env.err.body, NotFoundLayout)); + default: + throw RuntimeError.remote(env.err.id); + } + } + + async count(): Promise { + const env = await this.peer.call(ServiceSender.PROTOCOL, { id: 1, name: "count" }, null, { layout: "unit" }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "u64"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } + + async notify(params: ServiceNotifyParams): Promise { + await this.peer.notify(ServiceSender.PROTOCOL, { id: 2, name: "notify" }, params, { layout: ServiceNotifyParamsLayout }); + } +} + diff --git a/codegen/tests/golden/format_json/typescript/connection.ts b/codegen/tests/golden/format_json/typescript/connection.ts new file mode 100644 index 0000000..1a1cedb --- /dev/null +++ b/codegen/tests/golden/format_json/typescript/connection.ts @@ -0,0 +1,62 @@ +// 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, + 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 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. + * @internal + */ +export function provideServices(conn: Connection, services: Services): void { + new ns_conformance.ServiceDispatcher(services.service).provideOn(conn); +} + +/** +* Accept a connection over `transport`: run the handshake, then provide +* every protocol in `services` on it. The connection comes back serving, +* so the server can call the client through it. +*/ +export async function accept(transport: Transport, services: Services): Promise { + const conn = await Connection.accept(transport, Format, CONNECTION_IR_HASH); + provideServices(conn, services); + return conn; +} + +/** {@link accept}, then serve every call until the peer leaves. */ +export async function serve(transport: Transport, services: Services): Promise { + await (await accept(transport, services)).closed; +} + +/** +* Dial over `transport`: run the handshake. Call the server's protocols +* through their senders. +*/ +export async function connect(transport: Transport): Promise { + const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH); + return conn; +} diff --git a/codegen/tests/golden/format_json/typescript/wire.ts b/codegen/tests/golden/format_json/typescript/wire.ts new file mode 100644 index 0000000..409baeb --- /dev/null +++ b/codegen/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/codegen/tests/golden/framing_datagram3/typescript/conformance.ts b/codegen/tests/golden/framing_datagram3/typescript/conformance.ts new file mode 100644 index 0000000..88ac190 --- /dev/null +++ b/codegen/tests/golden/framing_datagram3/typescript/conformance.ts @@ -0,0 +1,108 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + RuntimeError, + resolveKind, + type Codec, + type Connection, + type Dispatch, + type Kind, + type Layout, + type Peer, + type Reply, +} from "@comline/runtime"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 0xbb9f4216f7365478n; + +export interface CounterAddParams { + n: number; +} + +/** @internal */ +export const CounterAddParamsLayout: Layout = { struct: [["n", "u32"]] }; + +export interface Counter { + add(peer: Peer, params: CounterAddParams): Promise; + 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; + + private readonly impl: Counter; + + constructor(impl: Counter) { + this.impl = impl; + } + + calls(): readonly string[] { + return COUNTER_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch ("id" in call ? call.id : -1) { + case 1: { + try { + const p = codec.decode(params, CounterAddParamsLayout); + reply.ok(codec.encode((await this.impl.add(peer, p)) ?? null, "u32")); + } catch { + reply.fault(); + } + return; + } + case 0: { + try { + await this.impl.reset(peer); + } catch { + /* one-way: nowhere to report this */ + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** 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); + } +} + +/** Calls protocol `Counter` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class CounterSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async add(params: CounterAddParams): Promise { + const env = await this.peer.call(CounterSender.PROTOCOL, { id: 1, name: "add" }, params, { layout: CounterAddParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "u32"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } + + async reset(): Promise { + await this.peer.notify(CounterSender.PROTOCOL, { id: 0, name: "reset" }, null, { layout: "unit" }); + } +} + diff --git a/codegen/tests/golden/framing_datagram3/typescript/connection.ts b/codegen/tests/golden/framing_datagram3/typescript/connection.ts new file mode 100644 index 0000000..0d1f323 --- /dev/null +++ b/codegen/tests/golden/framing_datagram3/typescript/connection.ts @@ -0,0 +1,63 @@ +// 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, + 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 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. + * @internal + */ +export function provideServices(conn: Connection, services: Services): void { + new ns_conformance.CounterDispatcher(services.counter).provideOn(conn); +} + +/** +* Accept a connection over `transport`: run the handshake, then provide +* every protocol in `services` on it. The connection comes back serving, +* so the server can call the client through it. +*/ +export async function accept(transport: Transport, services: Services): Promise { + const conn = await Connection.accept(transport, Format, CONNECTION_IR_HASH, new Datagram3Framing()); + provideServices(conn, services); + return conn; +} + +/** {@link accept}, then serve every call until the peer leaves. */ +export async function serve(transport: Transport, services: Services): Promise { + await (await accept(transport, services)).closed; +} + +/** +* Dial over `transport`: run the handshake. Call the server's protocols +* through their senders. +*/ +export async function connect(transport: Transport): Promise { + const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH, new Datagram3Framing()); + return conn; +} diff --git a/codegen/tests/golden/framing_datagram3/typescript/wire.ts b/codegen/tests/golden/framing_datagram3/typescript/wire.ts new file mode 100644 index 0000000..b536004 --- /dev/null +++ b/codegen/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/codegen/tests/golden/framing_jsonrpc/typescript/conformance.ts b/codegen/tests/golden/framing_jsonrpc/typescript/conformance.ts new file mode 100644 index 0000000..5fb7fe1 --- /dev/null +++ b/codegen/tests/golden/framing_jsonrpc/typescript/conformance.ts @@ -0,0 +1,88 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + Client, + Server, + RuntimeError, + resolveKind, + JsonRpcFraming, + JsonCodec, + type Codec, + type Dispatch, + type Framing, + type Kind, + type Layout, + type Reply, + type Transport, +} from "@comline/runtime"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 0x1a95418a1177cd91n; + +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 { + private readonly impl: Rpc; + + constructor(impl: Rpc) { + this.impl = impl; + } + + calls(): readonly string[] { + return RPC_CALLS; + } + + async dispatch(call: Kind, params: Uint8Array, codec: Codec, reply: Reply): Promise { + switch (resolveKind(call, RPC_CALLS)) { + case 0: { + try { + const p = codec.decode(params, RpcPingParamsLayout); + reply.ok(codec.encode((await this.impl.ping(p)) ?? null, "u32")); + } catch { + reply.fault(); + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } +} + +export class RpcClient { + private readonly client: Client; + + constructor(client: Client) { + this.client = client; + } + + static async connect(transport: Transport, codec: Codec = new JsonCodec(), framing: Framing = new JsonRpcFraming()): Promise { + return new RpcClient(await Client.connect(transport, codec, IR_HASH, framing)); + } + + async ping(params: RpcPingParams): Promise { + const env = await this.client.call({ id: 0, name: "ping" }, params, { layout: RpcPingParamsLayout }); + if ("ok" in env) return this.client.codec.decode(env.ok, "u32"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } +} + +export function serveRpc(impl: Rpc, transport: Transport, codec: Codec = new JsonCodec(), framing: Framing = new JsonRpcFraming()): Promise { + return new Server(new RpcDispatcher(impl), codec, framing).serve(transport, IR_HASH); +} + diff --git a/codegen/tests/golden/handshake_comline2/typescript/conformance.ts b/codegen/tests/golden/handshake_comline2/typescript/conformance.ts new file mode 100644 index 0000000..cd8ba98 --- /dev/null +++ b/codegen/tests/golden/handshake_comline2/typescript/conformance.ts @@ -0,0 +1,111 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + RuntimeError, + resolveKind, + checkCall, + type Codec, + type Connection, + type Dispatch, + type Kind, + type Layout, + type Peer, + type Reply, +} from "@comline/runtime"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 0x9328a48fb76a93dfn; + +export interface ChatSendParams { + text: number; +} + +/** @internal */ +export const ChatSendParamsLayout: Layout = { struct: [["text", "u32"]] }; + +export interface Chat { + send(peer: Peer, params: ChatSendParams): Promise; + 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; + + private readonly impl: Chat; + + constructor(impl: Chat) { + this.impl = impl; + } + + calls(): readonly string[] { + return CHAT_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch ("id" in call ? call.id : -1) { + case 1: { + try { + const p = codec.decode(params, ChatSendParamsLayout); + reply.ok(codec.encode((await this.impl.send(peer, p)) ?? null, "u32")); + } catch { + reply.fault(); + } + return; + } + case 0: { + try { + await this.impl.leave(peer); + } catch { + /* one-way: nowhere to report this */ + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with the package's `accept` / `connect`, which run `comline@2` with this package's facts, or let the package's `serve` / `connect` do it. */ + provideOn(conn: Connection): void { + conn.provide(ChatDispatcher.PROTOCOL, this); + } +} + +/** Calls protocol `Chat` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class ChatSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async send(params: ChatSendParams): Promise { + checkCall(this.peer, ChatSender.PROTOCOL, 1, "conformance::Chat", "send"); + const env = await this.peer.call(ChatSender.PROTOCOL, { id: 1, name: "send" }, params, { layout: ChatSendParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "u32"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } + + async leave(): Promise { + checkCall(this.peer, ChatSender.PROTOCOL, 0, "conformance::Chat", "leave"); + await this.peer.notify(ChatSender.PROTOCOL, { id: 0, name: "leave" }, null, { layout: "unit" }); + } +} + diff --git a/codegen/tests/golden/handshake_comline2/typescript/connection.ts b/codegen/tests/golden/handshake_comline2/typescript/connection.ts new file mode 100644 index 0000000..23e9a02 --- /dev/null +++ b/codegen/tests/golden/handshake_comline2/typescript/connection.ts @@ -0,0 +1,119 @@ +// 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, + Comline2Handshake, + Negotiated, + 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 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, + 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x00, 0x01, 0x00, + 0x00, 0x03, 0x00, 0x52, 0x18, 0x5f, 0xd6, 0x09, 0x92, 0xad, 0x43, 0x02, + 0x9c, 0xc2, 0x99, 0x62, 0xb3, 0xaf, 0xb4, 0x01, 0x4e, 0x6e, 0xde, 0x7c, + 0xc8, 0xf5, 0xaa, 0x52, 0xce, 0x16, 0x9f, 0x9e, 0x65, 0x67, 0x40, 0xe2, + 0x02, 0x58, 0x80, 0x9a, 0xaf, 0x4b, 0x47, 0xd5, 0x6c, 0x69, 0xb2, 0xc1, + 0xfc, 0x9d, 0x43, 0x30, 0xc1, 0x01, 0x00, 0x00, 0x01, 0x00, 0x5a, 0x5a, + 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, + 0x5a, 0x5a, 0x02, 0x00, 0x01, +]); + +/** + * The `comline@2` handshake, with {@link HELLO} and the parameters the package states. + * @internal + */ +export function handshake(): Comline2Handshake { + return new Comline2Handshake(HELLO, { + scope: "protocol", + newerConsumer: "refuse", + sameVersionDiffers: "refuse", + exchange: "offer", + }); +} + +/** The package's protocols on the connection, by wire number. */ +const PROTOCOLS = new Map([[0, "conformance::Chat"]]); + +/** What the connection's `comline@2` handshake agreed, if `accept` / `connect` opened it. */ +export function negotiated(conn: Peer): Negotiated | undefined { + return conn.extensions.get(Negotiated); +} + +/** + * The protocols that connected although their wire shape differs from the + * peer's at the same version (`same_version_differs = warn`), by path. + */ +export function warnings(conn: Peer): string[] { + return (negotiated(conn)?.warnings ?? []).map((n) => PROTOCOLS.get(n) ?? `#${n}`); +} + +/** 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. + * @internal + */ +export function provideServices(conn: Connection, services: Services): void { + new ns_conformance.ChatDispatcher(services.chat).provideOn(conn); +} + +/** +* Accept a connection over `transport`: run the handshake, then provide +* every protocol in `services` on it. The connection comes back serving, +* so the server can call the client through it. +*/ +export async function accept(transport: Transport, services: Services): Promise { + const agreed = handshake(); + const conn = await Connection.accept(transport, Format, CONNECTION_IR_HASH, new Datagram3Framing(), agreed); + conn.extensions.set(agreed.negotiated!); + provideServices(conn, services); + return conn; +} + +/** {@link accept}, then serve every call until the peer leaves. */ +export async function serve(transport: Transport, services: Services): Promise { + await (await accept(transport, services)).closed; +} + +/** +* Dial over `transport`: run the handshake. Call the server's protocols +* through their senders. +*/ +export async function connect(transport: Transport): Promise { + const agreed = handshake(); + const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH, new Datagram3Framing(), agreed); + conn.extensions.set(agreed.negotiated!); + return conn; +} diff --git a/codegen/tests/golden/handshake_comline2/typescript/wire.ts b/codegen/tests/golden/handshake_comline2/typescript/wire.ts new file mode 100644 index 0000000..d24e55e --- /dev/null +++ b/codegen/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/codegen/tests/golden/handshake_none/typescript/conformance.ts b/codegen/tests/golden/handshake_none/typescript/conformance.ts new file mode 100644 index 0000000..a76c689 --- /dev/null +++ b/codegen/tests/golden/handshake_none/typescript/conformance.ts @@ -0,0 +1,104 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + RuntimeError, + resolveKind, + type Codec, + type Connection, + type Dispatch, + type Kind, + type Layout, + type Peer, + type Reply, +} from "@comline/runtime"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 0xb7e7d5c80c4d8287n; + +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. */ + static readonly PROTOCOL = 0; + + private readonly impl: Gateway; + + constructor(impl: Gateway) { + this.impl = impl; + } + + calls(): readonly string[] { + return GATEWAY_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch (resolveKind(call, GATEWAY_CALLS)) { + case 0: { + try { + const p = codec.decode(params, GatewayPingParamsLayout); + reply.ok(codec.encode((await this.impl.ping(peer, p)) ?? null, "u32")); + } catch { + reply.fault(); + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** 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); + } +} + +/** + * **Unverified:** gives up schema agreement and encoding agreement. + * Reason given: the gateway predates Comline + */ +/** Calls protocol `Gateway` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class GatewaySender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async ping(params: GatewayPingParams): Promise { + const env = await this.peer.call(GatewaySender.PROTOCOL, { id: 0, name: "ping" }, params, { layout: GatewayPingParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "u32"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } +} + diff --git a/codegen/tests/golden/handshake_none/typescript/connection.ts b/codegen/tests/golden/handshake_none/typescript/connection.ts new file mode 100644 index 0000000..91d1b57 --- /dev/null +++ b/codegen/tests/golden/handshake_none/typescript/connection.ts @@ -0,0 +1,63 @@ +// 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, + NoHandshake, + 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 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. + * @internal + */ +export function provideServices(conn: Connection, services: Services): void { + new ns_conformance.GatewayDispatcher(services.gateway).provideOn(conn); +} + +/** +* Accept a connection over `transport`: run the handshake, then provide +* every protocol in `services` on it. The connection comes back serving, +* so the server can call the client through it. +*/ +export async function accept(transport: Transport, services: Services): Promise { + const conn = await Connection.accept(transport, Format, CONNECTION_IR_HASH, undefined, new NoHandshake()); + provideServices(conn, services); + return conn; +} + +/** {@link accept}, then serve every call until the peer leaves. */ +export async function serve(transport: Transport, services: Services): Promise { + await (await accept(transport, services)).closed; +} + +/** +* Dial over `transport`: run the handshake. Call the server's protocols +* through their senders. +*/ +export async function connect(transport: Transport): Promise { + const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH, undefined, new NoHandshake()); + return conn; +} diff --git a/codegen/tests/golden/handshake_none/typescript/wire.ts b/codegen/tests/golden/handshake_none/typescript/wire.ts new file mode 100644 index 0000000..1290676 --- /dev/null +++ b/codegen/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/codegen/tests/golden/import_alias/typescript/api.ts b/codegen/tests/golden/import_alias/typescript/api.ts new file mode 100644 index 0000000..89f4948 --- /dev/null +++ b/codegen/tests/golden/import_alias/typescript/api.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +import { SharedLayout as AliasedLayout } from "./shared.js"; +import type { Shared as Aliased } from "./shared.js"; + +export interface Holder { + one: Aliased; +} + +export const HolderLayout: Layout = { struct: [["one", () => AliasedLayout]] }; + diff --git a/codegen/tests/golden/import_alias/typescript/shared.ts b/codegen/tests/golden/import_alias/typescript/shared.ts new file mode 100644 index 0000000..362c34d --- /dev/null +++ b/codegen/tests/golden/import_alias/typescript/shared.ts @@ -0,0 +1,11 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +export interface Shared { + value: number; +} + +export const SharedLayout: Layout = { struct: [["value", "s32"]] }; + diff --git a/codegen/tests/golden/import_glob/typescript/api.ts b/codegen/tests/golden/import_glob/typescript/api.ts new file mode 100644 index 0000000..356d131 --- /dev/null +++ b/codegen/tests/golden/import_glob/typescript/api.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +import { SharedLayout } from "./shared.js"; +import type { Shared } from "./shared.js"; + +export interface Holder { + one: Shared; +} + +export const HolderLayout: Layout = { struct: [["one", () => SharedLayout]] }; + diff --git a/codegen/tests/golden/import_glob/typescript/shared.ts b/codegen/tests/golden/import_glob/typescript/shared.ts new file mode 100644 index 0000000..f5efa1f --- /dev/null +++ b/codegen/tests/golden/import_glob/typescript/shared.ts @@ -0,0 +1,17 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +export interface Shared { + value: number; +} + +export const SharedLayout: Layout = { struct: [["value", "s32"]] }; + +export interface Unused { + ignored: boolean; +} + +export const UnusedLayout: Layout = { struct: [["ignored", "bool"]] }; + diff --git a/codegen/tests/golden/large_fixed_arrays_nested/typescript/conformance.ts b/codegen/tests/golden/large_fixed_arrays_nested/typescript/conformance.ts new file mode 100644 index 0000000..f3147b8 --- /dev/null +++ b/codegen/tests/golden/large_fixed_arrays_nested/typescript/conformance.ts @@ -0,0 +1,12 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +export interface Blocks { + maybe?: number[]; + many: number[][]; +} + +export const BlocksLayout: Layout = { struct: [["maybe", { option: { fixed: "u8", length: 64 } }], ["many", { array: { fixed: "u8", length: 64 } }]] }; + diff --git a/codegen/tests/golden/lockstep/typescript/conformance.ts b/codegen/tests/golden/lockstep/typescript/conformance.ts new file mode 100644 index 0000000..e180ea8 --- /dev/null +++ b/codegen/tests/golden/lockstep/typescript/conformance.ts @@ -0,0 +1,136 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + Client, + Server, + RuntimeError, + resolveKind, + DatagramFraming, + PackedCodec, + type Codec, + type Dispatch, + type Framing, + type Kind, + type Layout, + type Reply, + type Transport, +} from "@comline/runtime"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 0x7ea94b595fcf4393n; + +/** The package's wire format (`wire.format`): what this file's helpers +* encode with, and what the peer has to speak too. */ +export const Format: Codec = new PackedCodec(); + +export interface Message { + body: string; +} + +export const MessageLayout: Layout = { struct: [["body", "string"]] }; + +export interface RecipientNotFound { +} + +export const RecipientNotFoundLayout: Layout = { struct: [] }; + +export class RecipientNotFoundError extends Error { + static readonly ordinal = 0; + readonly data: RecipientNotFound; + constructor(data: RecipientNotFound) { + super("RecipientNotFound"); + this.data = data; + this.name = "RecipientNotFoundError"; + } +} + +export interface MailSendMessageParams { + message: Message; +} + +/** @internal */ +export const MailSendMessageParamsLayout: Layout = { struct: [["message", () => MessageLayout]] }; + +export interface Mail { + /** @throws {RecipientNotFoundError} */ + send_message(params: MailSendMessageParams): Promise; + fetch_inbox(): Promise; +} + +/** @internal */ +export const MAIL_CALLS = ["send_message", "fetch_inbox"] as const; + +export class MailDispatcher implements Dispatch { + private readonly impl: Mail; + + constructor(impl: Mail) { + this.impl = impl; + } + + calls(): readonly string[] { + return MAIL_CALLS; + } + + async dispatch(call: Kind, params: Uint8Array, codec: Codec, reply: Reply): Promise { + switch (resolveKind(call, MAIL_CALLS)) { + case 0: { + try { + const p = codec.decode(params, MailSendMessageParamsLayout); + reply.ok(codec.encode((await this.impl.send_message(p)) ?? null, "string")); + } catch (e) { + if (e instanceof RecipientNotFoundError) { reply.err(RecipientNotFoundError.ordinal, codec.encode(e.data, RecipientNotFoundLayout)); return; } + reply.fault(); + } + return; + } + case 1: { + try { + reply.ok(codec.encode((await this.impl.fetch_inbox()) ?? null, { array: MessageLayout })); + } catch { + reply.fault(); + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } +} + +export class MailClient { + private readonly client: Client; + + constructor(client: Client) { + this.client = client; + } + + static async connect(transport: Transport, codec: Codec = Format, framing: Framing = new DatagramFraming()): Promise { + return new MailClient(await Client.connect(transport, codec, IR_HASH, framing)); + } + + async send_message(params: MailSendMessageParams): Promise { + const env = await this.client.call({ id: 0, name: "send_message" }, params, { layout: MailSendMessageParamsLayout }); + if ("ok" in env) return this.client.codec.decode(env.ok, "string"); + if ("fault" in env) throw RuntimeError.provider(); + switch (env.err.id) { + case RecipientNotFoundError.ordinal: + throw new RecipientNotFoundError(this.client.codec.decode(env.err.body, RecipientNotFoundLayout)); + default: + throw RuntimeError.remote(env.err.id); + } + } + + async fetch_inbox(): Promise { + const env = await this.client.call({ id: 1, name: "fetch_inbox" }, null, { layout: "unit" }); + if ("ok" in env) return this.client.codec.decode(env.ok, { array: MessageLayout }); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } +} + +export function serveMail(impl: Mail, transport: Transport, codec: Codec = Format, framing: Framing = new DatagramFraming()): Promise { + return new Server(new MailDispatcher(impl), codec, framing).serve(transport, IR_HASH); +} + diff --git a/codegen/tests/golden/nested_namespace/typescript/package.json b/codegen/tests/golden/nested_namespace/typescript/package.json new file mode 100644 index 0000000..f4e1629 --- /dev/null +++ b/codegen/tests/golden/nested_namespace/typescript/package.json @@ -0,0 +1,30 @@ +{ + "name": "conformance", + "version": "0.0.0", + "type": "module", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + }, + "./*": { + "types": "./dist/*.d.ts", + "import": "./dist/*.js" + } + }, + "files": ["dist", "src"], + "scripts": { + "build": "tsc" + }, + "peerDependencies": { + "@comline/runtime": "^0.1.0", + "typescript": ">=5.0" + }, + "peerDependenciesMeta": { + "@comline/runtime": { "optional": true }, + "typescript": { "optional": true } + }, + "devDependencies": { + "typescript": "^5.6.0" + } +} diff --git a/codegen/tests/golden/nested_namespace/typescript/src/group/first.ts b/codegen/tests/golden/nested_namespace/typescript/src/group/first.ts new file mode 100644 index 0000000..313b80f --- /dev/null +++ b/codegen/tests/golden/nested_namespace/typescript/src/group/first.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +import { TopLayout } from "../top.js"; +import type { Top } from "../top.js"; + +export interface First { + top: Top; +} + +export const FirstLayout: Layout = { struct: [["top", () => TopLayout]] }; + diff --git a/codegen/tests/golden/nested_namespace/typescript/src/group/index.ts b/codegen/tests/golden/nested_namespace/typescript/src/group/index.ts new file mode 100644 index 0000000..bf825b8 --- /dev/null +++ b/codegen/tests/golden/nested_namespace/typescript/src/group/index.ts @@ -0,0 +1,4 @@ +// Generated by Comline + +export * as first from "./first.js"; +export * as second from "./second.js"; diff --git a/codegen/tests/golden/nested_namespace/typescript/src/group/second.ts b/codegen/tests/golden/nested_namespace/typescript/src/group/second.ts new file mode 100644 index 0000000..4206fcc --- /dev/null +++ b/codegen/tests/golden/nested_namespace/typescript/src/group/second.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +import { FirstLayout } from "./first.js"; +import type { First } from "./first.js"; + +export interface Second { + first: First; +} + +export const SecondLayout: Layout = { struct: [["first", () => FirstLayout]] }; + diff --git a/codegen/tests/golden/nested_namespace/typescript/src/index.ts b/codegen/tests/golden/nested_namespace/typescript/src/index.ts new file mode 100644 index 0000000..45db4ac --- /dev/null +++ b/codegen/tests/golden/nested_namespace/typescript/src/index.ts @@ -0,0 +1,4 @@ +// Generated by Comline + +export * as group from "./group/index.js"; +export * as top from "./top.js"; diff --git a/codegen/tests/golden/nested_namespace/typescript/src/top.ts b/codegen/tests/golden/nested_namespace/typescript/src/top.ts new file mode 100644 index 0000000..fb35d7a --- /dev/null +++ b/codegen/tests/golden/nested_namespace/typescript/src/top.ts @@ -0,0 +1,11 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +export interface Top { + value: number; +} + +export const TopLayout: Layout = { struct: [["value", "s32"]] }; + diff --git a/codegen/tests/golden/nested_namespace/typescript/tsconfig.json b/codegen/tests/golden/nested_namespace/typescript/tsconfig.json new file mode 100644 index 0000000..931f802 --- /dev/null +++ b/codegen/tests/golden/nested_namespace/typescript/tsconfig.json @@ -0,0 +1,16 @@ +{ + "compilerOptions": { + "target": "ES2020", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "outDir": "dist", + "rootDir": "src", + "declaration": true, + "strict": true, + "exactOptionalPropertyTypes": true, + "noUncheckedIndexedAccess": true, + "verbatimModuleSyntax": true, + "skipLibCheck": true + }, + "include": ["src/**/*.ts"] +} diff --git a/codegen/tests/golden/nested_protocol/typescript/chat/admin.ts b/codegen/tests/golden/nested_protocol/typescript/chat/admin.ts new file mode 100644 index 0000000..02baaeb --- /dev/null +++ b/codegen/tests/golden/nested_protocol/typescript/chat/admin.ts @@ -0,0 +1,103 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + RuntimeError, + resolveKind, + checkCall, + type Codec, + type Connection, + type Dispatch, + type Kind, + type Layout, + type Peer, + type Reply, +} from "@comline/runtime"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 0xa6f61afefe65d74an; + +export interface Notice { + text: string; +} + +export const NoticeLayout: Layout = { struct: [["text", "string"]] }; + +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; + + private readonly impl: Admin; + + constructor(impl: Admin) { + this.impl = impl; + } + + calls(): readonly string[] { + return ADMIN_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch ("id" in call ? call.id : -1) { + case 0: { + try { + const p = codec.decode(params, AdminGreetParamsLayout); + reply.ok(codec.encode((await this.impl.greet(peer, p)) ?? null, "u32")); + } catch { + reply.fault(); + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** Provide this protocol on `conn`: the peer's calls to it come here. Open `conn` with the package's `accept` / `connect`, which run `comline@2` with this package's facts, or let the package's `serve` / `connect` do it. */ + provideOn(conn: Connection): void { + conn.provide(AdminDispatcher.PROTOCOL, this); + } +} + +/** Calls protocol `Admin` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class AdminSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async greet(params: AdminGreetParams): Promise { + checkCall(this.peer, AdminSender.PROTOCOL, 0, "chat::admin::Admin", "greet"); + const env = await this.peer.call(AdminSender.PROTOCOL, { id: 0, name: "greet" }, params, { layout: AdminGreetParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "u32"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } +} + diff --git a/codegen/tests/golden/nested_protocol/typescript/connection.ts b/codegen/tests/golden/nested_protocol/typescript/connection.ts new file mode 100644 index 0000000..82a2972 --- /dev/null +++ b/codegen/tests/golden/nested_protocol/typescript/connection.ts @@ -0,0 +1,119 @@ +// 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, + Comline2Handshake, + Negotiated, + 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 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, + 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0x00, 0x01, 0x00, + 0x00, 0x03, 0x00, 0x52, 0x18, 0x5f, 0xd6, 0x09, 0x92, 0xad, 0x43, 0x02, + 0x9c, 0xc2, 0x99, 0x62, 0xb3, 0xaf, 0xb4, 0x01, 0x4e, 0x6e, 0xde, 0x7c, + 0xc8, 0xf5, 0xaa, 0x52, 0xce, 0x16, 0x9f, 0x9e, 0x65, 0x67, 0x40, 0xe2, + 0x02, 0x58, 0x80, 0x9a, 0xaf, 0x4b, 0x47, 0xd5, 0x6c, 0x69, 0xb2, 0xc1, + 0xfc, 0x9d, 0x43, 0x30, 0xc1, 0x01, 0x00, 0x00, 0x01, 0x00, 0x5a, 0x5a, + 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, 0x5a, + 0x5a, 0x5a, 0x01, 0x00, +]); + +/** + * The `comline@2` handshake, with {@link HELLO} and the parameters the package states. + * @internal + */ +export function handshake(): Comline2Handshake { + return new Comline2Handshake(HELLO, { + scope: "protocol", + newerConsumer: "degrade", + sameVersionDiffers: "refuse", + exchange: "offer", + }); +} + +/** The package's protocols on the connection, by wire number. */ +const PROTOCOLS = new Map([[0, "chat::admin::Admin"]]); + +/** What the connection's `comline@2` handshake agreed, if `accept` / `connect` opened it. */ +export function negotiated(conn: Peer): Negotiated | undefined { + return conn.extensions.get(Negotiated); +} + +/** + * The protocols that connected although their wire shape differs from the + * peer's at the same version (`same_version_differs = warn`), by path. + */ +export function warnings(conn: Peer): string[] { + return (negotiated(conn)?.warnings ?? []).map((n) => PROTOCOLS.get(n) ?? `#${n}`); +} + +/** What the accepting side provides: one field per protocol, so leaving one out doesn't type-check. */ +export interface Services { + admin: ns_chat_admin.Admin; +} + +/** + * 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); +} + +/** +* Accept a connection over `transport`: run the handshake, then provide +* every protocol in `services` on it. The connection comes back serving, +* so the server can call the client through it. +*/ +export async function accept(transport: Transport, services: Services): Promise { + const agreed = handshake(); + const conn = await Connection.accept(transport, Format, CONNECTION_IR_HASH, new Datagram3Framing(), agreed); + conn.extensions.set(agreed.negotiated!); + provideServices(conn, services); + return conn; +} + +/** {@link accept}, then serve every call until the peer leaves. */ +export async function serve(transport: Transport, services: Services): Promise { + await (await accept(transport, services)).closed; +} + +/** +* Dial over `transport`: run the handshake. Call the server's protocols +* through their senders. +*/ +export async function connect(transport: Transport): Promise { + const agreed = handshake(); + const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH, new Datagram3Framing(), agreed); + conn.extensions.set(agreed.negotiated!); + return conn; +} diff --git a/codegen/tests/golden/nested_protocol/typescript/wire.ts b/codegen/tests/golden/nested_protocol/typescript/wire.ts new file mode 100644 index 0000000..cf9accb --- /dev/null +++ b/codegen/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/codegen/tests/golden/optional_and_arrays/typescript/conformance.ts b/codegen/tests/golden/optional_and_arrays/typescript/conformance.ts new file mode 100644 index 0000000..f535b07 --- /dev/null +++ b/codegen/tests/golden/optional_and_arrays/typescript/conformance.ts @@ -0,0 +1,14 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +export interface Bag { + required: string; + maybe?: number; + many: string[]; + maybe_many?: number[]; +} + +export const BagLayout: Layout = { struct: [["required", "string"], ["maybe", { option: "u32" }], ["many", { array: "string" }], ["maybe_many", { option: { array: "u32" } }]] }; + diff --git a/codegen/tests/golden/primitives/typescript/conformance.ts b/codegen/tests/golden/primitives/typescript/conformance.ts new file mode 100644 index 0000000..600fa7e --- /dev/null +++ b/codegen/tests/golden/primitives/typescript/conformance.ts @@ -0,0 +1,18 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +export interface Scalars { + flag: boolean; + small: number; + medium: number; + large: bigint; + huge: bigint; + signed_small: number; + signed_large: bigint; + name: string; +} + +export const ScalarsLayout: Layout = { struct: [["flag", "bool"], ["small", "u8"], ["medium", "u32"], ["large", "u64"], ["huge", "u128"], ["signed_small", "s8"], ["signed_large", "s64"], ["name", "string"]] }; + diff --git a/codegen/tests/golden/protocol/typescript/conformance.ts b/codegen/tests/golden/protocol/typescript/conformance.ts new file mode 100644 index 0000000..cd34d80 --- /dev/null +++ b/codegen/tests/golden/protocol/typescript/conformance.ts @@ -0,0 +1,161 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + RuntimeError, + resolveKind, + type Codec, + type Connection, + type Dispatch, + type Kind, + type Layout, + type Peer, + type Reply, +} from "@comline/runtime"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 0x8ee00745c73a32b2n; + +export interface Record { + id: number; + name: string; +} + +export const RecordLayout: Layout = { struct: [["id", "s32"], ["name", "string"]] }; + +export interface NotFound { +} + +export const NotFoundLayout: Layout = { struct: [] }; + +export class NotFoundError extends Error { + static readonly ordinal = 0; + readonly data: NotFound; + constructor(data: NotFound) { + super("NotFound"); + this.data = data; + this.name = "NotFoundError"; + } +} + +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 { + /** @throws {NotFoundError} */ + lookup(peer: Peer, params: ServiceLookupParams): Promise; + count(peer: Peer): Promise; + 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; + + private readonly impl: Service; + + constructor(impl: Service) { + this.impl = impl; + } + + calls(): readonly string[] { + return SERVICE_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch (resolveKind(call, SERVICE_CALLS)) { + case 0: { + try { + const p = codec.decode(params, ServiceLookupParamsLayout); + reply.ok(codec.encode((await this.impl.lookup(peer, p)) ?? null, RecordLayout)); + } catch (e) { + if (e instanceof NotFoundError) { reply.err(NotFoundError.ordinal, codec.encode(e.data, NotFoundLayout)); return; } + reply.fault(); + } + return; + } + case 1: { + try { + reply.ok(codec.encode((await this.impl.count(peer)) ?? null, "u64")); + } catch { + reply.fault(); + } + return; + } + case 2: { + try { + const p = codec.decode(params, ServiceNotifyParamsLayout); + await this.impl.notify(peer, p); + } catch { + /* one-way: nowhere to report this */ + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** 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); + } +} + +/** Calls protocol `Service` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class ServiceSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async lookup(params: ServiceLookupParams): Promise { + const env = await this.peer.call(ServiceSender.PROTOCOL, { id: 0, name: "lookup" }, params, { layout: ServiceLookupParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, RecordLayout); + if ("fault" in env) throw RuntimeError.provider(); + switch (env.err.id) { + case NotFoundError.ordinal: + throw new NotFoundError(this.peer.codec.decode(env.err.body, NotFoundLayout)); + default: + throw RuntimeError.remote(env.err.id); + } + } + + async count(): Promise { + const env = await this.peer.call(ServiceSender.PROTOCOL, { id: 1, name: "count" }, null, { layout: "unit" }); + if ("ok" in env) return this.peer.codec.decode(env.ok, "u64"); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } + + async notify(params: ServiceNotifyParams): Promise { + await this.peer.notify(ServiceSender.PROTOCOL, { id: 2, name: "notify" }, params, { layout: ServiceNotifyParamsLayout }); + } +} + diff --git a/codegen/tests/golden/protocol/typescript/connection.ts b/codegen/tests/golden/protocol/typescript/connection.ts new file mode 100644 index 0000000..1a1cedb --- /dev/null +++ b/codegen/tests/golden/protocol/typescript/connection.ts @@ -0,0 +1,62 @@ +// 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, + 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 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. + * @internal + */ +export function provideServices(conn: Connection, services: Services): void { + new ns_conformance.ServiceDispatcher(services.service).provideOn(conn); +} + +/** +* Accept a connection over `transport`: run the handshake, then provide +* every protocol in `services` on it. The connection comes back serving, +* so the server can call the client through it. +*/ +export async function accept(transport: Transport, services: Services): Promise { + const conn = await Connection.accept(transport, Format, CONNECTION_IR_HASH); + provideServices(conn, services); + return conn; +} + +/** {@link accept}, then serve every call until the peer leaves. */ +export async function serve(transport: Transport, services: Services): Promise { + await (await accept(transport, services)).closed; +} + +/** +* Dial over `transport`: run the handshake. Call the server's protocols +* through their senders. +*/ +export async function connect(transport: Transport): Promise { + const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH); + return conn; +} diff --git a/codegen/tests/golden/protocol/typescript/wire.ts b/codegen/tests/golden/protocol/typescript/wire.ts new file mode 100644 index 0000000..b656979 --- /dev/null +++ b/codegen/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/codegen/tests/golden/shapes/typescript/conformance.ts b/codegen/tests/golden/shapes/typescript/conformance.ts new file mode 100644 index 0000000..c16949a --- /dev/null +++ b/codegen/tests/golden/shapes/typescript/conformance.ts @@ -0,0 +1,18 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +export interface Sample { + ratio: number; + precise: number; + rgba: number[]; + digest: number[]; + rows: number[][]; + maybe_rgba?: number[]; +} + +export const SampleLayout: Layout = { struct: [["ratio", "f32"], ["precise", "f64"], ["rgba", { fixed: "u8", length: 4 }], ["digest", { fixed: "u8", length: 64 }], ["rows", { array: { fixed: "u16", length: 3 } }], ["maybe_rgba", { option: { fixed: "u8", length: 4 } }]] }; + +export const SCALE = 2; + diff --git a/codegen/tests/golden/type_refs/typescript/conformance.ts b/codegen/tests/golden/type_refs/typescript/conformance.ts new file mode 100644 index 0000000..abe007d --- /dev/null +++ b/codegen/tests/golden/type_refs/typescript/conformance.ts @@ -0,0 +1,19 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +export interface Inner { + value: number; +} + +export const InnerLayout: Layout = { struct: [["value", "s32"]] }; + +export interface Outer { + one: Inner; + some?: Inner; + list: Inner[]; +} + +export const OuterLayout: Layout = { struct: [["one", () => InnerLayout], ["some", { option: () => InnerLayout }], ["list", { array: () => InnerLayout }]] }; + diff --git a/codegen/tests/golden/unions/typescript/conformance.ts b/codegen/tests/golden/unions/typescript/conformance.ts new file mode 100644 index 0000000..d32194c --- /dev/null +++ b/codegen/tests/golden/unions/typescript/conformance.ts @@ -0,0 +1,15 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import type { Layout } from "@comline/runtime"; + +export type Id = string | number; + +export const IdLayout: Layout = { union: ["string", "u32"] }; + +export interface Lookup { + key: string | number; +} + +export const LookupLayout: Layout = { struct: [["key", { union: ["string", "u32"] }]] }; + diff --git a/codegen/tests/golden/validators/typescript/conformance.ts b/codegen/tests/golden/validators/typescript/conformance.ts new file mode 100644 index 0000000..c72d455 --- /dev/null +++ b/codegen/tests/golden/validators/typescript/conformance.ts @@ -0,0 +1,117 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + RuntimeError, + resolveKind, + type Codec, + type Connection, + type Dispatch, + type Kind, + type Layout, + type Peer, + type Reply, +} from "@comline/runtime"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 0xeab4408b940579fbn; + +export const MIN_HANDLE = 2; + +export type Handle = string; + +export const HandleLayout: Layout = "string"; + +export interface Profile { + handle: Handle; + age: number; + nickname?: Handle; + friends: Handle[]; +} + +export const ProfileLayout: Layout = { struct: [["handle", () => HandleLayout], ["age", "u32"], ["nickname", { option: () => HandleLayout }], ["friends", { array: () => HandleLayout }]] }; + +export interface Post { + author: Profile; + body: string; +} + +export const PostLayout: Layout = { struct: [["author", () => ProfileLayout], ["body", "string"]] }; + +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; + + private readonly impl: Social; + + constructor(impl: Social) { + this.impl = impl; + } + + calls(): readonly string[] { + return SOCIAL_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch (resolveKind(call, SOCIAL_CALLS)) { + case 0: { + try { + const p = codec.decode(params, SocialRenameParamsLayout); + reply.ok(codec.encode((await this.impl.rename(peer, p)) ?? null, HandleLayout)); + } catch { + reply.fault(); + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** 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); + } +} + +/** Calls protocol `Social` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class SocialSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async rename(params: SocialRenameParams): Promise { + const env = await this.peer.call(SocialSender.PROTOCOL, { id: 0, name: "rename" }, params, { layout: SocialRenameParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, HandleLayout); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } +} + diff --git a/codegen/tests/golden/validators/typescript/connection.ts b/codegen/tests/golden/validators/typescript/connection.ts new file mode 100644 index 0000000..abe85a9 --- /dev/null +++ b/codegen/tests/golden/validators/typescript/connection.ts @@ -0,0 +1,62 @@ +// 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, + 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 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. + * @internal + */ +export function provideServices(conn: Connection, services: Services): void { + new ns_conformance.SocialDispatcher(services.social).provideOn(conn); +} + +/** +* Accept a connection over `transport`: run the handshake, then provide +* every protocol in `services` on it. The connection comes back serving, +* so the server can call the client through it. +*/ +export async function accept(transport: Transport, services: Services): Promise { + const conn = await Connection.accept(transport, Format, CONNECTION_IR_HASH); + provideServices(conn, services); + return conn; +} + +/** {@link accept}, then serve every call until the peer leaves. */ +export async function serve(transport: Transport, services: Services): Promise { + await (await accept(transport, services)).closed; +} + +/** +* Dial over `transport`: run the handshake. Call the server's protocols +* through their senders. +*/ +export async function connect(transport: Transport): Promise { + const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH); + return conn; +} diff --git a/codegen/tests/golden/validators/typescript/std/validators.ts b/codegen/tests/golden/validators/typescript/std/validators.ts new file mode 100644 index 0000000..affa264 --- /dev/null +++ b/codegen/tests/golden/validators/typescript/std/validators.ts @@ -0,0 +1,3 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + diff --git a/codegen/tests/golden/validators/typescript/wire.ts b/codegen/tests/golden/validators/typescript/wire.ts new file mode 100644 index 0000000..71c56b7 --- /dev/null +++ b/codegen/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/codegen/tests/golden/validators_on_decode/typescript/conformance.ts b/codegen/tests/golden/validators_on_decode/typescript/conformance.ts new file mode 100644 index 0000000..c72d455 --- /dev/null +++ b/codegen/tests/golden/validators_on_decode/typescript/conformance.ts @@ -0,0 +1,117 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + RuntimeError, + resolveKind, + type Codec, + type Connection, + type Dispatch, + type Kind, + type Layout, + type Peer, + type Reply, +} from "@comline/runtime"; + +/** Canonical digest of the frozen IR this file was generated from — the +* two ends of a connection must agree on it. */ +export const IR_HASH = 0xeab4408b940579fbn; + +export const MIN_HANDLE = 2; + +export type Handle = string; + +export const HandleLayout: Layout = "string"; + +export interface Profile { + handle: Handle; + age: number; + nickname?: Handle; + friends: Handle[]; +} + +export const ProfileLayout: Layout = { struct: [["handle", () => HandleLayout], ["age", "u32"], ["nickname", { option: () => HandleLayout }], ["friends", { array: () => HandleLayout }]] }; + +export interface Post { + author: Profile; + body: string; +} + +export const PostLayout: Layout = { struct: [["author", () => ProfileLayout], ["body", "string"]] }; + +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; + + private readonly impl: Social; + + constructor(impl: Social) { + this.impl = impl; + } + + calls(): readonly string[] { + return SOCIAL_CALLS; + } + + /** Only served on a connection, whose handlers are given the peer: anywhere else the caller hears a fault. */ + async dispatch(_call: Kind, _params: Uint8Array, _codec: Codec, reply: Reply): Promise { + reply.fault(); + } + + async dispatchWith(call: Kind, params: Uint8Array, reply: Reply, peer: Peer): Promise { + const codec = peer.codec; + switch (resolveKind(call, SOCIAL_CALLS)) { + case 0: { + try { + const p = codec.decode(params, SocialRenameParamsLayout); + reply.ok(codec.encode((await this.impl.rename(peer, p)) ?? null, HandleLayout)); + } catch { + reply.fault(); + } + return; + } + default: + throw RuntimeError.unknownCall(); + } + } + + /** 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); + } +} + +/** Calls protocol `Social` on the other end of a connection: the peer a `Connection` reaches, or the one a handler was given. */ +export class SocialSender { + /** This protocol's number on a connection. */ + static readonly PROTOCOL = 0; + + private readonly peer: Peer; + + constructor(peer: Peer) { + this.peer = peer; + } + + async rename(params: SocialRenameParams): Promise { + const env = await this.peer.call(SocialSender.PROTOCOL, { id: 0, name: "rename" }, params, { layout: SocialRenameParamsLayout }); + if ("ok" in env) return this.peer.codec.decode(env.ok, HandleLayout); + if ("fault" in env) throw RuntimeError.provider(); + throw RuntimeError.remote(env.err.id); + } +} + diff --git a/codegen/tests/golden/validators_on_decode/typescript/connection.ts b/codegen/tests/golden/validators_on_decode/typescript/connection.ts new file mode 100644 index 0000000..abe85a9 --- /dev/null +++ b/codegen/tests/golden/validators_on_decode/typescript/connection.ts @@ -0,0 +1,62 @@ +// 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, + 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 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. + * @internal + */ +export function provideServices(conn: Connection, services: Services): void { + new ns_conformance.SocialDispatcher(services.social).provideOn(conn); +} + +/** +* Accept a connection over `transport`: run the handshake, then provide +* every protocol in `services` on it. The connection comes back serving, +* so the server can call the client through it. +*/ +export async function accept(transport: Transport, services: Services): Promise { + const conn = await Connection.accept(transport, Format, CONNECTION_IR_HASH); + provideServices(conn, services); + return conn; +} + +/** {@link accept}, then serve every call until the peer leaves. */ +export async function serve(transport: Transport, services: Services): Promise { + await (await accept(transport, services)).closed; +} + +/** +* Dial over `transport`: run the handshake. Call the server's protocols +* through their senders. +*/ +export async function connect(transport: Transport): Promise { + const conn = await Connection.connect(transport, Format, CONNECTION_IR_HASH); + return conn; +} diff --git a/codegen/tests/golden/validators_on_decode/typescript/std/validators.ts b/codegen/tests/golden/validators_on_decode/typescript/std/validators.ts new file mode 100644 index 0000000..affa264 --- /dev/null +++ b/codegen/tests/golden/validators_on_decode/typescript/std/validators.ts @@ -0,0 +1,3 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + diff --git a/codegen/tests/golden/validators_on_decode/typescript/wire.ts b/codegen/tests/golden/validators_on_decode/typescript/wire.ts new file mode 100644 index 0000000..71c56b7 --- /dev/null +++ b/codegen/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; diff --git a/features.json b/features.json new file mode 100644 index 0000000..57b947a --- /dev/null +++ b/features.json @@ -0,0 +1,541 @@ +{ + "features": [ + { + "description": "`struct` declarations", + "id": "structs", + "title": "structs" + }, + { + "description": "`enum` declarations", + "id": "enums", + "title": "enums" + }, + { + "description": "fields marked `optional`", + "id": "optional-fields", + "title": "optional fields" + }, + { + "description": "variable-length arrays, `T[]`", + "id": "arrays", + "title": "arrays" + }, + { + "description": "fixed-length arrays, `T[N]`", + "id": "fixed-arrays", + "title": "fixed-length arrays" + }, + { + "description": "a `T[N]` with N over 32 anywhere but a field's own, non-optional type: inside another array, optional, an alias, an argument or a return", + "id": "large-fixed-arrays-nested", + "title": "fixed arrays over 32 elements, nested" + }, + { + "description": "`union(A B ...)` types", + "id": "unions", + "title": "unions" + }, + { + "description": "`type Name = ...` declarations", + "id": "type-aliases", + "title": "type aliases" + }, + { + "description": "`const` declarations", + "id": "constants", + "title": "constants" + }, + { + "description": "`protocol` declarations and their functions", + "id": "protocols", + "title": "protocols" + }, + { + "description": "`error` declarations", + "id": "errors", + "title": "errors" + }, + { + "description": "functions declared with `! Error`", + "id": "throws", + "title": "functions that throw" + }, + { + "description": "`@validators` on fields and type aliases, checked in generated code", + "id": "validators", + "title": "validators" + }, + { + "description": "`use` of another schema's declarations", + "id": "imports", + "title": "imports between schemas" + }, + { + "description": "schemas in subdirectories (`chat::admin`)", + "id": "nested-namespaces", + "title": "nested namespaces" + }, + { + "description": "`--mode lib`: a buildable package, not bare source files", + "id": "lib-mode", + "title": "`lib` mode" + }, + { + "description": "`[generate] external_std`: `std` referenced as its own package", + "id": "external-std", + "title": "`external_std`" + }, + { + "description": "`[generate] validate_on_decode`: decoding runs the checks", + "id": "validate-on-decode", + "title": "`validate_on_decode`" + }, + { + "description": "`@framing = \"jsonrpc\"` (or as the package default)", + "id": "framing-jsonrpc", + "title": "JSON-RPC framing" + }, + { + "description": "`@handshake = \"none\"` (or as the package default)", + "id": "handshake-none", + "title": "no handshake" + }, + { + "description": "`@framing = \"datagram@3\"` (or as the package default): calls addressed by wire numbers", + "id": "framing-datagram3", + "title": "`datagram@3` framing" + }, + { + "description": "`@handshake = \"comline@2\"` (or as the package default): compatibility checked by each version's facts, calls the peer lacks failing locally", + "id": "handshake-comline2", + "title": "`comline@2` handshake" + }, + { + "description": "protocols on a connection, with calls in both directions: `datagram@3` (the default) or `datagram@2`, or `@provider = Client` / `Multiple`", + "id": "connections", + "title": "connections" + }, + { + "description": "`[generate] async`: connection protocols get async handlers and senders", + "id": "async", + "title": "`async`" + }, + { + "description": "`wire.format = \"packed@1\"`, the default: fixed-width fields, no tags", + "id": "format-packed", + "title": "the `packed@1` format" + }, + { + "description": "`wire.format = \"json@1\"`", + "id": "format-json", + "title": "the `json@1` format" + }, + { + "description": "`wire.format = \"msgpack@1\"`", + "id": "format-msgpack", + "title": "the `msgpack@1` format" + }, + { + "description": "a maximum or exact length on a string or list (`char[max 64]`, `char[8]`, `T[max N]`), or a depth limit (`@max_depth`): checked while decoding and encoding", + "id": "bounds", + "title": "bounds" + }, + { + "description": "`char`: one Unicode scalar value", + "id": "chars", + "title": "single characters" + } + ], + "generators": [ + { + "name": "typescript", + "support": { + "arrays": { + "note": null, + "proven_by": [ + "optional_and_arrays", + "type_refs", + "shapes", + "cross_schema", + "validators", + "validators_on_decode", + "large_fixed_arrays_nested", + "lockstep", + "bounds" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "async": { + "note": "handlers and senders always return Promises: the output is async either way", + "proven_by": [ + "connections_async" + ], + "since": null, + "state": "ignored", + "tracking": null + }, + "bounds": { + "note": null, + "proven_by": [ + "bounds" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "chars": { + "note": null, + "proven_by": [ + "chars" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "connections": { + "note": null, + "proven_by": [ + "protocol", + "error_shapes", + "validators", + "validators_on_decode", + "handshake_none", + "framing_datagram3", + "handshake_comline2", + "connections", + "connections_async", + "connections_jsonrpc", + "connections_default", + "format_json", + "dependency_protocol", + "dependency_and_own_protocols", + "nested_protocol" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "constants": { + "note": null, + "proven_by": [ + "constant", + "shapes", + "validators", + "validators_on_decode" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "enums": { + "note": null, + "proven_by": [ + "enum_basic" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "errors": { + "note": null, + "proven_by": [ + "protocol", + "error_shapes", + "lockstep", + "format_json" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "external-std": { + "note": null, + "proven_by": [ + "external_std" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "fixed-arrays": { + "note": "rendered as `T[]`: the length isn't part of the type", + "proven_by": [ + "shapes", + "large_fixed_arrays_nested" + ], + "since": null, + "state": "partial", + "tracking": null + }, + "format-json": { + "note": null, + "proven_by": [ + "format_json" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "format-msgpack": { + "note": "`@comline/runtime` has no MessagePack codec yet", + "proven_by": [ + "format_msgpack" + ], + "since": null, + "state": "unsupported", + "tracking": null + }, + "format-packed": { + "note": null, + "proven_by": [ + "protocol", + "error_shapes", + "validators", + "validators_on_decode", + "handshake_none", + "framing_datagram3", + "handshake_comline2", + "lockstep", + "connections", + "connections_async", + "connections_default", + "dependency_protocol", + "dependency_and_own_protocols", + "nested_protocol" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "framing-datagram3": { + "note": null, + "proven_by": [ + "framing_datagram3", + "handshake_comline2", + "connections_default", + "dependency_protocol", + "dependency_and_own_protocols", + "nested_protocol" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "framing-jsonrpc": { + "note": null, + "proven_by": [ + "framing_jsonrpc", + "connections_jsonrpc" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "handshake-comline2": { + "note": null, + "proven_by": [ + "handshake_comline2", + "connections_default", + "dependency_protocol", + "dependency_and_own_protocols", + "nested_protocol" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "handshake-none": { + "note": null, + "proven_by": [ + "handshake_none" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "imports": { + "note": null, + "proven_by": [ + "cross_schema", + "import_alias", + "import_glob", + "nested_namespace", + "external_std", + "validators", + "validators_on_decode", + "dependency_protocol", + "dependency_and_own_protocols" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "large-fixed-arrays-nested": { + "note": "rendered as `T[]`: the length isn't part of the type", + "proven_by": [ + "large_fixed_arrays_nested" + ], + "since": null, + "state": "partial", + "tracking": null + }, + "lib-mode": { + "note": null, + "proven_by": [ + "nested_namespace", + "external_std" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "nested-namespaces": { + "note": null, + "proven_by": [ + "nested_namespace", + "external_std", + "validators", + "validators_on_decode", + "dependency_protocol", + "dependency_and_own_protocols", + "nested_protocol" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "optional-fields": { + "note": null, + "proven_by": [ + "optional_and_arrays", + "type_refs", + "shapes", + "cross_schema", + "validators", + "validators_on_decode", + "large_fixed_arrays_nested", + "bounds" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "protocols": { + "note": null, + "proven_by": [ + "protocol", + "error_shapes", + "validators", + "validators_on_decode", + "framing_jsonrpc", + "handshake_none", + "framing_datagram3", + "handshake_comline2", + "lockstep", + "connections", + "connections_async", + "connections_jsonrpc", + "connections_default", + "format_json", + "dependency_protocol", + "dependency_and_own_protocols", + "nested_protocol" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "structs": { + "note": null, + "proven_by": [ + "primitives", + "optional_and_arrays", + "type_refs", + "protocol", + "shapes", + "cross_schema", + "import_alias", + "import_glob", + "nested_namespace", + "external_std", + "validators", + "validators_on_decode", + "unions", + "large_fixed_arrays_nested", + "lockstep", + "format_json", + "bounds", + "chars", + "dependency_protocol", + "dependency_and_own_protocols", + "nested_protocol" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "throws": { + "note": null, + "proven_by": [ + "protocol", + "error_shapes", + "lockstep", + "format_json" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "type-aliases": { + "note": null, + "proven_by": [ + "validators", + "validators_on_decode", + "unions", + "bounds" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "unions": { + "note": null, + "proven_by": [ + "unions" + ], + "since": null, + "state": "supported", + "tracking": null + }, + "validate-on-decode": { + "note": "no checks are generated to run on decode yet", + "proven_by": [ + "validators_on_decode" + ], + "since": null, + "state": "ignored", + "tracking": "core#96" + }, + "validators": { + "note": "the types are generated; the checks aren't run yet", + "proven_by": [ + "validators", + "validators_on_decode" + ], + "since": null, + "state": "ignored", + "tracking": "core#96" + } + }, + "version": "5.0", + "versions": { + "changes": [], + "floor": "5.0", + "forward_compatible": false, + "verified_up_to": "5.9" + } + } + ] +} diff --git a/xtask/Cargo.toml b/xtask/Cargo.toml index f4cc303..3ffb81c 100644 --- a/xtask/Cargo.toml +++ b/xtask/Cargo.toml @@ -8,7 +8,7 @@ publish = false # Same revs `codegen` pins, so this tool and the generator it drives agree on # one `comline-core` - see codegen/Cargo.toml's own comment. comline-core = { git = "https://github.com/ComlineProject/core", rev = "69039e7ab05953760bb7a6818f61e98c14b43922" } -comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "e900919375429591d73c906380f1d354d636ab22" } +comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "31e808ff05632acbfa4f48d208b8d5a2fbca3b0e" } comline-codegen-typescript = { path = "../codegen" } eyre = "0.6.8"