@cloudflare/workers-response-store 1.1.3 → 1.1.4

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>;
@@ -78,7 +78,9 @@ var CacheMetadata = class extends DurableObject {
78
78
  revalidator_args TEXT,
79
79
  expiry_behavior TEXT,
80
80
  cache_tags TEXT,
81
- tombstoned INTEGER NOT NULL DEFAULT 0
81
+ tombstoned INTEGER NOT NULL DEFAULT 0,
82
+ replaced_revision INTEGER,
83
+ invalidated_revision INTEGER
82
84
  );
83
85
  CREATE INDEX IF NOT EXISTS entries_cache_key ON entries(cache_key);
84
86
  CREATE INDEX IF NOT EXISTS entries_active_object_key
@@ -101,7 +103,8 @@ var CacheMetadata = class extends DurableObject {
101
103
  tag TEXT PRIMARY KEY,
102
104
  invalidated_at INTEGER NOT NULL,
103
105
  invalidation_sequence INTEGER NOT NULL DEFAULT 0,
104
- expires_at INTEGER
106
+ expires_at INTEGER,
107
+ stale_at INTEGER NOT NULL DEFAULT 0
105
108
  ) WITHOUT ROWID;
106
109
  CREATE TABLE IF NOT EXISTS metadata_schema_migrations (
107
110
  version INTEGER PRIMARY KEY
@@ -138,8 +141,8 @@ var CacheMetadata = class extends DurableObject {
138
141
  ) WITHOUT ROWID;
139
142
  `);
140
143
  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;
144
+ 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));
145
+ if (migrations.size === 9) return;
143
146
  const schemas = ctx.storage.sql.exec(`SELECT name, sql FROM sqlite_schema
144
147
  WHERE type = 'table'
145
148
  AND name IN ('entries', 'tag_invalidations', 'metadata_state', 'pending_objects', 'pending_r2_tombstones')`).toArray();
@@ -183,6 +186,18 @@ var CacheMetadata = class extends DurableObject {
183
186
  `);
184
187
  ctx.storage.sql.exec("INSERT INTO metadata_schema_migrations (version) VALUES (8)");
185
188
  }
189
+ if (!migrations.has(9)) {
190
+ if (!(schemas.find(({ name }) => name === "entries")?.sql)?.includes("replaced_revision")) ctx.storage.sql.exec(`
191
+ ALTER TABLE entries ADD COLUMN replaced_revision INTEGER;
192
+ ALTER TABLE entries ADD COLUMN invalidated_revision INTEGER;
193
+ `);
194
+ ctx.storage.sql.exec("UPDATE entries SET invalidated_revision = active_revision");
195
+ ctx.storage.sql.exec("INSERT INTO metadata_schema_migrations (version) VALUES (9)");
196
+ }
197
+ if (!migrations.has(10)) {
198
+ 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");
199
+ ctx.storage.sql.exec("INSERT INTO metadata_schema_migrations (version) VALUES (10)");
200
+ }
186
201
  });
