shabbat-gate 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -3,7 +3,73 @@
 All notable changes to this package are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/).
 
-## [0.3.0] - Unreleased
+## [0.4.0] - Unreleased
+
+### Fixed
+
+- **A *slow* Hebcal took a consumer's site down with 504s - the exact opposite of this
+  package's fail-open design.** Found in production on 2026-07-28 on `primestack.co.il`: 24h of
+  Cloudflare zone analytics showed 14 homepage `504`s, clustered in the same hours as 53 `504`s
+  on the internal cache key `/shabbat-gate-windows-v1`. Nothing else on the site 504'd.
+
+  Root cause: `fetchWindows` did a plain `await fetch(url)` with no timeout and no
+  `AbortSignal`. The gate wraps everything in a `try/catch` that fails open - **but a
+  `try/catch` only rescues a rejection, never a hang.** When Hebcal was slow rather than down,
+  the fetch never settled, the Worker invocation ran past its limit, and Cloudflare returned
+  504 to the visitor; the catch never ran, so "fail open" never happened. And because it was a
+  cache miss, *every* concurrent visitor started their own fetch - a thundering herd, which is
+  why the 504s arrived in clusters rather than one at a time.
+
+  Four changes, so that a slow or broken upstream can never again reach the visitor:
+  - **`fetchWindows` now aborts** via `AbortController` after `timeoutMs` (new
+    `FetchWindowsOptions` field, default 3000; exported as `DEFAULT_HEBCAL_TIMEOUT_MS`),
+    rejecting with a distinct `HebcalTimeoutError` so the failure mode is greppable in logs. A
+    real abort rather than a `Promise.race`, which would leave the underlying request dangling.
+    The signal stays armed across `res.json()` too - a stalled body stream hangs an invocation
+    just as effectively as a stalled connection.
+  - **Stale-while-revalidate.** A cached window list is now served past its 24h freshness
+    window (up to 7 days) while it refreshes in the background via `waitUntil`, so once the
+    cache is warm no visitor ever waits on Hebcal at all. Windows are fetched 45 days ahead, so
+    a week-old list is still correct for the next ~38 days.
+  - **Failures are cached for 60s**, so a struggling upstream gets one retry per minute instead
+    of one per visitor.
+  - **Concurrent fetches are deduped** per cache key within an isolate, closing the cold-start
+    herd the Cache API alone can't (it only helps once a fetch has *finished*).
+
+  Regression tests stub `fetch` with a promise that never resolves and assert the gate returns
+  the real site rather than hanging - both tests hang and fail against the old code.
+
+### Added
+
+- `ShabbatGateConfig.hebcalTimeoutMs` (default 3000) - how long to wait for Hebcal before
+  giving up and failing open. Only ever paid on a cold cache.
+- `createShabbatGateForWorker`'s handler now takes an optional second argument, the Worker's
+  `ctx`: `gate(request, ctx)`. Passing it lets a stale window list refresh *after* the response
+  is sent instead of the refresh being cancelled when the invocation ends. Backward compatible -
+  existing `gate(request)` calls keep working, they just lose background revalidation.
+  `createShabbatGate` (Pages) wires this up automatically from its own `context`.
+
+### Changed
+
+- **The internal cache key moved to `...-windows-v2`** (and `...-visitor-v2`), because cache
+  entries now carry their fetch timestamp and failure state rather than being a bare window
+  array. Consumers reading `INTERNAL_CACHE_KEY_URL` are unaffected; anyone who hardcoded the
+  `v1` string will now be reading a key nothing writes to.
+
+## [0.3.1] - Unreleased (never published separately; folded into 0.4.0)
+
+### Documentation
+
+- Documented middleware **chaining** for Cloudflare Pages sites that already have a root
+  `functions/_middleware`. Cloudflare runs only one root middleware file - two (`_middleware.js`
+  **and** `_middleware.ts`) means one is silently ignored. Since `gate` already calls
+  `context.next()`, it composes as-is: export the root `onRequest` as an array
+  (`export const onRequest = [noindex, (context) => gate(context)]`) and Cloudflare runs them in
+  order. No code change - the gate was already a composable middleware primitive; this just adds
+  the README section (both languages) so consumers don't add a clashing second file. Found live
+  installing on eyalmeshulam.com (which already had a preview-noindex middleware).
+
+## [0.3.0] - 2026-07-19
 
 ### Added
 

package/README.he.md

