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
4 changes: 2 additions & 2 deletions .github/scripts/sync-from-marfa.test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -542,7 +542,7 @@ event_fields_expected="$(cat <<'EOF'
| `stream_incomplete` | `reason` | `string` | Why. |
| `catchup_too_old` | `requested` | `string` | The ID you sent. |
| `cursor_ahead` | `head` | `string` | The latest ID. |
| `read_view_changed` | None | | |
| `reach_changed` | None | | |
EOF
)"

Expand Down Expand Up @@ -723,7 +723,7 @@ schemas = {
"StreamIncompleteFrame": frame("stream_incomplete", {"reason": {"type": "string", "enum": ["reader_behind"], "description": "Why."}}),
"CatchupTooOldFrame": frame("catchup_too_old", {"requested": {"type": "string", "description": "The ID you sent."}}),
"CursorAheadFrame": frame("cursor_ahead", {"head": {"type": "string", "description": "The latest ID."}}),
"ReadViewChangedFrame": frame("read_view_changed", {}),
"ReachChangedFrame": frame("reach_changed", {}),
}
print(json.dumps({"openapi": "3.1.0", "info": {"title": "Marfa", "version": "0", "description": sys.argv[1]}, "paths": {}, "components": {"schemas": schemas}}))
PY
Expand Down
2 changes: 1 addition & 1 deletion content/docs/(overview)/events.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -36,4 +36,4 @@ A webhook has no cursor and no replay: it delivers only events written after you

[Receive webhooks](/guides/receive-webhooks) shows how to register one and check each delivery.

The rules behind this page are in the [events](https://github.com/withmarfa/marfa/blob/main/conformance/spec/events.md) and [read views](https://github.com/withmarfa/marfa/blob/main/conformance/spec/read-views.md) chapters of the contract.
The rules behind this page are in the [events](https://github.com/withmarfa/marfa/blob/main/conformance/spec/events.md) and [reach](https://github.com/withmarfa/marfa/blob/main/conformance/spec/reach.md) chapters of the contract.
2 changes: 1 addition & 1 deletion content/docs/(reference)/swift-sdk.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ Each `Change` names the `itemId` or `edgeId` it concerns, and its `origin` says
| `.queueDrained`, `.queueNotDrained` | The drain the stream ran when the server came back ended, or stopped with an error. | Nothing: the stream drains by itself. |
| `.stopped(MarfaError)` | What fed the stream stopped. Local writes are still told. | See below. |

**Two stops need the app's help.** On `.copyExpired`, hydrate again: the queue survives. Its `reason`, such as `read_view_changed` or `instance_changed`, is an open string, so keep a `default`. On `.unauthorized` or `.signedOut`, give the copy a new credential with `useKey(_:)`.
**Two stops need the app's help.** On `.copyExpired`, hydrate again: the queue survives. Its `reason`, such as `reach_changed` or `instance_changed`, is an open string, so keep a `default`. On `.unauthorized` or `.signedOut`, give the copy a new credential with `useKey(_:)`.

## Send writes and read verdicts

Expand Down
2 changes: 1 addition & 1 deletion content/docs/guides/keep-in-sync.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: Follow an instance's event stream from a cursor, so a copy of your

A search index, a cache or a report keeps its own copy of an instance's data. Read what you need once, then apply each change from the [event stream](/events) and save a cursor, so that after a break you receive everything you missed and nothing twice. The [Swift SDK](/swift-sdk) and the [CLI](/cli) do this for you.

You need a credential that can read the types you copy. A copy that answers reads offline in the instance's place, as a device does, needs more: the [read views chapter of the contract](https://github.com/withmarfa/marfa/blob/main/conformance/spec/read-views.md) says what.
You need a credential that can read the types you copy. A copy that answers reads offline in the instance's place, as a device does, needs more: the [reach chapter of the contract](https://github.com/withmarfa/marfa/blob/main/conformance/spec/reach.md) says what.

## What the stream sends

Expand Down
2 changes: 1 addition & 1 deletion content/docs/guides/sync-a-folder.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,7 @@ defaults:

A new key with the same `--source` is refused `409 conflict` while the old key is live. [Revoke the old key](/guides/manage-keys#revoke-a-key), run the `keys create` command from the first step again, then run `marfa keys keep` so the folder reads the new key from the keychain.

Then run `marfa folders push Notes`. If the key's read view changed, the push rebuilds the working copy once and sends the waiting writes in the same run, keeping earlier verdicts. If the view changes again during that run, the push stops and keeps the remaining writes queued. Try again once the key's access is settled.
Then run `marfa folders push Notes`. If the key's reach changed, the push rebuilds the working copy once and sends the waiting writes in the same run, keeping earlier verdicts. If the reach changes again during that run, the push stops and keeps the remaining writes queued. Try again once the key's access is settled.

## Stop following a folder

Expand Down
4 changes: 2 additions & 2 deletions content/docs/guides/troubleshooting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -233,7 +233,7 @@ You asked to resume from a cursor older than anything the instance's event log s
Start over as you did the first time: read your data again from the API, and follow the stream from its head. The log keeps events for at least 30 days unless the instance is set otherwise. [Keep a copy in sync](/guides/keep-in-sync) shows the whole loop.

</Accordion>
<Accordion title="409 read_view_changed">
<Accordion title="409 reach_changed">

What your credential may read has changed since the working copy was built, for example because its key was narrowed. The copy can't be resumed, because what it holds no longer matches what the credential reads.

Expand All @@ -242,7 +242,7 @@ Build the working copy again. [Devices](/devices) explains when a copy has to st
</Accordion>
<Accordion title="this working copy can no longer be kept current: …; rebuild the copy from the server">

This is how the CLI's device commands report `catchup_too_old` and `read_view_changed`, with the code `copy_expired` and exit code `4`. Writes waiting in the queue are kept.
This is how the CLI's device commands report `catchup_too_old` and `reach_changed`, with the code `copy_expired` and exit code `4`. Writes waiting in the queue are kept.

Run `marfa device hydrate` again. If the credential no longer reads one of the types you held, leave that type out of `--types`, or the hydrate is refused with `type_not_permitted`.

Expand Down
Loading
Loading