From fe9ceaf65cf1b30e8e2a6ce4350577e2ee91173b Mon Sep 17 00:00:00 2001 From: Tony Garnock-Jones Date: Tue, 31 Oct 2023 21:56:44 +0100 Subject: [PATCH] Update comment syntax for Preserves 0.991 --- schemas/dataspacePatterns.prs | 2 +- schemas/gatekeeper.prs | 60 ++++++++++++++++----------------- schemas/http.prs | 20 +++++------ schemas/noise.prs | 62 +++++++++++++++++------------------ schemas/service.prs | 58 ++++++++++++++++---------------- schemas/stream.prs | 18 +++++----- schemas/sturdy.prs | 36 ++++++++++---------- schemas/trace.prs | 30 ++++++++--------- 8 files changed, 143 insertions(+), 143 deletions(-) diff --git a/schemas/dataspacePatterns.prs b/schemas/dataspacePatterns.prs index 835336e..5c55d11 100644 --- a/schemas/dataspacePatterns.prs +++ b/schemas/dataspacePatterns.prs @@ -1,7 +1,7 @@ version 1 . embeddedType EntityRef.Cap . -; Dataspace patterns: a sublanguage of attenuation patterns. +# Dataspace patterns: a sublanguage of attenuation patterns. Pattern = DDiscard / DBind / DLit / DCompound . DDiscard = <_>. diff --git a/schemas/gatekeeper.prs b/schemas/gatekeeper.prs index 5bc463e..9b11db6 100644 --- a/schemas/gatekeeper.prs +++ b/schemas/gatekeeper.prs @@ -1,58 +1,58 @@ version 1 . embeddedType EntityRef.Cap . -;--------------------------------------------------------------------------- -; Protocol at *gatekeeper* entities +# --------------------------------------------------------------------------- +# Protocol at *gatekeeper* entities -; Assertion. Gatekeeper will attempt to resolve `step`, responding with a `Resolved` to -; `observer`. +# Assertion. Gatekeeper will attempt to resolve `step`, responding with a `Resolved` to +# `observer`. Resolve = . Resolved = / Rejected . Step = < @stepType symbol [@detail any]> . -;--------------------------------------------------------------------------- -; Protocol at dataspaces *associated* with gatekeeper entities +# --------------------------------------------------------------------------- +# Protocol at dataspaces *associated* with gatekeeper entities -; Assertion. Gatekeeper will compute an appropriate PathStep from `description` pointing at -; `target`, and will respond with a `Bound` to `observer` (if supplied). +# Assertion. Gatekeeper will compute an appropriate PathStep from `description` pointing at +# `target`, and will respond with a `Bound` to `observer` (if supplied). Bind = . Description = < @stepType symbol [@detail any]> . BindObserver = @present #!Bound / @absent #f . Bound = / Rejected . -;--------------------------------------------------------------------------- -; Protocol at client-side dataspaces, for resolution utilities +# --------------------------------------------------------------------------- +# Protocol at client-side dataspaces, for resolution utilities -; Assertion. In response to observation of this with appropriate captures/wildcards in `addr` -; and `resolved`, respondent will follow `route.pathSteps` starting from one of the -; `route.transports`, asserting `ResolvePath` with the final `Resolved` as well as the selected -; transport `addr` and a `control` for it. +# Assertion. In response to observation of this with appropriate captures/wildcards in `addr` +# and `resolved`, respondent will follow `route.pathSteps` starting from one of the +# `route.transports`, asserting `ResolvePath` with the final `Resolved` as well as the selected +# transport `addr` and a `control` for it. ResolvePath = . TransportConnection = . ResolvedPathStep = . PathStep = < @stepType symbol [@detail any]> . -; A `Route` describes a network path that can be followed to reach some target entity. -; -; It starts with a set of zero or more possible non-Syndicate `transports`. These could be -; `transportAddress.Tcp` values or similar. They are just suggestions; it's quite possible the -; endpoint is reachable by some means not listed. The network outside Syndicate is, after all, -; pretty diverse! In particular, *zero* `transports` may be provided, in which case some -; out-of-band means has to be used to make that first connection. -; -; The `transports` give instructions for contacting the first entity in the `Route` path. Often -; this will be a `gatekeeper`, or a `noise` protocol endpoint, or both. Occasionally, it may -; even be the desired target entity. Subsequent `pathSteps` describe how to proceed from the -; initial entity to the target. -; -; (`transports` should by rights be a set, not a sequence, but that opens up a Can Of Worms -; regarding dataspace patterns including literal sets that I can't deal with right now.) +# A `Route` describes a network path that can be followed to reach some target entity. +# +# It starts with a set of zero or more possible non-Syndicate `transports`. These could be +# `transportAddress.Tcp` values or similar. They are just suggestions; it's quite possible the +# endpoint is reachable by some means not listed. The network outside Syndicate is, after all, +# pretty diverse! In particular, *zero* `transports` may be provided, in which case some +# out-of-band means has to be used to make that first connection. +# +# The `transports` give instructions for contacting the first entity in the `Route` path. Often +# this will be a `gatekeeper`, or a `noise` protocol endpoint, or both. Occasionally, it may +# even be the desired target entity. Subsequent `pathSteps` describe how to proceed from the +# initial entity to the target. +# +# (`transports` should by rights be a set, not a sequence, but that opens up a Can Of Worms +# regarding dataspace patterns including literal sets that I can't deal with right now.) Route = . TransportControl = ForceDisconnect . ForceDisconnect = . -;--------------------------------------------------------------------------- +# --------------------------------------------------------------------------- Rejected = . diff --git a/schemas/http.prs b/schemas/http.prs index a9069bc..c64a738 100644 --- a/schemas/http.prs +++ b/schemas/http.prs @@ -1,15 +1,15 @@ version 1 . -; Assertion in driver DS -; Causes creation of server and route +# Assertion in driver DS +# Causes creation of server and route HttpBinding = . -; Assertion in driver DS -; Describes active server and route +# Assertion in driver DS +# Describes active server and route HttpService = . -; Assertion in driver DS -; Describes active listener +# Assertion in driver DS +# Describes active listener HttpListener = . HostPattern = @host string / @any #f . @@ -18,7 +18,7 @@ PathPatternElement = @label string / @wildcard =_ / @rest =... . MethodPattern = @any #f / @specific @"Lowercase" symbol . -; Assertion in driver DS +# Assertion in driver DS HttpRequest = . RequestBody = @present bytes / @absent #f . -; Assertion to handler entity +# Assertion to handler entity HttpContext = . @ -; Messages +# Messages HttpResponse = / /
@@ -47,5 +47,5 @@ HttpResponse = Chunk = @string string / @bytes bytes . -; e.g. text/plain, text/html, application/json +# e.g. text/plain, text/html, application/json MimeType = symbol . diff --git a/schemas/noise.prs b/schemas/noise.prs index 33be53f..3558b36 100644 --- a/schemas/noise.prs +++ b/schemas/noise.prs @@ -1,30 +1,30 @@ version 1 . -; https://noiseprotocol.org/ +# https://noiseprotocol.org/ -;--------------------------------------------------------------------------- -; Binding and connection +# --------------------------------------------------------------------------- +# Binding and connection NoiseStepType = =noise . -; In a gatekeeper.Step, use ServiceSelector as detail. +# In a gatekeeper.Step, use ServiceSelector as detail. NoiseStepDetail = ServiceSelector . -; In a gatekeeper.PathStep, use a NoiseSpec as detail. +# In a gatekeeper.PathStep, use a NoiseSpec as detail. NoisePathStepDetail = NoiseSpec . -; In a gatekeeper.Description, use a NoiseServiceSpec as detail. +# In a gatekeeper.Description, use a NoiseServiceSpec as detail. NoiseDescriptionDetail = NoiseServiceSpec . -;--------------------------------------------------------------------------- -; Specification of target and bind addresses +# --------------------------------------------------------------------------- +# Specification of target and bind addresses ServiceSelector = any . NoiseSpec = { - ; The `serviceSelector` to use in a `NoiseStep` for `gatekeeper.Resolve`. + # The `serviceSelector` to use in a `NoiseStep` for `gatekeeper.Resolve`. service: ServiceSelector, - ; The responder's static public key. If not required (uncommon!), supply the empty ByteString. + # The responder's static public key. If not required (uncommon!), supply the empty ByteString. key: bytes, } & @protocol NoiseProtocol @@ -34,32 +34,32 @@ NoiseSpec = { NoiseServiceSpec = @base NoiseSpec & @secretKey SecretKeyField . SecretKeyField = @present { secretKey: bytes } / @invalid { secretKey: any } / @absent {} . -; If absent, a default of DefaultProtocol is used. Most services will speak the default. +# If absent, a default of DefaultProtocol is used. Most services will speak the default. NoiseProtocol = @present { protocol: string } / @invalid { protocol: any } / @absent {} . DefaultProtocol = "Noise_NK_25519_ChaChaPoly_BLAKE2s" . -; If present, Noise pre-shared-keys (PSKs) are drawn from the sequence as required; if the -; sequence is exhausted or not supplied, an all-zeros key is used each time a PSK is needed. +# If present, Noise pre-shared-keys (PSKs) are drawn from the sequence as required; if the +# sequence is exhausted or not supplied, an all-zeros key is used each time a PSK is needed. NoisePreSharedKeys = @present { preSharedKeys: [bytes ...] } / @invalid { preSharedKeys: any } / @absent {} . -; Sessions proceed by sending Packets to the initiatorSession and responderSession according to -; the Noise protocol definition. Each Packet represents a complete logical unit of -; communication; for example, a complete Turn when layering the Syndicate protocol over Noise. -; Note well the restriction on Noise messages: no individual complete packet or packet fragment -; may exceed 65535 bytes (N.B. not 65536!). When `fragmented`, each portion of a Packet is a -; complete Noise "transport message"; when `complete`, the whole thing is likewise a complete -; "transport message". +# Sessions proceed by sending Packets to the initiatorSession and responderSession according to +# the Noise protocol definition. Each Packet represents a complete logical unit of +# communication; for example, a complete Turn when layering the Syndicate protocol over Noise. +# Note well the restriction on Noise messages: no individual complete packet or packet fragment +# may exceed 65535 bytes (N.B. not 65536!). When `fragmented`, each portion of a Packet is a +# complete Noise "transport message"; when `complete`, the whole thing is likewise a complete +# "transport message". Packet = @complete bytes / @fragmented [bytes ...] . -; When layering Syndicate protocol over noise, -; -; - the canonical encoding of the serviceSelector is the prologue -; - protocol.Packets MUST be encoded using the machine-oriented Preserves syntax -; - zero or more Turns are permitted per noise.Packet -; - each Turn must fit inside a single noise.Packet (fragment if needed) -; - payloads inside a noise.Packet may be padded at the end with byte 0x80 (128), which -; encodes `#f` in the machine-oriented Preserves syntax. -; -; In summary, each noise.Packet, once (reassembled and) decrypted, will be a sequence of zero -; or more machine-encoded protocol.Packets, followed by zero or more 0x80 bytes. +# When layering Syndicate protocol over noise, +# +# - the canonical encoding of the serviceSelector is the prologue +# - protocol.Packets MUST be encoded using the machine-oriented Preserves syntax +# - zero or more Turns are permitted per noise.Packet +# - each Turn must fit inside a single noise.Packet (fragment if needed) +# - payloads inside a noise.Packet may be padded at the end with byte 0x80 (128), which +# encodes `#f` in the machine-oriented Preserves syntax. +# +# In summary, each noise.Packet, once (reassembled and) decrypted, will be a sequence of zero +# or more machine-encoded protocol.Packets, followed by zero or more 0x80 bytes. . diff --git a/schemas/service.prs b/schemas/service.prs index 506208d..00fecbb 100644 --- a/schemas/service.prs +++ b/schemas/service.prs @@ -1,51 +1,51 @@ version 1 . embeddedType EntityRef.Cap . -; Asserts that a service should begin (and stay) running after waiting -; for its dependencies and considering reverse-dependencies, blocks, -; and so on. +# Asserts that a service should begin (and stay) running after waiting +# for its dependencies and considering reverse-dependencies, blocks, +# and so on. RequireService = . -; Asserts that a service should begin (and stay) running RIGHT NOW, -; without considering its dependencies. +# Asserts that a service should begin (and stay) running RIGHT NOW, +# without considering its dependencies. RunService = . -; Asserts one or more current states of service `serviceName`. The -; overall state of the service is the union of asserted `state`s. -; -; Only a few combinations make sense: -; - `started` -; - `started` + `ready` -; - `failed` -; - `complete` -; +# Asserts one or more current states of service `serviceName`. The +# overall state of the service is the union of asserted `state`s. +# +# Only a few combinations make sense: +# - `started` +# - `started` + `ready` +# - `failed` +# - `complete` +# ServiceState = . -; A running service publishes zero or more of these. The details of -; the object vary by service. -; +# A running service publishes zero or more of these. The details of +# the object vary by service. +# ServiceObject = . -; Possible service states. +# Possible service states. State = -/ ; The service has begun its startup routine, and may or may not be - ; ready to take requests from other parties. +/ # The service has begun its startup routine, and may or may not be + # ready to take requests from other parties. =started -/ ; The service is ready to take requests from other parties. - ; (This state is special in that it is asserted *in addition* to `started`.) +/ # The service is ready to take requests from other parties. + # (This state is special in that it is asserted *in addition* to `started`.) =ready -/ ; The service has failed. +/ # The service has failed. =failed -/ ; The service has completed execution. +/ # The service has completed execution. =complete -/ ; Extension or user-defined state +/ # Extension or user-defined state @userDefined any . -; Asserts that, when `depender` is `require-service`d, it should not be started until -; `dependee` has been asserted, and also that `dependee`'s `serviceName` should be -; `require-service`d. +# Asserts that, when `depender` is `require-service`d, it should not be started until +# `dependee` has been asserted, and also that `dependee`'s `serviceName` should be +# `require-service`d. ServiceDependency = . -; Message. Triggers a service restart. +# Message. Triggers a service restart. RestartService = . diff --git a/schemas/stream.prs b/schemas/stream.prs index f59101f..079825a 100644 --- a/schemas/stream.prs +++ b/schemas/stream.prs @@ -1,38 +1,38 @@ version 1 . embeddedType EntityRef.Cap . -; Assertion: +# Assertion: StreamConnection = . -; Assertions: +# Assertions: StreamListenerReady = . StreamListenerError = . -; Assertion: +# Assertion: StreamError = . Source = - ; Assertions: + # Assertions: / / StreamError - ; Messages: + # Messages: / . Sink = - ; Assertions: + # Assertions: / / StreamError - ; Messages: + # Messages: / / . -; Value: +# Value: CreditAmount = @count int / @unbounded =unbounded . -; Value: +# Value: Mode = =bytes / @lines LineMode / / . LineMode = =lf / =crlf . diff --git a/schemas/sturdy.prs b/schemas/sturdy.prs index 3be0e23..20e8eb0 100644 --- a/schemas/sturdy.prs +++ b/schemas/sturdy.prs @@ -1,33 +1,33 @@ version 1 . embeddedType EntityRef.Cap . -;--------------------------------------------------------------------------- -; Binding and connection +# --------------------------------------------------------------------------- +# Binding and connection SturdyStepType = =ref . -; In a gatekeeper.Step or gatekeeper.PathStep, use Parameters as detail. +# In a gatekeeper.Step or gatekeeper.PathStep, use Parameters as detail. SturdyStepDetail = Parameters . SturdyPathStepDetail = Parameters . -; In a gatekeeper.Description, use the following detail. +# In a gatekeeper.Description, use the following detail. SturdyDescriptionDetail = { oid: any, key: bytes, } . -;--------------------------------------------------------------------------- -; Macaroons +# --------------------------------------------------------------------------- +# Macaroons -; The sequence of Caveats is run RIGHT-TO-LEFT. -; That is, the newest Caveats are at the right. -; -; Let f(k,d) = HMAC-BLAKE2s-256(k,d)[0..16), -; e = canonical machine-oriented serialization of some preserves value, and -; k = the original secret key for the ref. -; -; The `sig` is then f(f(f(f(k, e(oid)), ...), e(Caveat)), ...). -; +# The sequence of Caveats is run RIGHT-TO-LEFT. +# That is, the newest Caveats are at the right. +# +# Let f(k,d) = HMAC-BLAKE2s-256(k,d)[0..16), +# e = canonical machine-oriented serialization of some preserves value, and +# k = the original secret key for the ref. +# +# The `sig` is then f(f(f(f(k, e(oid)), ...), e(Caveat)), ...). +# SturdyRef = . Parameters = { oid: any, @@ -35,8 +35,8 @@ Parameters = { } & @caveats CaveatsField . CaveatsField = @present { caveats: [Caveat ...] } / @invalid { caveats: any } / @absent {} . -; embodies 1st-party caveats over assertion structure, but nothing else -; can add 3rd-party caveats and richer predicates later +# embodies 1st-party caveats over assertion structure, but nothing else +# can add 3rd-party caveats and richer predicates later Caveat = Rewrite / Alts / Reject / @unknown any . Rewrite = . Reject = . @@ -45,7 +45,7 @@ Alts = . Oid = int . WireRef = @mine [0 @oid Oid] / @yours [1 @oid Oid @attenuation Caveat ...]. -;--------------------------------------------------------------------------- +# --------------------------------------------------------------------------- Lit = . diff --git a/schemas/trace.prs b/schemas/trace.prs index 6259ef3..9f965c6 100644 --- a/schemas/trace.prs +++ b/schemas/trace.prs @@ -25,10 +25,10 @@ TurnId = any . ExitStatus = =ok / protocol.Error . -; Trace information associated with a turn. +# Trace information associated with a turn. TurnDescription = . -; The cause of a turn. +# The cause of a turn. TurnCause = / @turn / @@ -40,27 +40,27 @@ TurnCause = LinkedTaskReleaseReason = =cancelled / =normal . -; An actual event carried within a turn. +# An actual event carried within a turn. TurnEvent = / / / / -/ ; A souped-up, disguised, special-purpose `retract` event. +/ # A souped-up, disguised, special-purpose `retract` event. @breakLink . TargetedTurnEvent = . -; An action taken during a turn. +# An action taken during a turn. ActionDescription = -/ ; The active party is processing a new `event` for `target` from the received Turn. +/ # The active party is processing a new `event` for `target` from the received Turn. -/ ; The active party has queued a new `event` to be processed later by `target`. +/ # The active party has queued a new `event` to be processed later by `target`. -/ ; The active party is processing an internally-queued event for one of its own entities. +/ # The active party is processing an internally-queued event for one of its own entities. @dequeueInternal -/ ; The active party has scheduled an internally-queued event for one of its own entities. +/ # The active party has scheduled an internally-queued event for one of its own entities. @enqueueInternal / / . -; An assertion or the body of a message: either a Preserves value, or -; some opaque system-internal value, represented according to the -; system concerned. +# An assertion or the body of a message: either a Preserves value, or +# some opaque system-internal value, represented according to the +# system concerned. AssertionDescription = / / @@ -90,7 +90,7 @@ FacetStopReason = Target = . -; For the future: consider including information about `protocol`-level `Turn`s etc sent to -; peers over e.g. Websockets or TCP/IP, allowing cross-correlation of traces from different -; processes and implementations with each other to form a large overall picture. +# For the future: consider including information about `protocol`-level `Turn`s etc sent to +# peers over e.g. Websockets or TCP/IP, allowing cross-correlation of traces from different +# processes and implementations with each other to form a large overall picture. .