From de39824e7af30fbbe947d676192d3a8419dc7ea3 Mon Sep 17 00:00:00 2001 From: Thomas Kosiewski Date: Sat, 21 Nov 2026 09:22:13 +0000 Subject: [PATCH 1/3] docs(wire-compat): record the git heap-cap 422 on branches/create, tags and the git:read routes Add a deviation row for the 422 that the git heap cap answers on the git:read routes, on POST branches/create and POST tags (#929), and on POST merge with a pin that is not the source tip. Change-Id: I7e735dd35a1dd7785bc7b60e436e34a15b16cd10 Signed-off-by: Thomas Kosiewski --- docs/explanation/wire-compatibility.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/explanation/wire-compatibility.md b/docs/explanation/wire-compatibility.md index 60205db8..9dc833a0 100644 --- a/docs/explanation/wire-compatibility.md +++ b/docs/explanation/wire-compatibility.md @@ -242,6 +242,7 @@ the [archived phase notes](../archive/phases/)): | Implicit push forwarding: in upstream's GitHub App mode every `git push` to the default remote is proxied straight to GitHub, always on, with no REST trigger ([integrations guide](../upstream/guides/integrations.md)). Since spec `412b90c3` (2026-11-02), the REST writes (`commit-pack`, `diff-commit`, `reset-commits`, `restore-commit`, `merge`, and branch and tag create and delete) on a repository with a GitHub upstream also push to GitHub before they answer. They answer `412` when the write cannot reach GitHub or GitHub refuses it: the commit writes (`commit-pack`, `diff-commit`, `reset-commits`, `restore-commit`) with `result.status` `failed`, the others with the code `github_app_not_configured`, `github_repository_inaccessible` or `precondition_failed`. They answer `502` when GitHub fails or cannot be reached, and then the write can already be applied | Explicit `POST /repos/push-upstream` (non-force by default, `force: true` opt-in) plus an opt-in per-repo `base_repo.forward_pushes` flag (default **off**) that schedules a forward after every won local push and mirrors back on success. A rejected non-fast-forward fails the run with per-ref reasons instead of rewriting upstream history. Ref deletions are not propagated in either direction (the inbound mirror deliberately avoids `--mirror` for the same reason). With `forward_pushes` off, a local push still triggers the inbound mirror, which force-resets local refs to upstream state ("upstream wins"). REST writes change only local refs and answer without contacting GitHub. A won REST write pokes the same sync scheduler as a won push, with the same caller gates: on a `forward_pushes` repo it schedules the same forward, unless the token lacks `git:read` or carries a ref-policy op. Then the write stays local until the next authorized trigger. A scheduled forward runs in the background, and the answer does not wait for it. No REST write returns a `412` or `502` for a GitHub failure | Recorded deviation ([ADR-44](../adr/044-outbound-push-forwarding-rides-a-separate-push-claim-lane.md), issue #90): implicit always-on forwarding invites silent divergence and needs GitHub App infrastructure this backend does not have. The explicit trigger + opt-in flag keep the direction observable (`repo.push_upstream.*` events) and non-destructive by default. Upstream's REST write-through runs through its GitHub App, and open.storage rejects `access: "app"` with `400` ([#654](https://github.com/coder/openstorage/issues/654)) | | `repo.sync.started`, `repo.sync.succeeded` and `repo.sync.failed` (spec `bed02bed`, 2026-11-19): upstream retries a sync that fails with a transient error for up to 2 hours. `repo.sync.failed` goes out at the first failure of such a series and for an error that a retry cannot fix. After a failure, `repo.sync.started` goes out only when a later run of the series succeeds, right before `repo.sync.succeeded`. The spec also allows events per run: "During the move to the new sync engine, some repositories get this event once per run, when the retries of the run end" (`repo.sync.failed`), and some "send this event at the start of every run, also after a failure" (`repo.sync.started`) | Every inbound run sends `repo.sync.started` when it starts, after a failed run too, and `repo.sync.succeeded` or `repo.sync.failed` when it ends. open.storage does not retry a failed inbound run, so each failed run sends its own `repo.sync.failed`. A cancelled run, such as one that a detach or a server shutdown stops, sends no end event. The events of one run have the same `started_at`, and `repo.sync.started` has a `run_count` 1 lower than the end event, as upstream documents. Each event is its own delivery with its own retries, so the events of a run can arrive out of order. A receiver should read each `repo.sync.failed` as the end of one failed run, not as the start of a retry series, and should wait for `repo.sync.succeeded` before it treats a failing repository as recovered, because a run that starts after a failure can still fail. It should order the events of a run by `started_at` and `run_count`, not by arrival, and should not wait for an end event after every `repo.sync.started` | Inbound sync here has no transient-retry series, so per-run events are the form that the spec allows during upstream's move. Desk decision ([#908](https://github.com/coder/openstorage/issues/908)): record the difference. Building a retry series is out of scope | | `GET .../file` and `POST .../archive`: no documented file-size cap and no `422`; `archive` has only the caller-chosen `max_blob_size` | `file` and `archive` answer 422 for a file over 100 MiB (`archive` can skip such files with `max_blob_size`), before any response byte. The other read-side git [resource limits](../reference/http-api.md#resource-limits-on-git-reads) apply too. After an `archive` response has started, a limit closes the connection instead of returning a status | Hardening ([ADR-49](../adr/049-read-side-git-children-run-under-one-per-request-budget.md)): the limits bound server memory, temporary disk and delivery time for data that anyone who can push controls. Fetch larger files with git | +| No operation lists a `422` response. The spec's error-code list names the generic code `unprocessable_entity` (422), and `POST .../branches/create`, `POST .../tags` and `POST .../merge` list 200, 400, 401, 403, 404, 409, 412, 429, 500, 502 and 503 | On Linux, a git subprocess that needs more heap than its cap (256 MiB, 32 MiB for single-object reads) makes the request answer `422` `unprocessable_entity`, "history or object too large for the server's git memory limit". This holds on both path styles of three groups of routes. The first is every `git:read` route that runs git: `GET` and `HEAD .../file`, `files`, `files/metadata`, `branches/diff`, `commits`, `commit`, `diff`, `GET .../tags`, `tag`, `blame`, `notes`, `merge/preview`, `grep` and `archive`. The second is `POST .../branches/create` and `POST .../tags`, which since [#929](https://github.com/coder/openstorage/pull/929) walk the history of the commit they name under the same caps ([which commit a base can name](../reference/http-api.md#which-commit-the-base-and-the-tag-target-can-name)). The third is `POST .../merge` with an `expected_source_sha` that is not the source tip, which walks that commit the same way. `GET .../branches`, `branch`, `notes/refs` and `repo` run no git under a cap. An `archive` whose response has started closes the connection instead (row above) | Hardening ([ADR-49](../adr/049-read-side-git-children-run-under-one-per-request-budget.md)): anyone who can push shapes the history and objects that git reads, and the caps bound server memory ([resource limits](../reference/http-api.md#resource-limits-on-git-reads)). The same request needs the same memory on a retry, so the answer is a `4xx`, not the `503` of a busy server. The create, tag and pinned merge walks need the most memory for a history that no ref reaches: 100,000 such commits need more than the cap | | Every `503` response can carry an optional `Retry-After` header, the minimum delay in seconds before a retry (spec 2026-10-21) | Two 503s leave `Retry-After` out: a git read that exceeds its [time budget](../reference/http-api.md#resource-limits-on-git-reads), and a sync create whose upstream link was removed before its first sync was scheduled ([pending creates](../reference/http-api.md#repository-lifecycle-repowrite--orgread)). The 503 for exhausted git concurrency and the 503s for a create that is not finished carry `Retry-After` | A retry of either request fails the same way, so a `Retry-After` would invite a useless retry. The same page needs the same git time ([ADR-49](../adr/049-read-side-git-children-run-under-one-per-request-budget.md)). The pending create stays pending until `DELETE /repos/delete` clears the name ([#388](https://github.com/coder/openstorage/issues/388)) | | A token that fails verification (malformed, bad signature, expired, unknown issuer): upstream's live docs and servers answer `403` `forbidden` (`Invalid or expired token`) on the REST API, and `403` on the Git and LFS transports too (checked 2026-11-04). The vendored spec documents no status for it | The REST API answers `403` `forbidden` (`Invalid or expired token`), as upstream does ([#664](https://github.com/coder/openstorage/issues/664)). The Git and LFS transports answer `401` with `WWW-Authenticate: Basic`, as for a missing token ([authentication](../reference/authentication.md#failure-mapping)) | Git asks for credentials only after a `401`, and only a `401` makes it erase a stored credential. After a `403`, git fails and keeps the expired token in the credential helper, so every later command fails the same way until the user removes the token | | A `crit` member in the JWT header: the vendored docs and spec say nothing about it. They list `alg` and `typ` as the header ([authentication guide](../upstream/getting-started/authentication.md)) | A token whose header has a `crit` member of any value fails verification, even when the signature is valid. The status is the one for any token that fails verification (the row above) | RFC 7515 §4.1.11: a recipient that does not understand a listed extension must refuse the token. open.storage understands none, so it refuses any `crit` | From fa3eb96fc6c1afb3fcb1495316ea79e378b21dc9 Mon Sep 17 00:00:00 2001 From: Thomas Kosiewski Date: Sat, 21 Nov 2026 09:44:07 +0000 Subject: [PATCH 2/3] docs(wire-compat): fix the walk figure and name the write-route exception Verifier round 1: 100,000 unreferenced commits fit under the heap cap (500,000 do not), the pinned merge walk never meets an unreferenced history, and http-api.md said the write endpoints are not covered by the git read limits. Change-Id: I53030284a193dbdaf6996ce279f71607a11af5a2 Signed-off-by: Thomas Kosiewski --- docs/explanation/wire-compatibility.md | 2 +- docs/reference/http-api.md | 9 +++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/explanation/wire-compatibility.md b/docs/explanation/wire-compatibility.md index 9dc833a0..e90af42c 100644 --- a/docs/explanation/wire-compatibility.md +++ b/docs/explanation/wire-compatibility.md @@ -242,7 +242,7 @@ the [archived phase notes](../archive/phases/)): | Implicit push forwarding: in upstream's GitHub App mode every `git push` to the default remote is proxied straight to GitHub, always on, with no REST trigger ([integrations guide](../upstream/guides/integrations.md)). Since spec `412b90c3` (2026-11-02), the REST writes (`commit-pack`, `diff-commit`, `reset-commits`, `restore-commit`, `merge`, and branch and tag create and delete) on a repository with a GitHub upstream also push to GitHub before they answer. They answer `412` when the write cannot reach GitHub or GitHub refuses it: the commit writes (`commit-pack`, `diff-commit`, `reset-commits`, `restore-commit`) with `result.status` `failed`, the others with the code `github_app_not_configured`, `github_repository_inaccessible` or `precondition_failed`. They answer `502` when GitHub fails or cannot be reached, and then the write can already be applied | Explicit `POST /repos/push-upstream` (non-force by default, `force: true` opt-in) plus an opt-in per-repo `base_repo.forward_pushes` flag (default **off**) that schedules a forward after every won local push and mirrors back on success. A rejected non-fast-forward fails the run with per-ref reasons instead of rewriting upstream history. Ref deletions are not propagated in either direction (the inbound mirror deliberately avoids `--mirror` for the same reason). With `forward_pushes` off, a local push still triggers the inbound mirror, which force-resets local refs to upstream state ("upstream wins"). REST writes change only local refs and answer without contacting GitHub. A won REST write pokes the same sync scheduler as a won push, with the same caller gates: on a `forward_pushes` repo it schedules the same forward, unless the token lacks `git:read` or carries a ref-policy op. Then the write stays local until the next authorized trigger. A scheduled forward runs in the background, and the answer does not wait for it. No REST write returns a `412` or `502` for a GitHub failure | Recorded deviation ([ADR-44](../adr/044-outbound-push-forwarding-rides-a-separate-push-claim-lane.md), issue #90): implicit always-on forwarding invites silent divergence and needs GitHub App infrastructure this backend does not have. The explicit trigger + opt-in flag keep the direction observable (`repo.push_upstream.*` events) and non-destructive by default. Upstream's REST write-through runs through its GitHub App, and open.storage rejects `access: "app"` with `400` ([#654](https://github.com/coder/openstorage/issues/654)) | | `repo.sync.started`, `repo.sync.succeeded` and `repo.sync.failed` (spec `bed02bed`, 2026-11-19): upstream retries a sync that fails with a transient error for up to 2 hours. `repo.sync.failed` goes out at the first failure of such a series and for an error that a retry cannot fix. After a failure, `repo.sync.started` goes out only when a later run of the series succeeds, right before `repo.sync.succeeded`. The spec also allows events per run: "During the move to the new sync engine, some repositories get this event once per run, when the retries of the run end" (`repo.sync.failed`), and some "send this event at the start of every run, also after a failure" (`repo.sync.started`) | Every inbound run sends `repo.sync.started` when it starts, after a failed run too, and `repo.sync.succeeded` or `repo.sync.failed` when it ends. open.storage does not retry a failed inbound run, so each failed run sends its own `repo.sync.failed`. A cancelled run, such as one that a detach or a server shutdown stops, sends no end event. The events of one run have the same `started_at`, and `repo.sync.started` has a `run_count` 1 lower than the end event, as upstream documents. Each event is its own delivery with its own retries, so the events of a run can arrive out of order. A receiver should read each `repo.sync.failed` as the end of one failed run, not as the start of a retry series, and should wait for `repo.sync.succeeded` before it treats a failing repository as recovered, because a run that starts after a failure can still fail. It should order the events of a run by `started_at` and `run_count`, not by arrival, and should not wait for an end event after every `repo.sync.started` | Inbound sync here has no transient-retry series, so per-run events are the form that the spec allows during upstream's move. Desk decision ([#908](https://github.com/coder/openstorage/issues/908)): record the difference. Building a retry series is out of scope | | `GET .../file` and `POST .../archive`: no documented file-size cap and no `422`; `archive` has only the caller-chosen `max_blob_size` | `file` and `archive` answer 422 for a file over 100 MiB (`archive` can skip such files with `max_blob_size`), before any response byte. The other read-side git [resource limits](../reference/http-api.md#resource-limits-on-git-reads) apply too. After an `archive` response has started, a limit closes the connection instead of returning a status | Hardening ([ADR-49](../adr/049-read-side-git-children-run-under-one-per-request-budget.md)): the limits bound server memory, temporary disk and delivery time for data that anyone who can push controls. Fetch larger files with git | -| No operation lists a `422` response. The spec's error-code list names the generic code `unprocessable_entity` (422), and `POST .../branches/create`, `POST .../tags` and `POST .../merge` list 200, 400, 401, 403, 404, 409, 412, 429, 500, 502 and 503 | On Linux, a git subprocess that needs more heap than its cap (256 MiB, 32 MiB for single-object reads) makes the request answer `422` `unprocessable_entity`, "history or object too large for the server's git memory limit". This holds on both path styles of three groups of routes. The first is every `git:read` route that runs git: `GET` and `HEAD .../file`, `files`, `files/metadata`, `branches/diff`, `commits`, `commit`, `diff`, `GET .../tags`, `tag`, `blame`, `notes`, `merge/preview`, `grep` and `archive`. The second is `POST .../branches/create` and `POST .../tags`, which since [#929](https://github.com/coder/openstorage/pull/929) walk the history of the commit they name under the same caps ([which commit a base can name](../reference/http-api.md#which-commit-the-base-and-the-tag-target-can-name)). The third is `POST .../merge` with an `expected_source_sha` that is not the source tip, which walks that commit the same way. `GET .../branches`, `branch`, `notes/refs` and `repo` run no git under a cap. An `archive` whose response has started closes the connection instead (row above) | Hardening ([ADR-49](../adr/049-read-side-git-children-run-under-one-per-request-budget.md)): anyone who can push shapes the history and objects that git reads, and the caps bound server memory ([resource limits](../reference/http-api.md#resource-limits-on-git-reads)). The same request needs the same memory on a retry, so the answer is a `4xx`, not the `503` of a busy server. The create, tag and pinned merge walks need the most memory for a history that no ref reaches: 100,000 such commits need more than the cap | +| No operation lists a `422` response. The spec's error-code list names the generic code `unprocessable_entity` (422), and `POST .../branches/create`, `POST .../tags` and `POST .../merge` list 200, 400, 401, 403, 404, 409, 412, 429, 500, 502 and 503 | On Linux, a git subprocess that needs more heap than its cap (256 MiB, 32 MiB for single-object reads) makes the request answer `422` `unprocessable_entity`, "history or object too large for the server's git memory limit". Three groups of routes can answer it, on both path styles. The first is every `git:read` route that runs git: `GET` and `HEAD .../file`, `files`, `files/metadata`, `branches/diff`, `commits`, `commit`, `diff`, `GET .../tags`, `tag`, `blame`, `notes`, `merge/preview`, `grep` and `archive`. The second is `POST .../branches/create` and `POST .../tags`, which since [#929](https://github.com/coder/openstorage/pull/929) walk the history of the commit they name under the same caps ([which commit a base can name](../reference/http-api.md#which-commit-the-base-and-the-tag-target-can-name)). The third is `POST .../merge` with an `expected_source_sha` that is not the source tip, which walks that commit the same way. `GET .../branches`, `branch`, `notes/refs` and `repo` run no git under a cap. An `archive` whose response has started closes the connection instead (row above) | Hardening ([ADR-49](../adr/049-read-side-git-children-run-under-one-per-request-budget.md)): anyone who can push shapes the history and objects that git reads, and the caps bound server memory ([resource limits](../reference/http-api.md#resource-limits-on-git-reads)). The same request needs the same memory on a retry, so the answer is a `4xx`, not the `503` of a busy server. The create and tag walks need the most memory for a long history that no ref reaches ([which commit a base can name](../reference/http-api.md#which-commit-the-base-and-the-tag-target-can-name)) | | Every `503` response can carry an optional `Retry-After` header, the minimum delay in seconds before a retry (spec 2026-10-21) | Two 503s leave `Retry-After` out: a git read that exceeds its [time budget](../reference/http-api.md#resource-limits-on-git-reads), and a sync create whose upstream link was removed before its first sync was scheduled ([pending creates](../reference/http-api.md#repository-lifecycle-repowrite--orgread)). The 503 for exhausted git concurrency and the 503s for a create that is not finished carry `Retry-After` | A retry of either request fails the same way, so a `Retry-After` would invite a useless retry. The same page needs the same git time ([ADR-49](../adr/049-read-side-git-children-run-under-one-per-request-budget.md)). The pending create stays pending until `DELETE /repos/delete` clears the name ([#388](https://github.com/coder/openstorage/issues/388)) | | A token that fails verification (malformed, bad signature, expired, unknown issuer): upstream's live docs and servers answer `403` `forbidden` (`Invalid or expired token`) on the REST API, and `403` on the Git and LFS transports too (checked 2026-11-04). The vendored spec documents no status for it | The REST API answers `403` `forbidden` (`Invalid or expired token`), as upstream does ([#664](https://github.com/coder/openstorage/issues/664)). The Git and LFS transports answer `401` with `WWW-Authenticate: Basic`, as for a missing token ([authentication](../reference/authentication.md#failure-mapping)) | Git asks for credentials only after a `401`, and only a `401` makes it erase a stored credential. After a `403`, git fails and keeps the expired token in the credential helper, so every later command fails the same way until the user removes the token | | A `crit` member in the JWT header: the vendored docs and spec say nothing about it. They list `alg` and `typ` as the header ([authentication guide](../upstream/getting-started/authentication.md)) | A token whose header has a `crit` member of any value fails verification, even when the signature is valid. The status is the one for any token that fails verification (the row above) | RFC 7515 §4.1.11: a recipient that does not understand a listed extension must refuse the token. open.storage understands none, so it refuses any `crit` | diff --git a/docs/reference/http-api.md b/docs/reference/http-api.md index f926e7e3..70bbb6a1 100644 --- a/docs/reference/http-api.md +++ b/docs/reference/http-api.md @@ -774,9 +774,10 @@ on 500,000 linear commits: the tip of a branch takes 5 ms, a commit 1,000 back 1 commits and trees, and also the walk of the history of the refs down to its commit date (1,000 new commits dated after the tip took 14 ms, and the same commits dated 1970 took 1.7 s). A commit whose parent no pack holds always costs the whole history (1.6 s). A separate unreferenced history -costs more, because git also holds its trees: 50,000 commits took 2.4 s, and 100,000 commits need -more than the heap cap. The walk runs under the admission slots, the 30-second time budget and the -256 MiB heap cap (Linux) of the git:read routes ([Resource limits on git +costs more, because git also holds its trees: 50,000 commits took 2.4 s. A long enough one needs +more than the heap cap: with one new blob and three new trees per commit, 100,000 commits fit +under it and 500,000 did not (git 2.55). The walk runs under the admission slots, the 30-second +time budget and the 256 MiB heap cap (Linux) of the git:read routes ([Resource limits on git reads](#resource-limits-on-git-reads)): a request that finds no free slot answers `503` with `Retry-After`, a walk that outlasts its budget answers `503`, and a walk that needs more memory answers `422`. A create whose `base_ref` is refused walks `preferred_base` under the same slot @@ -1162,7 +1163,7 @@ Other limits and gaps: - **Platforms.** The memory limit needs `RLIMIT_DATA`, which only Linux enforces. On other server platforms, such as macOS, git runs without a memory cap, and the concurrency, time, output and file-size limits still apply. No endpoint refuses a request because the memory cap is unavailable. For deployments where untrusted users can push, run the server on Linux. See [ADR-49](../adr/049-read-side-git-children-run-under-one-per-request-budget.md). - `archive` streams its response. An error after the response has started (for example, the time limit, or a delta-compressed file whose base object does not fit in memory) closes the connection, so the client sees a truncated, invalid gzip stream instead of a status code. -- Not covered by these limits: hydrating the cache repository before the git reads (serialized per repository), git clone and fetch over the git protocol (`upload-pack`, which has its own request-size limits), and the write endpoints. +- Not covered by these limits: hydrating the cache repository before the git reads (serialized per repository), git clone and fetch over the git protocol (`upload-pack`, which has its own request-size limits), and the write endpoints. The exception is the history walk of `POST /repos/branches/create`, `POST /repos/tags` and a `POST /repos/merge` whose `expected_source_sha` is not the source tip, which runs under these limits ([which commit the base and the tag target can name](#which-commit-the-base-and-the-tag-target-can-name)). ## Status-code contract (what clients key on) From e6fed63bba6190dee5e8a60890260534d3de8726 Mon Sep 17 00:00:00 2001 From: Thomas Kosiewski Date: Sat, 21 Nov 2026 10:00:30 +0000 Subject: [PATCH 3/3] docs(api): name the limits that the write routes' history walk runs under Verifier round 2 (CLEAN, one low finding): the walk runs under the concurrency, time and memory limits, not every limit of the table, and it frees its slot when the walk ends. Also use the section's own name for its link and say that branches, branch, notes/refs and repo run no git. Change-Id: Ide939952cbfc1bfdbf75baa57d0f329eba8bc49d Signed-off-by: Thomas Kosiewski --- docs/explanation/wire-compatibility.md | 2 +- docs/reference/http-api.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/explanation/wire-compatibility.md b/docs/explanation/wire-compatibility.md index e90af42c..3f37b0d7 100644 --- a/docs/explanation/wire-compatibility.md +++ b/docs/explanation/wire-compatibility.md @@ -242,7 +242,7 @@ the [archived phase notes](../archive/phases/)): | Implicit push forwarding: in upstream's GitHub App mode every `git push` to the default remote is proxied straight to GitHub, always on, with no REST trigger ([integrations guide](../upstream/guides/integrations.md)). Since spec `412b90c3` (2026-11-02), the REST writes (`commit-pack`, `diff-commit`, `reset-commits`, `restore-commit`, `merge`, and branch and tag create and delete) on a repository with a GitHub upstream also push to GitHub before they answer. They answer `412` when the write cannot reach GitHub or GitHub refuses it: the commit writes (`commit-pack`, `diff-commit`, `reset-commits`, `restore-commit`) with `result.status` `failed`, the others with the code `github_app_not_configured`, `github_repository_inaccessible` or `precondition_failed`. They answer `502` when GitHub fails or cannot be reached, and then the write can already be applied | Explicit `POST /repos/push-upstream` (non-force by default, `force: true` opt-in) plus an opt-in per-repo `base_repo.forward_pushes` flag (default **off**) that schedules a forward after every won local push and mirrors back on success. A rejected non-fast-forward fails the run with per-ref reasons instead of rewriting upstream history. Ref deletions are not propagated in either direction (the inbound mirror deliberately avoids `--mirror` for the same reason). With `forward_pushes` off, a local push still triggers the inbound mirror, which force-resets local refs to upstream state ("upstream wins"). REST writes change only local refs and answer without contacting GitHub. A won REST write pokes the same sync scheduler as a won push, with the same caller gates: on a `forward_pushes` repo it schedules the same forward, unless the token lacks `git:read` or carries a ref-policy op. Then the write stays local until the next authorized trigger. A scheduled forward runs in the background, and the answer does not wait for it. No REST write returns a `412` or `502` for a GitHub failure | Recorded deviation ([ADR-44](../adr/044-outbound-push-forwarding-rides-a-separate-push-claim-lane.md), issue #90): implicit always-on forwarding invites silent divergence and needs GitHub App infrastructure this backend does not have. The explicit trigger + opt-in flag keep the direction observable (`repo.push_upstream.*` events) and non-destructive by default. Upstream's REST write-through runs through its GitHub App, and open.storage rejects `access: "app"` with `400` ([#654](https://github.com/coder/openstorage/issues/654)) | | `repo.sync.started`, `repo.sync.succeeded` and `repo.sync.failed` (spec `bed02bed`, 2026-11-19): upstream retries a sync that fails with a transient error for up to 2 hours. `repo.sync.failed` goes out at the first failure of such a series and for an error that a retry cannot fix. After a failure, `repo.sync.started` goes out only when a later run of the series succeeds, right before `repo.sync.succeeded`. The spec also allows events per run: "During the move to the new sync engine, some repositories get this event once per run, when the retries of the run end" (`repo.sync.failed`), and some "send this event at the start of every run, also after a failure" (`repo.sync.started`) | Every inbound run sends `repo.sync.started` when it starts, after a failed run too, and `repo.sync.succeeded` or `repo.sync.failed` when it ends. open.storage does not retry a failed inbound run, so each failed run sends its own `repo.sync.failed`. A cancelled run, such as one that a detach or a server shutdown stops, sends no end event. The events of one run have the same `started_at`, and `repo.sync.started` has a `run_count` 1 lower than the end event, as upstream documents. Each event is its own delivery with its own retries, so the events of a run can arrive out of order. A receiver should read each `repo.sync.failed` as the end of one failed run, not as the start of a retry series, and should wait for `repo.sync.succeeded` before it treats a failing repository as recovered, because a run that starts after a failure can still fail. It should order the events of a run by `started_at` and `run_count`, not by arrival, and should not wait for an end event after every `repo.sync.started` | Inbound sync here has no transient-retry series, so per-run events are the form that the spec allows during upstream's move. Desk decision ([#908](https://github.com/coder/openstorage/issues/908)): record the difference. Building a retry series is out of scope | | `GET .../file` and `POST .../archive`: no documented file-size cap and no `422`; `archive` has only the caller-chosen `max_blob_size` | `file` and `archive` answer 422 for a file over 100 MiB (`archive` can skip such files with `max_blob_size`), before any response byte. The other read-side git [resource limits](../reference/http-api.md#resource-limits-on-git-reads) apply too. After an `archive` response has started, a limit closes the connection instead of returning a status | Hardening ([ADR-49](../adr/049-read-side-git-children-run-under-one-per-request-budget.md)): the limits bound server memory, temporary disk and delivery time for data that anyone who can push controls. Fetch larger files with git | -| No operation lists a `422` response. The spec's error-code list names the generic code `unprocessable_entity` (422), and `POST .../branches/create`, `POST .../tags` and `POST .../merge` list 200, 400, 401, 403, 404, 409, 412, 429, 500, 502 and 503 | On Linux, a git subprocess that needs more heap than its cap (256 MiB, 32 MiB for single-object reads) makes the request answer `422` `unprocessable_entity`, "history or object too large for the server's git memory limit". Three groups of routes can answer it, on both path styles. The first is every `git:read` route that runs git: `GET` and `HEAD .../file`, `files`, `files/metadata`, `branches/diff`, `commits`, `commit`, `diff`, `GET .../tags`, `tag`, `blame`, `notes`, `merge/preview`, `grep` and `archive`. The second is `POST .../branches/create` and `POST .../tags`, which since [#929](https://github.com/coder/openstorage/pull/929) walk the history of the commit they name under the same caps ([which commit a base can name](../reference/http-api.md#which-commit-the-base-and-the-tag-target-can-name)). The third is `POST .../merge` with an `expected_source_sha` that is not the source tip, which walks that commit the same way. `GET .../branches`, `branch`, `notes/refs` and `repo` run no git under a cap. An `archive` whose response has started closes the connection instead (row above) | Hardening ([ADR-49](../adr/049-read-side-git-children-run-under-one-per-request-budget.md)): anyone who can push shapes the history and objects that git reads, and the caps bound server memory ([resource limits](../reference/http-api.md#resource-limits-on-git-reads)). The same request needs the same memory on a retry, so the answer is a `4xx`, not the `503` of a busy server. The create and tag walks need the most memory for a long history that no ref reaches ([which commit a base can name](../reference/http-api.md#which-commit-the-base-and-the-tag-target-can-name)) | +| No operation lists a `422` response. The spec's error-code list names the generic code `unprocessable_entity` (422), and `POST .../branches/create`, `POST .../tags` and `POST .../merge` list 200, 400, 401, 403, 404, 409, 412, 429, 500, 502 and 503 | On Linux, a git subprocess that needs more heap than its cap (256 MiB, 32 MiB for single-object reads) makes the request answer `422` `unprocessable_entity`, "history or object too large for the server's git memory limit". Three groups of routes can answer it, on both path styles. The first is every `git:read` route that runs git: `GET` and `HEAD .../file`, `files`, `files/metadata`, `branches/diff`, `commits`, `commit`, `diff`, `GET .../tags`, `tag`, `blame`, `notes`, `merge/preview`, `grep` and `archive`. The second is `POST .../branches/create` and `POST .../tags`, which since [#929](https://github.com/coder/openstorage/pull/929) walk the history of the commit they name under the same caps ([which commit the base and the tag target can name](../reference/http-api.md#which-commit-the-base-and-the-tag-target-can-name)). The third is `POST .../merge` with an `expected_source_sha` that is not the source tip, which walks that commit the same way. `GET .../branches`, `branch`, `notes/refs` and `repo` run no git. An `archive` whose response has started closes the connection instead (row above) | Hardening ([ADR-49](../adr/049-read-side-git-children-run-under-one-per-request-budget.md)): anyone who can push shapes the history and objects that git reads, and the caps bound server memory ([resource limits](../reference/http-api.md#resource-limits-on-git-reads)). The same request needs the same memory on a retry, so the answer is a `4xx`, not the `503` of a busy server. The create and tag walks need the most memory for a long history that no ref reaches ([which commit the base and the tag target can name](../reference/http-api.md#which-commit-the-base-and-the-tag-target-can-name)) | | Every `503` response can carry an optional `Retry-After` header, the minimum delay in seconds before a retry (spec 2026-10-21) | Two 503s leave `Retry-After` out: a git read that exceeds its [time budget](../reference/http-api.md#resource-limits-on-git-reads), and a sync create whose upstream link was removed before its first sync was scheduled ([pending creates](../reference/http-api.md#repository-lifecycle-repowrite--orgread)). The 503 for exhausted git concurrency and the 503s for a create that is not finished carry `Retry-After` | A retry of either request fails the same way, so a `Retry-After` would invite a useless retry. The same page needs the same git time ([ADR-49](../adr/049-read-side-git-children-run-under-one-per-request-budget.md)). The pending create stays pending until `DELETE /repos/delete` clears the name ([#388](https://github.com/coder/openstorage/issues/388)) | | A token that fails verification (malformed, bad signature, expired, unknown issuer): upstream's live docs and servers answer `403` `forbidden` (`Invalid or expired token`) on the REST API, and `403` on the Git and LFS transports too (checked 2026-11-04). The vendored spec documents no status for it | The REST API answers `403` `forbidden` (`Invalid or expired token`), as upstream does ([#664](https://github.com/coder/openstorage/issues/664)). The Git and LFS transports answer `401` with `WWW-Authenticate: Basic`, as for a missing token ([authentication](../reference/authentication.md#failure-mapping)) | Git asks for credentials only after a `401`, and only a `401` makes it erase a stored credential. After a `403`, git fails and keeps the expired token in the credential helper, so every later command fails the same way until the user removes the token | | A `crit` member in the JWT header: the vendored docs and spec say nothing about it. They list `alg` and `typ` as the header ([authentication guide](../upstream/getting-started/authentication.md)) | A token whose header has a `crit` member of any value fails verification, even when the signature is valid. The status is the one for any token that fails verification (the row above) | RFC 7515 §4.1.11: a recipient that does not understand a listed extension must refuse the token. open.storage understands none, so it refuses any `crit` | diff --git a/docs/reference/http-api.md b/docs/reference/http-api.md index 70bbb6a1..df0d9238 100644 --- a/docs/reference/http-api.md +++ b/docs/reference/http-api.md @@ -1163,7 +1163,7 @@ Other limits and gaps: - **Platforms.** The memory limit needs `RLIMIT_DATA`, which only Linux enforces. On other server platforms, such as macOS, git runs without a memory cap, and the concurrency, time, output and file-size limits still apply. No endpoint refuses a request because the memory cap is unavailable. For deployments where untrusted users can push, run the server on Linux. See [ADR-49](../adr/049-read-side-git-children-run-under-one-per-request-budget.md). - `archive` streams its response. An error after the response has started (for example, the time limit, or a delta-compressed file whose base object does not fit in memory) closes the connection, so the client sees a truncated, invalid gzip stream instead of a status code. -- Not covered by these limits: hydrating the cache repository before the git reads (serialized per repository), git clone and fetch over the git protocol (`upload-pack`, which has its own request-size limits), and the write endpoints. The exception is the history walk of `POST /repos/branches/create`, `POST /repos/tags` and a `POST /repos/merge` whose `expected_source_sha` is not the source tip, which runs under these limits ([which commit the base and the tag target can name](#which-commit-the-base-and-the-tag-target-can-name)). +- Not covered by these limits: hydrating the cache repository before the git reads (serialized per repository), git clone and fetch over the git protocol (`upload-pack`, which has its own request-size limits), and the write endpoints. The exception is the history walk of `POST /repos/branches/create`, `POST /repos/tags` and a `POST /repos/merge` whose `expected_source_sha` is not the source tip, which runs under the concurrency, time and memory limits above and frees its slot when the walk ends ([which commit the base and the tag target can name](#which-commit-the-base-and-the-tag-target-can-name)). ## Status-code contract (what clients key on)