@@ -37,6 +37,35 @@ const gate = createShabbatGate({ siteName: 'שם האתר שלי' });
 export const onRequest: PagesFunction = (context) => gate(context);
 ```
 
+### כשכבר קיים `functions/_middleware` באתר
+
+Cloudflare Pages מריץ **קובץ middleware אחד בלבד** בשורש `functions/`. אם קיימים שניים
+(`_middleware.js` **וגם** `_middleware.ts`), Cloudflare בוחר אחד בשקט והשני פשוט לא רץ - בלי
+שגיאה, בלי אזהרה. לכן **אין ליצור קובץ שני**. `gate` קורא בעצמו ל-`context.next()`, כלומר הוא
+כבר primitive שמשתלב בשרשרת: מייצאים את ה-`onRequest` בשורש כ**מערך** של handlers,
+ו-Cloudflare מריץ אותם לפי הסדר כשכל אחד קורא `next()`. לדוגמה, שרשור שומר-noindex לפריוויו
+לפני השער:
+
+```js
+import { createShabbatGate } from 'shabbat-gate';
+
+const PROD_HOSTS = new Set(['example.com', 'www.example.com']);
+
+const noindex = async ({ request, next }) => {
+  const res = await next();
+  if (PROD_HOSTS.has(new URL(request.url).hostname)) return res;
+  const tagged = new Response(res.body, res);
+  tagged.headers.set('X-Robots-Tag', 'noindex, nofollow');
+  return tagged;
+};
+
+const gate = createShabbatGate({ siteName: 'שם האתר שלי' });
+
+export const onRequest = [noindex, (context) => gate(context)];
+```
+
+אין צורך לעטוף `next()` ידנית - השער משתלב בשרשרת כמו שהוא.
+
 ### שימוש עם Worker רגיל + assets binding (לא Pages)
 
 `createShabbatGate` מחזירה handler בצורה של Pages Functions (`(context) => Response`), וזה
@@ -50,13 +79,17 @@ import { createShabbatGateForWorker } from 'shabbat-gate';
 const gate = createShabbatGateForWorker({ siteName: 'שם האתר שלי' });
 
 export default {
-  async fetch(request: Request, env: { ASSETS: Fetcher }) {
-    const blocked = await gate(request);
+  async fetch(request: Request, env: { ASSETS: Fetcher }, ctx: ExecutionContext) {
+    const blocked = await gate(request, ctx);
     return blocked ?? env.ASSETS.fetch(request);
   },
 };
 ```
 
