Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 36 additions & 5 deletions catalog/gen/catalog.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,31 +4,54 @@
"status": "stable",
"title": "schema agreement",
"description": "Both ends were built from compatible schemas, which the handshake checks.",
"comes_from": "handshake"
"comes_from": "handshake",
"scopes": [
"package",
"protocol"
]
},
"encoding_agreement": {
"status": "stable",
"title": "encoding agreement",
"description": "Both ends use the same format and framing, which the handshake checks.",
"comes_from": "handshake"
"comes_from": "handshake",
"scopes": [
"package",
"protocol"
]
},
"encoding_conformance": {
"status": "stable",
"title": "encoding conformance",
"description": "An implementation encodes what its name promises, proven by conformance vectors.",
"comes_from": "encoding"
"comes_from": "encoding",
"scopes": [
"package",
"protocol"
]
},
"version_honesty": {
"status": "stable",
"title": "version honesty",
"description": "A version bump says what the change breaks, as the version comparison works it out.",
"comes_from": "policy"
"comes_from": "policy",
"scopes": [
"package",
"protocol"
]
},
"bounded_size": {
"status": "stable",
"title": "bounded size",
"description": "Every value has a maximum size, so a decoder refuses an oversized one before allocating it.",
"comes_from": "type"
"comes_from": "type",
"scopes": [
"protocol",
"function",
"argument",
"field",
"type"
]
}
},
"facts": {
Expand Down Expand Up @@ -375,6 +398,14 @@
"version_honesty",
"bounded_size"
],
"scopes": [
"package",
"protocol",
"function",
"argument",
"field",
"type"
],
"formats": [
"packed@1",
"json@1",
Expand Down
5 changes: 5 additions & 0 deletions catalog/guarantees.cue
Original file line number Diff line number Diff line change
Expand Up @@ -5,25 +5,30 @@ guarantees: {
title: "schema agreement"
description: "Both ends were built from compatible schemas, which the handshake checks."
comes_from: "handshake"
scopes: ["package", "protocol"]
}
encoding_agreement: {
title: "encoding agreement"
description: "Both ends use the same format and framing, which the handshake checks."
comes_from: "handshake"
scopes: ["package", "protocol"]
}
encoding_conformance: {
title: "encoding conformance"
description: "An implementation encodes what its name promises, proven by conformance vectors."
comes_from: "encoding"
scopes: ["package", "protocol"]
}
version_honesty: {
title: "version honesty"
description: "A version bump says what the change breaks, as the version comparison works it out."
comes_from: "policy"
scopes: ["package", "protocol"]
}
bounded_size: {
title: "bounded size"
description: "Every value has a maximum size, so a decoder refuses an oversized one before allocating it."
comes_from: "type"
scopes: ["protocol", "function", "argument", "field", "type"]
}
}
9 changes: 9 additions & 0 deletions catalog/readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,15 @@ What an entry may say, and the rules across entries, are in
(`frozen_as`: `jsonrpc`, `datagram`), that spelling is an alias too.
- A reference (`establishes`, `feature`) names an entry that exists.
- A handshake's facts are booleans.
- A guarantee's `scopes` say where an `@unverified` marker acknowledging it
may sit: any of `package`, `protocol`, `function`, `argument`, `field` and
`type`, outermost to innermost, each at most once. They follow from where
its cause is: what the handshake, a policy or the encoding gives up
(`schema_agreement`, `version_honesty`, `encoding_conformance`, ...) is
settled for a package or a protocol, so those are its scopes; what a type
gives up (`bounded_size`) can also be acknowledged on a function, an
argument, a field or the type itself, and must include `type`. The schema
checks both, and `sets.scopes` lists the vocabulary.
- `since` is the spec version that introduced an entry, where the changelog
names one.

Expand Down
12 changes: 11 additions & 1 deletion catalog/rust.cue
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,14 @@ _rust: {
#in: "format" | "framing" | "handshake"
out: {format: "Kind::Format", framing: "Kind::Framing", handshake: "Kind::Handshake"}[#in]
}
scope: {
#in: #Scope
out: {package: "Scope::Package", protocol: "Scope::Protocol", function: "Scope::Function", argument: "Scope::Argument", field: "Scope::Field", type: "Scope::Type"}[#in]
}
scopes: {
#in: [...#Scope]
out: "&[" + strings.Join([for s in #in {(scope & {#in: s}).out}], ", ") + "]"
}
status: {
#in: "stable" | "experimental" | "deprecated"
out: {stable: "Status::Stable", experimental: "Status::Experimental", deprecated: "Status::Deprecated"}[#in]
Expand Down Expand Up @@ -80,7 +88,7 @@ _set: {
rust_catalog: """
// Generated from the catalog's CUE by `specs/check.sh`: don't edit by hand.

use crate::{Encoding, Fact, Feature, Guarantee, Kind, Origin, Status, Value};
use crate::{Encoding, Fact, Feature, Guarantee, Kind, Origin, Scope, Status, Value};

pub const SPEC_VERSION: &str = \((_rust.str & {#in: _spec_version}).out);

Expand All @@ -92,6 +100,7 @@ rust_catalog: """
title: \((_rust.str & {#in: g.title}).out),
description: \((_rust.str & {#in: g.description}).out),
comes_from: \({handshake: "Origin::Handshake", encoding: "Origin::Encoding", policy: "Origin::Policy", type: "Origin::Type"}[g.comes_from]),
scopes: \((_rust.scopes & {#in: g.scopes}).out),
\((_rust.lifecycle & {#in: g}).out)
},
"""}], "\n"))
Expand Down Expand Up @@ -165,6 +174,7 @@ rust_catalog: """
/// The catalog's sets.
pub mod sets {
\((_set & {#name: "GUARANTEES", #in: sets.guarantees}).out)
\((_set & {#name: "SCOPES", #in: sets.scopes}).out)
\((_set & {#name: "FORMATS", #in: sets.formats}).out)
\((_set & {#name: "FRAMINGS", #in: sets.framings}).out)
\((_set & {#name: "HANDSHAKES", #in: sets.handshakes}).out)
Expand Down
21 changes: 21 additions & 0 deletions catalog/schema.cue
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,12 @@ import "list"
}
}

// Where an `@unverified` marker may sit, outermost to innermost: the
// package, a protocol in it, a function of the protocol, one of its
// arguments, a field of a type, a type.
#Scopes: ["package", "protocol", "function", "argument", "field", "type"]
#Scope: or(#Scopes)

// A guarantee Comline gives between peers, which a protocol can give up
// with `@unverified`. Its id is the name written in `accept_unverified`,
// diagnostics and generated docs.
Expand All @@ -23,6 +29,9 @@ import "list"
// What gives it up: the handshake, the format and framing, a handshake
// policy, or a type.
comes_from!: "handshake" | "encoding" | "policy" | "type"
// Where an `@unverified` marker acknowledging it may sit, which follows
// from where its cause is. In `#Scopes` order, each at most once.
scopes!: [#Scope, ...#Scope]
})

// A fact an encoding's profile states, with every value it may take and
Expand Down Expand Up @@ -74,6 +83,18 @@ facts: {[=~#SnakeId]: #Fact, [!~#SnakeId]: _|_}
encodings: {[=~#EncodingId]: #Encoding, [!~#EncodingId]: _|_}
features: {[=~#FeatureId]: #Feature, [!~#FeatureId]: _|_}

// A guarantee's scopes follow from where it comes from: what a type gives
// up can be acknowledged on the type, or on whatever uses it, down from the
// protocol; what the handshake, the policies and the encoding give up is
// settled by the package and its protocols, never below a protocol.
_scope_rank: {for i, s in #Scopes {(s): i}}
_scopes_are_ordered: [for id, g in guarantees
let ranks = [for s in g.scopes {_scope_rank[s]}]
if len([for i, r in ranks if i > 0 if r <= ranks[i-1] {i}]) > 0 {id}] & []
_scopes_follow_origin: [for id, g in guarantees
let inner = [for s in g.scopes if _scope_rank[s] >= _scope_rank["function"] {s}]
if (g.comes_from == "type" && !list.Contains(g.scopes, "type")) || (g.comes_from != "type" && len(inner) > 0) {id}] & []

// A handshake's facts are booleans.
_boolean_handshake_facts: [for id, f in facts if f.applies_to == "handshake" if [for v, _ in f.values {v}] != ["true", "false"] {id}] & []

Expand Down
2 changes: 2 additions & 0 deletions catalog/sets.cue
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ package catalog
// label that names a top-level field is quoted, so it doesn't shadow it.
sets: {
"guarantees": [for id, _ in guarantees {id}]
// Where an `@unverified` marker may sit, outermost to innermost.
scopes: #Scopes
formats: [for id, e in encodings if e.kind == "format" {id}]
framings: [for id, e in encodings if e.kind == "framing" {id}]
handshakes: [for id, e in encodings if e.kind == "handshake" {id}]
Expand Down
8 changes: 7 additions & 1 deletion rust/src/catalog.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// Generated from the catalog's CUE by `specs/check.sh`: don't edit by hand.

use crate::{Encoding, Fact, Feature, Guarantee, Kind, Origin, Status, Value};
use crate::{Encoding, Fact, Feature, Guarantee, Kind, Origin, Scope, Status, Value};

pub const SPEC_VERSION: &str = r#"0.10"#;

Expand All @@ -11,6 +11,7 @@ pub const GUARANTEES: &[Guarantee] = &[
title: r#"schema agreement"#,
description: r#"Both ends were built from compatible schemas, which the handshake checks."#,
comes_from: Origin::Handshake,
scopes: &[Scope::Package, Scope::Protocol],
status: Status::Stable,
replaced_by: None,
since: None,
Expand All @@ -20,6 +21,7 @@ pub const GUARANTEES: &[Guarantee] = &[
title: r#"encoding agreement"#,
description: r#"Both ends use the same format and framing, which the handshake checks."#,
comes_from: Origin::Handshake,
scopes: &[Scope::Package, Scope::Protocol],
status: Status::Stable,
replaced_by: None,
since: None,
Expand All @@ -29,6 +31,7 @@ pub const GUARANTEES: &[Guarantee] = &[
title: r#"encoding conformance"#,
description: r#"An implementation encodes what its name promises, proven by conformance vectors."#,
comes_from: Origin::Encoding,
scopes: &[Scope::Package, Scope::Protocol],
status: Status::Stable,
replaced_by: None,
since: None,
Expand All @@ -38,6 +41,7 @@ pub const GUARANTEES: &[Guarantee] = &[
title: r#"version honesty"#,
description: r#"A version bump says what the change breaks, as the version comparison works it out."#,
comes_from: Origin::Policy,
scopes: &[Scope::Package, Scope::Protocol],
status: Status::Stable,
replaced_by: None,
since: None,
Expand All @@ -47,6 +51,7 @@ pub const GUARANTEES: &[Guarantee] = &[
title: r#"bounded size"#,
description: r#"Every value has a maximum size, so a decoder refuses an oversized one before allocating it."#,
comes_from: Origin::Type,
scopes: &[Scope::Protocol, Scope::Function, Scope::Argument, Scope::Field, Scope::Type],
status: Status::Stable,
replaced_by: None,
since: None,
Expand Down Expand Up @@ -503,6 +508,7 @@ pub mod feature {
/// The catalog's sets.
pub mod sets {
pub const GUARANTEES: &[&str] = &[r#"schema_agreement"#, r#"encoding_agreement"#, r#"encoding_conformance"#, r#"version_honesty"#, r#"bounded_size"#];
pub const SCOPES: &[&str] = &[r#"package"#, r#"protocol"#, r#"function"#, r#"argument"#, r#"field"#, r#"type"#];
pub const FORMATS: &[&str] = &[r#"packed@1"#, r#"json@1"#, r#"msgpack@1"#];
pub const FRAMINGS: &[&str] = &[r#"jsonrpc@1"#, r#"datagram@1"#, r#"datagram@2"#, r#"datagram@3"#];
pub const HANDSHAKES: &[&str] = &[r#"comline@1"#, r#"comline@2"#, r#"none"#];
Expand Down
76 changes: 76 additions & 0 deletions rust/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,38 @@ pub enum Origin {
Type,
}

/// Where an `@unverified` marker may sit, outermost to innermost.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Scope {
/// The whole package.
Package,
/// A protocol in it.
Protocol,
/// A function of a protocol.
Function,
/// An argument of a function.
Argument,
/// A field of a type.
Field,
/// A type.
Type,
}

impl Scope {
/// As the catalog writes it: `package`, `protocol`, `function`,
/// `argument`, `field`, `type`.
pub const fn as_str(self) -> &'static str {
match self {
Scope::Package => "package",
Scope::Protocol => "protocol",
Scope::Function => "function",
Scope::Argument => "argument",
Scope::Field => "field",
Scope::Type => "type",
}
}
}

/// Where an entry stands.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Status {
Expand All @@ -69,12 +101,23 @@ pub struct Guarantee {
pub title: &'static str,
pub description: &'static str,
pub comes_from: Origin,
/// Where an `@unverified` marker acknowledging it may sit, outermost to
/// innermost.
pub scopes: &'static [Scope],
pub status: Status,
pub replaced_by: Option<&'static str>,
/// The spec version that introduced it, where the changelog names one.
pub since: Option<&'static str>,
}

impl Guarantee {
/// Whether an `@unverified` marker acknowledging this guarantee may sit
/// at `scope`.
pub fn allows_scope(&self, scope: Scope) -> bool {
self.scopes.contains(&scope)
}
}

/// One value a fact may take, and what it means.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Value {
Expand Down Expand Up @@ -226,6 +269,39 @@ mod tests {
}
}

#[test]
fn every_guarantee_has_scopes_in_order() {
let rank = |s: &Scope| sets::SCOPES.iter().position(|id| *id == s.as_str()).unwrap();
for g in GUARANTEES {
assert!(!g.scopes.is_empty(), "{}", g.id);
assert!(g.scopes.windows(2).all(|w| rank(&w[0]) < rank(&w[1])), "{}", g.id);
assert_eq!(g.comes_from == Origin::Type, g.allows_scope(Scope::Type), "{}", g.id);
}
}

#[test]
fn a_type_guarantee_reaches_below_the_protocol() {
let bounded = guarantee(guarantee::BOUNDED_SIZE).unwrap();
assert!(bounded.allows_scope(Scope::Field));
assert!(!bounded.allows_scope(Scope::Package));
let agreement = guarantee(guarantee::SCHEMA_AGREEMENT).unwrap();
assert!(agreement.allows_scope(Scope::Package) && agreement.allows_scope(Scope::Protocol));
assert!(!agreement.allows_scope(Scope::Field));
}

#[test]
fn scopes_match_their_set() {
let all = [
Scope::Package,
Scope::Protocol,
Scope::Function,
Scope::Argument,
Scope::Field,
Scope::Type,
];
assert!(all.iter().map(|s| s.as_str()).eq(sets::SCOPES.iter().copied()));
}

#[test]
fn the_spec_version_is_a_version() {
let (major, minor) = SPEC_VERSION.split_once('.').unwrap();
Expand Down
Loading