From a594f28adf942692e3fb788f4340f3b026108d65 Mon Sep 17 00:00:00 2001 From: Tony Garnock-Jones Date: Wed, 1 Jun 2022 15:41:50 +0200 Subject: [PATCH] First steps of syndicate-protocols notes --- src/SUMMARY.md | 16 +-- src/protocols/syndicate/dataspace.md | 23 ++++ src/protocols/syndicate/dataspacePatterns.md | 119 +++++++++++++++++++ src/protocols/syndicate/gatekeeper.md | 1 + src/protocols/syndicate/index.md | 8 ++ src/protocols/syndicate/protocol.md | 1 + src/protocols/syndicate/service.md | 1 + src/protocols/syndicate/trace.md | 1 + src/protocols/syndicate/transportAddress.md | 1 + 9 files changed, 163 insertions(+), 8 deletions(-) create mode 100644 src/protocols/syndicate/dataspace.md create mode 100644 src/protocols/syndicate/dataspacePatterns.md create mode 100644 src/protocols/syndicate/gatekeeper.md create mode 100644 src/protocols/syndicate/index.md create mode 100644 src/protocols/syndicate/protocol.md create mode 100644 src/protocols/syndicate/service.md create mode 100644 src/protocols/syndicate/trace.md create mode 100644 src/protocols/syndicate/transportAddress.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 9a6af65..aa0c39e 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -49,14 +49,14 @@ - [Preserves schemas](protocols/preserves/index.md) - [Preserves Schema metaschema](protocols/preserves/schema.md) - [Preserves Path schema](protocols/preserves/path.md) -- [Syndicated Actor Model schemas]() - - ["Observe" assertions]() - - [Patterns over assertions]() - - [Gatekeeper and Sturdy-references]() - - [Wire-protocol]() - - [Service dependencies]() - - [Tracing]() - - [Transport addresses]() +- [Syndicated Actor Model schemas](protocols/syndicate/index.md) + - ["Observe" assertions](protocols/syndicate/dataspace.md) + - [Patterns over assertions](protocols/syndicate/dataspacePatterns.md) + - [Gatekeeper and Sturdy-references](protocols/syndicate/gatekeeper.md) + - [Wire-protocol](protocols/syndicate/protocol.md) + - [Service dependencies](protocols/syndicate/service.md) + - [Tracing](protocols/syndicate/trace.md) + - [Transport addresses](protocols/syndicate/transportAddress.md) - [Synit schemas]() - [Audio control]() - [Telephony (call and SMS) support]() diff --git a/src/protocols/syndicate/dataspace.md b/src/protocols/syndicate/dataspace.md new file mode 100644 index 0000000..dfd0c13 --- /dev/null +++ b/src/protocols/syndicate/dataspace.md @@ -0,0 +1,23 @@ +# "Observe" assertions + + - [`[syndicate-protocols]/schemas/dataspace.prs`](https://git.syndicate-lang.org/syndicate-lang/syndicate-protocols/src/branch/main/schemas/dataspace.prs) + +The protocol for interaction with a [dataspace entity](../../glossary.md#dataspace) is very +simple: *any* assertion can be sent to a dataspace. The job of a dataspace is to relay +assertions on to interested peers; they do not generally interpret assertions themselves. + +The sole exception is *assertions of interest in other assertions*. + +These are called "Observe" assertions, or *subscriptions*: + +```preserves-schema +Observe = . +``` + +An `Observe` assertion contains a [pattern](./dataspacePatterns.md) and a reference to an +observer entity. When an `Observe` assertion is published to a dataspace, the dataspace alters +its internal index to make a note of the new expression of interest. It also immediately relays +any of its already-existing assertions that match the pattern to the observer entity. As other +assertions come and go subsequently, the dataspace takes care to inform the observer entity in +the `Observe` record of the arrival or departure of any of the changing assertions that match +the pattern. diff --git a/src/protocols/syndicate/dataspacePatterns.md b/src/protocols/syndicate/dataspacePatterns.md new file mode 100644 index 0000000..059ef65 --- /dev/null +++ b/src/protocols/syndicate/dataspacePatterns.md @@ -0,0 +1,119 @@ +# Patterns over assertions + + - [`[syndicate-protocols]/schemas/dataspacePatterns.prs`](https://git.syndicate-lang.org/syndicate-lang/syndicate-protocols/src/branch/main/schemas/dataspacePatterns.prs) + +Each [subscription record](./dataspace.md) asserted at a dataspace entity contains a pattern +over [Preserves values](../../guide/preserves.md#grammar-of-values). + +The pattern language is carefully chosen to be reasonably expressive without closing the door +to efficient indexing of dataspace contents.[^efficient-indexing] + +## Interpretation of patterns + +A pattern is matched against a candidate input value. Matching can either fail or succeed; if +matching succeeds, a sequence of (numbered) bindings is produced. Each binding in the sequence +corresponds to a (possibly-nested) [binding pattern](#binding) in the overall pattern. + +## Example + +Consider the pattern: + +```preserves + > <_>]>> <_>]> +``` + +The following values each yield different results: + + - `[1 2 3]` fails, because `2` is not an array. + + - `[1 [2 3] 4]` succeeds, yielding a binding sequence `[[2 3] 2]`, because the outer `bind` + captures the whole `[2 3]` array, and the inner (nested) `bind` captures the `2`. + + - `[1 [2 3 4] 5]` fails, because `[2 3 4]` has more than the expected two elements. + + - `[1 [ ] []]` succeeds, yielding a binding sequence `[[ ] ]`. Each discard + pattern (`<_>`) ignores the specific input it is given. + +## Abstract syntax of patterns + +A *pattern* may be either a *discard*, a (nested) *binding*, a *literal*, or a *compound*. + +```preserves-schema +Pattern = DDiscard / DBind / DLit / DCompound . +``` + +### Discard + +A *discard pattern* matches any input value. + +```preserves-schema +DDiscard = <_>. +``` + +### Binding + +A *binding pattern* speculatively pushes the portion of the input under consideration onto the +end of the binding sequence being built, and then recursively evaluates its subpattern. If the +subpattern succeeds, so does the overall binding pattern (keeping the binding); otherwise, the +speculative addition to the binding sequence is undone, and the overall binding pattern fails. + +```preserves-schema +DBind = . +``` + +### Literal + +A *literal pattern* matches any **atomic** Preserves value. In order to match a literal +**compound** value, a combination of compound and literal patterns must be used. + +```preserves-schema +DLit = . +AnyAtom = + / @bool bool + / @float float + / @double double + / @int int + / @string string + / @bytes bytes + / @symbol symbol + / @embedded #!any +. +``` + +### Compound + +Each *compound pattern* first checks the type of its input: a `rec` pattern fails unless it is +given a Record, an `arr` demands a Sequence and a `dict` only matches a Dictionary. + +```preserves-schema +DCompound = + / + / . +``` + +If the type check fails, the pattern match fails. Otherwise, matching continues: + + - `rec` patterns compare the label of the input Record against the `label` field in the + pattern; unless they match literally and exactly, the overall match fails. Otherwise, if the + number of fields in the input does not equal the number expected in the pattern, the match + fails. Otherwise, matching proceeds structurally recursively. + + - `arr` patterns fail if the number of subpatterns does not match the number of items in the + input Sequence. Otherwise, matching proceeds structurally recursively. + + - `dict` patterns consider each of the key/subpattern pairs in `entries` in turn, according to + the Preserves order of the keys.[^dict-pattern-ordering] If any given key from the pattern + is not present in the input value, matching fails. Otherwise, matching proceeds recursively. + The pattern ignores keys in the input value that are not mentioned in the pattern. + +--- + +[^efficient-indexing]: Most implementations of Syndicated Actor Model dataspaces use an + efficient index datastructure [described here](https://git.syndicate-lang.org/syndicate-lang/syndicate-rkt/src/commit/90c4c60699069b496491b81ee63b5a45ffd638cb/syndicate/HOWITWORKS.md). + +[^dict-pattern-ordering]: The ordering of visiting of keys in a `dict` pattern is important + because bindings are *numbered* in this pattern language, not named. Recall that `>, b: >}>` is an identical Preserves value to `>, a: + >}>`, so to guarantee consistent binding results, we must choose some + deterministic order for visiting the subpatterns of the `dict`. (In this example, `a` will + be visited before `b`, because `a` < `b`). diff --git a/src/protocols/syndicate/gatekeeper.md b/src/protocols/syndicate/gatekeeper.md new file mode 100644 index 0000000..3cb5cd5 --- /dev/null +++ b/src/protocols/syndicate/gatekeeper.md @@ -0,0 +1 @@ +# Gatekeeper and Sturdy-references diff --git a/src/protocols/syndicate/index.md b/src/protocols/syndicate/index.md new file mode 100644 index 0000000..6da6b4c --- /dev/null +++ b/src/protocols/syndicate/index.md @@ -0,0 +1,8 @@ +# Syndicated Actor Model schemas + + - Schema definitions: [`[syndicate-protocols]/schemas/`](https://git.syndicate-lang.org/syndicate-lang/syndicate-protocols/src/branch/main/schemas/) + +The following pages document schemas associated with the [Syndicated Actor +Model](../../syndicated-actor-model.md). By and large, these schemas are contained in the +[syndicate-protocols Git +repository](https://git.syndicate-lang.org/syndicate-lang/syndicate-protocols/src/branch/main/schemas). diff --git a/src/protocols/syndicate/protocol.md b/src/protocols/syndicate/protocol.md new file mode 100644 index 0000000..1e0c28f --- /dev/null +++ b/src/protocols/syndicate/protocol.md @@ -0,0 +1 @@ +# Wire-protocol diff --git a/src/protocols/syndicate/service.md b/src/protocols/syndicate/service.md new file mode 100644 index 0000000..91e4442 --- /dev/null +++ b/src/protocols/syndicate/service.md @@ -0,0 +1 @@ +# Service dependencies diff --git a/src/protocols/syndicate/trace.md b/src/protocols/syndicate/trace.md new file mode 100644 index 0000000..6c328cf --- /dev/null +++ b/src/protocols/syndicate/trace.md @@ -0,0 +1 @@ +# Tracing diff --git a/src/protocols/syndicate/transportAddress.md b/src/protocols/syndicate/transportAddress.md new file mode 100644 index 0000000..282eced --- /dev/null +++ b/src/protocols/syndicate/transportAddress.md @@ -0,0 +1 @@ +# Transport addresses