Skip to content
Open
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
1 change: 1 addition & 0 deletions docs/explanation/wire-compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -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". 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` |
Expand Down
9 changes: 5 additions & 4 deletions docs/reference/http-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 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)).

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Limit the cap claim to the closure check

When branches/create performs a guarded move or merge receives an off-tip expected_source_sha, an ancestry walk runs before the capped registered-pack closure check: wrefIsAncestor uses plain wrefGit, while wmSourceContains uses wcScratch.git with no gitread.Budget on write requests. Those walks therefore have none of the stated concurrency, time, or memory limits and can exhaust resources or return 500 before the documented 422. Name the RegisteredClosure validation specifically instead of claiming that the endpoint's history walk is covered.

Useful? React with 👍 / 👎.


## Status-code contract (what clients key on)

Expand Down