diff --git a/Cargo.lock b/Cargo.lock index a67f64c..f40e315 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -117,7 +117,7 @@ dependencies = [ [[package]] name = "comline-catalog" -version = "0.10.0" +version = "0.11.0" [[package]] name = "comline-reference" diff --git a/runtime/conformance/reports/rust.json b/runtime/conformance/reports/rust.json index a3a9105..9c41c53 100644 --- a/runtime/conformance/reports/rust.json +++ b/runtime/conformance/reports/rust.json @@ -376,6 +376,7 @@ "state": "supported", "proven_by": [ "framing-datagram3/request", + "framing-datagram3/request-two-byte-protocol", "framing-datagram3/request-two-byte-numbers", "framing-datagram3/request-large-ids", "framing-datagram3/request-params-msgpack", diff --git a/runtime/conformance/spec/README.md b/runtime/conformance/spec/README.md index 1df1fa0..542b501 100644 --- a/runtime/conformance/spec/README.md +++ b/runtime/conformance/spec/README.md @@ -6,7 +6,7 @@ proven, the formats of these files, and the catalog of names they share. A runti tool implements against this repository, and pins it like any other dependency. Comline's own runtimes do the same. -Version: **0.10** ([`VERSION`](VERSION)). While Comline is in its early days +Version: **0.11** ([`VERSION`](VERSION)). While Comline is in its early days (0.x), a minor version may change anything, and the change is named in the pull request that makes it and in [the changes](#changes) below. @@ -32,6 +32,9 @@ will read it. - `vectors/.json`: that feature's cases. - [`benches/`](benches/README.md): the benchmarks every runtime runs, in the same value encoding. +- [`compiler/`](compiler/readme.md): compiler conformance cases, schema + graphs with the guarantees they give up and the diagnostics a build must + report, for a compiler or any tool that judges a package. - [`specs/`](specs/readme.md): the format of each of these files, in CUE, and the JSON Schemas generated from it, which each file names in `$schema`. @@ -213,7 +216,11 @@ What an implementation answers, and how its answers are judged: response; a response's input holds only the ordinal, so `by_ordinal` and `by_name` rest on the case passing. Its `payload` is shown by requests: an exact one with non-JSON params for `opaque`, and for `json`, an exact one with - JSON params and a refusal of that same frame with non-JSON in their place. A + JSON params and a refusal of that same frame with non-JSON in their place. Its + `protocol` is shown by exact `request` cases: for `named`, ones whose `protocol` + is 128 or more, isn't their `call_id`, and whose bytes hold that number as a + varint; for `unnamed`, ones whose input has no `protocol`, which decoding their + bytes gives back without one. A format's `output` is shown by exact `encode` cases: all JSON for `json`, and at least one not for `bytes`. Its other facts are shown by `decode` cases of the `Point` and `Color` shapes the official profiles use. A handshake's facts @@ -222,6 +229,24 @@ What an implementation answers, and how its answers are judged: ### Changes +- **0.11:** a framing states `protocol`: `named`, when a request's frame names the + protocol it calls into, by number or wire id, so several protocols can share one + transport, or `unnamed`, when it doesn't and a call names only its function. A + profile without it is refused. `datagram@2` and `datagram@3` are `named`; + `datagram@1` and `jsonrpc@1` are `unnamed`. JSON-RPC's `qualified` method names + (`chat.Chat/send`, which `request-qualified-method` shows) are a parameter of + the framing, not part of its profile: a request holds a method, and writing the + protocol into it is the caller's choice, so the framing doesn't name one. + Reused cases: + `framing-datagram2/request-two-byte-protocol` for `datagram@2`, + `framing-datagram/request` and `request-large-id` for `datagram@1`, and + `framing-jsonrpc/request` and `request-large-id` for `jsonrpc@1`. New case, on + `datagram@3`: `request-two-byte-protocol` (protocol 300, call 1, so the protocol's two + varint bytes are in the frame and no function number can be mistaken for + them); its bytes are `datagram@2`'s case of the same name with the call id + as `datagram@3` writes it, a varint (`01`), not `datagram@2`'s two bytes (`0100`). A runtime must reproduce it. No frame's + bytes change, and no other case. `specs/protocol.jq` holds each framing's + `protocol` to its cases, in `specs/check.sh`. - **0.10:** a framing states `directions`: `both`, when a frame says whether it's a request or a response so calls can go both ways on one transport, or `one`, when it doesn't. A profile without it is refused. New cases, on `datagram@2`, @@ -422,6 +447,9 @@ profile states it until live cross-runtime calls can prove it (see below). ## Implementing the spec +A compiler or another tool that judges packages vendors `compiler/cases/` +instead, and runs it as [`compiler/readme.md`](compiler/readme.md) says. + Vendor `features.json`, `vectors/` and `profiles/` at a pinned commit of this repository, and `specs/gen/` too if you want their `$schema` to resolve; a reader ignores it. `catalog/gen/catalog.json` holds the names and their diff --git a/runtime/conformance/spec/REV b/runtime/conformance/spec/REV index bb47add..6857159 100644 --- a/runtime/conformance/spec/REV +++ b/runtime/conformance/spec/REV @@ -1 +1 @@ -9a7142c395b2aefb7d4d77e9b36c74187c6f0199 +69882e92971e243b6b74a539a13b534d95b3abf7 diff --git a/runtime/conformance/spec/VERSION b/runtime/conformance/spec/VERSION index 68c123c..51176c7 100644 --- a/runtime/conformance/spec/VERSION +++ b/runtime/conformance/spec/VERSION @@ -1 +1 @@ -0.10 +0.11 diff --git a/runtime/conformance/spec/catalog/facts.cue b/runtime/conformance/spec/catalog/facts.cue index 0f4eb65..5894fd8 100644 --- a/runtime/conformance/spec/catalog/facts.cue +++ b/runtime/conformance/spec/catalog/facts.cue @@ -106,6 +106,16 @@ facts: { json: "JSON text, written into the frame" } } + protocol: { + applies_to: "framing" + title: "protocol" + description: "Whether a request's frame names the protocol it calls into." + since: "0.11" + values: { + named: "it does, by number or wire id, so several protocols can share one transport" + unnamed: "it doesn't: a call names only its function" + } + } schema_agreement: { applies_to: "handshake" title: "schema agreement" diff --git a/runtime/conformance/spec/catalog/gen/catalog.json b/runtime/conformance/spec/catalog/gen/catalog.json index 70f5156..5aeb4dc 100644 --- a/runtime/conformance/spec/catalog/gen/catalog.json +++ b/runtime/conformance/spec/catalog/gen/catalog.json @@ -169,6 +169,17 @@ "json": "JSON text, written into the frame" } }, + "protocol": { + "applies_to": "framing", + "status": "stable", + "title": "protocol", + "description": "Whether a request's frame names the protocol it calls into.", + "since": "0.11", + "values": { + "named": "it does, by number or wire id, so several protocols can share one transport", + "unnamed": "it doesn't: a call names only its function" + } + }, "schema_agreement": { "applies_to": "handshake", "status": "stable", @@ -1082,7 +1093,8 @@ "calls", "directions", "errors", - "payload" + "payload", + "protocol" ], "handshake_facts": [ "schema_agreement", diff --git a/runtime/conformance/spec/compiler/cases/acceptance.json b/runtime/conformance/spec/compiler/cases/acceptance.json new file mode 100644 index 0000000..3a31d6c --- /dev/null +++ b/runtime/conformance/spec/compiler/cases/acceptance.json @@ -0,0 +1,270 @@ +{ + "$schema": "../../specs/gen/compiler.schema.json", + "group": "acceptance", + "cases": [ + { + "id": "acceptance/not-accepted", + "description": "an unverified protocol of a dependency has to be accepted", + "packages": [ + { + "name": "billing", + "config": "congregation billing\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = \"the 2009 gateway\"\nprotocol Billing {\n function charge();\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "app", + "config": "congregation app\nspecification_version = 1\ndependencies = {\n billing = {\n path = \"../billing\"\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct A {\n x: u32\n}\n" + } + ], + "dependencies": [ + { + "name": "billing" + } + ] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [], + "error_contains": [ + "protocol `Billing` is unverified, giving up schema agreement and encoding agreement", + "the 2009 gateway" + ] + } + }, + { + "id": "acceptance/accepted", + "description": "accepted for exactly what it gives up, it builds", + "packages": [ + { + "name": "billing", + "config": "congregation billing\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = \"the 2009 gateway\"\nprotocol Billing {\n function charge();\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "app", + "config": "congregation app\nspecification_version = 1\ndependencies = {\n billing = {\n path = \"../billing\"\n accept_unverified = { Billing = [\"schema_agreement\", \"encoding_agreement\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct A {\n x: u32\n}\n" + } + ], + "dependencies": [ + { + "name": "billing", + "accept_unverified": { + "Billing": [ + "schema_agreement", + "encoding_agreement" + ] + } + } + ] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "acceptance/accepted-for-less", + "description": "accepted for less than it gives up, it stops again", + "packages": [ + { + "name": "billing", + "config": "congregation billing\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = \"the 2009 gateway\"\nprotocol Billing {\n function charge();\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "app", + "config": "congregation app\nspecification_version = 1\ndependencies = {\n billing = {\n path = \"../billing\"\n accept_unverified = { Billing = [\"schema_agreement\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct A {\n x: u32\n}\n" + } + ], + "dependencies": [ + { + "name": "billing", + "accept_unverified": { + "Billing": [ + "schema_agreement" + ] + } + } + ] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [], + "error_contains": [ + "protocol `Billing` now gives up schema agreement and encoding agreement", + "it was accepted for schema agreement" + ] + } + }, + { + "id": "acceptance/accepted-for-more", + "description": "accepted for more than it gives up, it stops too: the set has to match exactly", + "packages": [ + { + "name": "billing", + "config": "congregation billing\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = \"the 2009 gateway\"\nprotocol Billing {\n function charge();\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "app", + "config": "congregation app\nspecification_version = 1\ndependencies = {\n billing = {\n path = \"../billing\"\n accept_unverified = { Billing = [\"schema_agreement\", \"encoding_agreement\", \"bounded_size\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct A {\n x: u32\n}\n" + } + ], + "dependencies": [ + { + "name": "billing", + "accept_unverified": { + "Billing": [ + "schema_agreement", + "encoding_agreement", + "bounded_size" + ] + } + } + ] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [], + "error_contains": [ + "protocol `Billing` now gives up schema agreement and encoding agreement" + ] + } + }, + { + "id": "acceptance/package-reasons-shown", + "description": "what the package said once is what the consumer is shown to accept", + "packages": [ + { + "name": "billing", + "config": "congregation billing\nspecification_version = 1\nhandshake = \"none\"\nunverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n encoding_agreement = \"the gateway only speaks one encoding\"\n}\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol Billing {\n function charge();\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "app", + "config": "congregation app\nspecification_version = 1\ndependencies = {\n billing = {\n path = \"../billing\"\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct A {\n x: u32\n}\n" + } + ], + "dependencies": [ + { + "name": "billing" + } + ] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [], + "error_contains": [ + "protocol `Billing` is unverified, giving up schema agreement and encoding agreement", + "schema agreement \"the gateway pins schemas by contract\"", + "encoding agreement \"the gateway only speaks one encoding\"" + ] + } + }, + { + "id": "acceptance/judged-by-its-own-package", + "description": "a dependency is judged by its own package's settings and default handshake, not the consumer's", + "packages": [ + { + "name": "billing", + "config": "congregation billing\nspecification_version = 1\nhandshake = \"none\"\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@unverified = \"the 2009 gateway\"\nprotocol Billing {\n function charge();\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "app", + "config": "congregation app\nspecification_version = 1\ndependencies = {\n billing = {\n path = \"../billing\"\n accept_unverified = { Billing = [\"schema_agreement\", \"encoding_agreement\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct A {\n x: u32\n}\n" + } + ], + "dependencies": [ + { + "name": "billing", + "accept_unverified": { + "Billing": [ + "schema_agreement", + "encoding_agreement" + ] + } + } + ] + } + ], + "build": "app", + "expect": { + "protocols": [], + "builds": true, + "diagnostics": [] + } + } + ] +} diff --git a/runtime/conformance/spec/compiler/cases/bounded.json b/runtime/conformance/spec/compiler/cases/bounded.json new file mode 100644 index 0000000..41da32b --- /dev/null +++ b/runtime/conformance/spec/compiler/cases/bounded.json @@ -0,0 +1,376 @@ +{ + "$schema": "../../specs/gen/compiler.schema.json", + "group": "bounded", + "cases": [ + { + "id": "bounded/string-unmarked", + "description": "a string without a maximum is an error where no marker gives bounded size up", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function put(s: string);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "bounds::unbounded", + "severity": "error" + } + ] + } + }, + { + "id": "bounded/list-unmarked", + "description": "a list without a maximum is an error too", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function put(xs: u8[]);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "bounds::unbounded", + "severity": "error" + } + ] + } + }, + { + "id": "bounded/bounded", + "description": "a string and a list with maximums give nothing up", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function put(s: char[max 64], xs: u8[max 16]);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [] + } + ], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "bounded/string-marked", + "description": "a marked protocol gives bounded_size up for a string without a maximum", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@unverified = \"the uploader streams whatever it's given\"\nprotocol P {\n function put(s: string);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "bounded_size" + ], + "acknowledged": [ + { + "guarantee": "bounded_size", + "scope": "protocol", + "reason": "the uploader streams whatever it's given" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::bounded-size", + "severity": "warning" + } + ] + } + }, + { + "id": "bounded/keyed-for-something-else", + "description": "a keyed marker that doesn't list bounded_size doesn't cover a string without a maximum", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@unverified = { version_honesty = \"not this\" }\nprotocol P {\n function put(s: string);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::missing-guarantee", + "severity": "error" + } + ] + } + }, + { + "id": "bounded/recursion-unmarked", + "description": "a type that contains itself without @max_depth is an error", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct Node {\n kids: Node[max 4]\n}\n\nprotocol P {\n function f(n: Node);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "bounds::unbounded-depth", + "severity": "error" + } + ] + } + }, + { + "id": "bounded/recursion-marked", + "description": "a marked protocol gives bounded_size up for a type that contains itself without @max_depth", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct Node {\n kids: Node[max 4]\n}\n\n@unverified = \"trees are small in practice\"\nprotocol P {\n function f(n: Node);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "bounded_size" + ], + "acknowledged": [ + { + "guarantee": "bounded_size", + "scope": "protocol", + "reason": "trees are small in practice" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::bounded-size", + "severity": "warning" + } + ] + } + }, + { + "id": "bounded/recursion-max-depth", + "description": "a type that contains itself under @max_depth gives nothing up", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@max_depth = 4\nstruct Node {\n kids: Node[max 4]\n}\n\nprotocol P {\n function f(n: Node);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [] + } + ], + "builds": true, + "diagnostics": [] + } + }, + { + "id": "bounded/other-schema-unmarked", + "description": "a type from another schema that holds a string without a maximum is unbounded where an unmarked protocol uses it", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/models.ids", + "text": "struct Blob {\n data: string\n}\n\n@unverified = \"the uploader streams whatever it's given\"\nprotocol Upload {\n function put(b: Blob);\n}\n" + }, + { + "path": "src/api.ids", + "text": "use models::Blob\n\nprotocol Orders {\n function send(b: Blob);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "bounds::unbounded", + "severity": "error" + } + ] + } + }, + { + "id": "bounded/other-schema-marked", + "description": "a marked protocol using it gives bounded_size up, as the one that declares it does", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/models.ids", + "text": "struct Blob {\n data: string\n}\n\n@unverified = \"the uploader streams whatever it's given\"\nprotocol Upload {\n function put(b: Blob);\n}\n" + }, + { + "path": "src/api.ids", + "text": "use models::Blob\n\n@unverified = \"orders carry the upload\"\nprotocol Orders {\n function send(b: Blob);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "Upload", + "given_up": [ + "bounded_size" + ], + "acknowledged": [ + { + "guarantee": "bounded_size", + "scope": "protocol", + "reason": "the uploader streams whatever it's given" + } + ] + }, + { + "name": "Orders", + "given_up": [ + "bounded_size" + ], + "acknowledged": [ + { + "guarantee": "bounded_size", + "scope": "protocol", + "reason": "orders carry the upload" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::bounded-size", + "severity": "warning" + } + ] + } + }, + { + "id": "bounded/other-schema-bounded", + "description": "a type bounded where it is declared is bounded where it is used", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/models.ids", + "text": "struct Blob {\n data: char[max 64]\n}\n" + }, + { + "path": "src/api.ids", + "text": "use models::Blob\n\nprotocol Orders {\n function send(b: Blob);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "Orders", + "given_up": [] + } + ], + "builds": true, + "diagnostics": [] + } + } + ] +} diff --git a/runtime/conformance/spec/compiler/cases/chain.json b/runtime/conformance/spec/compiler/cases/chain.json new file mode 100644 index 0000000..6a36334 --- /dev/null +++ b/runtime/conformance/spec/compiler/cases/chain.json @@ -0,0 +1,289 @@ +{ + "$schema": "../../specs/gen/compiler.schema.json", + "group": "chain", + "cases": [ + { + "id": "chain/unmarked-is-unbounded", + "description": "a type that holds another package's unbounded value, two packages away, is unbounded where an unmarked protocol uses it", + "packages": [ + { + "name": "a", + "config": "congregation a\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct Blob {\n data: string\n}\n\n@unverified = \"the uploader streams whatever it's given\"\nprotocol Upload {\n function put(b: Blob);\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "b", + "config": "congregation b\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\ndependencies = {\n a = {\n path = \"../a\"\n accept_unverified = { Upload = [\"bounded_size\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use a::api::Blob\n\nstruct Wrapper {\n blob: Blob\n}\n\n@unverified = \"wrapping uploads\"\nprotocol Wrap {\n function wrap(w: Wrapper);\n}\n" + } + ], + "dependencies": [ + { + "name": "a", + "accept_unverified": { + "Upload": [ + "bounded_size" + ] + } + } + ] + }, + { + "name": "c", + "config": "congregation c\nspecification_version = 1\ndependencies = {\n b = {\n path = \"../b\"\n accept_unverified = { Wrap = [\"bounded_size\"] Upload = [\"bounded_size\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use b::api::Wrapper\n\nprotocol Orders {\n function send(w: Wrapper);\n}\n" + } + ], + "dependencies": [ + { + "name": "b", + "accept_unverified": { + "Wrap": [ + "bounded_size" + ], + "Upload": [ + "bounded_size" + ] + } + } + ] + } + ], + "build": "c", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "bounds::unbounded", + "severity": "error" + } + ] + } + }, + { + "id": "chain/marked-gives-up", + "description": "a marked protocol using it gives bounded_size up, for its own consumers to accept", + "packages": [ + { + "name": "a", + "config": "congregation a\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct Blob {\n data: string\n}\n\n@unverified = \"the uploader streams whatever it's given\"\nprotocol Upload {\n function put(b: Blob);\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "b", + "config": "congregation b\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\ndependencies = {\n a = {\n path = \"../a\"\n accept_unverified = { Upload = [\"bounded_size\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use a::api::Blob\n\nstruct Wrapper {\n blob: Blob\n}\n\n@unverified = \"wrapping uploads\"\nprotocol Wrap {\n function wrap(w: Wrapper);\n}\n" + } + ], + "dependencies": [ + { + "name": "a", + "accept_unverified": { + "Upload": [ + "bounded_size" + ] + } + } + ] + }, + { + "name": "c", + "config": "congregation c\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\ndependencies = {\n b = {\n path = \"../b\"\n accept_unverified = { Wrap = [\"bounded_size\"] Upload = [\"bounded_size\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use b::api::Wrapper\n\n@unverified = \"orders carry the upload\"\nprotocol Orders {\n function send(w: Wrapper);\n}\n" + } + ], + "dependencies": [ + { + "name": "b", + "accept_unverified": { + "Wrap": [ + "bounded_size" + ], + "Upload": [ + "bounded_size" + ] + } + } + ] + } + ], + "build": "c", + "expect": { + "protocols": [ + { + "name": "Orders", + "given_up": [ + "bounded_size" + ], + "acknowledged": [ + { + "guarantee": "bounded_size", + "scope": "protocol", + "reason": "orders carry the upload" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::bounded-size", + "severity": "warning" + } + ] + } + }, + { + "id": "chain/acceptance-needs-every-link", + "description": "accepting b's protocol is not enough: a's, which b's package contains, is accepted too", + "packages": [ + { + "name": "a", + "config": "congregation a\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct Blob {\n data: string\n}\n\n@unverified = \"the uploader streams whatever it's given\"\nprotocol Upload {\n function put(b: Blob);\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "b", + "config": "congregation b\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\ndependencies = {\n a = {\n path = \"../a\"\n accept_unverified = { Upload = [\"bounded_size\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use a::api::Blob\n\nstruct Wrapper {\n blob: Blob\n}\n\n@unverified = \"wrapping uploads\"\nprotocol Wrap {\n function wrap(w: Wrapper);\n}\n" + } + ], + "dependencies": [ + { + "name": "a", + "accept_unverified": { + "Upload": [ + "bounded_size" + ] + } + } + ] + }, + { + "name": "c", + "config": "congregation c\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\ndependencies = {\n b = {\n path = \"../b\"\n accept_unverified = { Wrap = [\"bounded_size\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use b::api::Wrapper\n\n@unverified = \"orders carry the upload\"\nprotocol Orders {\n function send(w: Wrapper);\n}\n" + } + ], + "dependencies": [ + { + "name": "b", + "accept_unverified": { + "Wrap": [ + "bounded_size" + ] + } + } + ] + } + ], + "build": "c", + "expect": { + "builds": false, + "diagnostics": [], + "error_contains": [ + "protocol `Upload` is unverified, giving up bounded size" + ] + } + }, + { + "id": "chain/middle-doesnt-accept-the-first", + "description": "b's own build fails when it doesn't accept a's protocol, so building c does", + "packages": [ + { + "name": "a", + "config": "congregation a\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "struct Blob {\n data: string\n}\n\n@unverified = \"the uploader streams whatever it's given\"\nprotocol Upload {\n function put(b: Blob);\n}\n" + } + ], + "dependencies": [] + }, + { + "name": "b", + "config": "congregation b\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\ndependencies = {\n a = {\n path = \"../a\"\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use a::api::Blob\n\nstruct Wrapper {\n blob: Blob\n}\n\n@unverified = \"wrapping uploads\"\nprotocol Wrap {\n function wrap(w: Wrapper);\n}\n" + } + ], + "dependencies": [ + { + "name": "a" + } + ] + }, + { + "name": "c", + "config": "congregation c\nspecification_version = 1\ndependencies = {\n b = {\n path = \"../b\"\n accept_unverified = { Wrap = [\"bounded_size\"] Upload = [\"bounded_size\"] }\n }\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "use b::api::Wrapper\n\nprotocol Orders {\n function send(w: Wrapper);\n}\n" + } + ], + "dependencies": [ + { + "name": "b", + "accept_unverified": { + "Wrap": [ + "bounded_size" + ], + "Upload": [ + "bounded_size" + ] + } + } + ] + } + ], + "build": "c", + "expect": { + "builds": false, + "diagnostics": [], + "error_contains": [ + "protocol `Upload` is unverified, giving up bounded size" + ] + } + } + ] +} diff --git a/runtime/conformance/spec/compiler/cases/keyed.json b/runtime/conformance/spec/compiler/cases/keyed.json new file mode 100644 index 0000000..42e1f4f --- /dev/null +++ b/runtime/conformance/spec/compiler/cases/keyed.json @@ -0,0 +1,183 @@ +{ + "$schema": "../../specs/gen/compiler.schema.json", + "group": "keyed", + "cases": [ + { + "id": "keyed/exact-set", + "description": "a reason for each guarantee given up, and no others", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = {\n schema_agreement = \"the gateway predates Comline\",\n encoding_agreement = \"the gateway only speaks one encoding\"\n}\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "schema_agreement", + "encoding_agreement" + ], + "acknowledged": [ + { + "guarantee": "schema_agreement", + "scope": "protocol", + "reason": "the gateway predates Comline" + }, + { + "guarantee": "encoding_agreement", + "scope": "protocol", + "reason": "the gateway only speaks one encoding" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + } + ] + } + }, + { + "id": "keyed/unknown-guarantee", + "description": "a key that is no guarantee's id is an error", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = {\n schema_agreement = \"the gateway predates Comline\",\n encoding_agreement = \"the gateway only speaks one encoding\",\n bounded_sise = \"a typo\"\n}\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::unknown-guarantee", + "severity": "error" + } + ] + } + }, + { + "id": "keyed/missing-guarantee", + "description": "a guarantee given up and not listed is an error", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = { schema_agreement = \"the gateway predates Comline\" }\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::missing-guarantee", + "severity": "error" + } + ] + } + }, + { + "id": "keyed/not-given-up", + "description": "a guarantee listed and not given up is a warning, and not frozen", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = {\n schema_agreement = \"the gateway predates Comline\",\n encoding_agreement = \"the gateway only speaks one encoding\",\n version_honesty = \"just in case\"\n}\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "schema_agreement", + "encoding_agreement" + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::not-given-up", + "severity": "warning" + }, + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + } + ] + } + }, + { + "id": "keyed/duplicate-guarantee", + "description": "a guarantee listed twice is an error", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = {\n schema_agreement = \"the gateway predates Comline\",\n encoding_agreement = \"the gateway only speaks one encoding\",\n schema_agreement = \"again\"\n}\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::duplicate-guarantee", + "severity": "error" + } + ] + } + } + ] +} diff --git a/runtime/conformance/spec/compiler/cases/marker.json b/runtime/conformance/spec/compiler/cases/marker.json new file mode 100644 index 0000000..5cbbe84 --- /dev/null +++ b/runtime/conformance/spec/compiler/cases/marker.json @@ -0,0 +1,251 @@ +{ + "$schema": "../../specs/gen/compiler.schema.json", + "group": "marker", + "cases": [ + { + "id": "marker/gate-off", + "description": "@unverified is refused where the package's settings don't allow it", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = \"the gateway predates Comline\"\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "settings::forbidden", + "severity": "error" + } + ] + } + }, + { + "id": "marker/missing-marker", + "description": "a protocol with no handshake gives up two guarantees and has to say why", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::missing-marker", + "severity": "error" + } + ] + } + }, + { + "id": "marker/plain-marker", + "description": "one reason covers everything a protocol gives up, and it is frozen as the set", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = \"the gateway predates Comline\"\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "schema_agreement", + "encoding_agreement" + ], + "acknowledged": [ + { + "guarantee": "schema_agreement", + "scope": "protocol", + "reason": "the gateway predates Comline" + }, + { + "guarantee": "encoding_agreement", + "scope": "protocol", + "reason": "the gateway predates Comline" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + } + ] + } + }, + { + "id": "marker/package-handshake-unmarked", + "description": "the package's default handshake counts: a protocol that takes none has to say why", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::missing-marker", + "severity": "error" + } + ] + } + }, + { + "id": "marker/package-handshake-marked", + "description": "the marker covers what the package's default handshake gives up", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@unverified = \"legacy\"\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "schema_agreement", + "encoding_agreement" + ], + "acknowledged": [ + { + "guarantee": "schema_agreement", + "scope": "protocol", + "reason": "legacy" + }, + { + "guarantee": "encoding_agreement", + "scope": "protocol", + "reason": "legacy" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + } + ] + } + }, + { + "id": "marker/missing-reason", + "description": "a marker with a blank reason is an error", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\n@unverified = \" \"\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::missing-reason", + "severity": "error" + } + ] + } + }, + { + "id": "marker/nothing-given-up", + "description": "a marker where nothing is given up is a warning, and freezes nothing", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@unverified = \"just in case\"\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::nothing-given-up", + "severity": "warning" + } + ] + } + } + ] +} diff --git a/runtime/conformance/spec/compiler/cases/package.json b/runtime/conformance/spec/compiler/cases/package.json new file mode 100644 index 0000000..2b8d112 --- /dev/null +++ b/runtime/conformance/spec/compiler/cases/package.json @@ -0,0 +1,384 @@ +{ + "$schema": "../../specs/gen/compiler.schema.json", + "group": "package", + "cases": [ + { + "id": "package/keyed-covers-inherited", + "description": "the package says why for a protocol that takes the package's handshake", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nunverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n encoding_agreement = \"the gateway pins schemas by contract\"\n}\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "schema_agreement", + "encoding_agreement" + ], + "acknowledged": [ + { + "guarantee": "schema_agreement", + "scope": "package", + "reason": "the gateway pins schemas by contract" + }, + { + "guarantee": "encoding_agreement", + "scope": "package", + "reason": "the gateway pins schemas by contract" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + } + ] + } + }, + { + "id": "package/plain-covers-inherited", + "description": "the plain form covers every guarantee a package setting gives up", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nunverified = \"the gateway pins schemas by contract\"\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "schema_agreement", + "encoding_agreement" + ], + "acknowledged": [ + { + "guarantee": "schema_agreement", + "scope": "package", + "reason": "the gateway pins schemas by contract" + }, + { + "guarantee": "encoding_agreement", + "scope": "package", + "reason": "the gateway pins schemas by contract" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + } + ] + } + }, + { + "id": "package/own-handshake-not-covered", + "description": "a protocol with its own @handshake isn't covered by the package", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nunverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n encoding_agreement = \"the gateway pins schemas by contract\"\n}\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function f();\n}\n\n@handshake = \"none\"\nprotocol Q {\n function g();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::missing-marker", + "severity": "error" + } + ] + } + }, + { + "id": "package/own-handshake-marked", + "description": "a protocol with its own @handshake says why itself; the package covers the other", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nunverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n encoding_agreement = \"the gateway pins schemas by contract\"\n}\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function f();\n}\n\n@handshake = \"none\"\n@unverified = \"Q talks to the gateway directly\"\nprotocol Q {\n function g();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "schema_agreement", + "encoding_agreement" + ], + "acknowledged": [ + { + "guarantee": "schema_agreement", + "scope": "package", + "reason": "the gateway pins schemas by contract" + }, + { + "guarantee": "encoding_agreement", + "scope": "package", + "reason": "the gateway pins schemas by contract" + } + ] + }, + { + "name": "Q", + "given_up": [ + "schema_agreement", + "encoding_agreement" + ], + "acknowledged": [ + { + "guarantee": "schema_agreement", + "scope": "protocol", + "reason": "Q talks to the gateway directly" + }, + { + "guarantee": "encoding_agreement", + "scope": "protocol", + "reason": "Q talks to the gateway directly" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + } + ] + } + }, + { + "id": "package/wrong-scope", + "description": "bounded_size can't be acknowledged at package scope", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nunverified = { bounded_size = \"the gateway pins schemas by contract\" }\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::wrong-scope", + "severity": "error" + } + ] + } + }, + { + "id": "package/not-given-up", + "description": "a guarantee the package lists and no protocol gives up through it is a warning", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nunverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n encoding_agreement = \"the gateway pins schemas by contract\"\n}\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::not-given-up", + "severity": "warning" + } + ] + } + }, + { + "id": "package/gate-off", + "description": "the package's unverified is held to the same gate as the marker", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nunverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n encoding_agreement = \"the gateway pins schemas by contract\"\n}\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "settings::forbidden", + "severity": "error" + } + ] + } + }, + { + "id": "package/adds-bounded-size", + "description": "a marker says why for bounded_size, which the package can't; the package says the rest", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nunverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n encoding_agreement = \"the gateway pins schemas by contract\"\n}\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@unverified = { bounded_size = \"the uploader streams whatever it's given\" }\nprotocol P {\n function put(s: string);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "protocols": [ + { + "name": "P", + "given_up": [ + "schema_agreement", + "encoding_agreement", + "bounded_size" + ], + "acknowledged": [ + { + "guarantee": "schema_agreement", + "scope": "package", + "reason": "the gateway pins schemas by contract" + }, + { + "guarantee": "encoding_agreement", + "scope": "package", + "reason": "the gateway pins schemas by contract" + }, + { + "guarantee": "bounded_size", + "scope": "protocol", + "reason": "the uploader streams whatever it's given" + } + ] + } + ], + "builds": true, + "diagnostics": [ + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + }, + { + "code": "unverified::bounded-size", + "severity": "warning" + } + ] + } + }, + { + "id": "package/bounded-size-not-covered", + "description": "the package covering the handshake doesn't cover an unbounded string", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nhandshake = \"none\"\nunverified = {\n schema_agreement = \"the gateway pins schemas by contract\"\n encoding_agreement = \"the gateway pins schemas by contract\"\n}\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "protocol P {\n function put(s: string);\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "bounds::unbounded", + "severity": "error" + } + ] + } + } + ] +} diff --git a/runtime/conformance/spec/compiler/readme.md b/runtime/conformance/spec/compiler/readme.md new file mode 100644 index 0000000..0045c42 --- /dev/null +++ b/runtime/conformance/spec/compiler/readme.md @@ -0,0 +1,174 @@ +# Compiler conformance cases + +Schema graphs as data, each with the outcome any compiler must reproduce: +core, the language server, or another tool, the way a runtime must reproduce +the [vectors](../README.md#the-corpus)' bytes. The cases say which guarantees a +protocol gives up, who acknowledged them and why, and which errors and +warnings a build reports, for the rules of +[the proposal](https://github.com/ComlineProject/docs/blob/proposals/shared-vocabulary/docs/docs/proposals/shared-vocabulary/granular-unverified.md) +that core implements today. They are +[core#224](https://github.com/ComlineProject/core/issues/224)'s, and the +outcomes are those of core at `d1b678a`. + +| What | Where | +| --- | --- | +| The cases, one JSON file a group | [`cases/.json`](cases) | +| The format of a file, in CUE, and as JSON Schema | [`specs/compiler.cue`](../specs/compiler.cue), [`specs/gen/compiler.schema.json`](../specs/gen/compiler.schema.json) | +| The cases' source, which the JSON is generated from | [`src/`](src) | +| What the schema can't say, checked by `jq` | [`specs/compiler.jq`](../specs/compiler.jq) | + +`specs/check.sh` regenerates `cases/` from `src/` and vets it, and CI runs it +with `--check`, which fails when a file is stale. Edit `src/`, never `cases/`. + +## A case + +```json +{ + "id": "marker/missing-marker", + "description": "a protocol with no handshake gives up two guarantees and has to say why", + "packages": [ + { + "name": "app", + "config": "congregation app\nspecification_version = 1\nsettings = { annotations = { unverified = { allowed = true } } }\n", + "schemas": [ + { + "path": "src/api.ids", + "text": "@handshake = \"none\"\nprotocol P {\n function f();\n}\n" + } + ], + "dependencies": [] + } + ], + "build": "app", + "expect": { + "builds": false, + "diagnostics": [ + { + "code": "unverified::missing-marker", + "severity": "error" + } + ] + } +} +``` + +- **`id`** is `/`, the group being the file's. An id is stable, + as a vector's is. +- **`description`** is one line. +- **`packages`** are the packages of the case: the one to build and those it + depends on, directly or not. Each has a `name`, which is its congregation's, + its directory's and how its dependants say it in `use`; its `config.idp` as + `config`, whole; its `schemas`, each a `path` under the package + (`src/.ids`, as on disk) and its `text`; and its `dependencies`: + the packages it depends on by path (`../`) and, for each, what the + config accepts of its unverified protocols (`accept_unverified`, a protocol + and the guarantee ids it gives up). The config text declares the same: the + compiler reads that, and `dependencies` restates it so a runner can lay the + packages out and a check can hold them to each other without reading + `config.idp`. A package never depends on itself or in a cycle. +- **`build`** names the package to build. +- **`expect`** is the outcome, below. + +Texts are written as they are, with the newlines JSON escapes. In a schema's +annotation a dictionary's entries are separated by commas +(`@unverified = { a = "..." , b = "..." }`); in `config.idp` by whitespace. + +### What is expected + +**`builds`** says whether the package builds. + +For a build that **succeeds**: + +- **`protocols`** lists every protocol of the package built, not those of its + dependencies, and no others, each with: + - **`given_up`**: the guarantee ids it gives up, the set frozen with it. + An order says nothing. A protocol that gives up nothing has `[]`. + - **`acknowledged`**, where the case asserts it: for each guarantee listed, + the **`scope`** it was acknowledged at, `protocol` (the protocol's own + `@unverified`, which wins where both say) or `package` (`config.idp`'s + `unverified`, which core freezes with the protocol as + `unverified_package`), and the **`reason`** shown for it. A guarantee not + listed isn't asserted. Only a guarantee given up is listed. +- **`diagnostics`** are the warnings the build reports for the package's own + schemas and config, and no others: a warning of a dependency is its authors' + to act on, and is not the case's. + +For a build that **fails**: + +- **`diagnostics`** are the errors with a code, and no others. +- **`error_contains`**, for an error without a code, lists text its message + contains. Core reports a dependency that isn't accepted as a plain error. + The substrings are minimal and as stable as core's wording; they are + **provisional**, and go when those errors get codes. +- A failing build says why with one or the other. It has no `protocols`, and + no warnings: they aren't reported once a build fails. + +A diagnostic is `{ "code", "severity" }`, matched on both and never on message +text, as a set: each once, in any order. The codes the corpus uses are a +closed list in [`specs/compiler.cue`](../specs/compiler.cue): a rule's code +that isn't there has no case yet. A case is written so that its outcome has +one cause, so which stage of a compiler stops the build first doesn't matter. + +## Running a case + +For each case in each file of `cases/`: + +1. Write every package into its own directory, side by side: + `//config.idp` from `config`, and each schema at its `path` + under `//`. +2. Build the package named by `build`, as `comline build` would resolve its + dependencies from the paths its config declares, and no further (no + fetching, no code generation). +3. Compare: whether it built, then per `expect`. The frozen set and the + acknowledgements are what the build froze with each protocol; the + diagnostics are what it reported, by code and severity. + +A tool that can only compile one package's sources in memory can't run the +cases with `dependencies`, which are in `acceptance` and `chain`. + +## The corpus + +| Group | Covers | +| --- | --- | +| `marker` | the gate (`annotations.unverified.allowed`); a marker required where a protocol gives something up (its own `@handshake`, the package's default); its reason; a marker where nothing is given up | +| `keyed` | `@unverified = { = "" }`: the exact set, an unknown id, a missing one, one listed that isn't given up, one listed twice | +| `package` | `unverified` in `config.idp`: the keyed and plain forms covering what a protocol takes from the package's settings; a protocol with its own `@handshake` not covered; `unverified::wrong-scope` for `bounded_size`; a guarantee no protocol gives up through it; the gate; a marker adding `bounded_size` | +| `bounded` | `bounded_size`: a string or list without a maximum, a type that contains itself without `@max_depth`, a type from another schema of the package that holds one, each unmarked (an error) and marked (given up), and the bounded variants | +| `acceptance` | a dependency's unverified protocols accepted under it in `config.idp`: not at all, exactly, for less, for more; the reasons the consumer is shown; the dependency judged by its own package | +| `chain` | three packages, `c` depending on `b` depending on `a`: a type holding `a`'s unbounded value, used in `c`; and the acceptance resolving `b` asks for `a`'s protocols too | + +A case's `description` says what it shows. Each rule has a passing and a +failing variant. + +### To come + +Cases for rules core doesn't implement yet, which go in when it does: +acknowledgements at the inner scopes (function, argument, field and type), +an outer scope covering an inner one, `strict`, pinning an acceptance to a +chain of packages and its invalidation, and failing closed. + +## Taking the cases + +Vendor `compiler/cases/*.json` at a pinned revision of this repository, as core +does the size vectors (`core/tests/spec/`): a `REV` file with the commit, a +`vendor.sh --check` in CI that fails when the copy differs from it, and a test +that the `REV` is the `comline-catalog` revision core is pinned to, since the +cases name guarantees as the catalog does. `specs/gen/compiler.schema.json` is +the format as JSON Schema, for a reader that wants it; a reader ignores the +`$schema` each file names. + +The files of a group are never split or renamed, and ids don't change. A +group or a case may be added, and a case's expected outcome changed, only as +the compiler's behaviour changes, in a pull request that says so. + +## Writing a case + +Cases are written in [`src/`](src), in CUE, where a package's files are +multi-line strings and a protocol's expected outcome a struct; the comment +at the top of [`src/lib.cue`](src/lib.cue) says how it becomes JSON. Run +`specs/check.sh` to regenerate `cases/`. + +A case should have one cause: where two things are wrong at once, which one a +tool reports first can differ, so it isn't a good case. Derive the outcome from +the compiler's tests and code, and state in the pull request any you aren't +sure of. diff --git a/runtime/conformance/spec/compiler/src/acceptance.cue b/runtime/conformance/spec/compiler/src/acceptance.cue new file mode 100644 index 0000000..98077a1 --- /dev/null +++ b/runtime/conformance/spec/compiler/src/acceptance.cue @@ -0,0 +1,135 @@ +package cases + +// Dependency acceptance: every unverified protocol of a dependency has to be +// accepted by the consumer, under the dependency in its `config.idp`, for +// exactly the guarantees it gives up. It is an error without a code, so these +// cases say what the message contains. + +// A package whose `Billing` runs no handshake, marked. +_billing: { + config: [_allow] + schemas: api: """ + @handshake = "none" + @unverified = "the 2009 gateway" + protocol Billing { + function charge(); + } + """ +} + +_consumerSchema: """ + struct A { + x: u32 + } + """ + +groups: acceptance: { + "not-accepted": { + about: "an unverified protocol of a dependency has to be accepted" + packages: { + billing: _billing + app: {schemas: api: _consumerSchema, dependencies: billing: {}} + } + build: "app" + expect: { + builds: false + error_contains: [ + "protocol `Billing` is unverified, giving up schema agreement and encoding agreement", + "the 2009 gateway", + ] + } + } + "accepted": { + about: "accepted for exactly what it gives up, it builds" + packages: { + billing: _billing + app: { + schemas: api: _consumerSchema + dependencies: billing: accept: Billing: ["schema_agreement", "encoding_agreement"] + } + } + build: "app" + expect: {builds: true, protocols: {}} + } + "accepted-for-less": { + about: "accepted for less than it gives up, it stops again" + packages: { + billing: _billing + app: { + schemas: api: _consumerSchema + dependencies: billing: accept: Billing: ["schema_agreement"] + } + } + build: "app" + expect: { + builds: false + error_contains: [ + "protocol `Billing` now gives up schema agreement and encoding agreement", + "it was accepted for schema agreement", + ] + } + } + "accepted-for-more": { + about: "accepted for more than it gives up, it stops too: the set has to match exactly" + packages: { + billing: _billing + app: { + schemas: api: _consumerSchema + dependencies: billing: accept: Billing: ["schema_agreement", "encoding_agreement", "bounded_size"] + } + } + build: "app" + expect: { + builds: false + error_contains: ["protocol `Billing` now gives up schema agreement and encoding agreement"] + } + } + "package-reasons-shown": { + about: "what the package said once is what the consumer is shown to accept" + packages: { + billing: { + config: ["handshake = \"none\"", """ + unverified = { + schema_agreement = "the gateway pins schemas by contract" + encoding_agreement = "the gateway only speaks one encoding" + } + """, _allow] + schemas: api: """ + protocol Billing { + function charge(); + } + """ + } + app: {schemas: api: _consumerSchema, dependencies: billing: {}} + } + build: "app" + expect: { + builds: false + error_contains: [ + "protocol `Billing` is unverified, giving up schema agreement and encoding agreement", + "schema agreement \"the gateway pins schemas by contract\"", + "encoding agreement \"the gateway only speaks one encoding\"", + ] + } + } + "judged-by-its-own-package": { + about: "a dependency is judged by its own package's settings and default handshake, not the consumer's" + packages: { + billing: { + config: ["handshake = \"none\"", _allow] + schemas: api: """ + @unverified = "the 2009 gateway" + protocol Billing { + function charge(); + } + """ + } + app: { + schemas: api: _consumerSchema + dependencies: billing: accept: Billing: ["schema_agreement", "encoding_agreement"] + } + } + build: "app" + expect: {builds: true, protocols: {}} + } +} diff --git a/runtime/conformance/spec/compiler/src/bounded.cue b/runtime/conformance/spec/compiler/src/bounded.cue new file mode 100644 index 0000000..0449776 --- /dev/null +++ b/runtime/conformance/spec/compiler/src/bounded.cue @@ -0,0 +1,222 @@ +package cases + +// Bounded size: every string, list and nesting a protocol reaches has a +// maximum, or the protocol gives up `bounded_size` with `@unverified`. + +_streams: "the uploader streams whatever it's given" + +// A type another schema of the package declares, held by a protocol there +// that is marked, so the string without a maximum is its to give up. +_models: """ + struct Blob { + data: string + } + + @unverified = "\(_streams)" + protocol Upload { + function put(b: Blob); + } + """ + +groups: bounded: { + "string-unmarked": { + about: "a string without a maximum is an error where no marker gives bounded size up" + packages: app: schemas: api: """ + protocol P { + function put(s: string); + } + """ + build: "app" + expect: {builds: false, errors: ["bounds::unbounded"]} + } + "list-unmarked": { + about: "a list without a maximum is an error too" + packages: app: schemas: api: """ + protocol P { + function put(xs: u8[]); + } + """ + build: "app" + expect: {builds: false, errors: ["bounds::unbounded"]} + } + "bounded": { + about: "a string and a list with maximums give nothing up" + packages: app: schemas: api: """ + protocol P { + function put(s: char[max 64], xs: u8[max 16]); + } + """ + build: "app" + expect: { + builds: true + protocols: P: given_up: [] + warnings: [] + } + } + "string-marked": { + about: "a marked protocol gives bounded_size up for a string without a maximum" + packages: app: { + config: [_allow] + schemas: api: """ + @unverified = "\(_streams)" + protocol P { + function put(s: string); + } + """ + } + build: "app" + expect: { + builds: true + protocols: P: { + given_up: ["bounded_size"] + acknowledged: bounded_size: {scope: "protocol", reason: _streams} + } + warnings: ["unverified::bounded-size"] + } + } + "keyed-for-something-else": { + about: "a keyed marker that doesn't list bounded_size doesn't cover a string without a maximum" + packages: app: { + config: [_allow] + schemas: api: """ + @unverified = { version_honesty = "not this" } + protocol P { + function put(s: string); + } + """ + } + build: "app" + expect: {builds: false, errors: ["unverified::missing-guarantee"]} + } + "recursion-unmarked": { + about: "a type that contains itself without @max_depth is an error" + packages: app: schemas: api: """ + struct Node { + kids: Node[max 4] + } + + protocol P { + function f(n: Node); + } + """ + build: "app" + expect: {builds: false, errors: ["bounds::unbounded-depth"]} + } + "recursion-marked": { + about: "a marked protocol gives bounded_size up for a type that contains itself without @max_depth" + packages: app: { + config: [_allow] + schemas: api: """ + struct Node { + kids: Node[max 4] + } + + @unverified = "trees are small in practice" + protocol P { + function f(n: Node); + } + """ + } + build: "app" + expect: { + builds: true + protocols: P: { + given_up: ["bounded_size"] + acknowledged: bounded_size: {scope: "protocol", reason: "trees are small in practice"} + } + warnings: ["unverified::bounded-size"] + } + } + "recursion-max-depth": { + about: "a type that contains itself under @max_depth gives nothing up" + packages: app: schemas: api: """ + @max_depth = 4 + struct Node { + kids: Node[max 4] + } + + protocol P { + function f(n: Node); + } + """ + build: "app" + expect: { + builds: true + protocols: P: given_up: [] + warnings: [] + } + } + "other-schema-unmarked": { + about: "a type from another schema that holds a string without a maximum is unbounded where an unmarked protocol uses it" + packages: app: { + config: [_allow] + schemas: { + models: _models + api: """ + use models::Blob + + protocol Orders { + function send(b: Blob); + } + """ + } + } + build: "app" + expect: {builds: false, errors: ["bounds::unbounded"]} + } + "other-schema-marked": { + about: "a marked protocol using it gives bounded_size up, as the one that declares it does" + packages: app: { + config: [_allow] + schemas: { + models: _models + api: """ + use models::Blob + + @unverified = "orders carry the upload" + protocol Orders { + function send(b: Blob); + } + """ + } + } + build: "app" + expect: { + builds: true + protocols: { + Upload: { + given_up: ["bounded_size"] + acknowledged: bounded_size: {scope: "protocol", reason: _streams} + } + Orders: { + given_up: ["bounded_size"] + acknowledged: bounded_size: {scope: "protocol", reason: "orders carry the upload"} + } + } + warnings: ["unverified::bounded-size"] + } + } + "other-schema-bounded": { + about: "a type bounded where it is declared is bounded where it is used" + packages: app: schemas: { + models: """ + struct Blob { + data: char[max 64] + } + """ + api: """ + use models::Blob + + protocol Orders { + function send(b: Blob); + } + """ + } + build: "app" + expect: { + builds: true + protocols: Orders: given_up: [] + warnings: [] + } + } +} diff --git a/runtime/conformance/spec/compiler/src/chain.cue b/runtime/conformance/spec/compiler/src/chain.cue new file mode 100644 index 0000000..b44d3f4 --- /dev/null +++ b/runtime/conformance/spec/compiler/src/chain.cue @@ -0,0 +1,150 @@ +package cases + +// Three packages: `c` depends on `b`, which depends on `a`. `a`'s `Blob` +// holds a string without a maximum that only its own marked `Upload` +// reaches; `b` holds it in `Wrapper`, which only its own marked `Wrap` +// reaches; `c` uses `Wrapper` in `Orders`. +// +// Resolving a dependency takes accepting every unverified protocol of its +// package and of the packages it depends on, as its own build saw them: `c` +// accepts `Upload` as well as `Wrap`. + +_a: { + config: [_allow] + schemas: api: """ + struct Blob { + data: string + } + + @unverified = "the uploader streams whatever it's given" + protocol Upload { + function put(b: Blob); + } + """ +} + +// `b`, which depends on `a`. +_b: { + config: [_allow] + schemas: api: """ + use a::api::Blob + + struct Wrapper { + blob: Blob + } + + @unverified = "wrapping uploads" + protocol Wrap { + function wrap(w: Wrapper); + } + """ + dependencies: a: {} +} + +// `b` accepting `a`'s `Upload`. +_bAccepting: _b & {dependencies: a: accept: Upload: ["bounded_size"]} + +groups: chain: { + "unmarked-is-unbounded": { + about: "a type that holds another package's unbounded value, two packages away, is unbounded where an unmarked protocol uses it" + packages: { + a: _a + b: _bAccepting + c: { + schemas: api: """ + use b::api::Wrapper + + protocol Orders { + function send(w: Wrapper); + } + """ + dependencies: b: accept: { + Wrap: ["bounded_size"] + Upload: ["bounded_size"] + } + } + } + build: "c" + expect: {builds: false, errors: ["bounds::unbounded"]} + } + "marked-gives-up": { + about: "a marked protocol using it gives bounded_size up, for its own consumers to accept" + packages: { + a: _a + b: _bAccepting + c: { + config: [_allow] + schemas: api: """ + use b::api::Wrapper + + @unverified = "orders carry the upload" + protocol Orders { + function send(w: Wrapper); + } + """ + dependencies: b: accept: { + Wrap: ["bounded_size"] + Upload: ["bounded_size"] + } + } + } + build: "c" + expect: { + builds: true + protocols: Orders: { + given_up: ["bounded_size"] + acknowledged: bounded_size: {scope: "protocol", reason: "orders carry the upload"} + } + warnings: ["unverified::bounded-size"] + } + } + "acceptance-needs-every-link": { + about: "accepting b's protocol is not enough: a's, which b's package contains, is accepted too" + packages: { + a: _a + b: _bAccepting + c: { + config: [_allow] + schemas: api: """ + use b::api::Wrapper + + @unverified = "orders carry the upload" + protocol Orders { + function send(w: Wrapper); + } + """ + dependencies: b: accept: Wrap: ["bounded_size"] + } + } + build: "c" + expect: { + builds: false + error_contains: ["protocol `Upload` is unverified, giving up bounded size"] + } + } + "middle-doesnt-accept-the-first": { + about: "b's own build fails when it doesn't accept a's protocol, so building c does" + packages: { + a: _a + b: _b + c: { + schemas: api: """ + use b::api::Wrapper + + protocol Orders { + function send(w: Wrapper); + } + """ + dependencies: b: accept: { + Wrap: ["bounded_size"] + Upload: ["bounded_size"] + } + } + } + build: "c" + expect: { + builds: false + error_contains: ["protocol `Upload` is unverified, giving up bounded size"] + } + } +} diff --git a/runtime/conformance/spec/compiler/src/keyed.cue b/runtime/conformance/spec/compiler/src/keyed.cue new file mode 100644 index 0000000..52e7e60 --- /dev/null +++ b/runtime/conformance/spec/compiler/src/keyed.cue @@ -0,0 +1,111 @@ +package cases + +// The keyed form, `@unverified = { = "" }`: a reason for +// each guarantee given up, under its id in the catalog. In a schema, the +// entries are separated by commas. +groups: keyed: { + "exact-set": { + about: "a reason for each guarantee given up, and no others" + packages: app: { + config: [_allow] + schemas: api: """ + @handshake = "none" + @unverified = { + schema_agreement = "the gateway predates Comline", + encoding_agreement = "the gateway only speaks one encoding" + } + protocol P { + function f(); + } + """ + } + build: "app" + expect: { + builds: true + protocols: P: { + given_up: ["schema_agreement", "encoding_agreement"] + acknowledged: { + schema_agreement: {scope: "protocol", reason: "the gateway predates Comline"} + encoding_agreement: {scope: "protocol", reason: "the gateway only speaks one encoding"} + } + } + warnings: ["unverified::schema-agreement", "unverified::encoding-agreement"] + } + } + "unknown-guarantee": { + about: "a key that is no guarantee's id is an error" + packages: app: { + config: [_allow] + schemas: api: """ + @handshake = "none" + @unverified = { + schema_agreement = "the gateway predates Comline", + encoding_agreement = "the gateway only speaks one encoding", + bounded_sise = "a typo" + } + protocol P { + function f(); + } + """ + } + build: "app" + expect: {builds: false, errors: ["unverified::unknown-guarantee"]} + } + "missing-guarantee": { + about: "a guarantee given up and not listed is an error" + packages: app: { + config: [_allow] + schemas: api: """ + @handshake = "none" + @unverified = { schema_agreement = "the gateway predates Comline" } + protocol P { + function f(); + } + """ + } + build: "app" + expect: {builds: false, errors: ["unverified::missing-guarantee"]} + } + "not-given-up": { + about: "a guarantee listed and not given up is a warning, and not frozen" + packages: app: { + config: [_allow] + schemas: api: """ + @handshake = "none" + @unverified = { + schema_agreement = "the gateway predates Comline", + encoding_agreement = "the gateway only speaks one encoding", + version_honesty = "just in case" + } + protocol P { + function f(); + } + """ + } + build: "app" + expect: { + builds: true + protocols: P: given_up: ["schema_agreement", "encoding_agreement"] + warnings: ["unverified::not-given-up", "unverified::schema-agreement", "unverified::encoding-agreement"] + } + } + "duplicate-guarantee": { + about: "a guarantee listed twice is an error" + packages: app: { + config: [_allow] + schemas: api: """ + @handshake = "none" + @unverified = { + schema_agreement = "the gateway predates Comline", + encoding_agreement = "the gateway only speaks one encoding", + schema_agreement = "again" + } + protocol P { + function f(); + } + """ + } + build: "app" + expect: {builds: false, errors: ["unverified::duplicate-guarantee"]} + } +} diff --git a/runtime/conformance/spec/compiler/src/lib.cue b/runtime/conformance/spec/compiler/src/lib.cue new file mode 100644 index 0000000..f2fad88 --- /dev/null +++ b/runtime/conformance/spec/compiler/src/lib.cue @@ -0,0 +1,110 @@ +package cases + +import ( + "list" + "strings" +) + +// The cases are written here, compactly, and `specs/check.sh` exports them as +// `compiler/cases/.json`, in the shape `specs/compiler.cue` gives +// (`#CompilerCases`). That is the file runners read; this is its source. +// +// A source case differs from its JSON in being easier to write: +// +// - `packages` is a struct by package name. A package's `config.idp` is +// `congregation ` and `specification_version = 1`, then each line of +// `config`, then the `dependencies` it declares by path (`../`), +// each with the unverified protocols it accepts. A schema is written +// under its namespace, `api` for `src/api.ids`. Every file ends in a +// newline. +// - `expect.protocols` is a struct by protocol name, and `acknowledged` one +// by guarantee. `errors` and `warnings` are codes, and become the +// `diagnostics`. + +// The package setting that lets a protocol say `@unverified`. +_allow: "settings = { annotations = { unverified = { allowed = true } } }" + +#Case: { + about!: string + packages!: [string]: { + config: [...string] | *[] + schemas: [string]: string + dependencies: [string]: {accept?: [string]: [...string]} + } + build!: string + expect!: { + builds!: bool + protocols?: [string]: { + given_up!: [...string] + acknowledged?: [string]: {scope!: "protocol" | "package", reason?: string} + } + errors?: [...string] + warnings?: [...string] + error_contains?: [...string] + } +} + +// Each group file declares `groups: : : #Case`. +groups: [string]: [string]: #Case + +// A package's `dependencies` block, which declares each by path and lists +// the unverified protocols it accepts. +_dependencies: { + deps: [string]: {accept?: [string]: [...string]} + text: strings.Join([for d, v in deps { + "dependencies = {\n \(d) = {\n path = \"../\(d)\"\n\(_accept[d]) }\n}\n" + }], "") + _accept: { + for d, v in deps { + (d): strings.Join([if v.accept != _|_ { + " accept_unverified = { " + strings.Join([for proto, ids in v.accept { + "\(proto) = [" + strings.Join([for id in ids {"\"\(id)\""}], ", ") + "]" + }], " ") + " }\n" + }], "") + } + } +} + +// What a case is as JSON. +out: { + for G, _ in groups {(G): { + $schema: "../../specs/gen/compiler.schema.json" + group: G + cases: [for n, c in groups[G] { + id: "\(G)/\(n)" + description: c.about + packages: [for name, p in c.packages { + let d = _dependencies & {deps: p.dependencies} + "name": name + config: strings.Join(list.Concat([["congregation \(name)", "specification_version = 1"], p.config]), "\n") + "\n" + d.text + schemas: [for path, text in p.schemas {"path": "src/\(path).ids", "text": text + "\n"}] + dependencies: [for dep, v in p.dependencies { + name: dep + if v.accept != _|_ {accept_unverified: v.accept} + }] + }] + build: c.build + expect: { + builds: c.expect.builds + if c.expect.protocols != _|_ { + protocols: [for name, p in c.expect.protocols { + "name": name + given_up: p.given_up + if p.acknowledged != _|_ { + acknowledged: [for g, a in p.acknowledged { + guarantee: g + scope: a.scope + if a.reason != _|_ {reason: a.reason} + }] + } + }] + } + diagnostics: list.Concat([ + if c.expect.errors != _|_ {[for e in c.expect.errors {code: e, severity: "error"}]}, + if c.expect.warnings != _|_ {[for w in c.expect.warnings {code: w, severity: "warning"}]}, + ]) + if c.expect.error_contains != _|_ {error_contains: c.expect.error_contains} + } + }] + }} +} diff --git a/runtime/conformance/spec/compiler/src/marker.cue b/runtime/conformance/spec/compiler/src/marker.cue new file mode 100644 index 0000000..f0e9647 --- /dev/null +++ b/runtime/conformance/spec/compiler/src/marker.cue @@ -0,0 +1,125 @@ +package cases + +groups: marker: { + "gate-off": { + about: "@unverified is refused where the package's settings don't allow it" + packages: app: schemas: api: """ + @handshake = "none" + @unverified = "the gateway predates Comline" + protocol P { + function f(); + } + """ + build: "app" + expect: {builds: false, errors: ["settings::forbidden"]} + } + "missing-marker": { + about: "a protocol with no handshake gives up two guarantees and has to say why" + packages: app: { + config: [_allow] + schemas: api: """ + @handshake = "none" + protocol P { + function f(); + } + """ + } + build: "app" + expect: {builds: false, errors: ["unverified::missing-marker"]} + } + "plain-marker": { + about: "one reason covers everything a protocol gives up, and it is frozen as the set" + packages: app: { + config: [_allow] + schemas: api: """ + @handshake = "none" + @unverified = "the gateway predates Comline" + protocol P { + function f(); + } + """ + } + build: "app" + expect: { + builds: true + protocols: P: { + given_up: ["schema_agreement", "encoding_agreement"] + acknowledged: { + schema_agreement: {scope: "protocol", reason: "the gateway predates Comline"} + encoding_agreement: {scope: "protocol", reason: "the gateway predates Comline"} + } + } + warnings: ["unverified::schema-agreement", "unverified::encoding-agreement"] + } + } + "package-handshake-unmarked": { + about: "the package's default handshake counts: a protocol that takes none has to say why" + packages: app: { + config: ["handshake = \"none\"", _allow] + schemas: api: """ + protocol P { + function f(); + } + """ + } + build: "app" + expect: {builds: false, errors: ["unverified::missing-marker"]} + } + "package-handshake-marked": { + about: "the marker covers what the package's default handshake gives up" + packages: app: { + config: ["handshake = \"none\"", _allow] + schemas: api: """ + @unverified = "legacy" + protocol P { + function f(); + } + """ + } + build: "app" + expect: { + builds: true + protocols: P: { + given_up: ["schema_agreement", "encoding_agreement"] + acknowledged: { + schema_agreement: {scope: "protocol", reason: "legacy"} + encoding_agreement: {scope: "protocol", reason: "legacy"} + } + } + warnings: ["unverified::schema-agreement", "unverified::encoding-agreement"] + } + } + "missing-reason": { + about: "a marker with a blank reason is an error" + packages: app: { + config: [_allow] + schemas: api: """ + @handshake = "none" + @unverified = " " + protocol P { + function f(); + } + """ + } + build: "app" + expect: {builds: false, errors: ["unverified::missing-reason"]} + } + "nothing-given-up": { + about: "a marker where nothing is given up is a warning, and freezes nothing" + packages: app: { + config: [_allow] + schemas: api: """ + @unverified = "just in case" + protocol P { + function f(); + } + """ + } + build: "app" + expect: { + builds: true + protocols: P: given_up: [] + warnings: ["unverified::nothing-given-up"] + } + } +} diff --git a/runtime/conformance/spec/compiler/src/package.cue b/runtime/conformance/spec/compiler/src/package.cue new file mode 100644 index 0000000..d9e498d --- /dev/null +++ b/runtime/conformance/spec/compiler/src/package.cue @@ -0,0 +1,176 @@ +package cases + +// The package's own `unverified`, in `config.idp`: why the package gives up +// what its own settings give up, once for every protocol that takes them. +// In `config.idp`, a dictionary's entries are separated by whitespace. + +_why: "the gateway pins schemas by contract" +_noHandshake: "handshake = \"none\"" +_packageKeyed: """ + unverified = { + schema_agreement = "\(_why)" + encoding_agreement = "\(_why)" + } + """ +_bare: """ + protocol P { + function f(); + } + """ + +groups: package: { + "keyed-covers-inherited": { + about: "the package says why for a protocol that takes the package's handshake" + packages: app: {config: [_noHandshake, _packageKeyed, _allow], schemas: api: _bare} + build: "app" + expect: { + builds: true + protocols: P: { + given_up: ["schema_agreement", "encoding_agreement"] + acknowledged: { + schema_agreement: {scope: "package", reason: _why} + encoding_agreement: {scope: "package", reason: _why} + } + } + warnings: ["unverified::schema-agreement", "unverified::encoding-agreement"] + } + } + "plain-covers-inherited": { + about: "the plain form covers every guarantee a package setting gives up" + packages: app: { + config: [_noHandshake, "unverified = \"\(_why)\"", _allow] + schemas: api: _bare + } + build: "app" + expect: { + builds: true + protocols: P: { + given_up: ["schema_agreement", "encoding_agreement"] + acknowledged: { + schema_agreement: {scope: "package", reason: _why} + encoding_agreement: {scope: "package", reason: _why} + } + } + warnings: ["unverified::schema-agreement", "unverified::encoding-agreement"] + } + } + "own-handshake-not-covered": { + about: "a protocol with its own @handshake isn't covered by the package" + packages: app: { + config: [_noHandshake, _packageKeyed, _allow] + schemas: api: """ + protocol P { + function f(); + } + + @handshake = "none" + protocol Q { + function g(); + } + """ + } + build: "app" + expect: {builds: false, errors: ["unverified::missing-marker"]} + } + "own-handshake-marked": { + about: "a protocol with its own @handshake says why itself; the package covers the other" + packages: app: { + config: [_noHandshake, _packageKeyed, _allow] + schemas: api: """ + protocol P { + function f(); + } + + @handshake = "none" + @unverified = "Q talks to the gateway directly" + protocol Q { + function g(); + } + """ + } + build: "app" + expect: { + builds: true + protocols: { + P: { + given_up: ["schema_agreement", "encoding_agreement"] + acknowledged: { + schema_agreement: {scope: "package", reason: _why} + encoding_agreement: {scope: "package", reason: _why} + } + } + Q: { + given_up: ["schema_agreement", "encoding_agreement"] + acknowledged: { + schema_agreement: {scope: "protocol", reason: "Q talks to the gateway directly"} + encoding_agreement: {scope: "protocol", reason: "Q talks to the gateway directly"} + } + } + } + warnings: ["unverified::schema-agreement", "unverified::encoding-agreement"] + } + } + "wrong-scope": { + about: "bounded_size can't be acknowledged at package scope" + packages: app: { + config: ["unverified = { bounded_size = \"\(_why)\" }", _allow] + schemas: api: _bare + } + build: "app" + expect: {builds: false, errors: ["unverified::wrong-scope"]} + } + "not-given-up": { + about: "a guarantee the package lists and no protocol gives up through it is a warning" + packages: app: {config: [_packageKeyed, _allow], schemas: api: _bare} + build: "app" + expect: { + builds: true + protocols: P: given_up: [] + warnings: ["unverified::not-given-up"] + } + } + "gate-off": { + about: "the package's unverified is held to the same gate as the marker" + packages: app: {config: [_noHandshake, _packageKeyed], schemas: api: _bare} + build: "app" + expect: {builds: false, errors: ["settings::forbidden"]} + } + "adds-bounded-size": { + about: "a marker says why for bounded_size, which the package can't; the package says the rest" + packages: app: { + config: [_noHandshake, _packageKeyed, _allow] + schemas: api: """ + @unverified = { bounded_size = "the uploader streams whatever it's given" } + protocol P { + function put(s: string); + } + """ + } + build: "app" + expect: { + builds: true + protocols: P: { + given_up: ["schema_agreement", "encoding_agreement", "bounded_size"] + acknowledged: { + schema_agreement: {scope: "package", reason: _why} + encoding_agreement: {scope: "package", reason: _why} + bounded_size: {scope: "protocol", reason: "the uploader streams whatever it's given"} + } + } + warnings: ["unverified::schema-agreement", "unverified::encoding-agreement", "unverified::bounded-size"] + } + } + "bounded-size-not-covered": { + about: "the package covering the handshake doesn't cover an unbounded string" + packages: app: { + config: [_noHandshake, _packageKeyed, _allow] + schemas: api: """ + protocol P { + function put(s: string); + } + """ + } + build: "app" + expect: {builds: false, errors: ["bounds::unbounded"]} + } +} diff --git a/runtime/conformance/spec/profiles/datagram@1.json b/runtime/conformance/spec/profiles/datagram@1.json index e6af17b..67149d1 100644 --- a/runtime/conformance/spec/profiles/datagram@1.json +++ b/runtime/conformance/spec/profiles/datagram@1.json @@ -29,6 +29,13 @@ "framing-datagram/request-params-msgpack", "framing-datagram/request-params-packed" ] + }, + "protocol": { + "value": "unnamed", + "proven_by": [ + "framing-datagram/request", + "framing-datagram/request-large-id" + ] } } } diff --git a/runtime/conformance/spec/profiles/datagram@2.json b/runtime/conformance/spec/profiles/datagram@2.json index 4b4dab3..4aa3d87 100644 --- a/runtime/conformance/spec/profiles/datagram@2.json +++ b/runtime/conformance/spec/profiles/datagram@2.json @@ -31,6 +31,12 @@ "framing-datagram2/request-params-msgpack", "framing-datagram2/request-params-packed" ] + }, + "protocol": { + "value": "named", + "proven_by": [ + "framing-datagram2/request-two-byte-protocol" + ] } } } diff --git a/runtime/conformance/spec/profiles/datagram@3.json b/runtime/conformance/spec/profiles/datagram@3.json index 9100fa7..abbfac5 100644 --- a/runtime/conformance/spec/profiles/datagram@3.json +++ b/runtime/conformance/spec/profiles/datagram@3.json @@ -32,6 +32,12 @@ "framing-datagram3/request-params-msgpack", "framing-datagram3/request-params-packed" ] + }, + "protocol": { + "value": "named", + "proven_by": [ + "framing-datagram3/request-two-byte-protocol" + ] } } } diff --git a/runtime/conformance/spec/profiles/jsonrpc@1.json b/runtime/conformance/spec/profiles/jsonrpc@1.json index ab27285..a48ea9a 100644 --- a/runtime/conformance/spec/profiles/jsonrpc@1.json +++ b/runtime/conformance/spec/profiles/jsonrpc@1.json @@ -32,6 +32,13 @@ "framing-jsonrpc/reject-request-params-msgpack", "framing-jsonrpc/reject-request-params-packed" ] + }, + "protocol": { + "value": "unnamed", + "proven_by": [ + "framing-jsonrpc/request", + "framing-jsonrpc/request-large-id" + ] } } } diff --git a/runtime/conformance/spec/renovate.json b/runtime/conformance/spec/renovate.json new file mode 100644 index 0000000..f8b00a1 --- /dev/null +++ b/runtime/conformance/spec/renovate.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://docs.renovatebot.com/renovate-schema.json", + "extends": ["github>ComlineProject/.github:renovate-config"] +} diff --git a/runtime/conformance/spec/rust/Cargo.toml b/runtime/conformance/spec/rust/Cargo.toml index 9bc2601..6922cb2 100644 --- a/runtime/conformance/spec/rust/Cargo.toml +++ b/runtime/conformance/spec/rust/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "comline-catalog" -version = "0.10.0" +version = "0.11.0" edition = "2021" rust-version = "1.82" license = "MPL-2.0" diff --git a/runtime/conformance/spec/rust/src/catalog.rs b/runtime/conformance/spec/rust/src/catalog.rs index 1bb1e8f..0ed3cee 100644 --- a/runtime/conformance/spec/rust/src/catalog.rs +++ b/runtime/conformance/spec/rust/src/catalog.rs @@ -5,7 +5,7 @@ use crate::{ SeqSize, Sizes, Status, StringSize, StructSize, Value, Width, }; -pub const SPEC_VERSION: &str = r#"0.10"#; +pub const SPEC_VERSION: &str = r#"0.11"#; /// Every guarantee, in the catalog's order. pub const GUARANTEES: &[Guarantee] = &[ @@ -184,6 +184,17 @@ pub const FACTS: &[Fact] = &[ replaced_by: None, since: Some(r#"0.7"#), }, + Fact { + id: r#"protocol"#, + applies_to: Kind::Framing, + title: r#"protocol"#, + description: r#"Whether a request's frame names the protocol it calls into."#, + values: &[Value { id: r#"named"#, meaning: r#"it does, by number or wire id, so several protocols can share one transport"# }, Value { id: r#"unnamed"#, meaning: r#"it doesn't: a call names only its function"# }], + establishes: None, + status: Status::Stable, + replaced_by: None, + since: Some(r#"0.11"#), + }, Fact { id: r#"schema_agreement"#, applies_to: Kind::Handshake, @@ -601,6 +612,7 @@ pub mod fact { pub const DIRECTIONS: &str = r#"directions"#; pub const ERRORS: &str = r#"errors"#; pub const PAYLOAD: &str = r#"payload"#; + pub const PROTOCOL: &str = r#"protocol"#; pub const SCHEMA_AGREEMENT: &str = r#"schema_agreement"#; pub const ENCODING_AGREEMENT: &str = r#"encoding_agreement"#; } @@ -648,7 +660,7 @@ pub mod sets { pub const OFFICIAL: &[&str] = &[r#"packed@1"#, r#"json@1"#, r#"msgpack@1"#, r#"jsonrpc@1"#, r#"datagram@1"#, r#"datagram@2"#, r#"datagram@3"#, r#"comline@1"#, r#"comline@2"#, r#"none"#]; pub const PROFILED: &[&str] = &[r#"packed@1"#, r#"json@1"#, r#"msgpack@1"#, r#"jsonrpc@1"#, r#"datagram@1"#, r#"datagram@2"#, r#"datagram@3"#, r#"comline@1"#, r#"comline@2"#]; pub const FORMAT_FACTS: &[&str] = &[r#"struct_fields"#, r#"unknown_field"#, r#"missing_optional"#, r#"enum_variants"#, r#"unknown_variant"#, r#"integer_width"#, r#"output"#]; - pub const FRAMING_FACTS: &[&str] = &[r#"calls"#, r#"directions"#, r#"errors"#, r#"payload"#]; + pub const FRAMING_FACTS: &[&str] = &[r#"calls"#, r#"directions"#, r#"errors"#, r#"payload"#, r#"protocol"#]; pub const HANDSHAKE_FACTS: &[&str] = &[r#"schema_agreement"#, r#"encoding_agreement"#]; pub const FEATURES: &[&str] = &[r#"name-hash"#, r#"handshake"#, r#"envelope"#, r#"framing-datagram"#, r#"framing-datagram2"#, r#"framing-datagram3"#, r#"handshake-comline2"#, r#"stream"#, r#"framing-jsonrpc"#, r#"format-json"#, r#"format-msgpack"#, r#"format-packed"#, r#"sizes-packed"#, r#"sizes-msgpack"#, r#"sizes-json"#]; /// Every alias, with the wire name it resolves to. diff --git a/runtime/conformance/spec/specs/check.sh b/runtime/conformance/spec/specs/check.sh index 7e961e2..60f2389 100755 --- a/runtime/conformance/spec/specs/check.sh +++ b/runtime/conformance/spec/specs/check.sh @@ -2,8 +2,9 @@ # Generates gen/*.schema.json (and benches/bench.schema.json, which ships with # the benches so a vendored copy of them is whole) from the specs, and # features.json, catalog/gen/catalog.json and rust/src/catalog.rs from the -# catalog, and vets every corpus file against them (and, with jq, holds the -# size rules to their vectors). `--check` fails instead of +# catalog, and compiler/cases/*.json from compiler/src, and vets every corpus +# file against them (and, with jq, holds the size rules to their vectors and the +# compiler cases to what their schema can't say). `--check` fails instead of # writing when a generated file is stale. set -eu cd "$(dirname "$0")" @@ -36,6 +37,7 @@ vet() { # ... } generate Bench ../benches/bench.schema.json +generate CompilerCases gen/compiler.schema.json generate Features gen/features.schema.json generate Profile gen/profile.schema.json generate Report gen/report.schema.json @@ -73,6 +75,21 @@ else rust_catalog > ../rust/src/catalog.rs fi +# The compiler cases, written compactly in compiler/src, as the JSON runners +# read (compiler/readme.md): one file per group. +groups=$(cue eval ../compiler/src -e 'strings.Join([for g, _ in groups {g}], "\n")' --out text) +for group in $groups; do + if $check; then + if ! cue export ../compiler/src -e "out.\"$group\"" | cmp -s - "../compiler/cases/$group.json"; then + echo "../compiler/cases/$group.json is out of date: run specs/check.sh" >&2 + failed=1 + fi + else + mkdir -p ../compiler/cases + cue export ../compiler/src -e "out.\"$group\"" -o "../compiler/cases/$group.json" -f + fi +done + # profiles/ and vectors/ hold exactly what the catalog names. same_names() { # if [ "$(printf '%s\n' "$2" | sort)" != "$(printf '%s\n' "$3" | sort)" ]; then @@ -85,6 +102,8 @@ names_in() { # } same_names profiles "$(cue export ../catalog -e 'strings.Join(sets.profiled, "\n")' --out text)" "$(names_in ../profiles)" same_names vectors "$(cue export ../catalog -e 'strings.Join(sets.features, "\n")' --out text)" "$(names_in ../vectors)" +# compiler/cases/ holds exactly the groups compiler/src declares. +same_names "compiler cases" "$groups" "$(names_in ../compiler/cases)" for file in ../profiles/*.json; do if ! cue vet -c -d '#OfficialProfile' ../catalog "json:" "$file"; then echo "$file isn't the profile the catalog gives its encoding" >&2 @@ -112,11 +131,39 @@ for file in ../profiles/*.json; do fi done +# A framing's `protocol` is shown by its cases: `named` by requests whose bytes +# hold the protocol's number, `unnamed` by requests that give none +# (`specs/protocol.jq`). +for file in ../profiles/*.json; do + [ "$(jq -r '.kind' "$file")" = framing ] || continue + if ! problems=$(jq -s -r --slurpfile profile "$file" -f protocol.jq ../vectors/framing-*.json); then + echo "$file or the framing vectors can't be read as a protocol fact and vectors" >&2 + failed=1 + elif [ -n "$problems" ]; then + echo "$file's protocol isn't proven by its vectors:" >&2 + echo "$problems" >&2 + failed=1 + fi +done + # Not the schema the benches ship with. vet Bench $(ls ../benches/*.json | grep -v '/bench\.schema\.json$') vet Features ../features.json vet Profile ../profiles/*.json vet Vectors ../vectors/*.json +vet CompilerCases ../compiler/cases/*.json + +# What the compiler cases' schema can't say (`specs/compiler.jq`). +for file in ../compiler/cases/*.json; do + if ! problems=$(jq -r -f compiler.jq "$file"); then + echo "$file can't be read as compiler cases" >&2 + failed=1 + elif [ -n "$problems" ]; then + echo "$file has problems:" >&2 + echo "$problems" >&2 + failed=1 + fi +done # `reports/` and `support/` live in each runtime's repository, which vets them # against its vendored copy of these specs. @@ -138,6 +185,7 @@ through() { # ... through ../benches/bench.schema.json ../benches/connection.json ../benches/framings.json ../benches/handshake.json through gen/features.schema.json ../features.json through gen/profile.schema.json ../profiles/*.json +through gen/compiler.schema.json ../compiler/cases/*.json through gen/vectors.schema.json ../vectors/envelope.json ../vectors/framing-*.json ../vectors/handshake*.json \ ../vectors/name-hash.json ../vectors/stream.json diff --git a/runtime/conformance/spec/specs/compiler.cue b/runtime/conformance/spec/specs/compiler.cue new file mode 100644 index 0000000..9c7a736 --- /dev/null +++ b/runtime/conformance/spec/specs/compiler.cue @@ -0,0 +1,117 @@ +package conformance + +import "github.com/comlineproject/specification/catalog" + +// `compiler/cases/.json`: compiler conformance cases. Each is a schema +// graph as data, with the outcome any compiler must reproduce for it: the +// way runtimes reproduce the vectors' bytes. `compiler/readme.md` says what +// a case holds and how a compiler runs one. +#CompilerCases: close({ + $schema?: string + // The file's name: every case's id is `/`. + group!: =~"^[a-z0-9-]+$" + cases!: [...#CompilerCase] +}) + +#CompilerCase: close({ + id!: #CaseId + // One line. + description!: =~"^[^\n]+$" + // The case's packages: one to build, and the ones it depends on, directly + // or not. Each is a directory named after it, side by side. + packages!: [#CompilerPackage, ...#CompilerPackage] + // The package to build: one of `packages`. + build!: #CompilerPackageName + expect!: #CompilerExpect +}) + +// A package's name is its congregation's, its directory's and the name +// its dependants use it by in `use`. +#CompilerPackageName: =~"^[a-z][a-z0-9_]*$" + +#CompilerPackage: close({ + name!: #CompilerPackageName + // `config.idp`, whole. + config!: string + // The schema files, `src/.ids`. + schemas!: [...close({ + path!: =~"^src/([a-z][a-z0-9_]*/)*[a-z][a-z0-9_]*\\.ids$" + text!: string + })] + // The packages this one depends on by path (`../`), as `config` + // declares them. Restated here so a runner can lay the packages out, and + // a check can hold them to `config`, without reading `config.idp`. + dependencies!: [...close({ + name!: #CompilerPackageName + // What `config` accepts of the dependency's unverified protocols: a + // protocol's name and the guarantees it gives up, which have to be + // exactly its set. + accept_unverified?: [string]: [...#CompilerGuarantee] + })] +}) + +// A guarantee's id in the catalog. +#CompilerGuarantee: or([for id, _ in catalog.guarantees {id}]) + +// What building the package gives. A build that succeeds says what each of +// its protocols gives up, and its warnings; one that fails, its errors, as +// codes where they have one and else as text. +#CompilerExpect: #CompilerBuilds | #CompilerFails + +#CompilerBuilds: close({ + builds!: true + // Every protocol of the package built, and no others. + protocols!: [...#CompilerProtocol] + // The warnings, and no others. + diagnostics!: [...#CompilerWarning] +}) + +#CompilerFails: close({ + builds!: false + // The errors, and no others, of those that have a code. + diagnostics!: [...#CompilerError] + // For an error without a code: text its message contains. Provisional, + // until such errors get codes. + error_contains?: [string, ...string] +}) + +#CompilerProtocol: close({ + name!: =~"^[A-Z][A-Za-z0-9]*$" + // The guarantees it gives up, as a set: what is frozen with it. + given_up!: [...#CompilerGuarantee] + // Who acknowledged some of what it gives up, and the reason shown for it, + // where the case asserts it: guarantees it doesn't list aren't asserted. + acknowledged?: [...close({ + guarantee!: #CompilerGuarantee + // Where the acknowledgement was written: on the protocol, or in + // `config.idp` for the package. + scope!: catalog.#Scope & ("package" | "protocol") + reason?: string + })] +}) + +// A diagnostic is matched on its code and severity, not its message. The +// vocabulary is closed; a code not here has no case yet. +#CompilerDiagnostic: #CompilerError | #CompilerWarning + +#CompilerError: or([ + close({code!: "unverified::missing-marker", severity!: "error"}), + close({code!: "unverified::missing-reason", severity!: "error"}), + close({code!: "unverified::unknown-guarantee", severity!: "error"}), + close({code!: "unverified::duplicate-guarantee", severity!: "error"}), + close({code!: "unverified::missing-guarantee", severity!: "error"}), + close({code!: "unverified::wrong-scope", severity!: "error"}), + close({code!: "bounds::unbounded", severity!: "error"}), + close({code!: "bounds::unbounded-depth", severity!: "error"}), + close({code!: "settings::forbidden", severity!: "error"}), +]) + +#CompilerWarning: or([ + close({code!: "unverified::not-given-up", severity!: "warning"}), + close({code!: "unverified::nothing-given-up", severity!: "warning"}), + close({code!: "unverified::schema-agreement", severity!: "warning"}), + close({code!: "unverified::encoding-agreement", severity!: "warning"}), + close({code!: "unverified::encoding-conformance", severity!: "warning"}), + close({code!: "unverified::bounded-size", severity!: "warning"}), + close({code!: "unverified::version-honesty", severity!: "warning"}), +]) diff --git a/runtime/conformance/spec/specs/compiler.jq b/runtime/conformance/spec/specs/compiler.jq new file mode 100644 index 0000000..c4ce27c --- /dev/null +++ b/runtime/conformance/spec/specs/compiler.jq @@ -0,0 +1,91 @@ +# Holds a compiler conformance file (`compiler/cases/.json`) to what +# its schema (`#CompilerCases`) can't say: `specs/check.sh` runs this on +# each file, and fails on any line it prints. +# +# - every case's id is `/`, and ids are unique; +# - the case's package names are unique, `build` and every dependency name +# one of them (not the package itself), and the dependencies have no cycle; +# - a package's schema paths are unique, and its `config` declares each +# dependency by path (`../`), and accepts what `accept_unverified` +# says; +# - `expect` names each protocol of the package built, once, and no +# others; a protocol's given-up guarantees and its acknowledged ones are +# sets, and only those given up are acknowledged; +# - an acknowledgement's reason is written in the package built; +# - diagnostics are unique; +# - a build that fails says why: an error with a code, or text it contains. + +def protocols_of($package): + [$package.schemas[].text | scan("(?m)^protocol ([A-Za-z0-9_]+)") | .[0]]; + +def duplicates: group_by(.) | map(select(length > 1) | .[0]); + +# Packages that remain after dropping the ones whose dependencies are all gone, +# until none is left or none can go: the cycle, if any. +def stuck($packages): + reduce range(0; $packages | length + 1) as $_ ( + $packages; + . as $left + | ($left | map(.name)) as $names + | map(select(any(.dependencies[].name; . as $d | $names | index($d)))) + ); + +. as $file +| .cases[] +| . as $case +| ($case.id) as $id +| ( + (if ($id | startswith($file.group + "/")) then empty else "\($id): not in group \($file.group)" end), + ($case.packages | map(.name)) as $names + | ( + ($names | duplicates | map("\($id): package \(.) twice") | .[]), + (if ($names | index($case.build)) then empty else "\($id): builds \($case.build), which is no package" end), + ($case.packages[] | . as $p + | ( + ($p.dependencies[] | .name as $d + | (if $d == $p.name then "\($id): \($p.name) depends on itself" + elif ($names | index($d)) then empty + else "\($id): \($p.name) depends on \($d), which is no package" end), + (if ($p.config | contains("path = \"../\($d)\"")) then empty + else "\($id): \($p.name)'s config doesn't declare \($d) by path" end), + ((.accept_unverified // {}) | to_entries[] + | (.key as $protocol | .value as $ids + | (if ($p.config | contains("\($protocol) = [" + ($ids | map("\"\(.)\"") | join(", ")) + "]")) + then empty + else "\($id): \($p.name)'s config doesn't accept \($protocol) for \($ids | join(", "))" end), + (if ($ids | length) == ($ids | unique | length) then empty + else "\($id): \($p.name) accepts a guarantee of \($protocol) twice" end)))), + ($p.schemas | map(.path) | duplicates | map("\($id): \($p.name) has \(.) twice") | .[]) + )), + (if (stuck($case.packages) | length) > 0 + then "\($id): packages depend on each other in a cycle: \(stuck($case.packages) | map(.name) | join(", "))" + else empty end), + ($case.packages[] | select(.name == $case.build) as $built + | $case.expect as $expect + | ( + ($expect.diagnostics | map(.code) | duplicates | map("\($id): diagnostic \(.) twice") | .[]), + (if $expect.builds then + (protocols_of($built) | sort) as $declared + | ($expect.protocols | map(.name) | sort) as $listed + | (if $declared == $listed then empty + else "\($id): expects protocols \($listed | join(", ")), and \($built.name) declares \($declared | join(", "))" end), + ($expect.protocols[] + | . as $protocol + | (if (.given_up | length) == (.given_up | unique | length) then empty + else "\($id): \($protocol.name) gives up a guarantee twice" end), + ((.acknowledged // []) | map(.guarantee) as $acknowledged + | (if ($acknowledged | length) == ($acknowledged | unique | length) then empty + else "\($id): \($protocol.name) acknowledges a guarantee twice" end), + ($acknowledged[] | select(. as $g | $protocol.given_up | index($g) | not) + | "\($id): \($protocol.name) acknowledges \(.), which it doesn't give up")), + ((.acknowledged // [])[] | select(.reason != null) + | . as $a + | if ($built.schemas | any(.text | contains($a.reason))) or ($built.config | contains($a.reason)) then empty + else "\($id): \($protocol.name)'s reason for \($a.guarantee) isn't written in \($built.name)" end)) + else + (if ($expect.diagnostics | length) > 0 or (($expect.error_contains // []) | length) > 0 then empty + else "\($id): fails and says neither an error nor text it contains" end) + end) + )) + ) + ) diff --git a/runtime/conformance/spec/specs/gen/compiler.schema.json b/runtime/conformance/spec/specs/gen/compiler.schema.json new file mode 100644 index 0000000..5613bbd --- /dev/null +++ b/runtime/conformance/spec/specs/gen/compiler.schema.json @@ -0,0 +1,358 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$defs": { + "CaseId": { + "type": "string", + "description": "A vector case's id: `/`.", + "pattern": "^[a-z0-9.@_-]+/[a-z0-9.@_-]+$" + }, + "CompilerBuilds": { + "type": "object", + "additionalProperties": false, + "properties": { + "builds": { + "const": true + }, + "diagnostics": { + "type": "array", + "description": "The warnings, and no others.", + "items": { + "$ref": "#/$defs/CompilerWarning" + } + }, + "protocols": { + "type": "array", + "description": "Every protocol of the package built, and no others.", + "items": { + "$ref": "#/$defs/CompilerProtocol" + } + } + }, + "required": [ + "builds", + "diagnostics", + "protocols" + ] + }, + "CompilerCase": { + "type": "object", + "additionalProperties": false, + "properties": { + "build": { + "description": "The package to build: one of `packages`.", + "$ref": "#/$defs/CompilerPackageName" + }, + "description": { + "type": "string", + "description": "One line.", + "pattern": "^[^\n]+$" + }, + "expect": { + "$ref": "#/$defs/CompilerExpect" + }, + "id": { + "$ref": "#/$defs/CaseId" + }, + "packages": { + "type": "array", + "description": "The case's packages: one to build, and the ones it depends on, directly\nor not. Each is a directory named after it, side by side.", + "items": { + "$ref": "#/$defs/CompilerPackage" + }, + "prefixItems": [ + { + "$ref": "#/$defs/CompilerPackage" + } + ], + "minItems": 1 + } + }, + "required": [ + "build", + "description", + "expect", + "id", + "packages" + ] + }, + "CompilerError": { + "enum": [ + { + "code": "unverified::missing-marker", + "severity": "error" + }, + { + "code": "unverified::missing-reason", + "severity": "error" + }, + { + "code": "unverified::unknown-guarantee", + "severity": "error" + }, + { + "code": "unverified::duplicate-guarantee", + "severity": "error" + }, + { + "code": "unverified::missing-guarantee", + "severity": "error" + }, + { + "code": "unverified::wrong-scope", + "severity": "error" + }, + { + "code": "bounds::unbounded", + "severity": "error" + }, + { + "code": "bounds::unbounded-depth", + "severity": "error" + }, + { + "code": "settings::forbidden", + "severity": "error" + } + ] + }, + "CompilerExpect": { + "description": "What building the package gives. A build that succeeds says what each of\nits protocols gives up, and its warnings; one that fails, its errors, as\ncodes where they have one and else as text.", + "anyOf": [ + { + "$ref": "#/$defs/CompilerBuilds" + }, + { + "$ref": "#/$defs/CompilerFails" + } + ] + }, + "CompilerFails": { + "type": "object", + "additionalProperties": false, + "properties": { + "builds": { + "const": false + }, + "diagnostics": { + "type": "array", + "description": "The errors, and no others, of those that have a code.", + "items": { + "$ref": "#/$defs/CompilerError" + } + }, + "error_contains": { + "type": "array", + "description": "For an error without a code: text its message contains. Provisional,\nuntil such errors get codes.", + "items": { + "type": "string" + }, + "prefixItems": [ + { + "type": "string" + } + ], + "minItems": 1 + } + }, + "required": [ + "builds", + "diagnostics" + ] + }, + "CompilerGuarantee": { + "description": "A guarantee's id in the catalog.", + "enum": [ + "schema_agreement", + "encoding_agreement", + "encoding_conformance", + "version_honesty", + "bounded_size" + ] + }, + "CompilerPackage": { + "type": "object", + "additionalProperties": false, + "properties": { + "config": { + "type": "string", + "description": "`config.idp`, whole." + }, + "dependencies": { + "type": "array", + "description": "The packages this one depends on by path (`../`), as `config`\ndeclares them. Restated here so a runner can lay the packages out, and\na check can hold them to `config`, without reading `config.idp`.", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "accept_unverified": { + "type": "object", + "description": "What `config` accepts of the dependency's unverified protocols: a\nprotocol's name and the guarantees it gives up, which have to be\nexactly its set.", + "additionalProperties": { + "type": "array", + "items": { + "$ref": "#/$defs/CompilerGuarantee" + } + } + }, + "name": { + "$ref": "#/$defs/CompilerPackageName" + } + }, + "required": [ + "name" + ] + } + }, + "name": { + "$ref": "#/$defs/CompilerPackageName" + }, + "schemas": { + "type": "array", + "description": "The schema files, `src/.ids`.", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "path": { + "type": "string", + "pattern": "^src/([a-z][a-z0-9_]*/)*[a-z][a-z0-9_]*\\.ids$" + }, + "text": { + "type": "string" + } + }, + "required": [ + "path", + "text" + ] + } + } + }, + "required": [ + "config", + "dependencies", + "name", + "schemas" + ] + }, + "CompilerPackageName": { + "type": "string", + "description": "A package's name is its congregation's, its directory's and the name\nits dependants use it by in `use`.", + "pattern": "^[a-z][a-z0-9_]*$" + }, + "CompilerProtocol": { + "type": "object", + "additionalProperties": false, + "properties": { + "acknowledged": { + "type": "array", + "description": "Who acknowledged some of what it gives up, and the reason shown for it,\nwhere the case asserts it: guarantees it doesn't list aren't asserted.", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "guarantee": { + "$ref": "#/$defs/CompilerGuarantee" + }, + "reason": { + "type": "string" + }, + "scope": { + "description": "Where the acknowledgement was written: on the protocol, or in\n`config.idp` for the package.", + "$ref": "#/$defs/Scope", + "enum": [ + "package", + "protocol" + ] + } + }, + "required": [ + "guarantee", + "scope" + ] + } + }, + "given_up": { + "type": "array", + "description": "The guarantees it gives up, as a set: what is frozen with it.", + "items": { + "$ref": "#/$defs/CompilerGuarantee" + } + }, + "name": { + "type": "string", + "pattern": "^[A-Z][A-Za-z0-9]*$" + } + }, + "required": [ + "given_up", + "name" + ] + }, + "CompilerWarning": { + "enum": [ + { + "code": "unverified::not-given-up", + "severity": "warning" + }, + { + "code": "unverified::nothing-given-up", + "severity": "warning" + }, + { + "code": "unverified::schema-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-agreement", + "severity": "warning" + }, + { + "code": "unverified::encoding-conformance", + "severity": "warning" + }, + { + "code": "unverified::bounded-size", + "severity": "warning" + }, + { + "code": "unverified::version-honesty", + "severity": "warning" + } + ] + }, + "Scope": { + "enum": [ + "package", + "protocol", + "function", + "argument", + "field", + "type" + ] + } + }, + "type": "object", + "description": "`compiler/cases/.json`: compiler conformance cases. Each is a schema\ngraph as data, with the outcome any compiler must reproduce for it: the\nway runtimes reproduce the vectors' bytes. `compiler/readme.md` says what\na case holds and how a compiler runs one.", + "additionalProperties": false, + "properties": { + "$schema": { + "type": "string" + }, + "cases": { + "type": "array", + "items": { + "$ref": "#/$defs/CompilerCase" + } + }, + "group": { + "type": "string", + "description": "The file's name: every case's id is `/`.", + "pattern": "^[a-z0-9-]+$" + } + }, + "required": [ + "cases", + "group" + ] +} diff --git a/runtime/conformance/spec/specs/gen/profile.schema.json b/runtime/conformance/spec/specs/gen/profile.schema.json index 32ed6b6..ea6bdf7 100644 --- a/runtime/conformance/spec/specs/gen/profile.schema.json +++ b/runtime/conformance/spec/specs/gen/profile.schema.json @@ -307,13 +307,33 @@ "proven_by", "value" ] + }, + "protocol": { + "type": "object", + "additionalProperties": false, + "properties": { + "proven_by": { + "$ref": "#/$defs/ProvenBy" + }, + "value": { + "enum": [ + "named", + "unnamed" + ] + } + }, + "required": [ + "proven_by", + "value" + ] } }, "required": [ "calls", "directions", "errors", - "payload" + "payload", + "protocol" ] }, "kind": { diff --git a/runtime/conformance/spec/specs/protocol.jq b/runtime/conformance/spec/specs/protocol.jq new file mode 100644 index 0000000..6d0c71b --- /dev/null +++ b/runtime/conformance/spec/specs/protocol.jq @@ -0,0 +1,47 @@ +# Holds a framing's `protocol` fact to the cases that prove it: `specs/check.sh` +# runs this on each framing profile ($profile), slurping the framing vectors +# (`.` is the array of them), and fails on any line it prints. +# +# - every case it names exists and is an exact `request` (not a rejection or +# an `accept`), in a feature of the profile's own framing; +# - `named`: the case's input has a `protocol` that is 128 or more, so its +# varint takes two bytes or more, and is not the case's `call_id`, so the +# bytes can't hold it as the function's number; and the bytes hold that +# number's varint (LEB128), from a byte boundary. A request that holds +# the protocol is one that names it; +# - `unnamed`: the case's input has no `protocol`, and decoding its bytes +# gives that input back, so the frame carries none. (A request can't be +# shown to ignore a protocol it was never given: encoding what the input +# holds is all a case asks.) +# +# That a `named` number is in the frame for every protocol, and where, is the +# framing's own vectors' to show: this holds the cases the profile names. + +# A number's LEB128 bytes, as lowercase hex. +def hex2: "0123456789abcdef" as $d | $d[. / 16 | floor : (. / 16 | floor) + 1] + $d[. % 16 : (. % 16) + 1]; +def varint: if . < 128 then [.] else [(. % 128) + 128] + ((. / 128 | floor) | varint) end; +def varint_hex: varint | map(hex2) | join(""); + +# Whether `needle` (hex) is in `hay` (hex) at a byte boundary. +def holds($needle): . as $hay | any(range(0; ($hay | length) / 2); . as $i | $hay[2 * $i : 2 * $i + ($needle | length)] == $needle); + +$profile[0] as $p +| $p.facts.protocol as $f +| ([.[].cases[]] | map({key: .id, value: .}) | from_entries) as $cases +| if $f == null then "no `protocol` fact" else + $f.proven_by[] as $id + | $cases[$id] as $c + | if $c == null then "protocol: no case \($id)" + elif $c.op != "request" or ($c.expect // "exact") != "exact" then "protocol: \($id) isn't an exact request" + elif $c.input.framing != $p.name then "protocol: \($id) is for \($c.input.framing), not \($p.name)" + elif $f.value == "named" then + if ($c.input.protocol // null) == null then "protocol: \($id) has no protocol to name" + elif $c.input.protocol < 128 then "protocol: \($id)'s protocol is under 128, which a byte can hold by chance" + elif $c.input.protocol == $c.input.call_id then "protocol: \($id)'s protocol is its call_id, so its bytes can't tell them apart" + elif ($c.bytes | holds($c.input.protocol | varint_hex)) | not then "protocol: \($id)'s bytes don't hold its protocol \($c.input.protocol)" + else empty end + elif $f.value == "unnamed" then + if $c.input | has("protocol") then "protocol: \($id) gives a protocol, which its frame doesn't carry" + else empty end + else "protocol: \($f.value) isn't a value this check knows" end + end diff --git a/runtime/conformance/spec/specs/readme.md b/runtime/conformance/spec/specs/readme.md index b01fc8f..c490ec8 100644 --- a/runtime/conformance/spec/specs/readme.md +++ b/runtime/conformance/spec/specs/readme.md @@ -8,6 +8,7 @@ runtime that vendors `benches/` alone has it. | Definition | Files | Spec | | --- | --- | --- | | `#Bench` | `benches/*.json` | [`bench.cue`](bench.cue) | +| `#CompilerCases` | `compiler/cases/*.json` | [`compiler.cue`](compiler.cue) | | `#Features` | `features.json` | [`features.cue`](features.cue) | | `#Profile` | `profiles/*.json` | [`profile.cue`](profile.cue) | | `#Report` | `reports/.json`, in each runtime's repository | [`report.cue`](report.cue) | @@ -29,7 +30,11 @@ catalog, and vets every file. It also checks that `profiles/` and `vectors/` hold exactly what the catalog names, and, with [`jq`](https://jqlang.github.io/jq/) ([`sizes.jq`](sizes.jq)), that each format's size rules are proven by its size vectors: every rule lists cases that exist and show it, every case proves -a rule, and every witness is as long as its case says. CI runs `./check.sh --check`, which fails +a rule, and every witness is as long as its case says. It generates +`../compiler/cases/` from `../compiler/src/` (the [compiler cases](../compiler/readme.md)), +and, with [`compiler.jq`](compiler.jq), holds them to what their schema can't say. +It also holds each framing's `protocol` fact to the cases it names +([`protocol.jq`](protocol.jq)). CI runs `./check.sh --check`, which fails instead when a generated file is stale. It needs [`cue`](https://cuelang.org) at the version `.github/workflows/check.yml` pins. diff --git a/runtime/conformance/spec/vectors/framing-datagram3.json b/runtime/conformance/spec/vectors/framing-datagram3.json index ece96ab..52093ad 100644 --- a/runtime/conformance/spec/vectors/framing-datagram3.json +++ b/runtime/conformance/spec/vectors/framing-datagram3.json @@ -25,6 +25,22 @@ }, "bytes": "0000032a000000000000005b372c2278225d" }, + { + "id": "framing-datagram3/request-two-byte-protocol", + "op": "request", + "input": { + "call_id": 1, + "format": "json@1", + "framing": "datagram@3", + "method": "ping", + "params": { + "array": [] + }, + "protocol": 300, + "request_id": "5" + }, + "bytes": "00ac020105000000000000005b5d" + }, { "id": "framing-datagram3/request-two-byte-numbers", "op": "request", diff --git a/runtime/conformance/src/lib.rs b/runtime/conformance/src/lib.rs index d48b631..16f0b0b 100644 --- a/runtime/conformance/src/lib.rs +++ b/runtime/conformance/src/lib.rs @@ -33,8 +33,8 @@ pub use engine::{answer, decode_typed, encode_as, encoded_len_as, run, Answer}; pub(crate) use engine::to_json; pub use json_equal::json_equal; pub use profile::{ - fact_shown, Calls, EnumVariants, Errors, Fact, Facts, FormatFacts, FramingFacts, - HandshakeFacts, IntegerWidth, MissingOptional, Output, Payload, Profile, ProfileKind, Stated, + case_framing, fact_shown, Calls, EnumVariants, Errors, Fact, Facts, FormatFacts, FramingFacts, + HandshakeFacts, IntegerWidth, MissingOptional, Output, Payload, Profile, Protocol, ProfileKind, Stated, StructFields, UnknownField, UnknownVariant, }; diff --git a/runtime/conformance/src/profile.rs b/runtime/conformance/src/profile.rs index 65bfc6b..bdaf9bc 100644 --- a/runtime/conformance/src/profile.rs +++ b/runtime/conformance/src/profile.rs @@ -79,6 +79,7 @@ impl Facts { of(Fact::Directions, &f.directions), of(Fact::Errors, &f.errors), of(Fact::Payload, &f.payload), + of(Fact::Protocol, &f.protocol), ], Facts::Handshake(f) => [ f.encoding_agreement @@ -147,6 +148,7 @@ pub struct FramingFacts { pub directions: Stated, pub errors: Stated, pub payload: Stated, + pub protocol: Stated, } /// A handshake may leave a fact out, which reads as `false`: not established. @@ -205,6 +207,7 @@ fact_values! { Errors = fact::ERRORS { ByOrdinal = "by_ordinal", ByName = "by_name" } Output = fact::OUTPUT { Bytes = "bytes", Json = "json" } Payload = fact::PAYLOAD { Opaque = "opaque", Json = "json" } + Protocol = fact::PROTOCOL { Named = "named", Unnamed = "unnamed" } } impl Payload { @@ -250,6 +253,7 @@ pub enum Fact { Errors(Errors), Output(Output), Payload(Payload), + Protocol(Protocol), SchemaAgreement(bool), EncodingAgreement(bool), } @@ -269,6 +273,7 @@ impl Fact { Fact::Errors(_) => Errors::FACT, Fact::Output(_) => Output::FACT, Fact::Payload(_) => Payload::FACT, + Fact::Protocol(_) => Protocol::FACT, Fact::SchemaAgreement(_) => fact::SCHEMA_AGREEMENT, Fact::EncodingAgreement(_) => fact::ENCODING_AGREEMENT, } @@ -288,6 +293,7 @@ impl Fact { Fact::Errors(v) => v.as_str(), Fact::Output(v) => v.as_str(), Fact::Payload(v) => v.as_str(), + Fact::Protocol(v) => v.as_str(), Fact::SchemaAgreement(true) | Fact::EncodingAgreement(true) => "true", Fact::SchemaAgreement(false) | Fact::EncodingAgreement(false) => "false", } @@ -353,6 +359,7 @@ fn decoding_fact_shown(fact: Fact, first: &Case, cases: &[&Case]) -> bool { Fact::Output(output) => output_shown(output, cases), Fact::Payload(Payload::Opaque) => cases.iter().any(|c| carries_non_json(c)), Fact::Payload(Payload::Json) => embedding_shown(cases), + Fact::Protocol(protocol) => protocol_shown(protocol, cases), Fact::SchemaAgreement(_) | Fact::EncodingAgreement(_) => { unreachable!("handshake facts aren't shown by decoding") } @@ -402,6 +409,50 @@ fn directions_shown(directions: Directions, cases: &[&Case]) -> bool { } } +/// `protocol` is shown by exact requests. For `named`, each one's `protocol` +/// is 128 or more, so its varint takes two bytes or more, and isn't its +/// `call_id`, so its bytes can't hold it as the function's number; and its +/// bytes hold that number's varint (LEB128) at a byte boundary. A request that +/// holds the protocol is one that names it. For `unnamed`, each one's input has +/// no `protocol`, and decoding its bytes gives that input back, so the frame +/// carries none. Which framing a case is for is the profile's to check +/// ([`case_framing`]). +fn protocol_shown(protocol: Protocol, cases: &[&Case]) -> bool { + !cases.is_empty() + && cases.iter().all(|case| match &case.input { + Input::Request(Framed::Full(i)) if case.expect == Expect::Exact => match protocol { + Protocol::Named => i.protocol.is_some_and(|number| { + let varint = leb128(number); + number >= 128 + && number != i.call_id + && case.bytes.0.windows(varint.len()).any(|w| w == varint) + }), + Protocol::Unnamed => i.protocol.is_none(), + }, + _ => false, + }) +} + +/// A number's LEB128 bytes. +fn leb128(mut number: u16) -> Vec { + let mut bytes = Vec::new(); + while number >= 0x80 { + bytes.push((number & 0x7f) as u8 | 0x80); + number >>= 7; + } + bytes.push(number as u8); + bytes +} + +/// The framing a request or response case is for. +pub fn case_framing(case: &Case) -> Option<&str> { + match &case.input { + Input::Request(Framed::Full(i)) => Some(&i.framing), + Input::Response(Framed::Full(i)) => Some(&i.framing), + _ => None, + } +} + /// A case that shows how a framing carries an error: an exact error response. /// A response's input holds only the error's ordinal, so whether the frame has /// that or a name (`by_ordinal`, `by_name`) rests on the case passing. @@ -542,6 +593,7 @@ mod tests { (Errors::FACT, values(Errors::ALL, Errors::as_str)), (Output::FACT, values(Output::ALL, Output::as_str)), (Payload::FACT, values(Payload::ALL, Payload::as_str)), + (Protocol::FACT, values(Protocol::ALL, Protocol::as_str)), (fact::SCHEMA_AGREEMENT, vec!["true", "false"]), (fact::ENCODING_AGREEMENT, vec!["true", "false"]), ]; @@ -580,9 +632,13 @@ mod tests { let by_name = json!({ "value": "by_name", "proven_by": ["a/c"] }); let opaque = json!({ "value": "opaque", "proven_by": ["a/d"] }); let both = json!({ "value": "both", "proven_by": ["a/e"] }); + let named = json!({ "value": "named", "proven_by": ["a/f"] }); let read = profile( "framing", - json!({ "calls": by_id, "directions": both, "errors": by_name, "payload": opaque }), + json!({ + "calls": by_id, "directions": both, "errors": by_name, "payload": opaque, + "protocol": named, + }), ) .unwrap(); assert_eq!(read.kind(), ProfileKind::Framing); @@ -594,12 +650,26 @@ mod tests { ("errors", "by_name") ); assert_eq!(stated[3].0, Fact::Payload(Payload::Opaque)); + assert_eq!(stated[4].0, Fact::Protocol(Protocol::Named)); // A fact missing, an unknown fact, an unknown value. - assert!(profile("framing", json!({ "calls": by_id, "errors": by_name, "payload": opaque })).is_err()); - let more = json!({ "calls": by_id, "directions": both, "errors": by_name, "payload": opaque, "more": by_name }); + let without_directions = json!({ + "calls": by_id, "errors": by_name, "payload": opaque, "protocol": named, + }); + assert!(profile("framing", without_directions).is_err()); + let without_protocol = json!({ + "calls": by_id, "directions": both, "errors": by_name, "payload": opaque, + }); + assert!(profile("framing", without_protocol).is_err()); + let more = json!({ + "calls": by_id, "directions": both, "errors": by_name, "payload": opaque, + "protocol": named, "more": by_name, + }); assert!(profile("framing", more).is_err()); - let wrong = json!({ "calls": { "value": "by_ordinal" }, "directions": both, "errors": by_name, "payload": opaque }); + let wrong = json!({ + "calls": { "value": "by_ordinal" }, "directions": both, "errors": by_name, + "payload": opaque, "protocol": named, + }); assert!(profile("framing", wrong).is_err()); } @@ -694,6 +764,56 @@ mod tests { assert!(!shown(Directions::Both, &[&sent, &reads_as_response])); } + #[test] + fn protocol_is_shown_by_requests_that_hold_it_or_give_none() { + let case = |protocol: Option, call_id: u16, bytes: &[u8], expect| { + let mut input = json!({ + "framing": "f", "call_id": call_id, "method": "m", "request_id": "1", + "format": "json@1", "params": { "unit": null }, + }); + if let Some(protocol) = protocol { + input["protocol"] = json!(protocol); + } + Case { + id: "a/b".into(), + input: Input::parse(Op::Request, &input).unwrap(), + bytes: crate::Hex(bytes.to_vec()), + expect, + compare: crate::Compare::Bytes, + } + }; + let shown = |fact, case: &Case| fact_shown(Fact::Protocol(fact), &[case]).is_ok(); + + // 300 is the varint `ac 02`. + let named = case(Some(300), 1, &[0, 0xac, 0x02, 1], Expect::Exact); + assert!(shown(Protocol::Named, &named)); + assert!(!shown(Protocol::Unnamed, &named)); + // Not in the frame, or not at a byte boundary of it. + let elsewhere = case(Some(300), 1, &[0, 0xac, 1, 2], Expect::Exact); + assert!(!shown(Protocol::Named, &elsewhere)); + let cut_short = case(Some(300), 1, &[0, 0xac], Expect::Exact); + assert!(!shown(Protocol::Named, &cut_short)); + // A byte can hold a number under 128 by chance, and a protocol that + // is the call's number can be mistaken for it. + let by_chance = case(Some(5), 1, &[0, 5, 1], Expect::Exact); + assert!(!shown(Protocol::Named, &by_chance)); + let as_the_call = case(Some(300), 300, &[0, 0xac, 0x02], Expect::Exact); + assert!(!shown(Protocol::Named, &as_the_call)); + // A request that gives none names none; a rejection shows nothing. + let unnamed = case(None, 1, &[0, 1], Expect::Exact); + assert!(shown(Protocol::Unnamed, &unnamed)); + assert!(!shown(Protocol::Named, &unnamed)); + let refused = case(Some(300), 1, &[0, 0xac, 0x02], Expect::Reject); + assert!(!shown(Protocol::Named, &refused)); + let none_refused = case(None, 1, &[0, 1], Expect::Reject); + assert!(!shown(Protocol::Unnamed, &none_refused)); + assert!(fact_shown(Fact::Protocol(Protocol::Named), &[]).is_err()); + assert_eq!(leb128(0), [0]); + assert_eq!(leb128(127), [0x7f]); + assert_eq!(leb128(128), [0x80, 0x01]); + assert_eq!(leb128(u16::MAX), [0xff, 0xff, 0x03]); + } + #[test] fn a_profile_writes_back_as_it_was_read() { let file = json!({ diff --git a/runtime/conformance/src/reference/mod.rs b/runtime/conformance/src/reference/mod.rs index a870788..836bbe6 100644 --- a/runtime/conformance/src/reference/mod.rs +++ b/runtime/conformance/src/reference/mod.rs @@ -342,6 +342,19 @@ pub fn reference_cases() -> Vec { request(p("request"), FRAMING_DATAGRAM3, 3, "greet", 42, ¶ms), 0, ), + // The protocol is 300, two varint bytes, and the call 1, one: no + // function number can be mistaken for the protocol's bytes. + d3( + request( + p("request-two-byte-protocol"), + FRAMING_DATAGRAM3, + 1, + "ping", + 5, + &Value::Array(vec![]), + ), + 300, + ), // 300 is two varint bytes, 65535 three. d3( request( diff --git a/runtime/conformance/src/runner.rs b/runtime/conformance/src/runner.rs index 294ec18..2320f91 100644 --- a/runtime/conformance/src/runner.rs +++ b/runtime/conformance/src/runner.rs @@ -37,10 +37,10 @@ use serde::Deserialize; use serde_json::{json, Value as Json}; use crate::{ - answer, fact_shown, hex, json_equal, to_json, Answer, Case, Compare, EncodeIn, Expect, Hex, + answer, case_framing, fact_shown, hex, json_equal, to_json, Answer, Case, Compare, EncodeIn, Expect, Hex, Input, Op, SizeIn, }; -use crate::{Outcome, Profile, Vectors}; +use crate::{Fact, Outcome, Profile, Vectors}; /// The version of the public spec: the case format (`vectors/*.json`, /// `profiles/*.json`) and the ops protocol, as the vendored specification's @@ -213,6 +213,12 @@ pub fn prove<'a>( None => return Err(format!("case `{id}` wasn't run")), } } + if matches!(fact, Fact::Protocol(_)) { + let elsewhere = |c: &&&Case| case_framing(c) != Some(&profile.name); + if let Some(c) = proving.iter().find(elsewhere) { + return Err(format!("case `{}` isn't for `{}`", c.id, profile.name)); + } + } fact_shown(fact, &proving) })(); FactProof { diff --git a/runtime/conformance/tests/conformance.rs b/runtime/conformance/tests/conformance.rs index 1b585ae..ae55ccb 100644 --- a/runtime/conformance/tests/conformance.rs +++ b/runtime/conformance/tests/conformance.rs @@ -20,7 +20,7 @@ use comline_runtime::contract::{ FRAMING_DATAGRAM3, FRAMING_JSONRPC, HANDSHAKE_COMLINE, HANDSHAKE_COMLINE2, }; use comline_runtime_conformance::{ - fact_shown, reference_cases, render, run, Case, Fact, Facts, Features, Op, Outcome, Output, + case_framing, fact_shown, reference_cases, render, run, Case, Fact, Facts, Features, Op, Outcome, Output, Payload, Profile, ProvenClaim, Report, State, Support, Vectors, }; @@ -275,6 +275,12 @@ fn profiles_are_proven() { if let Err(e) = fact_shown(fact, &proving) { problems.push(format!("`{name}`: `{label}`: {e}")); } + // A framing's `protocol` is shown by cases of that framing. + if matches!(fact, Fact::Protocol(_)) { + for c in proving.iter().filter(|c| case_framing(c) != Some(name)) { + problems.push(format!("`{name}`: `{label}`'s case `{}` isn't for it", c.id)); + } + } } } }