docs: concurrency, read consistency, Long/BigInt, and resource status codes#534
Conversation
…e status codes Four clarifications surfaced by the QA-explorer campaign: - Resource API: a 'Concurrency and Safe Concurrent Writes' section — atomic deltas are the only concurrency-safe write primitive; compare-and-set/ read-then-write patterns are not re-validated at commit. - Database API: a 'Read Consistency' section — per-request snapshot scope, and why a cross-request search-then-fetch can disagree (two snapshots, not a bug). - Schema: clarify that Long is bounded by 2^53 (not true 64-bit); use BigInt (sent as an actual bigint) for larger integers. - Resource API: a 'Returning Errors and Status Codes' section — which throw/ return shapes set the HTTP status and the common footguns that do not. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds documentation sections regarding read consistency, large integer types (Long vs BigInt), concurrency/safe concurrent writes, and returning errors/status codes. The review feedback points out two technical inaccuracies in the documentation: first, the term 'read-your-own-write consistency' is incorrectly used to describe a read-only sequence and should be changed to 'repeatable read consistency'; second, the JavaScript safe integer limit is incorrectly stated as 2^53 instead of 2^53 - 1.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-534 This preview will update automatically when you push new commits. |
| ```javascript | ||
| // throw an error with an explicit statusCode | ||
| const err = new Error('Not found'); | ||
| err.statusCode = 404; | ||
| throw err; | ||
|
|
||
| // return a Response | ||
| return new Response(body, { status: 201 }); | ||
|
|
||
| // set it on the context | ||
| this.getContext().response.status = 202; | ||
| ``` |
There was a problem hiding this comment.
nit: I prefer that all code blocks are actually "valid" javascript, even if incomplete. I think this can sometimes be confusing when you have what is three separate implementations all in what seems as a single block. Especially with throw/return where you really shouldn't have anything after it (since its unreachable). Also, this is somewhat vague on how it applies with promises. Like "returning a Response" is actually only valid if the user is implementing an async function. Otherwise, I think the more correct terminology is "resolve a Response".
Anyways, its honestly fine I'm being a little pedantic here I think.
There was a problem hiding this comment.
Not pedantic at all — fixed in da78fdd. Split the examples into individually valid async method blocks (so nothing sits after a throw/return), which also makes the resolve-vs-return point implicit since each is an async method. The section also now reflects harper#1501, where throw {status} and a thrown Response become supported (the thrown Response rolls back the transaction). Leaving this thread for you to close if it looks right.
— KrAIs (Claude Opus 4.8), on behalf of Kris
… wording
- Returning Errors and Status Codes: `throw {status}` and a thrown `Response`
are now honored (paired with HarperFast/harper#1501), so document them as
working patterns instead of footguns; note that a thrown Response rolls back
the transaction (throw vs. return). Split the examples into individually
valid async-method blocks (review nit). Keep the `return {status}`-without-
`headers` caveat.
- Long: bound is |value| < 2^53 (MAX_SAFE_INTEGER 9,007,199,254,740,991), not <=.
- Read consistency: "repeatable-read" is the accurate term for the query/fetch
snapshot scenario.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-534 This preview will update automatically when you push new commits. |
🧹 Preview CleanupThe preview deployment for this PR has been removed. |
3 participants
Summary
Four documentation clarifications surfaced by the QA-explorer exploratory campaign. Each is a defensible-but-surprising behavior where the gap was documentation, not correctness — these write down the contract so developers don't have to discover it the hard way.
reference/resources/resource-api.mdaddTo/subtractFrom) are the only concurrency-safe write primitive; compare-and-set / read-then-write patterns (ifVersion, create-only,If-Match, read-decide-write) are not re-validated at commit, so concurrent writers can both pass. Covers theaddTono-return / no-floor limitations and the cluster replication-window caveat.reference/database/api.mdtransaction()for read-your-own-write.LongvsBigIntreference/database/schema.mdLongis bounded by 2^53 despite the name (not true 64-bit); useBigInt(sent as an actual bigint via CBOR/MessagePack, not a JSON number) for larger integers, including@indexedrange queries.reference/resources/resource-api.mderror.statusCode,return new Response(...),context.response.status) and the footguns that silently don't (throw {status}, a thrownResponse,return {status}withoutheaders).No behavior changes — documentation only. Diff is +61 lines across three files.
🤖 Generated with Claude Code