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
2 changes: 1 addition & 1 deletion .github/workflows/check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ jobs:
name: specs
runs-on: ubuntu-latest
env:
# Keep in step with specs/cue.mod/module.cue.
# Keep in step with cue.mod/module.cue.
CUE_VERSION: v0.17.1
steps:
- uses: actions/checkout@v4
Expand Down
25 changes: 17 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,29 @@

What every Comline implementation is held to: the wire contract as byte-exact
conformance vectors, the facts each official encoding states and how they're
proven, and the formats of these files. A runtime, a third-party encoding or a
proven, the formats of these files, and the catalog of names they share. A runtime, a third-party encoding or a
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
(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.

The shared vocabulary of names (encodings, guarantees, facts, features and
the sets they form) will join this repository too: see
[the proposal](https://github.com/ComlineProject/docs/pull/162) and
[core#219](https://github.com/ComlineProject/core/issues/219).
## The catalog

[`catalog/`](catalog/readme.md) defines once every name that more than one
program has to agree on: the guarantees, the facts and the values each may
take, the official encodings with their aliases, and the wire features, with
the sets they form. The profiles' facts and `features.json` come from it, and
[`catalog/gen/catalog.json`](catalog/gen/catalog.json) holds it as JSON for
readers without CUE. See [the proposal](https://github.com/ComlineProject/docs/pull/162)
and [core#219](https://github.com/ComlineProject/core/issues/219) for what
will read it.

## The corpus

- [`features.json`](features.json): the wire features, with stable ids:
- [`features.json`](features.json), generated from the catalog: the wire
features, with stable ids:
`name-hash`, `handshake`, `envelope`, `framing-datagram`, `framing-datagram2`,
`framing-datagram3`, `handshake-comline2`, `framing-jsonrpc`, `stream`, `format-json`, `format-msgpack` and
`format-packed`.
Expand Down Expand Up @@ -310,7 +317,8 @@ define. Rust's are in [`runtime/conformance`](https://github.com/ComlineProject/
about how it encodes, which the version comparison turns into bumps. A format
states `struct_fields`, `unknown_field`, `missing_optional`, `enum_variants`,
`unknown_variant`, `integer_width` and `output`; a framing states `calls`,
`errors` and `payload`.
`directions`, `errors` and `payload`. The catalog gives each fact's values and
what they mean ([`catalog/facts.cue`](catalog/facts.cue)).

`payload` says what a framing needs of a payload, and `output` what a format
writes. A framing takes a format when its `payload` is `opaque` (it carries the
Expand Down Expand Up @@ -353,7 +361,8 @@ profile states it until live cross-runtime calls can prove it (see below).

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. `benches/` carries its own schema, so it vendors whole on
reader ignores it. `catalog/gen/catalog.json` holds the names and their
meanings. `benches/` carries its own schema, so it vendors whole on
its own. Keep the pinned revision in your repository and check in CI that your
copy still matches it. comline-typescript does this in
`runtime/test/conformance/`.
Expand Down
80 changes: 80 additions & 0 deletions catalog/encodings.cue
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
package catalog

encodings: {
"packed@1": {
kind: "format"
title: "packed"
description: "Fixed-width fields back to back, varint lengths, no tags."
feature: "format-packed"
tags: ["official"]
}
"json@1": {
kind: "format"
title: "JSON"
description: "Values as UTF-8 JSON: a struct as an object."
feature: "format-json"
tags: ["official"]
}
"msgpack@1": {
kind: "format"
title: "MessagePack"
description: "Values as MessagePack: a struct as an array."
feature: "format-msgpack"
tags: ["official"]
}
"jsonrpc@1": {
kind: "framing"
title: "JSON-RPC"
description: "JSON-RPC 2.0 requests and responses."
aliases: ["jsonrpc", "json-rpc", "jsonrpc-2.0"]
frozen_as: "jsonrpc"
feature: "framing-jsonrpc"
tags: ["official"]
}
"datagram@1": {
kind: "framing"
title: "datagram"
description: "Comline's own binary framing of requests and responses."
aliases: ["datagram", "comline.datagram"]
frozen_as: "datagram"
feature: "framing-datagram"
tags: ["official"]
}
"datagram@2": {
kind: "framing"
title: "datagram@2"
description: "The datagram framing with a request/reply kind and a protocol number, for calls both ways and several protocols on one connection."
feature: "framing-datagram2"
tags: ["official"]
}
"datagram@3": {
kind: "framing"
title: "datagram@3"
description: "The datagram framing that addresses a call by its protocol's and function's wire numbers."
feature: "framing-datagram3"
since: "0.4"
tags: ["official"]
}
"comline@1": {
kind: "handshake"
title: "comline@1"
description: "The fixed frame each end sends first: magic, version, IR hash, wire format, framing and capabilities."
feature: "handshake"
tags: ["official"]
}
"comline@2": {
kind: "handshake"
title: "comline@2"
description: "The compatibility-checking handshake: lines, shape hashes and wire numbers instead of an exact IR match."
feature: "handshake-comline2"
since: "0.4"
tags: ["official"]
}
none: {
kind: "handshake"
title: "no handshake"
description: "No frame and nothing checked. Unversioned, since there is nothing to evolve; it establishes neither agreement."
profile: false
tags: ["official"]
}
}
131 changes: 131 additions & 0 deletions catalog/facts.cue
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
package catalog

// In the order a profile lists them, which `specs/profile.cue` and its
// generated schema follow.
facts: {
struct_fields: {
applies_to: "format"
title: "struct fields"
description: "How a struct's fields are written."
values: {
by_position: "back to back, in declaration order"
by_name: "each keyed by its name"
}
}
unknown_field: {
applies_to: "format"
title: "unknown field"
description: "What a reader does with a field its type doesn't have."
values: {
rejected: "refuses the value"
ignored: "skips the field"
}
}
missing_optional: {
applies_to: "format"
title: "missing optional"
description: "What a reader does when an optional field isn't there."
values: {
rejected: "refuses the value"
absent: "reads it as absent"
}
}
enum_variants: {
applies_to: "format"
title: "enum variants"
description: "How an enum's variant is written."
values: {
by_name: "by its name"
by_index: "by its position in the declaration"
}
}
unknown_variant: {
applies_to: "format"
title: "unknown variant"
description: "What a reader does with a variant its type doesn't have."
values: {
rejected: "refuses the value"
tolerated: "reads it without failing"
}
}
integer_width: {
applies_to: "format"
title: "integer width"
description: "Whether an integer reads into another width."
values: {
by_value: "any width the value fits"
exact: "only the width it was written as"
}
}
output: {
applies_to: "format"
title: "output"
description: "The grammar a format writes in, which a framing's `payload` must take."
since: "0.7"
values: {
bytes: "bytes in no grammar a framing reads"
json: "JSON text"
}
}
calls: {
applies_to: "framing"
title: "calls"
description: "How a request names the function it calls."
values: {
by_index: "by the function's position"
by_name: "by the function's name"
by_id: "by the protocol's and function's wire numbers"
}
}
directions: {
applies_to: "framing"
title: "directions"
description: "Whether a frame says if it's a request or a response."
since: "0.10"
values: {
both: "it does, so calls can go both ways on one transport"
one: "it doesn't"
}
}
errors: {
applies_to: "framing"
title: "errors"
description: "How an error response names its error."
values: {
by_ordinal: "by its position in the declaration"
by_name: "by its name"
}
}
payload: {
applies_to: "framing"
title: "payload"
description: "What a framing needs of a payload, which a format's `output` must fit."
since: "0.7"
values: {
opaque: "any bytes, carried as they are"
json: "JSON text, written into the frame"
}
}
schema_agreement: {
applies_to: "handshake"
title: "schema agreement"
description: "Whether the handshake checks both ends were built from compatible schemas."
since: "0.2"
establishes: "schema_agreement"
values: {
"true": "it does, and refuses a peer that wasn't"
"false": "it doesn't"
}
}
encoding_agreement: {
applies_to: "handshake"
title: "encoding agreement"
description: "Whether the handshake checks both ends use the same format and framing."
since: "0.2"
establishes: "encoding_agreement"
values: {
"true": "it does, and refuses a peer that doesn't"
"false": "it doesn't"
}
}
}
55 changes: 55 additions & 0 deletions catalog/features.cue
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
package catalog

// In the order `features.json` lists them.
features: {
"name-hash": {
title: "name hash"
description: "FNV-1a 64 of a wire format or framing name, as the handshake carries it"
}
handshake: {
title: "handshake"
description: "the fixed 31-byte frame each side sends first: magic, version, IR hash, wire format, framing, capabilities"
}
envelope: {
title: "envelope"
description: "a response's outcome: ok with a payload, an error ordinal with its body, or a provider fault"
}
"framing-datagram": {
title: "datagram framing"
description: "Comline's own binary framing of requests and responses"
}
"framing-datagram2": {
title: "datagram@2 framing"
description: "the datagram framing with a request/reply kind and a protocol number, for calls in both directions and several protocols on one connection"
}
"framing-datagram3": {
title: "datagram@3 framing"
description: "the datagram framing that addresses a call by its protocol's and function's wire numbers, both varints (calls = by_id); replies as datagram@2"
since: "0.4"
}
"handshake-comline2": {
title: "comline@2 handshake"
description: "the compatibility-checking handshake: its hello, answer and verdict messages, and its negotiation steps under every parameter, with every refusal reason"
since: "0.4"
}
stream: {
title: "stream framing"
description: "frames on a byte stream (TCP, a pipe): each behind a u32 little-endian length prefix, refused over the limit, by default 16 MiB (16777216 bytes) in every runtime"
}
"framing-jsonrpc": {
title: "JSON-RPC framing"
description: "JSON-RPC 2.0 requests and responses, a fault as -32603"
}
"format-json": {
title: "JSON wire format"
description: "values as UTF-8 JSON: a struct as an object"
}
"format-msgpack": {
title: "MessagePack wire format"
description: "values as MessagePack: a struct as an array"
}
"format-packed": {
title: "packed wire format"
description: "values as packed@1: fixed-width fields back to back, varint lengths, no tags"
}
}
Loading
Loading