+העברת `ctx` היא אופציונלית אבל מומלצת: זה מה שמאפשר לרשימת חלונות שפג תוקפה להתרענן **אחרי**
+ששלחנו את התשובה (ראו [עמידות](#עמידות-timeout-ו-stale-while-revalidate)) במקום שהרענון יבוטל
+כשההרצה מסתיימת. `createShabbatGate` (ב-Pages) מקבל את זה אוטומטית מה-`context` שלו.
+
 **מוקש שמבטל את כל השער בשקט:** Cloudflare Worker עם `assets` binding מגיש כל בקשה שתואמת
 קובץ בתיקיית ה-assets **ישירות**, בלי להריץ בכלל את ה-`fetch` handler של ה-Worker - אלא אם
 מגדירים `run_worker_first: true`. בלי זה, קוד השער רץ ונראה מחובר נכון, הבדיקות עוברות, אבל
@@ -127,6 +160,11 @@ export interface ShabbatGateConfig {
    *  מיקום לבקשה (למשל `wrangler dev` מקומי, או IP ש-Cloudflare לא ממקם) - אותה בקשה
    *  נופלת חזרה להחלטה לפי ישראל בלבד. */
   enforceVisitorLocation?: boolean;
+
+  /** כמה זמן לחכות ל-Hebcal לפני שמוותרים ונופלים פתוח (ברירת מחדל: 3000 מילישניות).
+   *  משולם רק כשהקאש קר - ברגע שהוא חם, רשימת חלונות שפג תוקפה מוגשת מיד ומתרעננת
+   *  ברקע, כך שה-timeout הזה אף פעם לא נוחת על בקשה של גולש. */
+  hebcalTimeoutMs?: number;
 }
 ```
 
@@ -181,13 +219,31 @@ export const onRequest: PagesFunction = (context) => gate(context);
 6. אם הזמן הנוכחי נופל בתוך חלון, מוצג דף ה"סגור" (HTTP 200). אחרת, האתר האמיתי עובר.
 7. כל שגיאה בדרך גורמת למעבר לאתר האמיתי.
 
+## עמידות: timeout ו-stale-while-revalidate
+
+השער תלוי ב-API של צד שלישי (Hebcal) על הנתיב הקריטי של כל טעינת עמוד, ולכן הוא בנוי כך
+ש-Hebcal שלא זמין - או, מסוכן יותר, **איטי** - לא יוכל להפיל את האתר יחד איתו.
+
+- **הקריאה ל-Hebcal מבוטלת אחרי `hebcalTimeoutMs`** (ברירת מחדל 3 שניות). upstream איטי גרוע
+  יותר מכזה שנופל: `fetch` בלי abort לא נסגר לעולם, ההרצה של ה-Worker עוברת את מגבלת הזמן,
+  וקלאודפלייר מחזירה **504** לגולש - ה-`try/catch` שאמור "ליפול פתוח" אף פעם לא רץ, כי
+  `try/catch` מציל מ-rejection, לא מתקיעה. ה-abort הופך את התקיעה ל-rejection שהשער יודע
+  ליפול עליו פתוח. (זה לא תרחיש תיאורטי - ראו את רשומת 0.4.0 ביומן השינויים.)
+- **stale-while-revalidate.** גולש מחכה ל-Hebcal רק כשאין בכלל מידע שמיש בקאש. החלונות נשלפים
+  45 יום קדימה, ולכן ברגע שהקאש חם, רשימה שפג תוקפה מוגשת **מיד** ומתרעננת ברקע דרך
+  `waitUntil` - upstream איטי אף פעם לא יושב על בקשה של גולש. חלונות ישנים מוגשים עד 7 ימים.
+- **כישלון נשמר בקאש ל-60 שניות.** אחרת כל גולש מקביל פותח בקשה משלו מול upstream שכבר מתקשה,
+  וזה מה שהופך תשובה איטית אחת לאשכול של 504.
+- **קריאות מקבילות ממוזגות** לפי מפתח קאש בתוך אותו isolate, כך שהתנעה קרה פותחת חיבור אחד
+  ולא אחד לכל בקשה שנמצאת באוויר.
+
 ## מפתח קאש פנימי
 
 רשימת החלונות המאוחדת נשמרת בקאש תחת מפתח פנימי קבוע
-(`https://internal.cache/shabbat-gate-windows-v1`, מיוצא בשם `INTERNAL_CACHE_KEY_URL`) לכ-24
-שעות דרך Workers Cache API. אם הקוד שלכם עושה caching משלו לנתונים נגזרים (למשל חלונות עם
-buffer משלכם), כדאי להשתמש במפתח אחר - שימוש חוזר במפתח הזה יגרום בשקט להחזרת נתונים ישנים
-ולא-מעובדים למשך עד 24 שעות.
+(`https://internal.cache/shabbat-gate-windows-v2`, מיוצא בשם `INTERNAL_CACHE_KEY_URL`) דרך
+Workers Cache API - טרייה לכ-24 שעות, ואחר כך מוגשת ישנה תוך כדי רענון. אם הקוד שלכם עושה
+caching משלו לנתונים נגזרים (למשל חלונות עם buffer משלכם), כדאי להשתמש במפתח אחר - שימוש חוזר
+במפתח הזה יגרום בשקט להחזרת נתונים ישנים ולא-מעובדים.
 
 ## היסטוריית שינויים
 

package/README.md

@@ -37,6 +37,35 @@ const gate = createShabbatGate({ siteName: 'My Site' });
 export const onRequest: PagesFunction = (context) => gate(context);
 ```
 
+### When the site already has a `functions/_middleware`
+
+Cloudflare Pages runs **only one** middleware file at the root of `functions/`. If two exist
+(`_middleware.js` **and** `_middleware.ts`), Cloudflare silently picks one and the other never
+runs - no error, no warning. So **do not add a second file**. `gate` calls `context.next()`
+itself, which means it is already a composable middleware primitive: export the root
+`onRequest` as an **array** of handlers and Cloudflare runs them in order, each calling
+`next()`. For example, chaining a preview-noindex guard before the gate:
+
+```js
+import { createShabbatGate } from 'shabbat-gate';
+
+const PROD_HOSTS = new Set(['example.com', 'www.example.com']);
+
+const noindex = async ({ request, next }) => {
+  const res = await next();
+  if (PROD_HOSTS.has(new URL(request.url).hostname)) return res;
+  const tagged = new Response(res.body, res);
+  tagged.headers.set('X-Robots-Tag', 'noindex, nofollow');
+  return tagged;
+};
+
+const gate = createShabbatGate({ siteName: 'My Site' });
+
+export const onRequest = [noindex, (context) => gate(context)];
+```
+
+No manual `next()` wrapping is needed - the gate participates in the chain as-is.
+
 ### Using with a plain Worker + Assets binding (not Pages)
 
 `createShabbatGate` returns a Pages-Functions-shaped handler (`(context) => Response`), which
@@ -50,13 +79,18 @@ import { createShabbatGateForWorker } from 'shabbat-gate';
 const gate = createShabbatGateForWorker({ siteName: 'My Site' });
 
 export default {
-  async fetch(request: Request, env: { ASSETS: Fetcher }) {
-    const blocked = await gate(request);
+  async fetch(request: Request, env: { ASSETS: Fetcher }, ctx: ExecutionContext) {
+    const blocked = await gate(request, ctx);
     return blocked ?? env.ASSETS.fetch(request);
   },
 };
 ```
 
+Passing `ctx` is optional but recommended: it's what lets a stale window list refresh *after*
+the response is sent (see [Resilience](#resilience-timeouts-and-stale-while-revalidate)) instead
+of the refresh being cancelled when the invocation ends. `createShabbatGate` (Pages) gets this
+automatically from its own `context`.
+
 **Gotcha that silently defeats the whole gate:** a Cloudflare Worker with an `assets` binding
 serves any request matching a file in the assets directory *directly*, without invoking the
 Worker's `fetch` handler at all - unless `run_worker_first: true` is set. Without it, the gate
@@ -127,6 +161,12 @@ export interface ShabbatGateConfig {
    *  the Israel-only decision when a request has no geolocation (local dev,
    *  unplaceable IP). */
   enforceVisitorLocation?: boolean;
+
+  /** How long to wait for Hebcal before giving up and failing open (default
+   *  3000ms). Only ever paid on a cold cache - once warm, an expired window list
+   *  is served immediately and refreshed in the background, so this timeout never
+   *  lands on a visitor's request. */
+  hebcalTimeoutMs?: number;
 }
 ```
 
@@ -184,13 +224,35 @@ export const onRequest: PagesFunction = (context) => gate(context);
    the real site through.
 7. Any error along the way falls through to the real site.
 
+## Resilience: timeouts and stale-while-revalidate
+
+The gate depends on a third-party API (Hebcal) on the critical path of every page load, so it
+is built so that Hebcal being unavailable - or, more dangerously, being *slow* - cannot take
+the site down with it.
+
+- **The Hebcal request is aborted after `hebcalTimeoutMs` (default 3s).** A slow upstream is
+  worse than a failing one: a `fetch` with no abort never settles, the Worker invocation runs
+  past its limit, and Cloudflare returns **504** to the visitor - the fail-open `try/catch`
+  never runs, because a `try/catch` rescues a rejection, never a hang. Aborting turns the hang
+  into a rejection the gate can fail open on. (This is not hypothetical; see the 0.4.0 entry in
+  the changelog.)
+- **Stale-while-revalidate.** A visitor only ever waits on Hebcal when there is nothing usable
+  cached at all. Windows are fetched 45 days ahead, so once the cache is warm an expired list
+  is served *immediately* and refreshed in the background via `waitUntil` - a slow upstream
+  never sits on a visitor's request. Stale windows are served for up to 7 days.
+- **Failures are cached for 60s.** Otherwise every concurrent visitor starts their own request
+  against an upstream that is already struggling, which is what turns one slow response into a
+  cluster of 504s.
+- **Concurrent fetches are deduped** per cache key within an isolate, so a cold start opens one
+  connection rather than one per in-flight request.
+
 ## Internal cache key
 
 The merged window list is cached under a fixed internal key
-(`https://internal.cache/shabbat-gate-windows-v1`, exported as `INTERNAL_CACHE_KEY_URL`) for
-~24h via the Workers Cache API. If your own code also caches derived data (e.g. windows with
-your own buffer applied) via `caches.default`, use a different key - reusing this one will
-silently serve stale, unprocessed data for up to 24h.
+(`https://internal.cache/shabbat-gate-windows-v2`, exported as `INTERNAL_CACHE_KEY_URL`) via
+the Workers Cache API - fresh for ~24h, then served stale while it refreshes. If your own code
+also caches derived data (e.g. windows with your own buffer applied) via `caches.default`, use
+a different key - reusing this one will silently serve stale, unprocessed data.
 
 ## Changelog
 

package/dist/hebcal.d.ts

@@ -71,6 +71,25 @@ export interface FetchWindowsOptions {
      *  `latitude`/`longitude` are ignored when it is present. Jerusalem=281184,
      *  Haifa=294801, Tel Aviv=293397, Beer Sheva=295530. */
     geonameid?: number;
+    /** How long to wait for Hebcal before aborting the request (default 3000ms).
+     *
+     *  A *slow* upstream is more dangerous here than a failing one: without an
+     *  abort the fetch never settles, the Worker invocation runs past its limit,
+     *  and Cloudflare returns 504 to the visitor - the gate's fail-open catch
+     *  never runs, because a try/catch rescues a rejection, never a hang. This
+     *  is not hypothetical: it took a site's homepage down in production on
+     *  2026-07-28. Aborting converts the hang into a rejection the caller can
+     *  fail open on. */
+    timeoutMs?: number;
+}
+/** Conservative default: Hebcal normally answers in well under a second, and
+ *  the answer only has to be waited for on a cold cache anyway. */
+export declare const DEFAULT_HEBCAL_TIMEOUT_MS = 3000;
+/** Thrown when the Hebcal request is aborted by {@link FetchWindowsOptions.timeoutMs}.
+ *  A distinct class (and a `shabbat-gate: hebcal timeout` message) so the next
+ *  occurrence is greppable in Workers logs, separately from other failures. */
+export declare class HebcalTimeoutError extends Error {
+    constructor(timeoutMs: number);
 }
 /**
  * Fetches and merges Shabbat + major-holiday windows for the next ~45 days from

package/dist/hebcal.js

@@ -60,6 +60,18 @@ export function pairWindows(items, defaults) {
 function toISODate(date) {
     return date.toISOString().slice(0, 10);
 }
+/** Conservative default: Hebcal normally answers in well under a second, and
+ *  the answer only has to be waited for on a cold cache anyway. */
+export const DEFAULT_HEBCAL_TIMEOUT_MS = 3000;
+/** Thrown when the Hebcal request is aborted by {@link FetchWindowsOptions.timeoutMs}.
+ *  A distinct class (and a `shabbat-gate: hebcal timeout` message) so the next
+ *  occurrence is greppable in Workers logs, separately from other failures. */
+export class HebcalTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`shabbat-gate: hebcal timeout after ${timeoutMs}ms`);
+        this.name = 'HebcalTimeoutError';
+    }
+}
 /**
  * Fetches and merges Shabbat + major-holiday windows for the next ~45 days from
  * Hebcal's free public JSON API. Defaults to Israel single-day Yom Tov mode at
@@ -98,13 +110,32 @@ export async function fetchWindows(latitude, longitude, options = {}) {
     const url = `https://www.hebcal.com/hebcal?cfg=json&v=1&maj=on&min=off&mod=off&nx=off&mf=off&ss=on` +
         `&c=on&i=${iParam}&${locationParam}&tzid=${encodeURIComponent(tzid)}` +
         `&start=${startParam}&end=${endParam}`;
-    const res = await fetch(url);
-    if (!res.ok) {
-        throw new Error(`hebcal fetch failed: ${res.status}`);
+    // The abort has to stay armed across `res.json()` too, not just the initial
+    // response - a stalled body stream hangs the invocation just as effectively
+    // as a stalled connection.
+    const timeoutMs = options.timeoutMs ?? DEFAULT_HEBCAL_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, { signal: controller.signal });
+        if (!res.ok) {
+            throw new Error(`hebcal fetch failed: ${res.status}`);
+        }
+        const data = (await res.json());
+        const windows = pairWindows(data.items ?? [], { label: SHABBAT_LABEL, closingLabel: SHABBAT_CLOSING_LABEL });
+        return windows.sort((a, b) => a.start - b.start);
+    }
+    catch (error) {
+        // Any rejection after the abort fired is the abort, whatever shape the
+        // runtime's error takes (DOMException in Workers, TypeError elsewhere).
+        if (controller.signal.aborted) {
+            throw new HebcalTimeoutError(timeoutMs);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
     }
-    const data = (await res.json());
-    const windows = pairWindows(data.items ?? [], { label: SHABBAT_LABEL, closingLabel: SHABBAT_CLOSING_LABEL });
-    return windows.sort((a, b) => a.start - b.start);
 }
 /**
  * Coalesces overlapping/touching windows into continuous ones. Needed when two

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { type HoldingPageContext } from './holdingPage.js';
 export type { Window, FetchWindowsOptions } from './hebcal.js';
 export type { HoldingPageContext, SecondaryMessage } from './holdingPage.js';
 export type { SupportedLanguage } from './translations.js';
-export { isBlocked, findActiveWindow, mergeWindows, pairWindows, fetchWindows } from './hebcal.js';
+export { isBlocked, findActiveWindow, mergeWindows, pairWindows, fetchWindows, HebcalTimeoutError, DEFAULT_HEBCAL_TIMEOUT_MS, } from './hebcal.js';
 export { SUPPORTED_LANGUAGES, resolveVisitorLanguage } from './translations.js';
 export { isBot, BOT_PATTERN } from './botPattern.js';
 export { defaultRenderHoldingPage } from './holdingPage.js';
@@ -46,13 +46,19 @@ export interface ShabbatGateConfig {
      *  unavailable for a request (e.g. local `wrangler dev`, or an IP Cloudflare
      *  can't place), that request falls back to the Israel-only decision. */
     enforceVisitorLocation?: boolean;
+    /** How long to wait for Hebcal before giving up and failing open (default
+     *  3000ms). Only ever paid on a cold cache - once warm, an expired window
+     *  list is served immediately and refreshed in the background, so this
+     *  timeout never lands on a visitor's request. Raise it only if you'd rather
+     *  a cold visitor wait than risk a missed block. */
+    hebcalTimeoutMs?: number;
 }
 /** Internal cache key for the merged window list (~24h TTL via the Workers
  *  Cache API). Exported so consumers that do their own caching of
  *  derived/post-processed window data (e.g. after applying their own buffer)
  *  can pick a different key and avoid accidentally colliding with this one -
  *  which would silently serve stale, unprocessed windows for up to 24h. */
