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:
co-authored by
Claude Opus 5.5
parent
9733ea8eaa
commit
e872bfa27d
@@ -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>>;
|
||||
|
||||
@@ -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],
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user