diff --git a/codegen/Cargo.toml b/codegen/Cargo.toml index 413e86e..ac29571 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 = "da81b688c949a0ebad4f213d6fdb648920cf641d" } +comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "922847b608764687b9d75020ff46a3f24d43b5bd" } comline-core = { git = "https://github.com/ComlineProject/core", rev = "868e8310e33df317e3cba4f76b81fbcd8639c1c2", default-features = false } eyre = "0.6.8" @@ -21,6 +21,6 @@ path = "src/bin/comline-gen-typescript.rs" # 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 = "da81b688c949a0ebad4f213d6fdb648920cf641d" } +comline-conformance = { git = "https://github.com/ComlineProject/generation", rev = "922847b608764687b9d75020ff46a3f24d43b5bd" } # The tests compile schemas, so they need core's compiler. comline-core = { git = "https://github.com/ComlineProject/core", rev = "868e8310e33df317e3cba4f76b81fbcd8639c1c2" } diff --git a/codegen/src/generator.rs b/codegen/src/generator.rs index ab7ce1c..206f99c 100644 --- a/codegen/src/generator.rs +++ b/codegen/src/generator.rs @@ -97,8 +97,8 @@ pub fn generate_typescript(req: &GenerateRequest) -> Result> comline_codegen::facts::check(req)?; let codec = type_of(&req.encodings, &req.wire_format); // JSON-RPC protocols sharing a connection whose bare method names one - // side couldn't tell apart. - connections::check(&req.schemas, &req.encodings)?; + // side couldn't tell apart; a dependency's protocols aren't on it. + connections::check_in(req)?; let external_std = req.external_std; // With `external_std`, std's schemas aren't this package's to emit - it @@ -1284,6 +1284,17 @@ fn package_module(header: &str, req: &GenerateRequest, emitted: &[(String, Vec String { + let mut path = comline_codegen::facts::namespace_segments(namespace).collect::>().join("::"); + path.push_str("::"); + path.push_str(name); + path +} + /// The package module's `comline@2` items: this end's Hello (the facts it was /// generated from), `handshake()` with the parameters the package states, and /// `negotiated` / `warnings` for what a connection agreed. @@ -1307,10 +1318,9 @@ fn comline2_items( .map(|(f, n)| format!("`{f}` {n}")) .collect(); s.push_str(&format!( - " * - {} `{}::{}`, line {}: {}\n", + " * - {} `{}`, line {}: {}\n", p.number, - p.namespace, - p.name, + display_path(&p.namespace, &p.name), p.line, functions.join(", ") )); @@ -1339,7 +1349,7 @@ fn comline2_items( )); let paths: Vec = protocols .iter() - .map(|p| format!("[{}, \"{}::{}\"]", p.number, p.namespace, p.name)) + .map(|p| format!("[{}, \"{}\"]", p.number, display_path(&p.namespace, &p.name))) .collect(); s.push_str(&format!( "/** The package's protocols on the connection, by wire number. */\n\ @@ -1769,14 +1779,15 @@ fn protocol( _ => None, }) .collect(); + let path = display_path(namespace, proto); for (i, f) in fns.iter().enumerate() { let id = calls[i]; // Under `comline@2`, checked against what the connection agreed // before it's written. let check = match &checks { Some(c) => format!( - " {check_call}(this.peer, {proto}Sender.PROTOCOL, {}, \"{namespace}::{proto}\", \"{}\");\n", - c[i], fn_names[i] + " {check_call}(this.peer, {proto}Sender.PROTOCOL, {}, \"{}\", \"{}\");\n", + c[i], path, fn_names[i] ), None => String::new(), }; diff --git a/codegen/tests/nested_namespaces.rs b/codegen/tests/nested_namespaces.rs new file mode 100644 index 0000000..a1d84cc --- /dev/null +++ b/codegen/tests/nested_namespaces.rs @@ -0,0 +1,165 @@ +//! A protocol in a nested schema (`chat/admin`, generation#148) and a package +//! whose dependency's protocols share a method name with its own +//! (generation#147). +//! +//! A protocol's path in the generated text is `chat::admin::Admin`, every +//! segment joined by `::`, not the request's `chat/admin::Admin`; only the +//! text, no number, order or hash is made from it. The output is kept in +//! `runtime/test/generated/nested/` and `runtime/test/generated/clash/` so the +//! Node job type-checks it (`npm run typecheck:generated`). Regenerate with +//! `TS_BLESS=1 cargo test -p comline-codegen-typescript`. + +use comline_codegen::validation::ValidateOnDecode; +use comline_codegen::{connections, facts, GenerateRequest, PackageMeta, TargetLanguage}; +use comline_codegen_typescript::generate_typescript; +use comline_conformance::{dependency_and_own_protocols, nested_protocol, Fixture}; +use comline_core::schema::ir::frozen::unit::{ConfigValue, FrozenUnit}; + +/// The request `comline generation` would send for `fx`: with the facts of the +/// package's own schemas when they're needed. +fn request(fx: &Fixture) -> GenerateRequest { + let dependencies: Vec = fx.dependencies.iter().map(|d| d.to_string()).collect(); + let own: Vec<_> = fx + .schemas + .iter() + .filter(|(namespace, _)| !connections::is_dependency(&dependencies, namespace)) + .cloned() + .collect(); + let mut req = GenerateRequest { + mode: fx.mode, + schemas: fx.schemas.clone(), + package: PackageMeta { name: "conformance".into(), version: "0.1.0".into() }, + target: TargetLanguage { + language: "typescript".into(), + version: comline_codegen_typescript::LANG_VERSION.into(), + }, + wire_format: "packed@1".into(), + external_std: false, + validate_on_decode: ValidateOnDecode::Off, + async_api: false, + encodings: comline_codegen::encodings::official_for("typescript"), + facts: None, + dependencies, + }; + if facts::needed_in(&req) { + req.facts = Some(comline_conformance::facts_for(&own, "packed@1")); + } + req +} + +/// Every file generated for `req`, checked against `runtime/test/generated/`. +fn generated(req: &GenerateRequest, dir: &str) -> Vec<(String, String)> { + let files = generate_typescript(req).unwrap_or_else(|e| panic!("{dir}: {e:#}")); + let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../runtime/test/generated").join(dir); + let mut out = Vec::new(); + for file in files { + let path = root.join(&file.path); + if std::env::var_os("TS_BLESS").is_some() { + std::fs::create_dir_all(path.parent().unwrap()).unwrap(); + std::fs::write(&path, &file.contents).unwrap(); + } else { + let committed = std::fs::read_to_string(&path).unwrap_or_default(); + assert_eq!( + file.contents, committed, + "generated output drifted from {} — re-bless with TS_BLESS=1 cargo test -p comline-codegen-typescript", + path.display() + ); + } + out.push((file.path.to_str().unwrap().to_string(), file.contents)); + } + out +} + +fn file<'a>(files: &'a [(String, String)], path: &str) -> &'a str { + &files.iter().find(|(p, _)| p == path).unwrap_or_else(|| panic!("no `{path}` in {:?}", files.iter().map(|(p, _)| p).collect::>())).1 +} + +/// The protocol's path reads `chat::admin::Admin` everywhere the generated +/// text shows it: the Hello comment, `PROTOCOLS` and the `checkCall` the +/// sender makes (which is what an `Unavailable` error names). The request's +/// `chat/admin` spelling is nowhere in it. +#[test] +fn a_nested_protocols_path_is_spelled_with_colons() { + let files = generated(&request(&nested_protocol()), "nested"); + + let connection = file(&files, "connection.ts"); + assert!(connection.contains(" * - 0 `chat::admin::Admin`, line 0.1.0: `greet` 0\n"), "{connection}"); + assert!(connection.contains("new Map([[0, \"chat::admin::Admin\"]])"), "{connection}"); + + let admin = file(&files, "chat/admin.ts"); + assert!(admin.contains(", \"chat::admin::Admin\", \"greet\");"), "{admin}"); + + for (path, text) in &files { + assert!(!text.contains("chat/admin::"), "{path}: {text}"); + assert!(!text.contains("`chat/admin"), "{path}: {text}"); + } +} + +/// The display path is the only thing that changed: the facts-addressed wire +/// numbers and the connection's hash are the same whichever way the namespace +/// is spelled. +#[test] +fn the_display_path_changes_no_number_or_hash() { + let req = request(&nested_protocol()); + let files = generated(&req, "nested"); + let connection = file(&files, "connection.ts"); + let hash = format!("CONNECTION_IR_HASH = {:#018x}n;", connections::connection_ir_hash(&req.schemas)); + assert!(connection.contains(&hash), "{connection}"); + let admin = file(&files, "chat/admin.ts"); + assert!(admin.contains("checkCall(this.peer, AdminSender.PROTOCOL, 0, "), "{admin}"); +} + +/// A dependency's `jsonrpc` protocol sharing a function name with the +/// package's own is no clash: the dependency's isn't on the package's +/// connection (generation#147), so generation isn't refused. +#[test] +fn a_dependencys_jsonrpc_method_name_does_not_refuse_generation() { + let mut fixture = dependency_and_own_protocols(); + let jsonrpc = || FrozenUnit::Property { name: "framing".to_string(), value: ConfigValue::Str("jsonrpc".to_string()) }; + for (_, units) in &mut fixture.schemas { + for unit in units { + if let FrozenUnit::Protocol { parameters, .. } = unit { + for p in parameters.iter_mut() { + if matches!(p, FrozenUnit::Property { name, .. } if name == "framing") { + *p = jsonrpc(); + } + } + } + } + } + // The client provides `Events`, which is what puts `jsonrpc` protocols on a + // connection where bare method names matter. + let api = &mut fixture.schemas.iter_mut().find(|(n, _)| n == "api").unwrap().1; + let mut events = api.iter().find(|u| matches!(u, FrozenUnit::Protocol { name, .. } if name == "Chat")).unwrap().clone(); + if let FrozenUnit::Protocol { name, parameters, functions, .. } = &mut events { + *name = "Events".to_string(); + parameters.push(FrozenUnit::Property { name: "provider".to_string(), value: ConfigValue::Name("Client".to_string()) }); + if let Some(FrozenUnit::Function { name, .. }) = functions.first_mut() { + *name = "notify".to_string(); + } + } + api.push(events); + let req = request(&fixture); + + // `localdeps`' `Foo` and the package's `Chat` both have `greet`, which the + // check unaware of dependencies refuses. + assert!(connections::check(&req.schemas, &req.encodings).is_err()); + assert!(connections::check_in(&req).is_ok()); + + let files = generated(&req, "clash"); + assert!(file(&files, "localdeps/greeting.ts").contains("export interface Foo")); + let connection = file(&files, "connection.ts"); + assert!(connection.contains("chat: ns_api.Chat;"), "{connection}"); + assert!(connection.contains("events: ns_api.Events;"), "{connection}"); + assert!(!connection.contains("Foo"), "{connection}"); + + // Two of the package's own still clash, the dependency or not. + let mut own = req.clone(); + let api = &mut own.schemas.iter_mut().find(|(n, _)| n == "api").unwrap().1; + let mut admin = api.iter().find(|u| matches!(u, FrozenUnit::Protocol { name, .. } if name == "Chat")).unwrap().clone(); + if let FrozenUnit::Protocol { name, .. } = &mut admin { + *name = "Admin".to_string(); + } + api.push(admin); + assert!(connections::check_in(&own).is_err()); +} diff --git a/runtime/test/generated/clash/api.ts b/runtime/test/generated/clash/api.ts new file mode 100644 index 0000000..ff0df7a --- /dev/null +++ b/runtime/test/generated/clash/api.ts @@ -0,0 +1,181 @@ +// 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 = 0xa14195a41e817a01n; + +/** 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 = 0xe9ca523b62a2c19fn; + +export interface Message { + greeting: Greeting; +} + +export const MessageLayout: Layout = { struct: [["greeting", () => GreetingLayout]] }; + +export interface ChatGreetParams { + n: number; +} + +export const ChatGreetParamsLayout: Layout = { struct: [["n", "u32"]] }; + +export interface Chat { + greet(peer: Peer, params: ChatGreetParams): Promise; +} + +export const CHAT_CALLS = ["greet"] as const; + +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, 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); + } +} + +export interface EventsNotifyParams { + n: number; +} + +export const EventsNotifyParamsLayout: Layout = { struct: [["n", "u32"]] }; + +export interface Events { + notify(peer: Peer, params: EventsNotifyParams): Promise; +} + +export const EVENTS_CALLS = ["notify"] as const; + +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, EventsNotifyParamsLayout); + reply.ok(codec.encode((await this.impl.notify(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(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 notify(params: EventsNotifyParams): Promise { + checkCall(this.peer, EventsSender.PROTOCOL, 0, "api::Events", "notify"); + const env = await this.peer.call(EventsSender.PROTOCOL, { id: 0, name: "notify" }, params, { layout: EventsNotifyParamsLayout }); + 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/runtime/test/generated/clash/connection.ts b/runtime/test/generated/clash/connection.ts new file mode 100644 index 0000000..3f78b96 --- /dev/null +++ b/runtime/test/generated/clash/connection.ts @@ -0,0 +1,120 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + Connection, + JsonCodec, + JsonRpcConnectionFraming, + PackedCodec, + Comline2Handshake, + Negotiated, + type Codec, + type Peer, + type Transport, +} from "@comline/runtime"; +import * as ns_api from "./api.js"; + +/** The package's wire format (`wire.format`). */ +export const Format: Codec = new PackedCodec(); + +/** Digest of every schema in the package — what a connection's handshake +* checks, so both ends agree on each protocol's number. */ +export const CONNECTION_IR_HASH = 0xe9ca523b62a2c19fn; + +/** + * 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 + * - 1 `api::Events`, line 0.1.0: `notify` 0 + */ +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, 0xff, 0xa1, 0x4e, 0xb2, + 0xbc, 0x0a, 0xe6, 0x18, 0x4d, 0x69, 0xb5, 0xac, 0xc5, 0x70, 0x91, 0x7e, + 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, + 0x01, 0x00, +]); + +/** The `comline@2` handshake, with {@link HELLO} and the parameters the package states. */ +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"], [1, "api::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_api.Chat; +} + +/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +export function provideServices(conn: Connection, services: Services): void { + new ns_api.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_api.Events; +} + +/** Provide every protocol in `services` on `conn`: the peer's calls to them come here. */ +export function provideClientServices(conn: Connection, services: ClientServices): void { + new ns_api.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, new JsonCodec(), CONNECTION_IR_HASH, new JsonRpcConnectionFraming(), 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, new JsonCodec(), CONNECTION_IR_HASH, new JsonRpcConnectionFraming(), agreed); + conn.extensions.set(agreed.negotiated!); + provideClientServices(conn, services); + return conn; +} diff --git a/runtime/test/generated/clash/localdeps/greeting.ts b/runtime/test/generated/clash/localdeps/greeting.ts new file mode 100644 index 0000000..2b81491 --- /dev/null +++ b/runtime/test/generated/clash/localdeps/greeting.ts @@ -0,0 +1,102 @@ +// 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 = 0x3c4249f5704f3397n; + +/** 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 = 0xe9ca523b62a2c19fn; + +export interface Greeting { + text: string; +} + +export const GreetingLayout: Layout = { struct: [["text", "string"]] }; + +export interface FooGreetParams { + n: number; +} + +export const FooGreetParamsLayout: Layout = { struct: [["n", "u32"]] }; + +export interface Foo { + greet(peer: Peer, params: FooGreetParams): Promise; +} + +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 (resolveKind(call, FOO_CALLS)) { + 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, new JsonCodec(), CONNECTION_IR_HASH, new JsonRpcConnectionFraming(), 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/runtime/test/generated/nested/chat/admin.ts b/runtime/test/generated/nested/chat/admin.ts new file mode 100644 index 0000000..eb84a27 --- /dev/null +++ b/runtime/test/generated/nested/chat/admin.ts @@ -0,0 +1,109 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + RuntimeError, + resolveKind, + checkCall, + 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 = 0xa6f61afefe65d74an; + +/** Digest of every schema in the package — what a connection's handshake +* checks, so both ends agree on each protocol's number. */ +export const CONNECTION_IR_HASH = 0xa6f61afefe65d74an; + +/** The package's wire format (`wire.format`): what this file's helpers +* encode with, and what the peer has to speak too. */ +export const Format: Codec = new PackedCodec(); + +export interface Notice { + text: string; +} + +export const NoticeLayout: Layout = { struct: [["text", "string"]] }; + +export interface AdminGreetParams { + n: number; +} + +export const AdminGreetParamsLayout: Layout = { struct: [["n", "u32"]] }; + +export interface Admin { + greet(peer: Peer, params: AdminGreetParams): Promise; +} + +export const ADMIN_CALLS = ["greet"] as const; + +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/runtime/test/generated/nested/connection.ts b/runtime/test/generated/nested/connection.ts new file mode 100644 index 0000000..dc47823 --- /dev/null +++ b/runtime/test/generated/nested/connection.ts @@ -0,0 +1,105 @@ +// Generated by Comline +// For TypeScript 5.0 or later; verified up to 5.9. + +import { + Connection, + Datagram3Framing, + PackedCodec, + Comline2Handshake, + Negotiated, + type Codec, + type Peer, + type Transport, +} from "@comline/runtime"; +import * as ns_chat_admin from "./chat/admin.js"; + +/** The package's wire format (`wire.format`). */ +export const Format: Codec = new PackedCodec(); + +/** Digest of every schema in the package — what a connection's handshake +* checks, so both ends agree on each protocol's number. */ +export const CONNECTION_IR_HASH = 0xa6f61afefe65d74an; + +/** + * 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 + */ +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. */ +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. */ +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, then provide every protocol in +* `services`, which the server calls. 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/xtask/Cargo.toml b/xtask/Cargo.toml index 18f57d1..e7af45b 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 = "868e8310e33df317e3cba4f76b81fbcd8639c1c2" } -comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "da81b688c949a0ebad4f213d6fdb648920cf641d" } +comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "922847b608764687b9d75020ff46a3f24d43b5bd" } comline-codegen-typescript = { path = "../codegen" } eyre = "0.6.8"