@cloudflare/workers-response-store 1.1.3 → 1.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/binding.d.ts CHANGED
@@ -10,6 +10,24 @@ export type SerializableValue = null | boolean | number | string | SerializableV
10
10
  export type ResponseStorePutOptions = {
11
11
  /** @internal Collapse overlapping framework writes for the same cache key. */
12
12
  coalesce?: boolean;
13
+ /**
14
+ * @internal The revision a stale read returned (`X-Workers-Response-Store-Revision`)
15
+ * that this write refreshes. While another refresh of that revision is published and
16
+ * fresh, and the key hasn't been invalidated or purged since, the write is dropped instead
17
+ * of replacing (and purging) it, and returns
18
+ * `{ backingStoreUpdated: false, edgePurgeAccepted: false }`. A value that isn't a
19
+ * positive integer is ignored.
20
+ */
21
+ replacesRevision?: number;
22
+ /**
23
+ * @internal With `replacesRevision`: tags the caller checks itself when reading (soft
24
+ * tags), and the `getTagExpiration()` of those tags that the stale read saw. Once they
25
+ * have expired since, the write isn't dropped. A malformed value leaves an ordinary write.
26
+ */
27
+ replacesTagExpiration?: {
28
+ tags: string[];
29
+ expiration: number;
30
+ };
13
31
  revalidator?: RevalidatorDescriptor;
14
32
  purgeExisting?: boolean;
15
33
  /**
@@ -67,6 +85,8 @@ type EntryMetadata = {
67
85
  };
68
86
  export type CandidateMetadata = EntryMetadata & {
69
87
  fenceTags: string[];
88
+ /** When the response's generation started (`GENERATED_AT_HEADER`). */
89
+ generatedAt?: number;
70
90
  };
71
91
  export type StoredEntry = EntryMetadata & {
72
92
  keyHash: string;
package/dist/binding.js CHANGED
@@ -75,6 +75,20 @@ const NULL_BODY_STATUSES = /* @__PURE__ */ new Set([
75
75
  304
76
76
  ]);
77
77
  const AGE_BASIS_HEADER = "X-Workers-Response-Store-Age-Basis";
78
+ /**
79
+ * @internal When a response's generation started (ms since epoch), on a put or a
80
+ * revalidator's response. Like Next.js "use cache", the entry is published stale if its
81
+ * tags were invalidated after that, and expired if they were purged, or an `expire` deadline
82
+ * passed, after it. Its freshness and stale-while-revalidate windows also count from then.
83
+ * A value that isn't a positive finite number is ignored, a fractional one is rounded down,
84
+ * and one in the future, e.g. from a skewed clock, counts as when the Store received it. It
85
+ * isn't stored.
86
+ */
87
+ const GENERATED_AT_HEADER = "X-Workers-Response-Store-Generated-At";
88
+ function generatedAtFromResponse(response) {
89
+ const value = Math.floor(Number(response.headers.get(GENERATED_AT_HEADER) ?? void 0));
90
+ return Number.isSafeInteger(value) && value > 0 ? Math.min(value, Date.now()) : void 0;
91
+ }
78
92
  const STORAGE_LAYOUT_VERSION = "r2-v2";
79
93
  const pendingPuts = /* @__PURE__ */ new Map();
80
94
  const pendingR2Reads = /* @__PURE__ */ new Map();
@@ -499,19 +513,20 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
499
513
  if (!body) await storedBody.cancel();
500
514
  return this.createStoredResponse(storedEntry, body, status, createdAt, initialAge, now);
501
515
  }
