diff --git a/core/Cargo.toml b/core/Cargo.toml index 4743ce9..a5e38ff 100644 --- a/core/Cargo.toml +++ b/core/Cargo.toml @@ -24,7 +24,7 @@ comline-core-stdlib = { path = "../core_stdlib", version = "0.1.0" } # The specification's catalog of shared names: guarantees, facts and their # values, the official encodings' aliases and frozen spellings. no_std and # dependency-free, so the IR-only build has it too. -comline-catalog = { git = "https://github.com/ComlineProject/specification", rev = "068500670debade6b004b85032924f945dbb0a2c" } +comline-catalog = { git = "https://github.com/ComlineProject/specification", rev = "69882e92971e243b6b74a539a13b534d95b3abf7" } # General eyre = "0.6.8" diff --git a/core/src/encodings/official.rs b/core/src/encodings/official.rs index 361855c..c90c5fe 100644 --- a/core/src/encodings/official.rs +++ b/core/src/encodings/official.rs @@ -181,6 +181,33 @@ mod tests { assert!(profile(EncodingKind::Format, "com.acme.x@1").is_none()); } + /// What each official framing states about its frames: `protocol` (named + /// by `datagram@2` and `datagram@3`, not by `datagram@1` or `jsonrpc@1`) + /// and `directions` (both ways but for `datagram@1`), and nothing for a + /// format or a handshake. + #[test] + fn the_official_framings_state_their_protocol_and_directions() { + let read = |written| { + let profile = profile(EncodingKind::Framing, written).unwrap(); + (profile.names_protocol(), profile.both_directions()) + }; + assert_eq!(read("datagram@1"), (Some(false), Some(false))); + assert_eq!(read("datagram@2"), (Some(true), Some(true))); + assert_eq!(read("datagram@3"), (Some(true), Some(true))); + assert_eq!(read("jsonrpc@1"), (Some(false), Some(true))); + // Any spelling of a framing reads the same. + assert_eq!(read("jsonrpc"), read("jsonrpc@1")); + assert_eq!(read("datagram"), read("datagram@1")); + for (kind, written) in [ + (EncodingKind::Format, "json@1"), + (EncodingKind::Format, "packed@1"), + (EncodingKind::Handshake, "comline@2"), + ] { + let profile = profile(kind, written).unwrap(); + assert_eq!((profile.names_protocol(), profile.both_directions()), (None, None), "{written}"); + } + } + #[test] fn the_snapshot_is_what_freezes() { let frozen = units(); diff --git a/core/src/encodings/official_units.json b/core/src/encodings/official_units.json index e8ebbc7..8e1261b 100644 --- a/core/src/encodings/official_units.json +++ b/core/src/encodings/official_units.json @@ -62,7 +62,7 @@ "Encoding": { "name": "jsonrpc@1", "kind": "framing", - "profile_hash": "29f9fcc7de82c7681d105e60f1ac232fa0e543cffb971190d9623b71199bcf6d", + "profile_hash": "eca9ae8d90aa1c06d06f93a7316585ffbe27e5eea49a78259e5df3967f9165d3", "map": { "rust": { "type": "comline_runtime::framing::JsonRpcFraming", @@ -86,7 +86,7 @@ "Encoding": { "name": "datagram@1", "kind": "framing", - "profile_hash": "5ea6f68be2ea6f4f300bcc67d1867f9c5d32b773d831c7694281351c1b3d8d4d", + "profile_hash": "2beb36e0158315f22118a3398ae7db8ade7f34c4119b2fe7fba54f89480655ab", "map": { "rust": { "type": "comline_runtime::contract::DatagramFraming", @@ -109,7 +109,7 @@ "Encoding": { "name": "datagram@2", "kind": "framing", - "profile_hash": "539252f1ec32967c99a9d27dc0ae9051c598a24f468aad0a0445908dc4b571fd", + "profile_hash": "f40fbb0dc5be22ca8e3eb906b82fcfaaf0c298d5f50446e68008d5627a5dbf3c", "map": { "rust": { "type": "comline_runtime::contract::Datagram2Framing", @@ -132,7 +132,7 @@ "Encoding": { "name": "datagram@3", "kind": "framing", - "profile_hash": "6414ef0d6aa33c9a9b3169f2debbaf6354e001a65ca7e8bf66b9cdc168c66278", + "profile_hash": "f4c1170187d59e40d8d68176a05103a47b7bc89f3f1b830548b7f057d1024256", "map": { "rust": { "type": "comline_runtime::contract::Datagram3Framing", diff --git a/core/src/encodings/profile.rs b/core/src/encodings/profile.rs index ac3dbd1..a92876d 100644 --- a/core/src/encodings/profile.rs +++ b/core/src/encodings/profile.rs @@ -7,7 +7,10 @@ //! profile format ComlineProject/specification defines (`specs/profile.cue`). //! The specification's vectors are where the profiles are proven; core only //! checks that a declared profile is one. When the profile format moves, this -//! copy moves with it, and the rev above changes. +//! copy moves with it, and the rev above changes. The fact list isn't part of +//! that copy: it's the catalog's (`comline-catalog`), so a fact the +//! specification adds, like 0.11's framing fact `protocol`, is known here once +//! the catalog is pinned at it. //! //! A handshake's facts, `schema_agreement` and `encoding_agreement`, are //! what it establishes; one it doesn't state as `true` is given up @@ -158,6 +161,34 @@ impl Profile { self.facts.get(fact).map(|f| f.value.clone()).filter(|value| value != none) } + /// Whether a framing's request frame names the protocol it calls into + /// (`protocol`): `Some(true)` for `named`, `Some(false)` for `unnamed`, + /// and `None` for a profile that isn't a framing's, or states some other + /// value. A connection may carry several protocols only where it does. + pub fn names_protocol(&self) -> Option { + self.framing_fact_is(fact::PROTOCOL, "named", "unnamed") + } + + /// Whether a framing carries calls both ways on one transport + /// (`directions`): `Some(true)` for `both`, `Some(false)` for `one`, and + /// `None` for a profile that isn't a framing's, or states some other value. + pub fn both_directions(&self) -> Option { + self.framing_fact_is(fact::DIRECTIONS, "both", "one") + } + + /// A framing's two-valued `fact`: `Some(true)` when it states `yes`, + /// `Some(false)` when it states `no`, else `None`. + fn framing_fact_is(&self, fact: &str, yes: &str, no: &str) -> Option { + if self.kind != ProfileKind::Framing { + return None; + } + match self.facts.get(fact)?.value.as_str() { + value if value == yes => Some(true), + value if value == no => Some(false), + _ => None, + } + } + /// What a framing states as `fact`; `None` for one this kind doesn't state. pub fn stated(&self, fact: &str) -> Option { self.facts.get(fact).map(|f| f.value.clone()) @@ -203,6 +234,9 @@ mod tests { (fact::CALLS, "by_name"), (fact::CALLS, "by_id"), (fact::DIRECTIONS, "one"), + (fact::DIRECTIONS, "both"), + (fact::PROTOCOL, "named"), + (fact::PROTOCOL, "unnamed"), (fact::ERRORS, "by_name"), (fact::PAYLOAD, "opaque"), (fact::PAYLOAD, "json"), @@ -219,16 +253,25 @@ mod tests { fn a_profile_is_held_to_the_catalogs_facts() { let profile = |facts: &str| format!(r#"{{ "name": "x@1", "kind": "framing", "facts": {{ {facts} }} }}"#); let fact = |name: &str, value: &str| format!(r#""{name}": {{ "value": "{value}", "proven_by": ["x/a"] }}"#); - let all = [fact("calls", "by_name"), fact("directions", "both"), fact("errors", "by_name"), fact("payload", "opaque")]; + let all = [ + fact("calls", "by_name"), + fact("directions", "both"), + fact("errors", "by_name"), + fact("payload", "opaque"), + fact("protocol", "named"), + ]; assert!(Profile::parse(profile(&all.join(", ")).as_bytes()).is_ok()); - let wrong = [fact("calls", "by_guess"), all[1].clone(), all[2].clone(), all[3].clone()]; + let wrong = [fact("calls", "by_guess"), all[1].clone(), all[2].clone(), all[3].clone(), all[4].clone()]; let error = Profile::parse(profile(&wrong.join(", ")).as_bytes()).unwrap_err(); assert_eq!(error, "its `calls` is `by_guess`: expected one of `by_index`, `by_name`, `by_id`"); let error = Profile::parse(profile(&all[1..].join(", ")).as_bytes()).unwrap_err(); assert_eq!(error, "it doesn't state `calls`"); + let error = Profile::parse(profile(&all[..4].join(", ")).as_bytes()).unwrap_err(); + assert_eq!(error, "it doesn't state `protocol`"); + let extra = [all.join(", "), fact("struct_fields", "by_name")]; let error = Profile::parse(profile(&extra.join(", ")).as_bytes()).unwrap_err(); assert_eq!(error, "it states `struct_fields`, which isn't a fact of a framing profile"); diff --git a/core/src/inspect.rs b/core/src/inspect.rs index cbada25..3356178 100644 --- a/core/src/inspect.rs +++ b/core/src/inspect.rs @@ -535,7 +535,8 @@ mod tests { format!( r#"{{ "name": "com.acme.f@1", "kind": "framing", "facts": {{ "calls": {{ "value": "by_name" }}, "directions": {{ "value": "both" }}, - "errors": {{ "value": "by_name" }}, "payload": {{ "value": "{payload}" }} }} }}"# + "errors": {{ "value": "by_name" }}, "payload": {{ "value": "{payload}" }}, + "protocol": {{ "value": "named" }} }} }}"# ), ) .unwrap(); @@ -560,7 +561,7 @@ mod tests { app.join("profiles/f.json"), r#"{ "name": "com.acme.f@1", "kind": "framing", "facts": { "calls": { "value": "by_name" }, "directions": { "value": "both" }, "errors": { "value": "by_name" }, - "payload": { "value": "opaque" } } }"#, + "payload": { "value": "opaque" }, "protocol": { "value": "named" } } }"#, ) .unwrap(); package( diff --git a/core/src/package/deps.rs b/core/src/package/deps.rs index 7215209..acfdf4d 100644 --- a/core/src/package/deps.rs +++ b/core/src/package/deps.rs @@ -1463,7 +1463,8 @@ mod tests { "calls": { "value": "by_name", "proven_by": [] }, "directions": { "value": "both", "proven_by": [] }, "errors": { "value": "by_name", "proven_by": [] }, - "payload": { "value": "opaque", "proven_by": [] } + "payload": { "value": "opaque", "proven_by": [] }, + "protocol": { "value": "named", "proven_by": [] } } }"#; let hashes = |wire: &str, unverified: &str, vectors: bool| { let tmp = tempfile::tempdir().unwrap(); diff --git a/core/tests/cas/dependency_configs_tests.rs b/core/tests/cas/dependency_configs_tests.rs index b91522d..ff16fa9 100644 --- a/core/tests/cas/dependency_configs_tests.rs +++ b/core/tests/cas/dependency_configs_tests.rs @@ -31,7 +31,8 @@ fn lines_profile(errors: &str) -> String { "calls": {{ "value": "by_name", "proven_by": ["lines/request"] }}, "directions": {{ "value": "both", "proven_by": ["lines/request"] }}, "errors": {{ "value": "{errors}", "proven_by": ["lines/error"] }}, - "payload": {{ "value": "json", "proven_by": ["lines/request"] }} + "payload": {{ "value": "json", "proven_by": ["lines/request"] }}, + "protocol": {{ "value": "named", "proven_by": ["lines/request"] }} }} }}"# ) diff --git a/core/tests/package/dependency_pin.rs b/core/tests/package/dependency_pin.rs index 4707941..f383074 100644 --- a/core/tests/package/dependency_pin.rs +++ b/core/tests/package/dependency_pin.rs @@ -15,7 +15,8 @@ const FRAMING: &str = r#"{ "calls": { "value": "by_name", "proven_by": ["lines/request"] }, "directions": { "value": "both", "proven_by": ["lines/request"] }, "errors": { "value": "by_name", "proven_by": ["lines/error"] }, - "payload": { "value": "opaque", "proven_by": ["lines/request-binary"] } + "payload": { "value": "opaque", "proven_by": ["lines/request-binary"] }, + "protocol": { "value": "named", "proven_by": ["lines/request"] } } }"#; @@ -113,10 +114,12 @@ fn resolve_pinned(root: &Path, path: &str, pin: &str) -> Result<(), String> { const OLD_PIN: &str = "blake3:728e1b2153908105259b94a8d35e91ddf4e589253c8f8c44a1d609545e61f33b"; /// What [`Config::base`] with both profiles and its vectors hashes to now. -/// If this moves, the hash scheme changed: every pin made before is wrong, -/// so it's a new `CONTENT_HASH_SCHEME` and a breaking change, not a fix to -/// this line. -const GOLDEN_PIN: &str = "blake3:634d212c23a663caf347a38646d0a8926611202b21b191bf058dee3b6fce7022"; +/// If this moves while that input stays the same, the hash scheme changed: +/// every pin made before is wrong, so it's a new `CONTENT_HASH_SCHEME` and a +/// breaking change, not a fix to this line. It moves legitimately only when +/// the input does: spec 0.11 made `FRAMING` state `protocol`, which changes +/// its frozen `Encoding` unit (was `blake3:634d212c…`). +const GOLDEN_PIN: &str = "blake3:85584227b207edb2e099f073aef9ce7c76315d3319e6e99769e69c007f4fb4af"; /// Pin the base dependency, change it with `change`, and it no longer /// verifies, and as a plain mismatch rather than an old pin. diff --git a/core/tests/package/encodings.rs b/core/tests/package/encodings.rs index b3c8582..a2d679f 100644 --- a/core/tests/package/encodings.rs +++ b/core/tests/package/encodings.rs @@ -15,7 +15,8 @@ const FRAMING_PROFILE: &str = r#"{ "calls": { "value": "by_name", "proven_by": ["lines/request"] }, "directions": { "value": "both", "proven_by": ["lines/request"] }, "errors": { "value": "by_name", "proven_by": ["lines/error"] }, - "payload": { "value": "opaque", "proven_by": ["lines/request-binary"] } + "payload": { "value": "opaque", "proven_by": ["lines/request-binary"] }, + "protocol": { "value": "named", "proven_by": ["lines/request"] } } }"#; @@ -466,7 +467,8 @@ mod format_fits_framing { "calls": {{ "value": "by_name", "proven_by": [] }}, "directions": {{ "value": "both", "proven_by": [] }}, "errors": {{ "value": "by_ordinal", "proven_by": [] }}, - "payload": {{ "value": "{payload}", "proven_by": [] }} + "payload": {{ "value": "{payload}", "proven_by": [] }}, + "protocol": {{ "value": "named", "proven_by": [] }} }} }}"# ) } @@ -583,7 +585,8 @@ mod framing_facts { "calls": {{ "value": "{calls}", "proven_by": [] }}, "directions": {{ "value": "{directions}", "proven_by": [] }}, "errors": {{ "value": "by_ordinal", "proven_by": [] }}, - "payload": {{ "value": "opaque", "proven_by": [] }} + "payload": {{ "value": "opaque", "proven_by": [] }}, + "protocol": {{ "value": "named", "proven_by": [] }} }} }}"# ) } diff --git a/core/tests/spec/REV b/core/tests/spec/REV index d7dee73..6857159 100644 --- a/core/tests/spec/REV +++ b/core/tests/spec/REV @@ -1 +1 @@ -068500670debade6b004b85032924f945dbb0a2c +69882e92971e243b6b74a539a13b534d95b3abf7 diff --git a/core_stdlib/packages/comline/profiles/datagram@1.json b/core_stdlib/packages/comline/profiles/datagram@1.json index 0220627..d7a67d0 100644 --- a/core_stdlib/packages/comline/profiles/datagram@1.json +++ b/core_stdlib/packages/comline/profiles/datagram@1.json @@ -28,6 +28,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/core_stdlib/packages/comline/profiles/datagram@2.json b/core_stdlib/packages/comline/profiles/datagram@2.json index 942ca6e..0ac6f15 100644 --- a/core_stdlib/packages/comline/profiles/datagram@2.json +++ b/core_stdlib/packages/comline/profiles/datagram@2.json @@ -30,6 +30,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/core_stdlib/packages/comline/profiles/datagram@3.json b/core_stdlib/packages/comline/profiles/datagram@3.json index 855a348..547eb20 100644 --- a/core_stdlib/packages/comline/profiles/datagram@3.json +++ b/core_stdlib/packages/comline/profiles/datagram@3.json @@ -31,6 +31,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/core_stdlib/packages/comline/profiles/jsonrpc@1.json b/core_stdlib/packages/comline/profiles/jsonrpc@1.json index 5e0d877..f936407 100644 --- a/core_stdlib/packages/comline/profiles/jsonrpc@1.json +++ b/core_stdlib/packages/comline/profiles/jsonrpc@1.json @@ -31,6 +31,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" + ] } } }