From 4fdf048c750c6c4fbdc0402a0239ce13576cb195 Mon Sep 17 00:00:00 2001 From: August Cayzer Date: Wed, 21 Oct 2026 17:50:14 +0100 Subject: [PATCH] docs: sync v0.0.22 and correct sentences the v0.0.21 and v0.0.22 fixes made untrue --- content/docs/(reference)/changelog.mdx | 9 +++++++++ content/docs/guides/back-up-and-restore.mdx | 2 +- content/docs/guides/deploy.mdx | 4 ++-- content/docs/guides/folder-safeguards.mdx | 8 ++++---- content/docs/guides/handle-files.mdx | 2 +- content/docs/guides/keep-folders-running.mdx | 4 ++-- content/docs/guides/receive-webhooks.mdx | 2 +- content/docs/guides/sync-a-folder.mdx | 2 +- src/generated/cli-download.md | 2 +- src/generated/marfa-release.json | 2 +- src/generated/server-image.md | 4 ++-- 11 files changed, 25 insertions(+), 16 deletions(-) diff --git a/content/docs/(reference)/changelog.mdx b/content/docs/(reference)/changelog.mdx index a6886d67..fe29547a 100644 --- a/content/docs/(reference)/changelog.mdx +++ b/content/docs/(reference)/changelog.mdx @@ -7,6 +7,15 @@ Each release of Marfa ships the server and its container image, the CLI for macO **Marfa doesn't upgrade a database in place.** A build refuses a database whose schema differs from its own, or that holds retired tables or settings, and leaves the file unchanged; a version change alone doesn't cause a refusal. [Upgrade](/guides/upgrade) shows how to test an export and restore on fresh storage before switching builds. +## v0.0.22 + +Released October 21, 2026. [v0.0.22 on GitHub](https://github.com/withmarfa/marfa/releases/tag/v0.0.22) + +For folders and app builders: + +- **A first sync of many files finishes in one run.** A working copy sends waiting new items and their placements in pages of up to 1,000, and reads them back in bulk, instead of using four requests for each file. Pushing 5,000 new notes took 11 pushes because of the request limit and now takes one. Fewer than 50 waiting items are sent one at a time, as before. +- **A write a page cannot settle is sent on its own.** An entry the server skips or refuses goes alone under its key, and a page the server rate-limits is sent again on the next pass. + ## v0.0.21 Released October 21, 2026. [v0.0.21 on GitHub](https://github.com/withmarfa/marfa/releases/tag/v0.0.21) diff --git a/content/docs/guides/back-up-and-restore.mdx b/content/docs/guides/back-up-and-restore.mdx index 937f68df..ad016511 100644 --- a/content/docs/guides/back-up-and-restore.mdx +++ b/content/docs/guides/back-up-and-restore.mdx @@ -35,7 +35,7 @@ Stop the server, put the copied files where `SQLITE_PATH` and `BLOB_PATH` name, ## With a bucket -When `S3_BUCKET` is set, **the container copies for you**. It streams each committed database write to the bucket within a second, keeps a day of hourly snapshots, and the `blob-replicate` housekeeping job copies each blob. A new volume started with the same bucket, prefix and secrets restores the database as it starts and brings the blobs back as replication runs. +When `S3_BUCKET` is set, **the container copies for you**. It streams each committed database write to the bucket within a second, keeps a day of hourly snapshots, and the `blob-replicate` housekeeping job copies each blob; a blob whose store hasn't answered is skipped and copied on a later run. A new volume started with the same bucket, prefix and secrets restores the database as it starts and brings the blobs back as replication runs. Everything the instance keeps in the bucket is under its `S3_PREFIX`, so **give each instance on a shared bucket its own prefix**. [Settings](/guides/settings#every-environment-setting) says what a prefix may hold. diff --git a/content/docs/guides/deploy.mdx b/content/docs/guides/deploy.mdx index 3fa22e4f..639ee2d8 100644 --- a/content/docs/guides/deploy.mdx +++ b/content/docs/guides/deploy.mdx @@ -11,7 +11,7 @@ An instance is one server process and one SQLite database, so there's no databas | --- | --- | --- | | A computer you own | A Mac or a home server that stays on. | [Run it without a container](#run-it-without-a-container), under a supervisor. | | A container | A server you already run. | [Run it in a container](#run-it-in-a-container), with one volume. | -| Railway | The quickest way to an instance on the internet, billed to you by Railway. | The [Marfa template](https://railway.com/new/template/5z9-Ja) creates the server, a volume and a backup bucket, and sets the secrets and the address, as [the Railway steps](https://github.com/withmarfa/marfa/blob/main/deploy/railway.md) say. | +| Railway | The quickest way to an instance on the internet, billed to you by Railway. | The [Marfa template](https://railway.com/new/template/5z9-Ja) creates a server that runs the published release image, a volume and a backup bucket, and sets the secrets and the address, as [the Railway steps](https://github.com/withmarfa/marfa/blob/main/deploy/railway.md) say. | The server runs [housekeeping jobs](/guides/housekeeping) and backups in the background, so turn off any host feature that stops an idle service, such as Railway's Serverless mode. @@ -153,7 +153,7 @@ The database and the blobs are the whole of your data, so put them on storage th `control/marfa.sock` lets a command run on the same machine, as the server's account, reach the instance with the owner's authority. You use it to claim the instance, make the first key and [recover the owner's password](/guides/sign-in-as-the-owner#recover-the-owners-password). -- The socket carries no key, so the server refuses item properties, edges, tags, search, counts, events and exports through it with `401 unauthorized`. Run those with a key. Item summaries, the trash and removing an unused type you registered work through the socket. +- The socket carries no key, so the server refuses item properties, edges, tags, search, counts, events and exports through it with `401 unauthorized`. Run those with a key. Item summaries, the trash, attachments, the status of bulk jobs and removing an unused type you registered work through the socket. - The CLI refuses `--socket` while `MARFA_API_URL` or `MARFA_API_KEY` is set, so unset them in that shell first. - The socket's folder must belong to the server's account and be readable by no one else. On Linux, install the `acl` package, which the server uses to check this. - A start replaces a socket that a crash left behind, and refuses one that another process listens on. Find that process before you remove the socket. diff --git a/content/docs/guides/folder-safeguards.mdx b/content/docs/guides/folder-safeguards.mdx index 67f578e2..335a084e 100644 --- a/content/docs/guides/folder-safeguards.mdx +++ b/content/docs/guides/folder-safeguards.mdx @@ -27,7 +27,7 @@ marfa folders push Notes ```text 0 created, 0 updated, 0 renamed, 4 unchanged, 12 missing, 0 deleted, 0 skipped a large removal waits: 12 delete(s) not sent; `folders confirm` sends them, `folders restore` writes the files back -answered 0, held 0 +the server answered 0 write(s) 0 file(s) written ``` @@ -51,7 +51,7 @@ if status.paused.isPaused { `restore` lists each file it couldn't write back, such as one whose bytes it couldn't fetch, with the reason, and every later pull tries again. -`marfa folders status Notes` shows where every file stands, and whether a removal waits, without asking the instance. `marfa folders health` takes the folder's ID and shows the server's latest report from each sign-in and local copy. A report's age says when it arrived, not whether that copy is reachable now. +`marfa folders status Notes` shows where every file stands, and whether a removal waits, without asking the instance. A document the scan refuses, such as one with an unknown type, shows as `held` with the reason. `marfa folders health` takes the folder's ID and shows the server's latest report from each sign-in and local copy. A report's age says when it arrived, not whether that copy is reachable now. ## A missing or unreadable directory @@ -80,7 +80,7 @@ marfa folders push Notes ```text 0 created, 0 updated, 0 renamed, 3 unchanged, 0 missing, 0 deleted, 0 skipped server.pem: not taken, because its name is one a secret goes by -answered 0, held 0 +the server answered 0 write(s) 0 file(s) written ``` @@ -123,6 +123,6 @@ Exit `0` doesn't mean the server took every edit. A refused edit stays in the fi ### Writes still waiting -A file whose write is sent but not yet answered counts as **waiting**, not unchanged: the report's first line adds `; 2 queued earlier and not delivered yet`, and `--json` has a `waiting` count. +A file whose write is sent but not yet answered counts as **waiting**, not unchanged: the report's first line adds `; 2 already queued by an earlier scan, so not counted as created or updated here`, and `--json` has a `waiting` count. The rules behind this page are in the [folders](https://github.com/withmarfa/marfa/blob/main/conformance/spec/folders.md) chapter of the contract. diff --git a/content/docs/guides/handle-files.mdx b/content/docs/guides/handle-files.mdx index a3406934..bdca5c58 100644 --- a/content/docs/guides/handle-files.mdx +++ b/content/docs/guides/handle-files.mdx @@ -52,7 +52,7 @@ Marfa answers with the blob's `hash`, the media type it will serve the bytes und The same bytes always give the same hash, so uploading them again **stores nothing new** and answers the same hash. -An upload has **no size cap and no total time limit**. Marfa ends one with `408 request_timeout`, storing no blob, only when no bytes arrive for `MARFA_UPLOAD_IDLE_TIMEOUT_MS`, 60 seconds unless the instance sets it. +An upload has **no size cap and no total time limit**. Marfa ends one with `408 request_timeout`, storing no blob, only when no bytes arrive for `MARFA_UPLOAD_IDLE_TIMEOUT_MS`, 60 seconds unless the instance sets it. While a store hasn't finished an earlier write or delete of the same bytes, an upload answers `503 blob_store_unavailable` and stores nothing: try again later. ## Point an item at the bytes diff --git a/content/docs/guides/keep-folders-running.mdx b/content/docs/guides/keep-folders-running.mdx index 71190def..510f91f5 100644 --- a/content/docs/guides/keep-folders-running.mdx +++ b/content/docs/guides/keep-folders-running.mdx @@ -21,7 +21,7 @@ marfa folders watch watching every folder /Users/sam/Library/Application Support/Marfa/folders.json lists (interrupt to stop) /Users/sam/Notes: watching /Users/sam/Recipes: watching -/Users/sam/Notes: 0 created, 1 updated, 0 renamed, 0 deleted; answered 1; 1 file(s) written +/Users/sam/Notes: 0 created, 1 updated, 0 renamed, 0 deleted; the server answered 1 write(s); 1 file(s) written ``` @@ -100,7 +100,7 @@ marfa folders push Notes --send-only ```text 1 created, 0 updated, 0 renamed, 2 unchanged, 0 missing, 0 deleted, 0 skipped -answered 2, held 0 +the server answered 2 write(s), creating 1 item(s) send-only run: nothing was pulled, so no item's file was written or removed; the next `folders push` pulls what the server holds ``` diff --git a/content/docs/guides/receive-webhooks.mdx b/content/docs/guides/receive-webhooks.mdx index 22f55228..4fca81bc 100644 --- a/content/docs/guides/receive-webhooks.mdx +++ b/content/docs/guides/receive-webhooks.mdx @@ -54,7 +54,7 @@ Marfa answers with the webhook, its `secret` included: } ``` -Marfa shows the secret **only this once**. Every later read shows `****` and its last four characters. Keep it where your receiver can read it and nothing else can, as you would a password. +Marfa shows the secret **only this once**. Every later read shows `****` and its last four characters. Keep it where your receiver can read it and nothing else can, as you would a password. The CLI prints the secret alone on the first line, as `marfa keys create` does with a key, and doesn't print back a secret you gave. To use a secret of your own instead, send `secret` with at least 32 characters. diff --git a/content/docs/guides/sync-a-folder.mdx b/content/docs/guides/sync-a-folder.mdx index 75eaea11..d2407428 100644 --- a/content/docs/guides/sync-a-folder.mdx +++ b/content/docs/guides/sync-a-folder.mdx @@ -148,7 +148,7 @@ marfa folders push Notes ```text 0 created, 1 updated, 0 renamed, 2 unchanged, 0 missing, 0 deleted, 0 skipped -answered 1, held 0 +the server answered 1 write(s) 1 file(s) written ``` diff --git a/src/generated/cli-download.md b/src/generated/cli-download.md index 4d85de2d..53c01d29 100644 --- a/src/generated/cli-download.md +++ b/src/generated/cli-download.md @@ -1,5 +1,5 @@ ```bash -curl -fsSL https://github.com/withmarfa/marfa/releases/download/v0.0.21/marfa-0.0.21-darwin-arm64.tar.gz | tar -xz +curl -fsSL https://github.com/withmarfa/marfa/releases/download/v0.0.22/marfa-0.0.22-darwin-arm64.tar.gz | tar -xz sudo mkdir -p /usr/local/bin sudo mv marfa /usr/local/bin/ marfa --version diff --git a/src/generated/marfa-release.json b/src/generated/marfa-release.json index 006a9628..6054cf97 100644 --- a/src/generated/marfa-release.json +++ b/src/generated/marfa-release.json @@ -1 +1 @@ -{"version":"v0.0.21"} +{"version":"v0.0.22"} diff --git a/src/generated/server-image.md b/src/generated/server-image.md index bfb7a5bd..79a13de7 100644 --- a/src/generated/server-image.md +++ b/src/generated/server-image.md @@ -1,5 +1,5 @@ ```bash -docker pull ghcr.io/withmarfa/marfa-server:0.0.21 +docker pull ghcr.io/withmarfa/marfa-server:0.0.22 docker run --name marfa -d --restart unless-stopped -p 127.0.0.1:8600:8600 \ - -v marfa-data:/data --env-file marfa.env ghcr.io/withmarfa/marfa-server:0.0.21 + -v marfa-data:/data --env-file marfa.env ghcr.io/withmarfa/marfa-server:0.0.22 ```