-export declare const INTERNAL_CACHE_KEY_URL = "https://internal.cache/shabbat-gate-windows-v1";
+export declare const INTERNAL_CACHE_KEY_URL = "https://internal.cache/shabbat-gate-windows-v2";
 /**
  * Returns a Cloudflare Pages Functions-compatible handler that closes the
  * site to human visitors during Shabbat and major Jewish holidays, while
@@ -71,13 +77,19 @@ export declare function createShabbatGate(config: ShabbatGateConfig): PagesFunct
  *   const gate = createShabbatGateForWorker({ siteName: 'My Site' });
  *   export default {
  *     async fetch(request, env, ctx) {
- *       const blocked = await gate(request);
+ *       const blocked = await gate(request, ctx);
  *       return blocked ?? env.ASSETS.fetch(request);
  *     },
  *   };
  *
+ * Passing `ctx` is optional but recommended: it's what lets a stale window
+ * list refresh in the background after the response is sent, instead of the
+ * refresh being cancelled when the invocation ends.
+ *
  * Note: a Worker with an `assets` binding skips the `fetch` handler entirely
  * for requests matching a static asset unless `assets.run_worker_first: true`
  * is set in `wrangler.jsonc` - without it, this gate never runs.
  */
-export declare function createShabbatGateForWorker(config: ShabbatGateConfig): (request: Request) => Promise<Response | null>;
+export declare function createShabbatGateForWorker(config: ShabbatGateConfig): (request: Request, ctx?: {
+    waitUntil(promise: Promise<unknown>): void;
+}) => Promise<Response | null>;