502
- async storeResponse(metadata, request, response, revalidator, expiryBehavior, reservation, cacheTags = cacheTagsFromResponse(response), expectedR2Etag) {
516
+ async storeResponse(metadata, request, response, revalidator, expiryBehavior, reservation, cacheTags = cacheTagsFromResponse(response), expectedR2Etag, replaces, generatedAt = generatedAtFromResponse(response)) {
503
517
  const cacheKey = reservation ?? await this.deriveCacheKey(request);
504
518
  const write = reservation ?? await this.reserveWrite(metadata, cacheKey, cacheTags);
505
519
  const { keyHash, objectKey: reservationObjectKey, revision } = write;
506
520
  let publication;
521
+ let publishedAt;
507
522
  let body;
508
523
  let policy;
509
524
  try {
510
525
  const now = Date.now();
511
- policy = deriveCachePolicy(response.headers, now);
526
+ policy = deriveCachePolicy(response.headers, now, generatedAt);
512
527
  const responseHeaders = [...response.headers].filter(([name]) => {
513
528
  const lower = name.toLowerCase();
514
- return lower !== "age" && lower !== "cache-tag" && lower !== "cf-cache-status" && lower !== "content-length";
529
+ return lower !== "age" && lower !== "cache-tag" && lower !== "cf-cache-status" && lower !== "content-length" && lower !== GENERATED_AT_HEADER.toLowerCase();
515
530
  });
516
531
  const candidate = {
517
532
  fenceTags: [.../* @__PURE__ */ new Set([...write.fenceTags, ...cacheTags])],
@@ -522,10 +537,12 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
522
537
  swrUntil: policy.swrUntil,
523
538
  revalidator: revalidator ?? null,
524
539
  expiryBehavior,
525
- cacheTags
540
+ cacheTags,
541
+ ...generatedAt !== void 0 ? { generatedAt } : {}
526
542
  };
527
543
  body = response.body ? await response.arrayBuffer() : /* @__PURE__ */ new ArrayBuffer(0);
528
- publication = await metadata.publish(keyHash, revision, candidate, write.claimId, reservationObjectKey);
544
+ publication = await metadata.publish(keyHash, revision, candidate, write.claimId, reservationObjectKey, replaces);
545
+ publishedAt = Date.now();
529
546
  } catch (error) {
530
547
  await this.releaseFailedWrite(metadata, write);
531
548
  throw error;
@@ -563,6 +580,11 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
563
580
  edgePurgeRequired: publication.edgePurgeRequired,
564
581
  published: true,
565
582
  entry,
583
+ ...replaces ? { replacedRevision: replaces.revision } : {},
584
+ ...generatedAt !== void 0 ? { generatedAt } : {},
585
+ publishedAt,
586
+ ...publication.publishedStale ? { publishedStale: true } : {},
587
+ policyFreshUntil: policy.freshUntil,
566
588
  ...stored && entry ? { response: this.createStoredResponse(entry, NULL_BODY_STATUSES.has(response.status) ? null : body, response.status, policy.createdAt, policy.initialAge) } : {}
567
589
  };
568
590
  }
@@ -671,11 +693,22 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
671
693
  return this.getTagMetadata(tags).getTagExpiration(tags);
672
694
  }
