Merge latest changes from the syndicate-protocols repository

This commit is contained in:
Tony Garnock-Jones 2023-10-31 21:57:25 +01:00
commit e026f42452
8 changed files with 143 additions and 143 deletions

View File

@ -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 = <_>.

View File

@ -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 = <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
; `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 = <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`
; 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 = <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.
;
; 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 = <route @transports [any ...] @pathSteps PathStep ...> .
TransportControl = ForceDisconnect .
ForceDisconnect = <force-disconnect> .
;---------------------------------------------------------------------------
# ---------------------------------------------------------------------------
Rejected = <rejected @detail any> .

View File

@ -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 = <http-bind @host HostPattern @port int @method MethodPattern @path PathPattern @handler #!HttpRequest> .
; Assertion in driver DS
; Describes active server and route
# Assertion in driver DS
# Describes active server and route
HttpService = <http-service @host HostPattern @port int @method MethodPattern @path PathPattern> .
; Assertion in driver DS
; Describes active listener
# Assertion in driver DS
# 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 .

View File

@ -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.
.

View File

@ -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 = <require-service @serviceName any>.
; 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 = <run-service @serviceName any>.
; 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 = <service-state @serviceName any @state State>.
; 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 = <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
; 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 = <depends-on @depender any @dependee ServiceState>.
; Message. Triggers a service restart.
# Message. Triggers a service restart.
RestartService = <restart-service @serviceName any>.

View File

@ -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 .

View File

@ -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 = <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
; 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 = <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>.

View File

@ -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
; 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 =
/ <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
; 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.
.