package/dist/index.js

@@ -2,7 +2,7 @@ import { isBot } from './botPattern.js';
 import { fetchWindows, findActiveWindow, mergeWindows, SHABBAT_LABEL } from './hebcal.js';
 import { defaultRenderHoldingPage } from './holdingPage.js';
 import { buildSecondaryMessage, resolveVisitorLanguage } from './translations.js';
-export { isBlocked, findActiveWindow, mergeWindows, pairWindows, fetchWindows } from './hebcal.js';
+export { isBlocked, findActiveWindow, mergeWindows, pairWindows, fetchWindows, HebcalTimeoutError, DEFAULT_HEBCAL_TIMEOUT_MS, } from './hebcal.js';
 export { SUPPORTED_LANGUAGES, resolveVisitorLanguage } from './translations.js';
 export { isBot, BOT_PATTERN } from './botPattern.js';
 export { defaultRenderHoldingPage } from './holdingPage.js';
@@ -13,30 +13,140 @@ const JERUSALEM_LONGITUDE = 35.2137;
  *  derived/post-processed window data (e.g. after applying their own buffer)
  *  can pick a different key and avoid accidentally colliding with this one -
  *  which would silently serve stale, unprocessed windows for up to 24h. */
-export const INTERNAL_CACHE_KEY_URL = 'https://internal.cache/shabbat-gate-windows-v1';
+export const INTERNAL_CACHE_KEY_URL = 'https://internal.cache/shabbat-gate-windows-v2';
 /** Cache-key prefix for per-visitor-location window lists. Keyed by rounded
  *  coordinates + timezone + reckoning so all visitors within ~1° of each other
  *  share one cached fetch (sunset differs by only a few minutes across a cell -
  *  immaterial at "block the whole site or not" granularity). */