673
695
  async put(request, response, options = {}) {
696
+ const generatedAt = generatedAtFromResponse(response);
674
697
  const cacheKey = await this.deriveCacheKey(request);
675
698
  const { keyHash } = cacheKey;
676
699
  const metadata = this.getMetadata(keyHash);
677
700
  const cacheTags = cacheTagsFromResponse(response);
678
701
  const pendingPutKey = `${this.getVersionId()}:${this.shardCount}:${keyHash}:${Boolean(options.purgeExisting)}`;
702
+ const tagExpiration = options.replacesTagExpiration;
703
+ const validTagExpiration = tagExpiration === void 0 || Array.isArray(tagExpiration?.tags) && tagExpiration.tags.every((tag) => typeof tag === "string") && Number.isFinite(tagExpiration.expiration);
704
+ const replacesRevision = Number.isSafeInteger(options.replacesRevision) && options.replacesRevision > 0 && validTagExpiration ? options.replacesRevision : void 0;
705
+ const replaces = replacesRevision === void 0 ? void 0 : {
706
+ revision: replacesRevision,
707
+ ...tagExpiration ? {
708
+ tags: tagExpiration.tags,
709
+ tagExpiration: tagExpiration.expiration
710
+ } : {}
711
+ };
679
712
  let reservation;
680
713
  if (options.coalesce) for (;;) {
681
714
  const pending = pendingPuts.get(pendingPutKey);
@@ -704,6 +737,8 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
704
737
  continue;
705
738
  }
706
739
  if (result?.published && result.entry) {
740
+ if (replaces !== void 0 && (result.entry.activeRevision <= replaces.revision || result.replacedRevision === replaces.revision)) break;
741
+ if ((result.publishedStale || (result.policyFreshUntil ?? Number.POSITIVE_INFINITY) <= Date.now()) && (generatedAt !== void 0 || result.generatedAt !== void 0) && (generatedAt ?? Number.POSITIVE_INFINITY) > (result.generatedAt ?? result.publishedAt ?? Number.POSITIVE_INFINITY)) break;
707
742
  const objectKey = reservation.objectKey;
708
743
  await metadata.finishPendingObjects([objectKey]).catch((error) => this.logCleanupFailure(objectKey, error));
709
744
  response.body?.cancel().catch(() => {});
@@ -716,7 +751,7 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
716
751
  }
717
752
  const write = (async () => {
718
753
  reservation ??= await this.reserveWrite(metadata, cacheKey, cacheTags);
719
- return this.storeResponse(metadata, request, response, options.revalidator, options.expiryBehavior === "miss" ? "miss" : "regenerate", reservation, cacheTags);
754
+ return this.storeResponse(metadata, request, response, options.revalidator, options.expiryBehavior === "miss" ? "miss" : "regenerate", reservation, cacheTags, void 0, replaces, generatedAt);
720
755
  })();
721
756
  let cleared = () => {};
722
757
  if (options.coalesce) {
@@ -5,7 +5,11 @@ export type CachePolicy = {
5
5
  freshUntil: number;
6
6
  swrUntil: number;
7
7
  };
8
- export declare function deriveCachePolicy(headers: Headers, now?: number): CachePolicy;
8
+ /**
9
+ * `generatedAt` dates the response from when its generation started: it is at least that old,
10
+ * and its stale-while-revalidate window still ends that long after its max-age.
11
+ */
12
+ export declare function deriveCachePolicy(headers: Headers, now?: number, generatedAt?: number): CachePolicy;
9
13
  export declare function representationAge(createdAt: number, initialAge: number, now?: number): number;
10
14
  export declare function edgeCacheControl(freshUntil: number, swrUntil: number, now?: number, hasRevalidator?: boolean): string;
11
15
  //#endregion
@@ -6,7 +6,11 @@ function parseSeconds(value) {
6
6
  const parsed = Number(match[1] ?? match[2]);
7
7
  return Number.isSafeInteger(parsed) ? parsed : void 0;
8
8
  }
9
- function deriveCachePolicy(headers, now = Date.now()) {
9
+ /**
10
+ * `generatedAt` dates the response from when its generation started: it is at least that old,
11
+ * and its stale-while-revalidate window still ends that long after its max-age.
12
+ */
13
+ function deriveCachePolicy(headers, now = Date.now(), generatedAt) {
10
14
  const cacheControl = headers.get("Cloudflare-CDN-Cache-Control") ?? headers.get("CDN-Cache-Control") ?? headers.get("Cache-Control");
11
15
  const directives = /* @__PURE__ */ new Map();
12
16
  for (const part of cacheControl?.split(",") ?? []) {
@@ -17,13 +21,16 @@ function deriveCachePolicy(headers, now = Date.now()) {
17
21
  const cacheStorageForbidden = directives.has("no-store") || directives.has("private");
18
22
  const staleServingForbidden = directives.has("s-maxage") || directives.has("must-revalidate") || directives.has("proxy-revalidate");
19
23
  const maxAge = cacheStorageForbidden || directives.has("no-cache") ? 0 : parseSeconds(directives.get("s-maxage")) ?? parseSeconds(directives.get("max-age")) ?? 0;
20
- const initialAge = parseSeconds(headers.get("Age") ?? void 0) ?? 0;
21
- const freshUntil = now + Math.max(0, maxAge - initialAge) * 1e3;
24
+ const ageMs = Math.max((parseSeconds(headers.get("Age") ?? void 0) ?? 0) * 1e3, generatedAt !== void 0 && generatedAt <= now ? now - generatedAt : 0);
25
+ const initialAge = Math.floor(ageMs / 1e3);
26
+ const freshUntil = now + Math.max(0, maxAge * 1e3 - ageMs);
27
+ const staleWhileRevalidate = cacheStorageForbidden || staleServingForbidden ? 0 : parseSeconds(directives.get("stale-while-revalidate")) ?? 0;
28
+ const staleMsUsed = generatedAt === void 0 ? 0 : Math.max(0, ageMs - maxAge * 1e3);
22
29
  return {
23
30
  createdAt: now,
24
31
  initialAge,
25
32
  freshUntil,
26
- swrUntil: freshUntil + (cacheStorageForbidden || staleServingForbidden ? 0 : parseSeconds(directives.get("stale-while-revalidate")) ?? 0) * 1e3
33
+ swrUntil: freshUntil + Math.max(0, staleWhileRevalidate * 1e3 - staleMsUsed)
27
34
  };
28
35
  }
29
36
  function representationAge(createdAt, initialAge, now = Date.now()) {
@@ -11,6 +11,11 @@ type PublicationResult = {
11
11
  edgePurgeRequired: boolean;
12
12
  entry: StoredEntry | null;
13
13
  published: boolean;
14
+ /**
15
+ * Published stale, or expired: generated before an invalidation, or with no fresh window
16
+ * left by this transaction's clock.
17
+ */
18
+ publishedStale?: true;
14
19
  };
15
20
  type WriteReservation = {
16
21
  objectKey: string;
@@ -26,6 +31,12 @@ export type PurgeReservation = {
26
31
  pendingTombstones: number;
27
32
  tombstoneSequence: number;
28
33
  };
34
+ /** The revision a refresh read stale, and the expiration of the soft tags that read saw. */
35
+ export type RefreshedRevision = {
36
+ revision: number;
37
+ tags?: string[];
38
+ tagExpiration?: number;
39
+ };
29
40
  type TombstoneDrainResult = {
30
41
  cursor?: string;
31
42
  failures: string[];
@@ -43,7 +54,7 @@ export type CacheMetadataStub = DurableObjectStub & {
43
54
  finishPendingObjects(objectKeys: string[]): Promise<void>;
44
55
  listExpiredPendingObjects(cutoff: number, limit: number): Promise<string[]>;
45
56
  sweepExpiredPendingObjects(cutoff?: number): Promise<number>;
46
- publish(keyHash: string, revision: number, metadata: CandidateMetadata, claimId?: string, reservationObjectKey?: string): Promise<PublicationResult>;
57
+ publish(keyHash: string, revision: number, metadata: CandidateMetadata, claimId?: string, reservationObjectKey?: string, replaces?: RefreshedRevision): Promise<PublicationResult>;
47
58
  invalidatePublishedRevision(keyHash: string, revision: number): Promise<TombstoneDrainResult>;
48
59
  getEntry(keyHash: string): Promise<StoredEntry | null>;
49
60
  getTagExpiration(tags: string[]): Promise<number>;
@@ -84,12 +95,14 @@ export declare class CacheMetadata extends DurableObject<CacheMetadataEnv> {
84
95
  reserveWrite(keyHash: string, cacheKey: string, objectKeyPrefix: string, createdAt: number): Promise<WriteReservation>;
85
96
  replaceFailedWrite(keyHash: string, cacheKey: string, objectKeyPrefix: string, failedObjectKey: string, fenceTags: string[], createdAt: number): Promise<WriteReservation | null>;
86
97
  reserveRegeneration(keyHash: string, cacheKey: string, objectKeyPrefix: string, createdAt: number, expectedActiveRevision?: number, expectedLatestRevision?: number): Promise<RegenerationReservation | null>;
87
- publish(keyHash: string, revision: number, metadata: CandidateMetadata, claimId?: string, reservationObjectKey?: string): Promise<PublicationResult>;
98
+ publish(keyHash: string, revision: number, metadata: CandidateMetadata, claimId?: string, reservationObjectKey?: string, replaces?: RefreshedRevision): Promise<PublicationResult>;
88
99
  invalidatePublishedRevision(keyHash: string, revision: number): Promise<TombstoneDrainResult>;
89
100
  getEntry(keyHash: string): StoredEntry | null;
90
101
  private getTagInvalidationMaximum;
91
102
  /** The earliest `expire` deadline still ahead of `now` among `tags`, or Infinity. */
92
103
  private getTagExpiryDeadline;
104
+ /** Whether an `expire` deadline among `tags` passed at or after `since`, by `now`. */
105
+ private hasTagExpiredSince;
93
106
  getTagExpiration(tags: string[]): number;
94
107
  findRefreshCandidates(options: ResponseStoreRefreshOptions): StoredEntry[];
95
108
  findRefreshCandidates(options: ResponseStoreRefreshOptions, projection: "reservation"): RefreshCandidate[];
@@ -98,6 +111,8 @@ export declare class CacheMetadata extends DurableObject<CacheMetadataEnv> {
98
111
  * `invalidatedAt` also expires the tags for soft-tag reads; pass 0 to leave
99
112
  * their expiration unchanged. Like Next.js, `expiresAt` replaces the tags'
100
113
  * deadline for entries published before it; null keeps the current one.
114
+ * `staleAt` marks the tags stale for entries generated before it; pass 0 to
115
+ * leave it unchanged.
101
116
  */
102
117
  private recordInvalidations;
103
118
  purgeMatching(options: ResponseStorePurgeOptions, invalidatedAt?: number): Promise<PurgeReservation>;
@@ -4,6 +4,7 @@ import { DurableObject } from "cloudflare:workers";
4
4
  const REFRESHABLE_ENTRY = `tombstoned = 0 AND active_revision IS NOT NULL
5
5
  AND object_key IS NOT NULL AND response_headers IS NOT NULL
6
6
  AND fresh_until IS NOT NULL AND swr_until IS NOT NULL`;
7
+ const PRE_UPGRADE_INVALIDATED_REVISION = Number.MAX_SAFE_INTEGER;
7
8
  const MAX_SQL_PARAMETERS = 100;
8
9
  const ORPHAN_RETENTION_MS = 36e5;
9
10
  const ORPHAN_CLEANUP_LIMIT = 100;
@@ -78,7 +79,9 @@ var CacheMetadata = class extends DurableObject {
78
79
  revalidator_args TEXT,
79
80
  expiry_behavior TEXT,
80
81
  cache_tags TEXT,
81
- tombstoned INTEGER NOT NULL DEFAULT 0
82
+ tombstoned INTEGER NOT NULL DEFAULT 0,
83
+ replaced_revision INTEGER,
84
+ invalidated_revision INTEGER
82
85
  );
83
86
  CREATE INDEX IF NOT EXISTS entries_cache_key ON entries(cache_key);
84
87
  CREATE INDEX IF NOT EXISTS entries_active_object_key
@@ -101,7 +104,8 @@ var CacheMetadata = class extends DurableObject {
101
104
  tag TEXT PRIMARY KEY,
102
105
  invalidated_at INTEGER NOT NULL,
103
106
  invalidation_sequence INTEGER NOT NULL DEFAULT 0,
104
- expires_at INTEGER
107
+ expires_at INTEGER,
108
+ stale_at INTEGER NOT NULL DEFAULT 0
105
109
  ) WITHOUT ROWID;
106
110
  CREATE TABLE IF NOT EXISTS metadata_schema_migrations (
107
111
  version INTEGER PRIMARY KEY
@@ -138,8 +142,8 @@ var CacheMetadata = class extends DurableObject {
138
142
  ) WITHOUT ROWID;
139
143
  `);
140
144
  ctx.storage.transactionSync(() => {
141
- const migrations = new Set(ctx.storage.sql.exec("SELECT version FROM metadata_schema_migrations WHERE version IN (2, 3, 4, 5, 6, 7, 8)").toArray().map(({ version }) => version));
142
- if (migrations.size === 7) return;
145
+ const migrations = new Set(ctx.storage.sql.exec("SELECT version FROM metadata_schema_migrations WHERE version IN (2, 3, 4, 5, 6, 7, 8, 9, 10)").toArray().map(({ version }) => version));
146
+ if (migrations.size === 9) return;
143
147
  const schemas = ctx.storage.sql.exec(`SELECT name, sql FROM sqlite_schema
144
148
  WHERE type = 'table'
145
149
  AND name IN ('entries', 'tag_invalidations', 'metadata_state', 'pending_objects', 'pending_r2_tombstones')`).toArray();
@@ -183,6 +187,18 @@ var CacheMetadata = class extends DurableObject {
183
187
  `);
184
188
  ctx.storage.sql.exec("INSERT INTO metadata_schema_migrations (version) VALUES (8)");
185
189
  }
190
+ if (!migrations.has(9)) {
191
+ if (!(schemas.find(({ name }) => name === "entries")?.sql)?.includes("replaced_revision")) ctx.storage.sql.exec(`
192
+ ALTER TABLE entries ADD COLUMN replaced_revision INTEGER;
193
+ ALTER TABLE entries ADD COLUMN invalidated_revision INTEGER
194
+ DEFAULT ${PRE_UPGRADE_INVALIDATED_REVISION};
195
+ `);
196
+ ctx.storage.sql.exec("INSERT INTO metadata_schema_migrations (version) VALUES (9)");
197
+ }
198
+ if (!migrations.has(10)) {
199
+ if (!(schemas.find(({ name }) => name === "tag_invalidations")?.sql)?.includes("stale_at")) ctx.storage.sql.exec("ALTER TABLE tag_invalidations ADD COLUMN stale_at INTEGER NOT NULL DEFAULT 0");
200
+ ctx.storage.sql.exec("INSERT INTO metadata_schema_migrations (version) VALUES (10)");
201
+ }
186
202
  });
187
203
  ctx.storage.sql.exec(`
188
204
  CREATE INDEX IF NOT EXISTS pending_r2_tombstones_r2_pending
@@ -372,7 +388,8 @@ var CacheMetadata = class extends DurableObject {
372
388
  }
373
389
  reserveRevision(keyHash, cacheKey, current) {
374
390
  const revision = (current?.latest_revision ?? 0) + 1;
375
- if (!current) this.ctx.storage.sql.exec("INSERT INTO entries (key_hash, cache_key, latest_revision, tombstoned) VALUES (?, ?, ?, 1)", keyHash, cacheKey, revision);
391
+ if (!current) this.ctx.storage.sql.exec(`INSERT INTO entries (key_hash, cache_key, latest_revision, tombstoned, invalidated_revision)
392
+ VALUES (?, ?, ?, 1, NULL)`, keyHash, cacheKey, revision);
376
393
  else this.ctx.storage.sql.exec("UPDATE entries SET cache_key = ?, latest_revision = ? WHERE key_hash = ?", cacheKey, revision, keyHash);
377
394
  return revision;
378
395
  }
@@ -438,7 +455,7 @@ var CacheMetadata = class extends DurableObject {
438
455
  if (result?.reservation) await this.ensureCleanupAlarm(createdAt);
439
456
  return result;
440
457
  }
441
- async publish(keyHash, revision, metadata, claimId, reservationObjectKey = metadata.objectKey) {
458
+ async publish(keyHash, revision, metadata, claimId, reservationObjectKey = metadata.objectKey, replaces) {
442
459
  return this.ctx.storage.transactionSync(() => {
443
460
  const current = this.ctx.storage.sql.exec(`SELECT entries.*,
444
461
  revalidation_claims.active_revision AS claim_active_revision,
@@ -452,7 +469,7 @@ var CacheMetadata = class extends DurableObject {
452
469
  LEFT JOIN pending_objects ON pending_objects.object_key = ?
453
470
  LEFT JOIN revalidation_claims ON revalidation_claims.key_hash = entries.key_hash
454
471
  WHERE entries.key_hash = ?`, reservationObjectKey, keyHash).toArray()[0];
455
- if (!current || current.pending_invalidation_sequence === null || current.pending_invalidation_sequence === void 0 || current.pending_publishable !== 1 || revision > current.latest_revision || current.active_revision !== null && revision <= current.active_revision || claimId !== void 0 && (current.claim_id !== claimId || current.claim_revision !== revision || current.claim_active_revision !== current.active_revision) || metadata.fenceTags.length > 0 && current.current_invalidation_sequence > current.pending_invalidation_sequence && this.getTagInvalidationMaximum(metadata.fenceTags, "invalidation_sequence") > current.pending_invalidation_sequence) {
472
+ if (!current || current.pending_invalidation_sequence === null || current.pending_invalidation_sequence === void 0 || current.pending_publishable !== 1 || revision > current.latest_revision || current.active_revision !== null && revision <= current.active_revision || replaces !== void 0 && current.replaced_revision === replaces.revision && (current.invalidated_revision === null || current.invalidated_revision <= replaces.revision) && current.fresh_until !== null && Date.now() < current.fresh_until && (replaces.tags === void 0 || this.getTagExpiration(replaces.tags) <= replaces.tagExpiration) || claimId !== void 0 && (current.claim_id !== claimId || current.claim_revision !== revision || current.claim_active_revision !== current.active_revision) || metadata.fenceTags.length > 0 && current.current_invalidation_sequence > current.pending_invalidation_sequence && this.getTagInvalidationMaximum(metadata.fenceTags, "invalidation_sequence") > current.pending_invalidation_sequence) {
456
473
  if (claimId) this.ctx.storage.sql.exec("DELETE FROM revalidation_claims WHERE key_hash = ? AND claim_id = ?", keyHash, claimId);
457
474
  this.ctx.storage.sql.exec("DELETE FROM pending_objects WHERE object_key = ?", reservationObjectKey);
458
475
  return {
@@ -463,15 +480,31 @@ var CacheMetadata = class extends DurableObject {
463
480
  }
464
481
  const now = Date.now();
465
482
  const deadline = this.getTagExpiryDeadline(metadata.cacheTags, now);
466
- const freshUntil = Math.min(metadata.freshUntil, deadline);
467
- const swrUntil = Math.min(metadata.swrUntil, deadline);
483
+ let freshUntil = Math.min(metadata.freshUntil, deadline);
484
+ let swrUntil = Math.min(metadata.swrUntil, deadline);
485
+ let startedBeforeInvalidation = false;
486
+ if (metadata.generatedAt !== void 0) {
487
+ if (this.getTagInvalidationMaximum(metadata.cacheTags, "invalidated_at") >= metadata.generatedAt || this.hasTagExpiredSince(metadata.cacheTags, metadata.generatedAt, now)) {
488
+ freshUntil = Math.min(freshUntil, now);
489
+ swrUntil = Math.min(swrUntil, now);
490
+ startedBeforeInvalidation = true;
491
+ } else if (this.getTagInvalidationMaximum(metadata.cacheTags, "stale_at") >= metadata.generatedAt) {
492
+ freshUntil = Math.min(freshUntil, now);
493
+ startedBeforeInvalidation = true;
494
+ }
495
+ }
468
496
  const published = this.ctx.storage.sql.exec(`UPDATE entries SET
469
497
  active_revision = ?, object_key = ?, status_text = ?, response_headers = ?,
470
498
  fresh_until = ?, swr_until = ?,
471
- revalidator_id = ?, revalidator_args = ?, expiry_behavior = ?, cache_tags = ?, tombstoned = 0
499
+ revalidator_id = ?, revalidator_args = ?, expiry_behavior = ?, cache_tags = ?, tombstoned = 0,
500
+ replaced_revision = ?,
501
+ invalidated_revision = CASE invalidated_revision
502
+ WHEN ${PRE_UPGRADE_INVALIDATED_REVISION} THEN active_revision
503
+ ELSE invalidated_revision
504
+ END
472
505
  WHERE key_hash = ? AND latest_revision >= ?
473
506
  AND (active_revision IS NULL OR active_revision < ?)
474
- RETURNING key_hash`, revision, metadata.objectKey, metadata.statusText, JSON.stringify(metadata.responseHeaders), freshUntil, swrUntil, metadata.revalidator?.id ?? null, metadata.revalidator ? JSON.stringify(metadata.revalidator.args) : null, metadata.expiryBehavior === "miss" ? "miss" : null, JSON.stringify(metadata.cacheTags), keyHash, revision, revision).toArray().length === 1;
507
+ RETURNING key_hash`, revision, metadata.objectKey, metadata.statusText, JSON.stringify(metadata.responseHeaders), freshUntil, swrUntil, metadata.revalidator?.id ?? null, metadata.revalidator ? JSON.stringify(metadata.revalidator.args) : null, metadata.expiryBehavior === "miss" ? "miss" : null, JSON.stringify(metadata.cacheTags), replaces !== void 0 && current.active_revision !== null && replaces.revision <= current.active_revision ? replaces.revision : null, keyHash, revision, revision).toArray().length === 1;
475
508
  if (published) this.replaceEntryTags(keyHash, metadata.cacheTags);
476
509
  this.ctx.storage.sql.exec("DELETE FROM pending_objects WHERE object_key = ?", reservationObjectKey);
477
510
  if (claimId) this.ctx.storage.sql.exec("DELETE FROM revalidation_claims WHERE key_hash = ? AND claim_id = ?", keyHash, claimId);
@@ -493,7 +526,8 @@ var CacheMetadata = class extends DurableObject {
493
526
  return {
494
527
  edgePurgeRequired: published && current.active_revision !== null && !replacedEdgeCopyExpired,
495
528
  entry: published ? entry : null,
496
- published
529
+ published,
530
+ ...published && (startedBeforeInvalidation || freshUntil <= now) ? { publishedStale: true } : {}
497
531
  };
498
532
  });
499
533
  }
@@ -510,8 +544,8 @@ var CacheMetadata = class extends DurableObject {
510
544
  latest_revision = ?, active_revision = ?, object_key = NULL,
511
545
  status_text = NULL, response_headers = NULL, fresh_until = NULL,
512
546
  swr_until = NULL, revalidator_id = NULL, revalidator_args = NULL,
513
- expiry_behavior = NULL, cache_tags = NULL, tombstoned = 1
514
- WHERE key_hash = ? AND active_revision = ?`, tombstoneRevision, tombstoneRevision, keyHash, revision);
547
+ expiry_behavior = NULL, cache_tags = NULL, tombstoned = 1, invalidated_revision = ?
548
+ WHERE key_hash = ? AND active_revision = ?`, tombstoneRevision, tombstoneRevision, tombstoneRevision, keyHash, revision);
515
549
  this.ctx.storage.sql.exec("DELETE FROM revalidation_claims WHERE key_hash = ?", keyHash);
516
550
  this.ctx.storage.sql.exec("DELETE FROM entry_tags WHERE key_hash = ?", keyHash);
517
551
  return true;
@@ -548,6 +582,13 @@ var CacheMetadata = class extends DurableObject {
548
582
  }
549
583
  return deadline;
550
584
  }
585
+ /** Whether an `expire` deadline among `tags` passed at or after `since`, by `now`. */
586
+ hasTagExpiredSince(tags, since, now) {
587
+ for (const batch of batches(normalizeTags(tags), 98)) if (this.ctx.storage.sql.exec(`SELECT 1 FROM tag_invalidations
588
+ WHERE expires_at >= ? AND expires_at <= ? AND tag IN (${batch.map(() => "?").join(", ")})
589
+ LIMIT 1`, since, now, ...batch).toArray().length) return true;
590
+ return false;
591
+ }
551
592
  getTagExpiration(tags) {
552
593
  return this.getTagInvalidationMaximum(tags, "invalidated_at");
553
594
  }
@@ -566,25 +607,29 @@ var CacheMetadata = class extends DurableObject {
566
607
  * `invalidatedAt` also expires the tags for soft-tag reads; pass 0 to leave
567
608
  * their expiration unchanged. Like Next.js, `expiresAt` replaces the tags'
568
609
  * deadline for entries published before it; null keeps the current one.
610
+ * `staleAt` marks the tags stale for entries generated before it; pass 0 to
611
+ * leave it unchanged.
569
612
  */
570
- recordInvalidations(keyHashes, tags, invalidatedAt, expiresAt) {
613
+ recordInvalidations(keyHashes, tags, invalidatedAt, expiresAt, staleAt) {
571
614
  this.ctx.storage.sql.exec(`UPDATE metadata_state SET tag_invalidation_sequence = tag_invalidation_sequence + 1
572
615
  WHERE singleton = 1`);
573
616
  for (const batch of batches(keyHashes, MAX_SQL_PARAMETERS)) this.ctx.storage.sql.exec(`INSERT INTO key_invalidations (key_hash, invalidation_sequence) VALUES ${batch.map(() => "(?, (SELECT tag_invalidation_sequence FROM metadata_state WHERE singleton = 1))").join(", ")}
574
617
  ON CONFLICT(key_hash) DO UPDATE SET invalidation_sequence =
575
618
  MAX(key_invalidations.invalidation_sequence, excluded.invalidation_sequence)`, ...batch);
576
- for (const batch of batches(tags, Math.floor(MAX_SQL_PARAMETERS / 3))) this.ctx.storage.sql.exec(`INSERT INTO tag_invalidations
577
- (tag, invalidated_at, expires_at, invalidation_sequence) VALUES ${batch.map(() => "(?, ?, ?, (SELECT tag_invalidation_sequence FROM metadata_state WHERE singleton = 1))").join(", ")}
619
+ for (const batch of batches(tags, Math.floor(MAX_SQL_PARAMETERS / 4))) this.ctx.storage.sql.exec(`INSERT INTO tag_invalidations
620
+ (tag, invalidated_at, expires_at, stale_at, invalidation_sequence) VALUES ${batch.map(() => "(?, ?, ?, ?, (SELECT tag_invalidation_sequence FROM metadata_state WHERE singleton = 1))").join(", ")}
578
621
  ON CONFLICT(tag) DO UPDATE SET invalidated_at =
579
622
  MAX(tag_invalidations.invalidated_at, excluded.invalidated_at),
580
623
  expires_at = COALESCE(excluded.expires_at, tag_invalidations.expires_at),
624
+ stale_at = MAX(tag_invalidations.stale_at, excluded.stale_at),
581
625
  invalidation_sequence = MAX(
582
626
  tag_invalidations.invalidation_sequence,
583
627
  excluded.invalidation_sequence
584
628
  )`, ...batch.flatMap((tag) => [
585
629
  tag,
586
630
  invalidatedAt,
587
- expiresAt
631
+ expiresAt,
632
+ staleAt
588
633
  ]));
589
634
  }
590
635
  async purgeMatching(options, invalidatedAt = Date.now()) {
@@ -592,7 +637,7 @@ var CacheMetadata = class extends DurableObject {
592
637
  const matches = this.findMatchingEntryRows(options, "purge");
593
638
  const tombstoneSequence = this.tombstoneSequence(matches.some((row) => row.object_key !== null));
594
639
  const tags = normalizeTags(options.tags ?? []);
595
- this.recordInvalidations(matches.map((row) => row.key_hash), tags, invalidatedAt, invalidatedAt);
640
+ this.recordInvalidations(matches.map((row) => row.key_hash), tags, invalidatedAt, invalidatedAt, 0);
596
641
  for (const batch of batches(matches, 99)) {
597
642
  const active = batch.filter((row) => row.object_key !== null);
598
643
  for (const entryBatch of batches(active, MAX_SQL_PARAMETERS / 5)) this.ctx.storage.sql.exec(`INSERT OR REPLACE INTO pending_r2_tombstones
@@ -617,7 +662,8 @@ var CacheMetadata = class extends DurableObject {
617
662
  revalidator_args = NULL,
618
663
  expiry_behavior = NULL,
619
664
  cache_tags = NULL,
620
- tombstoned = 1
665
+ tombstoned = 1,
666
+ invalidated_revision = latest_revision + 1
621
667
  WHERE key_hash IN (${placeholders})`, ...keyHashes);
622
668
  this.ctx.storage.sql.exec(`DELETE FROM revalidation_claims WHERE key_hash IN (${placeholders})`, ...keyHashes);
623
669
  this.ctx.storage.sql.exec(`DELETE FROM entry_tags WHERE key_hash IN (${placeholders})`, ...keyHashes);
@@ -644,7 +690,7 @@ var CacheMetadata = class extends DurableObject {
644
690
  const reserved = rows.filter((row) => !row.refreshable).map((row) => row.key_hash);
645
691
  const tags = normalizeTags(options.tags ?? []);
646
692
  const tombstoneSequence = this.tombstoneSequence(matches.length > 0);
647
- this.recordInvalidations(rows.map((row) => row.key_hash), tags, 0, expiresAt ?? null);
693
+ this.recordInvalidations(rows.map((row) => row.key_hash), tags, 0, expiresAt ?? null, invalidatedAt);
648
694
  for (const batch of batches(reserved, MAX_SQL_PARAMETERS)) this.ctx.storage.sql.exec(`UPDATE entries SET
649
695
  latest_revision = latest_revision + 1,
650
696
  active_revision = latest_revision + 1
@@ -686,7 +732,8 @@ var CacheMetadata = class extends DurableObject {
686
732
  latest_revision = latest_revision + 1,
687
733
  active_revision = latest_revision + 1,
688
734
  fresh_until = MIN(fresh_until, ?),
689
- swr_until = MIN(swr_until, COALESCE(?, swr_until))
735
+ swr_until = MIN(swr_until, COALESCE(?, swr_until)),
736
+ invalidated_revision = latest_revision + 1
690
737
  WHERE key_hash IN (${placeholders})`, invalidatedAt, expiresAt ?? null, ...keyHashes);
691
738
  this.ctx.storage.sql.exec(`DELETE FROM revalidation_claims WHERE key_hash IN (${placeholders})`, ...keyHashes);
692
739
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cloudflare/workers-response-store",
3
- "version": "1.1.3",
3
+ "version": "1.1.5",
4
4
  "description": "An R2-backed programmatic response store for Cloudflare Workers.",
5
5
  "homepage": "https://vinext.dev/",
6
6
  "license": "MIT",
@@ -29,7 +29,7 @@
29
29
  "miniflare": "5.20260730.0-alpha",
30
30
  "typescript": "^7.0.0",
31
31
  "vite-plus": "1.3.0",
32
- "wrangler": "^4.118.0"
32
+ "wrangler": "^4.153.0"
33
33
  },
34
34
  "engines": {
35
35
  "node": ">=22"