Merge latest changes from the syndicate-protocols repository

packages/core/protocols/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 = <_>.

packages/core/protocols/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
+# Assertion. Gatekeeper will attempt to resolve `step`, responding with a `Resolved` to
-; `observer`.
+# `observer`.
 Resolve = <resolve @step Step @observer #!Resolved> .
 Resolved = <accepted @responderSession #!any> / Rejected .
 Step = <<rec> @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
+# Assertion. Gatekeeper will compute an appropriate PathStep from `description` pointing at
-; `target`, and will respond with a `Bound` to `observer` (if supplied).
+# `target`, and will respond with a `Bound` to `observer` (if supplied).
 Bind = <bind @description Description @target #!any @observer BindObserver> .
 Description = <<rec> @stepType symbol [@detail any]> .
 BindObserver = @present #!Bound / @absent #f .
 Bound = <bound @pathStep PathStep> / 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`
+# 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
+# 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
+# `route.transports`, asserting `ResolvePath` with the final `Resolved` as well as the selected
-; transport `addr` and a `control` for it.
+# transport `addr` and a `control` for it.
 ResolvePath = <resolve-path @route Route @addr any @control #!TransportControl @resolved Resolved> .
 
 TransportConnection = <connect-transport @addr any @control #!TransportControl @resolved Resolved> .
 ResolvedPathStep = <path-step @origin #!Resolve @pathStep PathStep @resolved Resolved> .
 PathStep = <<rec> @stepType symbol [@detail any]> .
 
-; A `Route` describes a network path that can be followed to reach some target entity.
+# 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
+# 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
+# `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,
+# 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
+# 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.
+# 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
+# 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
+# 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
+# even be the desired target entity. Subsequent `pathSteps` describe how to proceed from the
-; initial entity to the target.
+# initial entity to the target.
-;
+#
-; (`transports` should by rights be a set, not a sequence, but that opens up a Can Of Worms
+# (`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.)
+# regarding dataspace patterns including literal sets that I can't deal with right now.)
 Route = <route @transports [any ...] @pathSteps PathStep ...> .
 
 TransportControl = ForceDisconnect .
 ForceDisconnect = <force-disconnect> .
 
-;---------------------------------------------------------------------------
+# ---------------------------------------------------------------------------
 
 Rejected = <rejected @detail any> .

packages/core/protocols/schemas/http.prs

@@ -1,15 +1,15 @@
 version 1 .
 
-; Assertion in driver DS
+# Assertion in driver DS
-; Causes creation of server and route
+# Causes creation of server and route
 HttpBinding = <http-bind @host HostPattern @port int @method MethodPattern @path PathPattern @handler #!HttpRequest> .
 
-; Assertion in driver DS
+# Assertion in driver DS
-; Describes active server and route
+# Describes active server and route
 HttpService = <http-service @host HostPattern @port int @method MethodPattern @path PathPattern> .
 
-; Assertion in driver DS
+# Assertion in driver DS
-; Describes active listener
+# Describes active listener
 HttpListener = <http-listener @port int> .
 
 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 = <http-request
                @sequenceNumber int
                @host string
@@ -33,11 +33,11 @@ Headers = {@"Lowercase" symbol: string ...:...} .
 QueryValue = @string string / <file @filename string @headers Headers @body bytes> .
 RequestBody = @present bytes / @absent #f .
 
-; Assertion to handler entity
+# Assertion to handler entity
 HttpContext = <request @req HttpRequest @res #!HttpResponse> .
 
 @<TODO "trailers?">
-; Messages
+# Messages
 HttpResponse =
 / <status @code int @message string>
 / <header @name symbol @value string>
@@ -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 .

packages/core/protocols/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
+# 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.
+# 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
+# Sessions proceed by sending Packets to the initiatorSession and responderSession according to
-; the Noise protocol definition. Each Packet represents a complete logical unit of
+# 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.
+# 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
+# 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
+# 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
+# complete Noise "transport message"; when `complete`, the whole thing is likewise a complete
-; "transport message".
+# "transport message".
 Packet = @complete bytes / @fragmented [bytes ...] .
 
-; When layering Syndicate protocol over noise,
+# When layering Syndicate protocol over noise,
-;
+#
-;  - the canonical encoding of the serviceSelector is the prologue
+#  - the canonical encoding of the serviceSelector is the prologue
-;  - protocol.Packets MUST be encoded using the machine-oriented Preserves syntax
+#  - protocol.Packets MUST be encoded using the machine-oriented Preserves syntax
-;  - zero or more Turns are permitted per noise.Packet
+#  - zero or more Turns are permitted per noise.Packet
-;  - each Turn must fit inside a single noise.Packet (fragment if needed)
+#  - 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
+#  - payloads inside a noise.Packet may be padded at the end with byte 0x80 (128), which
-;    encodes `#f` in the machine-oriented Preserves syntax.
+#    encodes `#f` in the machine-oriented Preserves syntax.
-;
+#
-; In summary, each noise.Packet, once (reassembled and) decrypted, will be a sequence of zero
+# 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.
+# or more machine-encoded protocol.Packets, followed by zero or more 0x80 bytes.
 .

packages/core/protocols/schemas/service.prs

@@ -1,51 +1,51 @@
 version 1 .
 embeddedType EntityRef.Cap .
 
-; Asserts that a service should begin (and stay) running after waiting
+# Asserts that a service should begin (and stay) running after waiting
-; for its dependencies and considering reverse-dependencies, blocks,
+# for its dependencies and considering reverse-dependencies, blocks,
-; and so on.
+# and so on.
 RequireService = <require-service @serviceName any>.
 
-; Asserts that a service should begin (and stay) running RIGHT NOW,
+# Asserts that a service should begin (and stay) running RIGHT NOW,
-; without considering its dependencies.
+# without considering its dependencies.
 RunService = <run-service @serviceName any>.
 
-; Asserts one or more current states of service `serviceName`. The
+# Asserts one or more current states of service `serviceName`. The
-; overall state of the service is the union of asserted `state`s.
+# overall state of the service is the union of asserted `state`s.
-;
+#
-; Only a few combinations make sense:
+# Only a few combinations make sense:
-;  - `started`
+#  - `started`
-;  - `started` + `ready`
+#  - `started` + `ready`
-;  - `failed`
+#  - `failed`
-;  - `complete`
+#  - `complete`
-;
+#
 ServiceState = <service-state @serviceName any @state State>.
 
-; A running service publishes zero or more of these. The details of
+# A running service publishes zero or more of these. The details of
-; the object vary by service.
+# the object vary by service.
-;
+#
 ServiceObject = <service-object @serviceName any @object any>.
 
-; Possible service states.
+# Possible service states.
 State =
-/ ; The service has begun its startup routine, and may or may not be
+/ # The service has begun its startup routine, and may or may not be
-  ; ready to take requests from other parties.
+  # ready to take requests from other parties.
   =started
-/ ; The service is ready to take requests from other parties.
+/ # The service is ready to take requests from other parties.
-  ; (This state is special in that it is asserted *in addition* to `started`.)
+  # (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
+# 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
+# `dependee` has been asserted, and also that `dependee`'s `serviceName` should be
-; `require-service`d.
+# `require-service`d.
 ServiceDependency = <depends-on @depender any @dependee ServiceState>.
 
-; Message. Triggers a service restart.
+# Message. Triggers a service restart.
 RestartService = <restart-service @serviceName any>.

packages/core/protocols/schemas/stream.prs

@@ -1,38 +1,38 @@
 version 1 .
 embeddedType EntityRef.Cap .
 
-; Assertion:
+# Assertion:
 StreamConnection = <stream-connection @source #!Source @sink #!Sink @spec any>.
 
-; Assertions:
+# Assertions:
 StreamListenerReady = <stream-listener-ready @spec any>.
 StreamListenerError = <stream-listener-error @spec any @message string>.
 
-; Assertion:
+# Assertion:
 StreamError = <error @message string>.
 
 Source =
-  ; Assertions:
+  # Assertions:
   / <sink @controller #!Sink>
   / StreamError
 
-  ; Messages:
+  # Messages:
   / <credit @amount CreditAmount @mode Mode>
 .
 
 Sink =
-  ; Assertions:
+  # Assertions:
   / <source @controller #!Source>
   / StreamError
 
-  ; Messages:
+  # Messages:
   / <data @payload any @mode Mode>
   / <eof>
 .
 
-; Value:
+# Value:
 CreditAmount = @count int / @unbounded =unbounded .
 
-; Value:
+# Value:
 Mode = =bytes / @lines LineMode / <packet @size int> / <object @description any>.
 LineMode = =lf / =crlf .

packages/core/protocols/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.
+# The sequence of Caveats is run RIGHT-TO-LEFT.
-; That is, the newest Caveats are at the right.
+# That is, the newest Caveats are at the right.
-;
+#
-; Let f(k,d) = HMAC-BLAKE2s-256(k,d)[0..16),
+# Let f(k,d) = HMAC-BLAKE2s-256(k,d)[0..16),
-;     e = canonical machine-oriented serialization of some preserves value, and
+#     e = canonical machine-oriented serialization of some preserves value, and
-;     k = the original secret key for the ref.
+#     k = the original secret key for the ref.
-;
+#
-; The `sig` is then f(f(f(f(k, e(oid)), ...), e(Caveat)), ...).
+# The `sig` is then f(f(f(f(k, e(oid)), ...), e(Caveat)), ...).
-;
+#
 SturdyRef = <ref @parameters Parameters> .
 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
+# embodies 1st-party caveats over assertion structure, but nothing else
-; can add 3rd-party caveats and richer predicates later
+# can add 3rd-party caveats and richer predicates later
 Caveat = Rewrite / Alts / Reject / @unknown any .
 Rewrite = <rewrite @pattern Pattern @template Template> .
 Reject = <reject @pattern Pattern> .
@@ -45,7 +45,7 @@ Alts = <or @alternatives [Rewrite ...]>.
 Oid = int .
 WireRef = @mine [0 @oid Oid] / @yours [1 @oid Oid @attenuation Caveat ...].
 
-;---------------------------------------------------------------------------
+# ---------------------------------------------------------------------------
 
 Lit = <lit @value any>.
 

packages/core/protocols/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 = <turn @id TurnId @cause TurnCause @actions [ActionDescription ...]> .
 
-; The cause of a turn.
+# The cause of a turn.
 TurnCause =
 / @turn <caused-by @id TurnId>
 / <cleanup>
@@ -40,27 +40,27 @@ TurnCause =
 
 LinkedTaskReleaseReason = =cancelled / =normal .
 
-; An actual event carried within a turn.
+# An actual event carried within a turn.
 TurnEvent =
 / <assert @assertion AssertionDescription @handle protocol.Handle>
 / <retract @handle protocol.Handle>
 / <message @body AssertionDescription>
 / <sync @peer Target>
-/ ; A souped-up, disguised, special-purpose `retract` event.
+/ # A souped-up, disguised, special-purpose `retract` event.
   @breakLink <break-link @source ActorId @handle protocol.Handle>
 .
 
 TargetedTurnEvent = <event @target Target @detail TurnEvent> .
 
-; 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.
   <dequeue @event TargetedTurnEvent>
-/ ; 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`.
   <enqueue @event TargetedTurnEvent>
-/ ; 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 <dequeue-internal @event TargetedTurnEvent>
-/ ; 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 <enqueue-internal @event TargetedTurnEvent>
 / <spawn @link bool @id ActorId>
 / <link
@@ -73,9 +73,9 @@ ActionDescription =
 / @linkedTaskStart <linked-task-start @taskName Name @id TaskId>
 .
 
-; An assertion or the body of a message: either a Preserves value, or
+# An assertion or the body of a message: either a Preserves value, or
-; some opaque system-internal value, represented according to the
+# some opaque system-internal value, represented according to the
-; system concerned.
+# system concerned.
 AssertionDescription =
 / <value @value any>
 / <opaque @description any>
@@ -90,7 +90,7 @@ FacetStopReason =
 
 Target = <entity @actor ActorId @facet FacetId @oid Oid> .
 
-; For the future: consider including information about `protocol`-level `Turn`s etc sent to
+# 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
+# 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.
+# processes and implementations with each other to form a large overall picture.
 .