187
202
  ctx.storage.sql.exec(`
188
203
  CREATE INDEX IF NOT EXISTS pending_r2_tombstones_r2_pending
@@ -438,7 +453,7 @@ var CacheMetadata = class extends DurableObject {
438
453
  if (result?.reservation) await this.ensureCleanupAlarm(createdAt);
439
454
  return result;
440
455
  }
441
- async publish(keyHash, revision, metadata, claimId, reservationObjectKey = metadata.objectKey) {
456
+ async publish(keyHash, revision, metadata, claimId, reservationObjectKey = metadata.objectKey, replaces) {
442
457
  return this.ctx.storage.transactionSync(() => {
443
458
  const current = this.ctx.storage.sql.exec(`SELECT entries.*,
444
459
  revalidation_claims.active_revision AS claim_active_revision,
@@ -452,7 +467,7 @@ var CacheMetadata = class extends DurableObject {
452
467
  LEFT JOIN pending_objects ON pending_objects.object_key = ?
453
468
  LEFT JOIN revalidation_claims ON revalidation_claims.key_hash = entries.key_hash
454
469
  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) {
470
+ 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
471
  if (claimId) this.ctx.storage.sql.exec("DELETE FROM revalidation_claims WHERE key_hash = ? AND claim_id = ?", keyHash, claimId);
457
472
  this.ctx.storage.sql.exec("DELETE FROM pending_objects WHERE object_key = ?", reservationObjectKey);
458
473
  return {
@@ -463,15 +478,27 @@ var CacheMetadata = class extends DurableObject {
463
478
  }
464
479
  const now = Date.now();
465
480
  const deadline = this.getTagExpiryDeadline(metadata.cacheTags, now);
466
- const freshUntil = Math.min(metadata.freshUntil, deadline);
467
- const swrUntil = Math.min(metadata.swrUntil, deadline);
481
+ let freshUntil = Math.min(metadata.freshUntil, deadline);
482
+ let swrUntil = Math.min(metadata.swrUntil, deadline);
483
+ let startedBeforeInvalidation = false;
484
+ if (metadata.generatedAt !== void 0) {
485
+ if (this.getTagInvalidationMaximum(metadata.cacheTags, "invalidated_at") >= metadata.generatedAt || this.hasTagExpiredSince(metadata.cacheTags, metadata.generatedAt, now)) {
486
+ freshUntil = Math.min(freshUntil, now);
487
+ swrUntil = Math.min(swrUntil, now);
488
+ startedBeforeInvalidation = true;
489
+ } else if (this.getTagInvalidationMaximum(metadata.cacheTags, "stale_at") >= metadata.generatedAt) {
490
+ freshUntil = Math.min(freshUntil, now);
491
+ startedBeforeInvalidation = true;
492
+ }
493
+ }
468
494
  const published = this.ctx.storage.sql.exec(`UPDATE entries SET
469
495
  active_revision = ?, object_key = ?, status_text = ?, response_headers = ?,
470
496
  fresh_until = ?, swr_until = ?,
471
- revalidator_id = ?, revalidator_args = ?, expiry_behavior = ?, cache_tags = ?, tombstoned = 0
497
+ revalidator_id = ?, revalidator_args = ?, expiry_behavior = ?, cache_tags = ?, tombstoned = 0,
498
+ replaced_revision = ?
472
499
  WHERE key_hash = ? AND latest_revision >= ?
473
500
  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;
501
+ 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
502
  if (published) this.replaceEntryTags(keyHash, metadata.cacheTags);
476
503
  this.ctx.storage.sql.exec("DELETE FROM pending_objects WHERE object_key = ?", reservationObjectKey);
477
504
  if (claimId) this.ctx.storage.sql.exec("DELETE FROM revalidation_claims WHERE key_hash = ? AND claim_id = ?", keyHash, claimId);
@@ -493,7 +520,8 @@ var CacheMetadata = class extends DurableObject {
493
520
  return {
494
521
  edgePurgeRequired: published && current.active_revision !== null && !replacedEdgeCopyExpired,
495
522
  entry: published ? entry : null,
496
- published
523
+ published,
524
+ ...published && (startedBeforeInvalidation || freshUntil <= now) ? { publishedStale: true } : {}
497
525
  };
498
526
  });
499
527
  }
@@ -510,8 +538,8 @@ var CacheMetadata = class extends DurableObject {
510
538
  latest_revision = ?, active_revision = ?, object_key = NULL,
511
539
  status_text = NULL, response_headers = NULL, fresh_until = NULL,
512
540
  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);
541
+ expiry_behavior = NULL, cache_tags = NULL, tombstoned = 1, invalidated_revision = ?
542
+ WHERE key_hash = ? AND active_revision = ?`, tombstoneRevision, tombstoneRevision, tombstoneRevision, keyHash, revision);
515
543
  this.ctx.storage.sql.exec("DELETE FROM revalidation_claims WHERE key_hash = ?", keyHash);
516
544
  this.ctx.storage.sql.exec("DELETE FROM entry_tags WHERE key_hash = ?", keyHash);
517
545
  return true;
@@ -548,6 +576,13 @@ var CacheMetadata = class extends DurableObject {
548
576
  }
549
577
  return deadline;
550
578
  }
579
+ /** Whether an `expire` deadline among `tags` passed at or after `since`, by `now`. */
580
+ hasTagExpiredSince(tags, since, now) {
581
+ for (const batch of batches(normalizeTags(tags), 98)) if (this.ctx.storage.sql.exec(`SELECT 1 FROM tag_invalidations
582
+ WHERE expires_at >= ? AND expires_at <= ? AND tag IN (${batch.map(() => "?").join(", ")})
583
+ LIMIT 1`, since, now, ...batch).toArray().length) return true;
584
+ return false;
585
+ }
551
586
  getTagExpiration(tags) {
552
587
  return this.getTagInvalidationMaximum(tags, "invalidated_at");
553
588
  }
@@ -566,25 +601,29 @@ var CacheMetadata = class extends DurableObject {
566
601
  * `invalidatedAt` also expires the tags for soft-tag reads; pass 0 to leave
567
602
  * their expiration unchanged. Like Next.js, `expiresAt` replaces the tags'
568
603
  * deadline for entries published before it; null keeps the current one.
604
+ * `staleAt` marks the tags stale for entries generated before it; pass 0 to
605
+ * leave it unchanged.
569
606
  */
570
- recordInvalidations(keyHashes, tags, invalidatedAt, expiresAt) {
607
+ recordInvalidations(keyHashes, tags, invalidatedAt, expiresAt, staleAt) {
571
608
  this.ctx.storage.sql.exec(`UPDATE metadata_state SET tag_invalidation_sequence = tag_invalidation_sequence + 1
572
609
  WHERE singleton = 1`);
573
610
  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
611
  ON CONFLICT(key_hash) DO UPDATE SET invalidation_sequence =
575
612
  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(", ")}
613
+ for (const batch of batches(tags, Math.floor(MAX_SQL_PARAMETERS / 4))) this.ctx.storage.sql.exec(`INSERT INTO tag_invalidations
614
+ (tag, invalidated_at, expires_at, stale_at, invalidation_sequence) VALUES ${batch.map(() => "(?, ?, ?, ?, (SELECT tag_invalidation_sequence FROM metadata_state WHERE singleton = 1))").join(", ")}
578
615
  ON CONFLICT(tag) DO UPDATE SET invalidated_at =
579
616
  MAX(tag_invalidations.invalidated_at, excluded.invalidated_at),
580
617
  expires_at = COALESCE(excluded.expires_at, tag_invalidations.expires_at),
618
+ stale_at = MAX(tag_invalidations.stale_at, excluded.stale_at),
581
619
  invalidation_sequence = MAX(
582
620
  tag_invalidations.invalidation_sequence,
583
621
  excluded.invalidation_sequence
584
622
  )`, ...batch.flatMap((tag) => [
585
623
  tag,
586
624
  invalidatedAt,
587
- expiresAt
625
+ expiresAt,
626
+ staleAt
588
627
  ]));
589
628
  }
590
629
  async purgeMatching(options, invalidatedAt = Date.now()) {
@@ -592,7 +631,7 @@ var CacheMetadata = class extends DurableObject {
592
631
  const matches = this.findMatchingEntryRows(options, "purge");
593
632
  const tombstoneSequence = this.tombstoneSequence(matches.some((row) => row.object_key !== null));
594
633
  const tags = normalizeTags(options.tags ?? []);
595
- this.recordInvalidations(matches.map((row) => row.key_hash), tags, invalidatedAt, invalidatedAt);
634
+ this.recordInvalidations(matches.map((row) => row.key_hash), tags, invalidatedAt, invalidatedAt, 0);
596
635
  for (const batch of batches(matches, 99)) {
597
636
  const active = batch.filter((row) => row.object_key !== null);
598
637
  for (const entryBatch of batches(active, MAX_SQL_PARAMETERS / 5)) this.ctx.storage.sql.exec(`INSERT OR REPLACE INTO pending_r2_tombstones
@@ -617,7 +656,8 @@ var CacheMetadata = class extends DurableObject {
617
656
  revalidator_args = NULL,
618
657
  expiry_behavior = NULL,
619
658
  cache_tags = NULL,
620
- tombstoned = 1
659
+ tombstoned = 1,
660
+ invalidated_revision = latest_revision + 1
621
661
  WHERE key_hash IN (${placeholders})`, ...keyHashes);
622
662
  this.ctx.storage.sql.exec(`DELETE FROM revalidation_claims WHERE key_hash IN (${placeholders})`, ...keyHashes);
623
663
  this.ctx.storage.sql.exec(`DELETE FROM entry_tags WHERE key_hash IN (${placeholders})`, ...keyHashes);
@@ -644,7 +684,7 @@ var CacheMetadata = class extends DurableObject {
644
684
  const reserved = rows.filter((row) => !row.refreshable).map((row) => row.key_hash);
645
685
  const tags = normalizeTags(options.tags ?? []);
646
686
  const tombstoneSequence = this.tombstoneSequence(matches.length > 0);
647
- this.recordInvalidations(rows.map((row) => row.key_hash), tags, 0, expiresAt ?? null);
687
+ this.recordInvalidations(rows.map((row) => row.key_hash), tags, 0, expiresAt ?? null, invalidatedAt);
648
688
  for (const batch of batches(reserved, MAX_SQL_PARAMETERS)) this.ctx.storage.sql.exec(`UPDATE entries SET
649
689
  latest_revision = latest_revision + 1,
650
690
  active_revision = latest_revision + 1
@@ -686,7 +726,8 @@ var CacheMetadata = class extends DurableObject {
686
726
  latest_revision = latest_revision + 1,
687
727
  active_revision = latest_revision + 1,
688
728
  fresh_until = MIN(fresh_until, ?),
689
- swr_until = MIN(swr_until, COALESCE(?, swr_until))
729
+ swr_until = MIN(swr_until, COALESCE(?, swr_until)),
730
+ invalidated_revision = latest_revision + 1
690
731
  WHERE key_hash IN (${placeholders})`, invalidatedAt, expiresAt ?? null, ...keyHashes);
691
732
  this.ctx.storage.sql.exec(`DELETE FROM revalidation_claims WHERE key_hash IN (${placeholders})`, ...keyHashes);
692
733
  }
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.4",
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"