docs(storage): state that a stream can outlive a replaced OPFS generation (05-14)

Orphan GC counts its grace from when a chunk was written, so a read of an
older generation can lose its chunks once a newer put commits. Refreshing
every dropped chunk would rewrite whole objects, so the port now states the
contract instead: the stream ends NOT_FOUND / REHYDRATE and a reopen reads
the new generation. A test pins that outcome.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 22:59:43 +09:00
co-authored by Claude Opus 5.5
parent 9733ea8eaa
commit e872bfa27d
2 changed files with 59 additions and 0 deletions
@@ -85,6 +85,14 @@ export interface DurableObjectStorePort {
put(
request: PutDurableObjectRequest,
): Promise<BrowserDataResult<DurableObjectDescriptor>>;
/**
* 05-14. `open` checks the manifest; the bytes are read and verified while
* the source streams. A put that replaces the object meanwhile leaves the
* older generation's chunks to orphan GC, whose grace counts from when a
* chunk was written, not from when it lost its last reference. A stream
* that reaches a chunk GC already took ends with `NOT_FOUND` / `REHYDRATE`.
* Nothing is lost: open again to read the generation that replaced it.
*/
open(
request: OpenDurableObjectRequest,
): Promise<BrowserDataResult<OpenedDurableObject>>;
+51
View File
@@ -2454,3 +2454,54 @@ describe("05-10 the object id grammar is the prepared-object grammar", () => {
).toThrow(TypeError);
});
});
describe("05-14 a read that outlives its generation", () => {
it("ends with NOT_FOUND / REHYDRATE once GC took the replaced chunks, and a reopen reads the new generation", async () => {
const { root, tab } = sharedRootTabs();
const store = tab("r");
const put = (bytes: number[], expectedGeneration: number | null) =>
store.objects.put({
objectId: "object_12345678",
expectedGeneration,
mediaType: "application/octet-stream",
source: bytesSource(new Uint8Array(bytes)),
});
expect(await put([1], null)).toMatchObject({ ok: true });
const opened = await store.objects.open({ objectId: "object_12345678" });
if (!opened.ok) throw new Error(opened.error.code);
// Generation 2 replaces it, and its old chunk is past the GC grace.
expect(await put([2], 1)).toMatchObject({ ok: true });
const digest = Array.from(
new Uint8Array(
await globalThis.crypto.subtle.digest("SHA-256", new Uint8Array([1])),
),
(byte) => byte.toString(16).padStart(2, "0"),
).join("");
memoryFileAt(root, chunkFilePath(scopeA, digest)).lastModified = 0;
expect(await store.maintenance.reconcile()).toMatchObject({
ok: true,
value: { deletedOrphanChunks: 1 },
});
const chunks = [];
for await (const chunk of opened.value.source.stream(
new AbortController().signal,
)) {
chunks.push(chunk);
}
expect(chunks).toEqual([
expect.objectContaining({
ok: false,
error: expect.objectContaining({
code: "NOT_FOUND",
recovery: "REHYDRATE",
}),
}),
]);
expect(await openedBytes(store, "object_12345678")).toEqual({
generation: 2,
bytes: [2],
});
});
});