chore(review): 1106 캐시·업로드 조치 브랜치를 합친다
This commit is contained in:
@@ -1016,6 +1016,16 @@ rollback 목록 없이 덮어쓴다. pointer 읽기의 일시 오류는 activati
|
||||
cleanup이 무엇을 지울지 볼 수 있다. 일시 오류에서는 inspect도 실패한다
|
||||
(2026-11-03 02-05).
|
||||
|
||||
pointer entry는 있는데 저장된 본문이 다시 쓰기 전까지 계속 읽히지 않으면(blob
|
||||
손실 등) 일시 오류와 구별되지 않는다. 조회, activation, cleanup, inspect가 모두
|
||||
같은 실패(`UNAVAILABLE`/`RETRY` 등)를 계속 돌려준다. pointer를 쓰는 곳은
|
||||
activation 하나라서 기다려도 돌아오지 않는다. 이때 운영자는
|
||||
`activateRelease(releaseRegistryId, manifestDigestHex, { replaceUnreadablePointer: true })`로
|
||||
검증된 후보를 활성화한다. 손상 pointer와 같이 rollback 목록 없이 덮어쓴다. 그 뒤
|
||||
cleanup은 새 활성 release 밖의 owned release cache를 모두 지운다. 옵션이 없으면
|
||||
지금처럼 멈춘다. 일시 오류 한 번으로 rollback 목록을 잃지 않기 위해서다
|
||||
(1106/02-01).
|
||||
|
||||
현재 `cleanupOwned()`와 `inspect()`는 위 ownership/integrity 경계를 지키지만
|
||||
cache count에 대한 cursor, per-invocation max count와 deadline은 제공하지 않는다.
|
||||
따라서 cache 수에 비례한 unbounded maintenance를 production boot path에
|
||||
|
||||
@@ -325,7 +325,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기
|
||||
- 멱등성 응답(`IDEMPOTENT_*`, `IDEMPOTENCY_*`)과 V3 표에 있는 web 공통 응답은 V3 실행기와 같은 표(`backend-envelope.ts`, 4절)로 판정한다. 400 `IDEMPOTENCY_KEY_INVALID`·422 `IDEMPOTENT_REQUEST_MISMATCH`는 `NOT_APPLIED`, 409 `IDEMPOTENT_IN_FLIGHT`·503 `IDEMPOTENCY_UNAVAILABLE`·503 `IDEMPOTENCY_COMPLETION_UNKNOWN`·500 `IDEMPOTENCY_RECOVERY_REQUIRED`는 `MAYBE_APPLIED`다.
|
||||
- `APPLIED_CONFIRMED`: 서버는 만들었다고 답했지만 응답을 읽지 못했다. 다시 올리지 않는다.
|
||||
- `code`는 백엔드 code 그대로다(`FILE_TOO_LARGE`, `UNSUPPORTED_MEDIA_TYPE`, `MALWARE_DETECTED` …). 백엔드가 code를 주지 않는 거절은 client가 이름을 붙인다(`FILE_REJECTED`, `FILE_EMPTY`, `FILE_NOT_READABLE`). 화면 문구는 기능이 code로 고른다.
|
||||
- 실패 Envelope의 `meta.traceId`는 실패의 `traceId`로 온다. V3 실행기와 같다. 지원 담당이 서버 로그에서 그 요청을 찾을 때 쓴다.
|
||||
- 실패 Envelope의 `meta.traceId`는 실패의 `traceId`로 온다. V3 실행기와 같다. 지원 담당이 서버 로그에서 그 요청을 찾을 때 쓴다. 202 `REJECTED`의 `FILE_REJECTED`도 성공 Envelope의 `meta.traceId`를 싣는다. 이 응답에는 거절 이유가 없다. 짝 백엔드는 검증기 code를 파일 레코드에만 적는다. 그래서 화면은 이유별 문구를 고를 수 없다.
|
||||
- client는 스스로 다시 보내지 않는다. `retryable: true`이고 `retryAfterMs`가 있으면 그만큼 기다린 뒤 기능이 다시 부른다. 서버가 상한(`maxRetryAfterMs`, 기본 30초)보다 길게 기다리라고 하면 `retryable: false`다.
|
||||
- `MAYBE_APPLIED`는 언제나 `retryable: false`다. 백엔드가 Envelope에 `retryable: true`와 `Retry-After`를 붙여도(504 `TRANSFER_TIMEOUT`) 기능이 자동으로 다시 부르지 않는다. 아래 주의대로 먼저 확인한다.
|
||||
|
||||
|
||||
@@ -27,6 +27,12 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle
|
||||
않는다. 두 operation은 Cache Storage와 mutation lock만 요구하고 실패 시
|
||||
recovery는 `RETRY`다. `stageRelease`만 fetcher를 요구하며 recovery는
|
||||
`ONLINE_ONLY`다.
|
||||
- active pointer 본문을 계속 읽지 못하면 조회, `activateRelease`,
|
||||
`cleanupOwned`, `inspect`가 모두 같은 실패를 계속 돌려준다. 다시 시도해도
|
||||
돌아오지 않는다. pointer를 쓰는 곳은 activation 하나다. 이때
|
||||
`activateRelease(id, digest, { replaceUnreadablePointer: true })`로 검증된
|
||||
release를 활성화한다. rollback 목록은 잃고, 다음 cleanup이 다른 owned release
|
||||
cache를 지운다. 옵션 없는 activation은 일시 오류에서 멈춘다(1106/02-01).
|
||||
- variant를 사용하는 policy(`allowedVaryHeaderNames` 비어 있지 않음)는 반드시
|
||||
`allowedResponseHeaderNames`에 `vary`를 포함해야 한다. 아니면 composition이
|
||||
`TypeError`로 즉시 실패한다. 저장된 variant가 같은 key로 충돌하는 상태를 만들지
|
||||
|
||||
@@ -719,9 +719,12 @@ export function createPublicResponseCacheAdapter(
|
||||
// under this policy) is replaced by this verified candidate with
|
||||
// an empty rollback list, rather than blocking every later
|
||||
// deployment. A transient read failure still stops activation.
|
||||
// 1106/02-01. Unless the caller asks to replace it: a body that
|
||||
// stays unreadable fails the same way, and only this writes it.
|
||||
if (
|
||||
!previousPointer.ok &&
|
||||
previousPointer.error.code !== "CORRUPT_DATA"
|
||||
previousPointer.error.code !== "CORRUPT_DATA" &&
|
||||
options.replaceUnreadablePointer !== true
|
||||
) {
|
||||
return rebaseFailure(
|
||||
previousPointer.error,
|
||||
|
||||
@@ -93,13 +93,23 @@ const ENVELOPE_INVALID: EnvelopeRead<never> = Object.freeze({ ok: false });
|
||||
/**
|
||||
* The success `data`. A missing key is the null the backend dropped.
|
||||
* 1103/03-02. A page list's `meta.page` comes with it.
|
||||
* 1106/01-01. And the backend's `meta.traceId`, when it sent one, as
|
||||
* `readFailureEnvelope` gives it, for a client that turns a well-formed
|
||||
* answer into a failure (Fileserver's 202 `REJECTED`).
|
||||
*/
|
||||
export function readSuccessEnvelope(
|
||||
value: unknown,
|
||||
): Readonly<{ ok: true; value: unknown; page?: EnvelopePage }> | Readonly<{ ok: false }> {
|
||||
):
|
||||
| Readonly<{
|
||||
ok: true;
|
||||
value: unknown;
|
||||
page?: EnvelopePage;
|
||||
traceId?: string;
|
||||
}>
|
||||
| Readonly<{ ok: false }> {
|
||||
const parsed = successEnvelopeSchema.safeParse(value);
|
||||
if (!parsed.success) return ENVELOPE_INVALID;
|
||||
const page = parsed.data.meta.page;
|
||||
const { page, traceId } = parsed.data.meta;
|
||||
return Object.freeze({
|
||||
ok: true as const,
|
||||
value: parsed.data.data,
|
||||
@@ -113,6 +123,7 @@ export function readSuccessEnvelope(
|
||||
...(typeof page.sort === "string" ? { sort: page.sort } : {}),
|
||||
}),
|
||||
}),
|
||||
...(traceId === undefined ? {} : { traceId }),
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
@@ -682,9 +682,15 @@ async function readAnswer(
|
||||
// 1105/01-01. The file is the user's to replace, as with a 413, 415 or
|
||||
// 422 refusal. The backend keeps the record unpublished and schedules
|
||||
// its bytes for removal, so nothing usable was stored.
|
||||
// 1106/01-01. The server answered, so the failure carries its
|
||||
// `meta.traceId` as an Envelope failure does (1105/01-03). The answer
|
||||
// names no reason: the backend keeps the verifier's code on its record.
|
||||
return failure("VALIDATION_REJECTED", "FILE_REJECTED", {
|
||||
httpStatus: status,
|
||||
effect: "NOT_APPLIED",
|
||||
...(envelope.traceId === undefined
|
||||
? {}
|
||||
: { traceId: envelope.traceId }),
|
||||
});
|
||||
}
|
||||
return Object.freeze({
|
||||
@@ -790,6 +796,7 @@ function failure(
|
||||
details: Readonly<{
|
||||
effect: FailureEffectCertainty;
|
||||
httpStatus?: number;
|
||||
traceId?: string;
|
||||
}>,
|
||||
): Result<never, AppFailure> {
|
||||
return Object.freeze({
|
||||
|
||||
@@ -45,7 +45,9 @@ export type PublicCacheInspection = Readonly<{
|
||||
* no longer accepts: lookup and cleanup stop on it and the next verified
|
||||
* activation replaces it with an empty rollback list. The candidates are
|
||||
* still listed so the operator can see what that activation and the
|
||||
* cleanup after it will keep. A transient pointer read is a failure.
|
||||
* cleanup after it will keep. A transient pointer read is a failure. One
|
||||
* that keeps failing is the case for `replaceUnreadablePointer` on
|
||||
* `activateRelease` (1106/02-01).
|
||||
*/
|
||||
activePointer: "NONE" | "READABLE" | "UNREADABLE";
|
||||
/** `null` unless `activePointer` is `READABLE`. */
|
||||
@@ -94,10 +96,23 @@ export interface PublicResponseCacheAdminPort {
|
||||
manifest: PublicCacheReleaseManifest,
|
||||
options?: Readonly<{ signal?: AbortSignal }>,
|
||||
): Promise<BrowserDataResult<PublicCacheReleaseSummary>>;
|
||||
/**
|
||||
* 1106/02-01. A pointer read that fails other than as damage stops the
|
||||
* activation, so one bad read does not lose the rollback list. A pointer
|
||||
* body that stays unreadable fails the same way every time, and lookup,
|
||||
* cleanup and inspect stop on it too; only an activation writes the
|
||||
* pointer. `replaceUnreadablePointer: true` is the caller's way back: this
|
||||
* activation then replaces a pointer it cannot read, as it always replaces
|
||||
* a damaged one, with an empty rollback list, and the next cleanup deletes
|
||||
* every other release cache.
|
||||
*/
|
||||
activateRelease(
|
||||
releaseRegistryId: string,
|
||||
manifestDigestHex: string,
|
||||
options?: Readonly<{ signal?: AbortSignal }>,
|
||||
options?: Readonly<{
|
||||
signal?: AbortSignal;
|
||||
replaceUnreadablePointer?: boolean;
|
||||
}>,
|
||||
): Promise<BrowserDataResult<PublicCacheReleaseSummary>>;
|
||||
cleanupOwned(
|
||||
request?: Readonly<{
|
||||
|
||||
@@ -214,6 +214,8 @@ describe("Fileserver multipart upload — success", () => {
|
||||
|
||||
it("reads 202 REJECTED as a refused file, not as a broken answer", async () => {
|
||||
// 1105/01-01. A verifier refused the file for a reason other than malware.
|
||||
// 1106/01-01. The server answered, so its `meta.traceId` comes with the
|
||||
// failure for support to find the upload in the server logs.
|
||||
answer({
|
||||
status: 202,
|
||||
body: successEnvelope(
|
||||
@@ -233,6 +235,7 @@ describe("Fileserver multipart upload — success", () => {
|
||||
retryable: false,
|
||||
action: "none",
|
||||
operationId: "FILESERVER_UPLOAD",
|
||||
traceId: "trace-1",
|
||||
}),
|
||||
});
|
||||
});
|
||||
|
||||
@@ -19,13 +19,14 @@ describe("paired backend Envelope boundary", () => {
|
||||
});
|
||||
|
||||
it("reads data, and a dropped data key as null", () => {
|
||||
// 1106/01-01. With `meta.traceId`, as the failure reader gives it.
|
||||
expect(
|
||||
readSuccessEnvelope({
|
||||
success: true,
|
||||
data: [],
|
||||
meta: { requestId: "request-1", traceId: "trace-1" },
|
||||
}),
|
||||
).toEqual({ ok: true, value: [] });
|
||||
).toEqual({ ok: true, value: [], traceId: "trace-1" });
|
||||
expect(readSuccessEnvelope({ success: true, meta: {} })).toEqual({
|
||||
ok: true,
|
||||
value: null,
|
||||
|
||||
@@ -50,7 +50,12 @@ describe("accessibility e2e API answers", () => {
|
||||
expect(answer.kind).toBe("empty-list");
|
||||
if (answer.kind !== "empty-list") return;
|
||||
// What the executor reads out of the frame is what the operation accepts.
|
||||
expect(readSuccessEnvelope(answer.body)).toEqual({ ok: true, value: [] });
|
||||
// 1106/01-01. The reader also gives the scenario meta's `traceId`.
|
||||
expect(readSuccessEnvelope(answer.body)).toEqual({
|
||||
ok: true,
|
||||
value: [],
|
||||
traceId: "0af7651916cd43dd8448eb211c80319c",
|
||||
});
|
||||
expect(LIST!.contract.outputValidator.safeParse([]).success).toBe(true);
|
||||
});
|
||||
|
||||
|
||||
@@ -970,4 +970,91 @@ describe("public cache pointer after a policy change or damage (0929/02-01)", ()
|
||||
await adapter.responses.matchActiveExact({ absoluteUrl: assetUrl("r1") }),
|
||||
).toMatchObject({ ok: true, value: expect.anything() });
|
||||
});
|
||||
|
||||
// 1106/02-01 (review experiment 02-R1 X3). The pointer entry is there, but
|
||||
// its stored body fails to read until something writes it again (a lost
|
||||
// blob). Without the option that looks like the transient failure above and
|
||||
// everything stops; only an activation writes the pointer.
|
||||
it("replaces a pointer whose body stays unreadable when the activation asks to (1106/02-01)", async () => {
|
||||
const cacheStorage = new MemoryCacheStorage();
|
||||
const policy = policyRetaining(1);
|
||||
const adapter = adapterFor(cacheStorage, policy);
|
||||
expect(await deploy(adapter, "r1", policy)).toMatchObject({ ok: true });
|
||||
const control = cacheStorage.caches.get(controlCacheName(policy))!;
|
||||
const pointerUrl = activePointerRequest(policy).url;
|
||||
const pointer = { unreadable: true, rewrites: 0 };
|
||||
const realMatch = control.match.bind(control);
|
||||
const realPut = control.put.bind(control);
|
||||
const urlOf = (request: RequestInfo | URL) =>
|
||||
request instanceof Request ? request.url : new URL(String(request)).href;
|
||||
control.put = async (request, response) => {
|
||||
if (urlOf(request) === pointerUrl) {
|
||||
pointer.unreadable = false;
|
||||
pointer.rewrites += 1;
|
||||
}
|
||||
await realPut(request, response);
|
||||
};
|
||||
control.match = async (request) => {
|
||||
const stored = await realMatch(request);
|
||||
if (!stored || urlOf(request) !== pointerUrl || !pointer.unreadable) {
|
||||
return stored;
|
||||
}
|
||||
return new Response(
|
||||
new ReadableStream<Uint8Array>({
|
||||
pull(controller) {
|
||||
controller.error(new TypeError("blob missing"));
|
||||
},
|
||||
}),
|
||||
{ headers: stored.headers },
|
||||
);
|
||||
};
|
||||
const next = await manifestOf("r2", policy);
|
||||
const activateNext = (
|
||||
options?: Readonly<{ replaceUnreadablePointer?: boolean }>,
|
||||
) =>
|
||||
adapter.admin.activateRelease(
|
||||
next.releaseRegistryId,
|
||||
next.manifestDigestHex,
|
||||
options,
|
||||
);
|
||||
const unavailable = (operation: string) => ({
|
||||
ok: false,
|
||||
error: { code: "UNAVAILABLE", operation, recovery: "RETRY" },
|
||||
});
|
||||
|
||||
// Staging does not read the pointer; everything else stops on it.
|
||||
expect(await adapter.admin.stageRelease(next)).toMatchObject({ ok: true });
|
||||
expect(
|
||||
await adapter.responses.matchActiveExact({ absoluteUrl: assetUrl("r1") }),
|
||||
).toMatchObject(unavailable("CACHE_LOOKUP"));
|
||||
expect(await activateNext()).toMatchObject(unavailable("CACHE_ACTIVATE"));
|
||||
expect(await adapter.admin.cleanupOwned()).toMatchObject(
|
||||
unavailable("CACHE_DELETE"),
|
||||
);
|
||||
expect(await adapter.admin.inspect()).toMatchObject(
|
||||
unavailable("CACHE_LOOKUP"),
|
||||
);
|
||||
expect(await activateNext()).toMatchObject(unavailable("CACHE_ACTIVATE"));
|
||||
expect(pointer).toEqual({ unreadable: true, rewrites: 0 });
|
||||
|
||||
// The way back: this activation replaces the pointer it cannot read.
|
||||
expect(
|
||||
await activateNext({ replaceUnreadablePointer: true }),
|
||||
).toMatchObject({ ok: true, value: { releaseRegistryId: "r2" } });
|
||||
expect(pointer).toEqual({ unreadable: false, rewrites: 1 });
|
||||
expect(
|
||||
await adapter.responses.matchActiveExact({ absoluteUrl: assetUrl("r2") }),
|
||||
).toMatchObject({ ok: true, value: expect.anything() });
|
||||
expect(await adapter.admin.inspect()).toMatchObject({
|
||||
ok: true,
|
||||
value: { activePointer: "READABLE", activeReleaseRegistryId: "r2" },
|
||||
});
|
||||
// The rollback list went with the old pointer, so cleanup drops r1.
|
||||
expect(await adapter.admin.cleanupOwned()).toMatchObject({
|
||||
ok: true,
|
||||
value: { deletedOwnedCaches: 1, retainedOwnedCaches: 2 },
|
||||
});
|
||||
// A later activation without the option works as before.
|
||||
expect(await deploy(adapter, "r3", policy)).toMatchObject({ ok: true });
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user