-const VISITOR_CACHE_KEY_PREFIX = 'https://internal.cache/shabbat-gate-visitor-v1';
+const VISITOR_CACHE_KEY_PREFIX = 'https://internal.cache/shabbat-gate-visitor-v2';
+/** How long a cached window list counts as fresh. Past this it is still served
+ *  (see stale-while-revalidate below) while a refresh runs out of band. */
 const CACHE_TTL_SECONDS = 24 * 60 * 60;
-/** Fetch a window list through the Workers Cache API under a fixed key. */
-async function getCachedWindows(cacheKeyUrl, fetcher) {
-    const cache = caches.default;
-    const cacheRequest = new Request(cacheKeyUrl);
-    const cached = await cache.match(cacheRequest);
-    if (cached) {
-        return (await cached.json());
+/** How long a *stale* list may still be served. Windows are fetched 45 days
+ *  ahead, so a week-old list is still correct for the next ~38 days - serving
+ *  it is strictly better than making a visitor wait on a slow upstream. Also
+ *  the Cache API `max-age`, so anything older stops matching entirely and the
+ *  next request refetches synchronously. */
+const CACHE_MAX_STALE_SECONDS = 7 * 24 * 60 * 60;
+/** After a failed or timed-out fetch, don't try again for this long. Without
+ *  it, every concurrent visitor starts their own request against an upstream
+ *  that is already struggling - the thundering herd that turned one slow
+ *  Hebcal response into a cluster of 504s in production on 2026-07-28. */
+const CACHE_FAILURE_TTL_SECONDS = 60;
+/** In-flight fetches per cache key, deduped within this isolate. The Cache API
+ *  only helps once a fetch has *finished*; on a cold start every concurrent
+ *  request would otherwise open its own connection. */
+const inFlightFetches = new Map();
+async function readCacheRecord(cacheKeyUrl) {
+    try {
+        const cached = await caches.default.match(new Request(cacheKeyUrl));
+        if (!cached) {
+            return null;
+        }
+        const body = (await cached.json());
+        if (!body || typeof body !== 'object' || !('fetchedAt' in body)) {
+            return null;
+        }
+        return {
+            windows: Array.isArray(body.windows) ? body.windows : null,
+            fetchedAt: typeof body.fetchedAt === 'number' ? body.fetchedAt : 0,
+            failedAt: typeof body.failedAt === 'number' ? body.failedAt : undefined,
+        };
+    }
+    catch {
+        // A corrupt/unreadable entry must not take the site down - treat it as a
+        // miss and refetch.
+        return null;
     }
-    const windows = await fetcher();
-    const cacheResponse = new Response(JSON.stringify(windows), {
+}
+async function writeCacheRecord(cacheKeyUrl, record) {
+    // A record with no usable windows is only a "don't retry yet" marker, so it
+    // must expire quickly; a real list should outlive its freshness window so it
+    // can still be served stale.
+    const maxAge = record.windows ? CACHE_MAX_STALE_SECONDS : CACHE_FAILURE_TTL_SECONDS;
+    await caches.default.put(new Request(cacheKeyUrl), new Response(JSON.stringify(record), {
         headers: {
             'content-type': 'application/json',
-            'cache-control': `max-age=${CACHE_TTL_SECONDS}`,
+            'cache-control': `max-age=${maxAge}`,
         },
+    }));
+}
+/** Runs (or joins) the single in-flight fetch for this key and records the
+ *  outcome - success or failure - in the cache. Rejects on failure; callers
+ *  decide whether that's fatal (cold start -> fail open) or ignorable
+ *  (background refresh -> keep serving stale). */
+function refreshWindows(cacheKeyUrl, fetcher, existing) {
+    const pending = inFlightFetches.get(cacheKeyUrl);
+    if (pending) {
+        return pending;
+    }
+    const attempt = (async () => {
+        let windows;
+        try {
+            windows = await fetcher();
+        }
+        catch (error) {
+            // Remember the failure so the next visitors don't pile onto a struggling
+            // upstream - but never discard windows we already have. Recording it is
+            // best-effort; if even that fails, the original error is what matters.
+            await writeCacheRecord(cacheKeyUrl, {
+                windows: existing?.windows ?? null,
+                fetchedAt: existing?.fetchedAt ?? 0,
+                failedAt: Date.now(),
+            }).catch(() => undefined);
+            throw error;
+        }
+        // Caching is an optimization, not a precondition: a cache write that fails
+        // must not throw away windows we successfully fetched.
+        await writeCacheRecord(cacheKeyUrl, { windows, fetchedAt: Date.now() }).catch((error) => {
+            console.error('shabbat-gate: could not cache windows', error);
+        });
+        return windows;
+    })();
+    inFlightFetches.set(cacheKeyUrl, attempt);
+    return attempt.finally(() => {
+        inFlightFetches.delete(cacheKeyUrl);
     });
-    await cache.put(cacheRequest, cacheResponse);
-    return windows;
+}
+function failedRecently(record, now) {
+    return record?.failedAt != null && now - record.failedAt < CACHE_FAILURE_TTL_SECONDS * 1000;
+}
+/**
+ * Fetch a window list through the Workers Cache API under a fixed key, with
+ * stale-while-revalidate: a visitor only ever waits on Hebcal when there is
+ * nothing usable cached at all. Once warm, an expired list is served
+ * immediately and refreshed in the background via `waitUntil`, so a slow
+ * upstream can never sit on a visitor's request.
+ */
+async function getCachedWindows(cacheKeyUrl, fetcher, waitUntil) {
+    const record = await readCacheRecord(cacheKeyUrl);
+    const now = Date.now();
+    if (record?.windows) {
+        if (now - record.fetchedAt < CACHE_TTL_SECONDS * 1000) {
+            return record.windows;
+        }
+        // Stale but usable: hand it back now, refresh out of band. Everything here
+        // is best-effort - a refresh that can't even be scheduled must not cost
+        // this visitor the perfectly good windows we're already holding.
+        if (!failedRecently(record, now)) {
+            const refreshing = refreshWindows(cacheKeyUrl, fetcher, record).catch((error) => {
+                console.error('shabbat-gate: background window refresh failed', error);
+            });
+            try {
+                waitUntil?.(refreshing);
+            }
+            catch (error) {
+                console.error('shabbat-gate: could not schedule background refresh', error);
+            }
+        }
+        return record.windows;
+    }
+    // Nothing usable cached. If an attempt just failed, fail open right away
+    // rather than making this visitor wait on an upstream we know is unhealthy.
+    if (failedRecently(record, now)) {
+        throw new Error('shabbat-gate: skipping hebcal retry, a recent fetch failed');
+    }
+    return refreshWindows(cacheKeyUrl, fetcher, record);
 }
 /** Reads the visitor's geolocation from Cloudflare's `request.cf`. Returns
  *  `null` when any needed field is missing/unparseable (local dev, an IP CF
@@ -60,17 +170,17 @@ function readVisitorLocation(request) {
  *  site's own times come from Hebcal's official city times (and the cache key is
  *  namespaced by it so switching location doesn't serve stale coordinate-based
  *  windows for up to 24h). */
-function getIsraelWindows(latitude, longitude, geonameid) {
+function getIsraelWindows(latitude, longitude, geonameid, timeoutMs, waitUntil) {
     const cacheKey = geonameid != null ? `${INTERNAL_CACHE_KEY_URL}?geonameid=${geonameid}` : INTERNAL_CACHE_KEY_URL;
-    return getCachedWindows(cacheKey, () => fetchWindows(latitude, longitude, geonameid != null ? { geonameid } : {}));
+    return getCachedWindows(cacheKey, () => fetchWindows(latitude, longitude, { ...(geonameid != null ? { geonameid } : {}), timeoutMs }), waitUntil);
 }
 /** Windows for a specific visitor location, cached per rounded cell. */
-function getVisitorWindows(loc) {
+function getVisitorWindows(loc, timeoutMs, waitUntil) {
     const rlat = Math.round(loc.latitude);
     const rlon = Math.round(loc.longitude);
     const iParam = loc.israelMode ? 'on' : 'off';
     const cacheKey = `${VISITOR_CACHE_KEY_PREFIX}?lat=${rlat}&lon=${rlon}&tz=${encodeURIComponent(loc.tzid)}&i=${iParam}`;
-    return getCachedWindows(cacheKey, () => fetchWindows(loc.latitude, loc.longitude, { israelMode: loc.israelMode, tzid: loc.tzid }));
+    return getCachedWindows(cacheKey, () => fetchWindows(loc.latitude, loc.longitude, { israelMode: loc.israelMode, tzid: loc.tzid, timeoutMs }), waitUntil);
 }
 function formatTime(epochMs, tzid) {
     return new Intl.DateTimeFormat('he-IL', {
@@ -95,7 +205,7 @@ function applyBuffer(windows, bufferMinutes) {
  * around this, so neither can drift out of sync on caching/fail-open/bypass
  * behavior.
  */
-async function evaluateGate(config, request) {
+async function evaluateGate(config, request, waitUntil) {
     const userAgent = request.headers.get('user-agent') ?? '';
     if (isBot(userAgent)) {
         return { type: 'pass' };
@@ -115,9 +225,9 @@ async function evaluateGate(config, request) {
         // local-time display shown to a visitor outside Israel.
         const visitor = readVisitorLocation(request);
         const isAbroad = visitor !== null && !visitor.israelMode;
-        let windows = applyBuffer(await getIsraelWindows(latitude, longitude, config.geonameid), bufferMinutes);
+        let windows = applyBuffer(await getIsraelWindows(latitude, longitude, config.geonameid, config.hebcalTimeoutMs, waitUntil), bufferMinutes);
         if (config.enforceVisitorLocation && visitor) {
-            const visitorWindows = applyBuffer(await getVisitorWindows(visitor), bufferMinutes);
+            const visitorWindows = applyBuffer(await getVisitorWindows(visitor, config.hebcalTimeoutMs, waitUntil), bufferMinutes);
             // Union of both calendars: block if it's Shabbat/Yom Tov in Israel OR
             // where the visitor is. Merge coalesces the overlap into one continuous
             // block so the shown reopen time is the true end of both.
@@ -162,7 +272,7 @@ async function evaluateGate(config, request) {
  */
 export function createShabbatGate(config) {
     return async (context) => {
-        const decision = await evaluateGate(config, context.request);
+        const decision = await evaluateGate(config, context.request, (promise) => context.waitUntil(promise));
         if (decision.type === 'pass') {
             return context.next();
         }
@@ -182,18 +292,22 @@ export function createShabbatGate(config) {
  *   const gate = createShabbatGateForWorker({ siteName: 'My Site' });
  *   export default {
  *     async fetch(request, env, ctx) {
- *       const blocked = await gate(request);
+ *       const blocked = await gate(request, ctx);
  *       return blocked ?? env.ASSETS.fetch(request);
  *     },
  *   };
  *
+ * Passing `ctx` is optional but recommended: it's what lets a stale window
+ * list refresh in the background after the response is sent, instead of the
+ * refresh being cancelled when the invocation ends.
+ *
  * Note: a Worker with an `assets` binding skips the `fetch` handler entirely
  * for requests matching a static asset unless `assets.run_worker_first: true`
  * is set in `wrangler.jsonc` - without it, this gate never runs.
  */
 export function createShabbatGateForWorker(config) {
-    return async (request) => {
-        const decision = await evaluateGate(config, request);
+    return async (request, ctx) => {
+        const decision = await evaluateGate(config, request, ctx ? (p) => ctx.waitUntil(p) : undefined);
         if (decision.type === 'pass') {
             return null;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shabbat-gate",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Cloudflare Pages/Workers middleware that closes a site to human visitors during Shabbat and major Jewish holidays (Israel-observance rules), while always letting search engines and AI crawlers through.",
   "type": "module",
   "main": "./dist/index.js",