Cloudflare.WaitingRoom reference

Settings

Source: src/Cloudflare/WaitingRoom/Settings.ts

Zone-wide Cloudflare Waiting Room settings (/zones/{zone_id}/waiting_rooms/settings).

The settings object is a zone singleton — it always exists with Cloudflare defaults, so this resource never creates or deletes anything physical. Reconcile PUTs the settings when the observed value differs from the desired one; destroy restores the value the zone had before Alchemy first managed it.

Writes are plan-gated: on zones without a Waiting Rooms entitlement (Business/Enterprise) every PUT fails with the typed ZoneNotEntitled error (Cloudflare code 1034). Reads work on every plan, and a no-op reconcile (desired equals observed) skips the API call entirely.

Settings: Managing settings

Let search engine crawlers bypass waiting rooms

yield* Cloudflare.WaitingRoom.Settings("CrawlerBypass", {
  zoneId: zone.zoneId,
  searchEngineCrawlerBypass: true,
});

Pin the settings to their defaults

yield* Cloudflare.WaitingRoom.Settings("Defaults", {
  zoneId: zone.zoneId,
  searchEngineCrawlerBypass: false,
});

WaitingRoom

Source: src/Cloudflare/WaitingRoom/WaitingRoom.ts

A Cloudflare Waiting Room — places visitors in a virtual queue when traffic to a host + path exceeds the configured thresholds, protecting the origin from overload.

Waiting Rooms require a Business or Enterprise zone plan; on unentitled zones every write fails with the typed ZoneNotEntitled error (Cloudflare code 1034). Several props (additionalRoutes, customPageHtml, non-fifo queueingMethod, disableSessionRenewal, jsonResponseEnabled) additionally require the Waiting Room Advanced subscription.

Everything except the zone is mutable in place via a full-body PUT. Waiting rooms carry no ownership markers, so when state is lost read matches by name and reports the room as Unowned — the engine refuses to take it over unless --adopt (or adopt(true)) is set.

WaitingRoom: Creating a Waiting Room

Basic waiting room on a host

const room = yield* Cloudflare.WaitingRoom.WaitingRoom("checkout", {
  zoneId: zone.zoneId,
  host: "shop.example.com",
  path: "/checkout",
  totalActiveUsers: 200,
  newUsersPerMinute: 200,
});

Queue all traffic during an incident

yield* Cloudflare.WaitingRoom.WaitingRoom("incident-gate", {
  zoneId: zone.zoneId,
  host: "example.com",
  totalActiveUsers: 500,
  newUsersPerMinute: 200,
  queueAll: true,
  queueingStatusCode: 429,
});

WaitingRoom: Customizing behavior

yield* Cloudflare.WaitingRoom.WaitingRoom("flash-sale", {
  zoneId: zone.zoneId,
  host: "example.com",
  path: "/sale",
  totalActiveUsers: 1000,
  newUsersPerMinute: 500,
  sessionDuration: 1,
  cookieSuffix: "sale",
  defaultTemplateLanguage: "de-DE",
});