Skip to content

docs(wire-compat): record the git heap-cap 422 on branches/create, tags and the git:read routes - #931

Open
ThomasK33 wants to merge 3 commits into
mainfrom
docs-wirecompat-heapcap-422
Open

ThomasK33 wants to merge 3 commits into
mainfrom
docs-wirecompat-heapcap-422

Conversation

@ThomasK33

@ThomasK33 ThomasK33 commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

Why

Since #929, POST /repos/branches/create and POST /repos/tags walk
the history of the commit they name under the git heap cap and answer
422 when the walk needs more memory. The upstream spec lists 422 on
no operation, and the deviation table in
docs/explanation/wire-compatibility.md recorded a 422 only for the
file size limit of file and archive. Docs only.

What changed

  • A new deviation row lists, on both path styles, every route that can
    answer the heap cap's 422: each git:read route that runs git
    (file GET and HEAD, files, files/metadata, branches/diff,
    commits, commit, diff, GET tags, tag, blame, notes,
    merge/preview, grep, archive), POST .../branches/create,
    POST .../tags, and POST .../merge with an expected_source_sha
    that is not the source tip (fix(api): refuse a branch or tag at a commit whose history the packs cannot walk #929 walks that pin too).
  • docs/reference/http-api.md: "100,000 unreferenced commits need more
    than the heap cap" was false. With one new blob and three new trees
    per commit, 100,000 fit and 500,000 did not. The "Not covered by
    these limits" bullet now names the write routes' walk as the
    exception.

Verification

  • Code: writeGitLimitErr (internal/api/git_budget.go) maps
    gitread.ErrMemoryLimit to 422. gitread.Run caps the heap only
    under a request budget, which the git:read middleware and
    wrefWalkBudget (create, tags, merge pin) set.
  • Probe (scratch test, not committed): with every heap-capped git child
    failing, each listed route answered 422 and branches, branch,
    notes/refs and repo answered 200. With only the history walk
    failing, only create, POST tags and the pinned merge answered 422.
  • The fix(api): refuse a branch or tag at a commit whose history the packs cannot walk #929 walk under ulimit -d 262144 (git 2.55): 100,000
    unreferenced commits exit 0, 500,000 exit 128 "Out of memory".
  • Docs gate: check-doc-links.py 0 broken, test_check_doc_links.py OK.

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high

…gs 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 <tk@coder.com>
@ThomasK33

Copy link
Copy Markdown
Member Author

@codex review

@ThomasK33

Copy link
Copy Markdown
Member Author

@codex security review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-21T10:05:13.539531Z e6fed63 Manual request
🔒 Security Review ✅ Completed 2026-11-21T10:03:54.874819Z e6fed63 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

Copy link
Copy Markdown

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: de39824e7a

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Hooray!

Reviewed commit: de39824e7a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

…tion

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 <tk@coder.com>
@ThomasK33

Copy link
Copy Markdown
Member Author

@codex review

@ThomasK33

Copy link
Copy Markdown
Member Author

@codex security review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: fa3eb96fc6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@chatgpt-codex-connector

Copy link
Copy Markdown

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: fa3eb96fc6

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

…nder

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 <tk@coder.com>
@ThomasK33

Copy link
Copy Markdown
Member Author

@codex review

@ThomasK33

Copy link
Copy Markdown
Member Author

@codex security review

@chatgpt-codex-connector

Copy link
Copy Markdown

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: e6fed63bba

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e6fed63bba

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

- **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 👍 / 👎.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant