homura-runtime 0.1.0

data/lib/cloudflare_workers/queue.rb

@@ -0,0 +1,407 @@
+# frozen_string_literal: true
+# backtick_javascript: true
+# await: true
+#
+# Phase 11B — Cloudflare Queues binding wrapper.
+#
+# Cloudflare Queues let a Worker send messages to a persistent queue
+# and another Worker (or the same one) consume them in batches.
+#
+#   Producer side:
+#     env.JOBS_QUEUE.send(body, options)
+#     env.JOBS_QUEUE.sendBatch(messages, options)
+#
+#   Consumer side (worker.mjs):
+#     export default { async queue(batch, env, ctx) { ... } }
+#     // batch.messages[i].body           — the payload
+#     // batch.messages[i].ack()          — per-message ack
+#     // batch.messages[i].retry()        — retry with backoff
+#     // batch.ackAll() / batch.retryAll()
+#
+# This file provides:
+#
+#   1. `Cloudflare::Queue` — a Ruby wrapper around the producer binding
+#      (`env.JOBS_QUEUE`). `#send(body, delay_seconds:, content_type:)`
+#      and `#send_batch(messages)` return JS Promises.
+#
+#   2. `Cloudflare::QueueBatch` / `Cloudflare::QueueMessage` — Ruby
+#      views over the JS batch passed to the `queue()` export. Each
+#      message exposes `.body` (parsed if JSON), `.id`, `.timestamp`,
+#      `.ack` / `.retry`.
+#
+#   3. A dispatcher hook (`globalThis.__HOMURA_QUEUE_DISPATCH__`)
+#      that `src/worker.mjs#queue` calls once per incoming batch. It
+#      walks `App.consume_queue_handlers` (registered via the
+#      `consume_queue 'queue-name' do |batch| ... end` DSL in
+#      lib/sinatra/queue.rb) and invokes whichever matches the batch's
+#      `queue` name.
+
+require 'json'
+
+module Cloudflare
+  class QueueError < StandardError
+    attr_reader :operation, :queue
+    def initialize(message, operation: nil, queue: nil)
+      @operation = operation
+      @queue = queue
+      super("[Cloudflare::Queue] queue=#{queue || '?'} op=#{operation || 'send'}: #{message}")
+    end
+  end
+
+  # Producer wrapper. The binding's JS API:
+  #   env.JOBS_QUEUE.send(body, options?)            — one message
+  #   env.JOBS_QUEUE.sendBatch(messages, options?)   — multiple
+  # Each returns a JS Promise resolving to undefined.
+  class Queue
+    attr_reader :js, :name
+
+    def initialize(js, name = nil)
+      @js = js
+      @name = (name || 'queue').to_s
+    end
+
+    def available?
+      js = @js
+      # Opal's Ruby nil is a runtime sentinel (Opal.nil), not JS null.
+      # See `lib/cloudflare_workers/cache.rb#available?` for the same
+      # pattern and rationale.
+      !!`(#{js} !== null && #{js} !== undefined && #{js} !== Opal.nil)`
+    end
+
+    # Send one message. `body` may be any JSON-serialisable Ruby value.
+    # Strings / numbers / booleans pass through; Hashes / Arrays are
+    # sent as plain JS objects (Workers Queues natively encodes them
+    # via structured clone).
+    #
+    #   delay_seconds: 60   # schedule for ~1 minute from now
+    #   content_type: "json" (default) | "text" | "bytes"
+    def send(body, delay_seconds: nil, content_type: nil)
+      js = @js
+      qname = @name
+      err_klass = Cloudflare::QueueError
+      raise QueueError.new('queue binding not bound', operation: 'send', queue: qname) unless available?
+
+      js_body = ruby_to_js(body)
+      js_opts = `({})`
+      `#{js_opts}.delaySeconds = #{delay_seconds.to_i}` if delay_seconds
+      `#{js_opts}.contentType  = #{content_type.to_s}`  if content_type
+
+      # Single-line IIFE — see `lib/cloudflare_workers/cache.rb#put`
+      # for the Opal multi-line x-string quirk. Passing arguments in
+      # explicitly (rather than interpolating inside the template)
+      # keeps the Promise a first-class expression.
+      `(async function(js, body, opts, qname, Kernel, err_klass) { try { await js.send(body, opts); } catch (e) { Kernel.$raise(err_klass.$new(e && e.message ? e.message : String(e), Opal.hash({ operation: 'send', queue: qname }))); } return null; })(#{js}, #{js_body}, #{js_opts}, #{qname}, #{Kernel}, #{err_klass})`
+    end
+
+    # Send an Array of {body:, delay_seconds?, content_type?} Hashes
+    # or plain bodies as a single batch.
+    def send_batch(messages, delay_seconds: nil)
+      js = @js
+      qname = @name
+      err_klass = Cloudflare::QueueError
+      raise QueueError.new('queue binding not bound', operation: 'send_batch', queue: qname) unless available?
+
+      js_msgs = `([])`
+      messages.each do |m|
+        if m.is_a?(Hash)
+          body = m['body'] || m[:body]
+          ct   = m['content_type'] || m[:content_type]
+          ds   = m['delay_seconds'] || m[:delay_seconds]
+          js_body = ruby_to_js(body)
+          js_msg = `({ body: #{js_body} })`
+          `#{js_msg}.contentType  = #{ct.to_s}` if ct
+          `#{js_msg}.delaySeconds = #{ds.to_i}` if ds
+          `#{js_msgs}.push(#{js_msg})`
+        else
+          js_body = ruby_to_js(m)
+          `#{js_msgs}.push({ body: #{js_body} })`
+        end
+      end
+      js_opts = `({})`
+      `#{js_opts}.delaySeconds = #{delay_seconds.to_i}` if delay_seconds
+
+      # Single-line IIFE — see `send` above for rationale.
+      `(async function(js, msgs, opts, qname, Kernel, err_klass) { try { await js.sendBatch(msgs, opts); } catch (e) { Kernel.$raise(err_klass.$new(e && e.message ? e.message : String(e), Opal.hash({ operation: 'send_batch', queue: qname }))); } return null; })(#{js}, #{js_msgs}, #{js_opts}, #{qname}, #{Kernel}, #{err_klass})`
+    end
+
+    private
+
+    # Same Ruby→JS conversion that Cloudflare::AI.ruby_to_js uses, but
+    # local to avoid cross-wrapper coupling.
+    def ruby_to_js(val)
+      return val if val.is_a?(String) || val.is_a?(Numeric) || val == true || val == false || val.nil?
+      if val.is_a?(Symbol)
+        return val.to_s
+      end
+      if val.is_a?(Hash)
+        obj = `({})`
+        val.each do |k, v|
+          ks = k.to_s
+          jv = ruby_to_js(v)
+          `#{obj}[#{ks}] = #{jv}`
+        end
+        return obj
+      end
+      if val.is_a?(Array)
+        arr = `([])`
+        val.each { |v| jv = ruby_to_js(v); `#{arr}.push(#{jv})` }
+        return arr
+      end
+      val
+    end
+  end
+
+  # Represents one message inside a queue batch. Wraps the JS message
+  # object so user code can call `.body`, `.id`, `.ack`, `.retry`.
+  class QueueMessage
+    attr_reader :js
+
+    def initialize(js)
+      @js = js
+    end
+
+    def id
+      js = @js
+      `(#{js} && #{js}.id ? String(#{js}.id) : '')`
+    end
+
+    def timestamp
+      js = @js
+      ms = `(#{js} && #{js}.timestamp && typeof #{js}.timestamp.getTime === 'function' ? #{js}.timestamp.getTime() : null)`
+      return nil if `#{ms} == null`
+      Time.at(ms.to_f / 1000.0)
+    end
+
+    # Parsed body. Workers Queues gives us the structured clone of
+    # whatever the producer sent, so this is usually already a Ruby
+    # Hash / Array after crossing the JS<->Ruby boundary. Raw
+    # strings pass through untouched — we deliberately do NOT attempt
+    # to `JSON.parse` an opaque String here because Workers Queues
+    # already structure-clones producer payloads, so a String body
+    # means the producer really meant a String. Callers that did
+    # encode a JSON string themselves can `JSON.parse(msg.body)` at
+    # the call site.
+    #
+    # (Copilot review PR #9 flagged the earlier "JSON-looking strings
+    # are parsed" comment — fixed by removing that claim.)
+    def body
+      return @body if defined?(@body)
+      js = @js
+      raw = `(#{js} && typeof #{js}.body !== 'undefined' ? #{js}.body : null)`
+      @body = js_to_ruby(raw)
+    end
+
+    # Raw body as it came from JS — useful when the consumer wants to
+    # see the unparsed value (e.g. a JSON string stored as-is).
+    def raw_body
+      js = @js
+      `(#{js} && typeof #{js}.body !== 'undefined' ? #{js}.body : null)`
+    end
+
+    # Queues API: mark this message as successfully handled.
+    def ack
+      js = @js
+      `(#{js} && typeof #{js}.ack === 'function' ? #{js}.ack() : null)`
+      nil
+    end
+
+    # Queues API: request a retry. `delay_seconds:` caps the retry
+    # backoff at a specific value.
+    def retry(delay_seconds: nil)
+      js = @js
+      if delay_seconds
+        ds = delay_seconds.to_i
+        `(#{js} && typeof #{js}.retry === 'function' ? #{js}.retry({ delaySeconds: #{ds} }) : null)`
+      else
+        `(#{js} && typeof #{js}.retry === 'function' ? #{js}.retry() : null)`
+      end
+      nil
+    end
+
+    private
+
+    def js_to_ruby(v)
+      return nil if `#{v} == null`
+      return v if `typeof #{v} === 'string' || typeof #{v} === 'number' || typeof #{v} === 'boolean'`
+      if `Array.isArray(#{v})`
+        out = []
+        len = `#{v}.length`
+        i = 0
+        while i < len
+          out << js_to_ruby(`#{v}[#{i}]`)
+          i += 1
+        end
+        return out
+      end
+      if `typeof #{v} === 'object'`
+        h = {}
+        keys = `Object.keys(#{v})`
+        len = `#{keys}.length`
+        i = 0
+        while i < len
+          k = `#{keys}[#{i}]`
+          h[k] = js_to_ruby(`#{v}[#{k}]`)
+          i += 1
+        end
+        return h
+      end
+      v
+    end
+  end
+
+  # Wraps the MessageBatch passed to `queue(batch, env, ctx)` in
+  # worker.mjs. Exposes `queue` name, an Array of QueueMessage, and
+  # batch-level ack/retry helpers.
+  class QueueBatch
+    attr_reader :js
+
+    def initialize(js)
+      @js = js
+    end
+
+    def queue
+      js = @js
+      `(#{js} && #{js}.queue ? String(#{js}.queue) : '')`
+    end
+
+    def messages
+      return @messages if @messages
+      js = @js
+      arr = `(#{js} && Array.isArray(#{js}.messages) ? #{js}.messages : [])`
+      out = []
+      len = `#{arr}.length`
+      i = 0
+      while i < len
+        out << QueueMessage.new(`#{arr}[#{i}]`)
+        i += 1
+      end
+      @messages = out
+    end
+
+    def size
+      messages.length
+    end
+
+    def ack_all
+      js = @js
+      `(#{js} && typeof #{js}.ackAll === 'function' ? #{js}.ackAll() : null)`
+      nil
+    end
+
+    def retry_all(delay_seconds: nil)
+      js = @js
+      if delay_seconds
+        ds = delay_seconds.to_i
+        `(#{js} && typeof #{js}.retryAll === 'function' ? #{js}.retryAll({ delaySeconds: #{ds} }) : null)`
+      else
+        `(#{js} && typeof #{js}.retryAll === 'function' ? #{js}.retryAll() : null)`
+      end
+      nil
+    end
+  end
+
+  # Consumer dispatcher. The Sinatra DSL (`consume_queue`) registers
+  # handlers here via `Cloudflare::QueueConsumer.register(queue_name, unbound_method)`.
+  # `src/worker.mjs#queue` calls `globalThis.__HOMURA_QUEUE_DISPATCH__`
+  # which forwards into `dispatch_js` below.
+  module QueueConsumer
+    @handlers = {}
+
+    class << self
+      attr_reader :handlers
+    end
+
+    def self.register(queue_name, unbound_method)
+      @handlers ||= {}
+      @handlers[queue_name.to_s] = unbound_method
+    end
+
+    def self.handler_for(queue_name)
+      (@handlers || {})[queue_name.to_s]
+    end
+
+    def self.handlers_by_queue
+      (@handlers || {}).dup
+    end
+
+    # Dispatcher called from the JS hook. `js_batch` is the MessageBatch,
+    # `js_env`, `js_ctx` are the Workers env and ExecutionContext.
+    # Returns a Hash summary ({ queue:, handled:, size: }) for diagnostics.
+    def self.dispatch_js(js_batch, js_env, js_ctx)
+      batch = QueueBatch.new(js_batch)
+      queue_name = batch.queue
+      handler = handler_for(queue_name)
+      if handler.nil?
+        warn "[Cloudflare::QueueConsumer] no handler registered for queue #{queue_name.inspect}; messages will time out and retry"
+        return { 'queue' => queue_name, 'handled' => false, 'size' => batch.size, 'reason' => 'no_handler' }
+      end
+
+      ctx = QueueContext.new(batch, js_env, js_ctx)
+      result = handler.bind(ctx).call(batch)
+      if `(#{result} != null && typeof #{result}.then === 'function')`
+        result = result.__await__
+      end
+      { 'queue' => queue_name, 'handled' => true, 'size' => batch.size, 'result' => result.is_a?(Hash) ? result : nil }
+    end
+
+    # Single-line backtick (see scheduled.rb for the Opal multi-line
+    # constraint). Logs+swallows thrown errors so one bad handler
+    # doesn't crash the Workers queue consumer.
+    def self.install_dispatcher
+      mod = self
+      `globalThis.__HOMURA_QUEUE_DISPATCH__ = async function(js_batch, js_env, js_ctx) { try { return await #{mod}.$dispatch_js(js_batch, js_env, js_ctx); } catch (err) { try { globalThis.console.error('[Cloudflare::QueueConsumer] dispatch failed:', err && err.stack || err); } catch (e) {} return { queue: (js_batch && js_batch.queue) || '', handled: false, size: (js_batch && Array.isArray(js_batch.messages) ? js_batch.messages.length : 0), error: String(err && err.message || err) }; } };(function(){var g=globalThis;g.__OPAL_WORKERS__=g.__OPAL_WORKERS__||{};g.__OPAL_WORKERS__.queue=g.__HOMURA_QUEUE_DISPATCH__;})();`
+    end
+  end
+
+  # `self` inside a `consume_queue do |batch| ... end` block. Exposes
+  # env / ctx helpers alongside the batch so the block can reach the
+  # same D1 / KV / R2 bindings an HTTP route would. This keeps the
+  # consumer side consistent with Phase 9's ScheduledContext.
+  class QueueContext
+    attr_reader :batch, :env, :js_env, :js_ctx
+
+    def initialize(batch, js_env, js_ctx)
+      @batch = batch
+      @js_env = js_env
+      @js_ctx = js_ctx
+      @env = build_env(js_env)
+    end
+
+    def db;     env['cloudflare.DB'];     end
+    def kv;     env['cloudflare.KV'];     end
+    def bucket; env['cloudflare.BUCKET']; end
+
+    # Hand a long-running promise to ctx.waitUntil. Mirrors the same
+    # helper in Sinatra::Scheduled's ScheduledContext.
+    def wait_until(promise)
+      return promise if @js_ctx.nil?
+      js_ctx = @js_ctx
+      `#{js_ctx}.waitUntil(#{promise})`
+      promise
+    end
+
+    private
+
+    def build_env(js_env)
+      env = {
+        'cloudflare.queue' => true,
+        'cloudflare.env'   => js_env,
+        'cloudflare.ctx'   => @js_ctx
+      }
+      # js_env is a raw JS object when called from the Workers runtime,
+      # so `.nil?` would explode with NoMethodError. Use a JS-level
+      # null/undefined/Opal.nil check instead — same pattern
+      # `Cloudflare::Cache#available?` uses.
+      return env if `(#{js_env} == null || #{js_env} === undefined || #{js_env} === Opal.nil)`
+      js_db = `#{js_env} && #{js_env}.DB`
+      js_kv = `#{js_env} && #{js_env}.KV`
+      js_r2 = `#{js_env} && #{js_env}.BUCKET`
+      env['cloudflare.DB']     = Cloudflare::D1Database.new(js_db)  if `#{js_db} != null`
+      env['cloudflare.KV']     = Cloudflare::KVNamespace.new(js_kv) if `#{js_kv} != null`
+      env['cloudflare.BUCKET'] = Cloudflare::R2Bucket.new(js_r2)    if `#{js_r2} != null`
+      env
+    end
+  end
+end
+
+Cloudflare::QueueConsumer.install_dispatcher

data/lib/cloudflare_workers/scheduled.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+# backtick_javascript: true
+# await: true
+#
+# Phase 9 — Cloudflare Workers Cron Trigger dispatcher.
+#
+# Cloudflare Workers fire `scheduled(event, env, ctx)` for each entry
+# in `wrangler.toml`'s `[triggers] crons = [...]` array. The runtime
+# guarantees `event.cron` is one of the cron expressions declared in
+# wrangler.toml; `event.scheduledTime` is the firing time as a JS
+# epoch-millis number.
+#
+# This file:
+#   1. Defines `Cloudflare::ScheduledEvent` — a Ruby wrapper around
+#      the JS ScheduledEvent so user blocks see plain Ruby values
+#      (`event.cron` -> String, `event.scheduled_time` -> Time).
+#
+#   2. Installs `globalThis.__HOMURA_SCHEDULED_DISPATCH__` — the JS
+#      hook called from `src/worker.mjs#scheduled`. The hook receives
+#      the JS event/env/ctx, builds a Ruby ScheduledEvent, and calls
+#      `Sinatra::Scheduled::ClassMethods#dispatch_scheduled` on the
+#      Rack handler's app.
+#
+#   3. Exposes `Cloudflare::Scheduled.app=` so non-Sinatra Rack apps
+#      can hook the dispatcher too. By default, `Rack::Handler::
+#      CloudflareWorkers.app` (set by `run app` in user code) is used.
+#
+# Test entry point: `Cloudflare::Scheduled.dispatch(cron, scheduled_time, js_env, js_ctx)`
+# — used by `test/scheduled_smoke.rb` so the same code path that the
+# Workers runtime takes is exercised under Node, without needing the
+# JS dispatcher.
+
+require 'time'
+
+module Cloudflare
+  # Wrapper around the JS ScheduledEvent. The Workers runtime gives us:
+  #
+  #   event.cron          — String, e.g. '*/5 * * * *'
+  #   event.scheduledTime — Number (millis-since-epoch)
+  #   event.type          — String, always 'scheduled'
+  #   event.waitUntil(p)  — same shape as ctx.waitUntil(p)
+  #
+  # We surface these as Ruby idioms so user code never needs backticks.
+  class ScheduledEvent
+    attr_reader :cron, :scheduled_time, :type, :raw
+
+    def initialize(cron:, scheduled_time:, type: 'scheduled', raw: nil)
+      @cron = cron.to_s.freeze
+      @scheduled_time = scheduled_time
+      @type = type.to_s.freeze
+      @raw = raw
+    end
+
+    # Build a ScheduledEvent from the native JS event. `js_event` may
+    # be nil during smoke tests; in that case the caller passes the
+    # cron / scheduled_time via the keyword form above.
+    #
+    # JS undefined / null guards are written in JS land instead of
+    # delegating to `nil?` because Opal doesn't always coerce a bare
+    # JS undefined into Ruby's nil — calling `.nil?` on it raises
+    # TypeError.
+    def self.from_js(js_event)
+      return new(cron: '', scheduled_time: Time.now) if `#{js_event} == null`
+
+      cron      = `(#{js_event}.cron == null ? '' : String(#{js_event}.cron))`
+      type      = `(#{js_event}.type == null ? 'scheduled' : String(#{js_event}.type))`
+      has_sched = `(#{js_event}.scheduledTime != null)`
+      sched_t   = if has_sched
+                    sched_ms = `Number(#{js_event}.scheduledTime)`
+                    Time.at(sched_ms.to_f / 1000.0)
+                  else
+                    Time.now
+                  end
+
+      new(cron: cron, scheduled_time: sched_t, type: type, raw: js_event)
+    end
+
+    def to_h
+      {
+        'cron'           => cron,
+        'scheduled_time' => scheduled_time.to_i,
+        'type'           => type
+      }
+    end
+  end
+
+  # Dispatcher singleton. The Rack handler installs the JS hook on
+  # boot; user code never calls anything in this module directly.
+  module Scheduled
+    @app = nil
+
+    class << self
+      # Override the dispatch target. By default the dispatcher uses
+      # `Rack::Handler::CloudflareWorkers.app`, which is whatever the
+      # user passed to top-level `run app`. Tests use this to plug
+      # a fake Sinatra subclass without booting the full handler.
+      attr_accessor :app
+    end
+
+    # Install the JS-side dispatcher on globalThis. Idempotent — safe
+    # to call multiple times (last writer wins).
+    #
+    # NOTE: kept as a single-line backtick x-string. Opal's parser
+    # treats multi-line backtick strings as raw statements that don't
+    # return a value AND it tries to lex-as-Ruby everything inside,
+    # so JS comments containing the Ruby backtick delimiter (`...`)
+    # crash the build. Single-line form sidesteps both pitfalls.
+    def self.install_dispatcher
+      mod = self
+      `globalThis.__HOMURA_SCHEDULED_DISPATCH__ = async function(js_event, js_env, js_ctx) { try { return await #{mod}.$dispatch_js(js_event, js_env, js_ctx); } catch (err) { try { globalThis.console.error('[Cloudflare::Scheduled] dispatch failed:', err && err.stack || err); } catch (e) {} return { error: String(err && err.message || err) }; } };(function(){var g=globalThis;g.__OPAL_WORKERS__=g.__OPAL_WORKERS__||{};g.__OPAL_WORKERS__.scheduled=g.__HOMURA_SCHEDULED_DISPATCH__;})();`
+    end
+
+    # Called from the JS hook. Resolves the Ruby app, builds a
+    # ScheduledEvent, runs `dispatch_scheduled` on the app class, and
+    # returns the result Hash for diagnostics. We `__await__` the
+    # inner dispatch so the returned object is the resolved Hash, not
+    # a Promise — the JS hook then `await`s our return promise once.
+    def self.dispatch_js(js_event, js_env, js_ctx)
+      event = ScheduledEvent.from_js(js_event)
+      target = resolve_app
+      if target.nil?
+        warn '[Cloudflare::Scheduled] no app registered; ignoring scheduled event'
+        return { 'fired' => 0, 'total' => 0, 'results' => [], 'error' => 'no_app' }
+      end
+      target.dispatch_scheduled(event, js_env, js_ctx).__await__
+    end
+
+    # Test-friendly direct entry point. Lets `test/scheduled_smoke.rb`
+    # exercise the same dispatch logic without going through the JS
+    # hook. `cron` / `scheduled_time` are plain Ruby values. Returns
+    # the awaited result Hash (callers can still `__await__` the
+    # outer Promise — this method is async since it uses `__await__`).
+    def self.dispatch(cron, scheduled_time = Time.now, js_env = nil, js_ctx = nil)
+      event = ScheduledEvent.new(cron: cron, scheduled_time: scheduled_time)
+      target = resolve_app
+      raise 'no app registered for Cloudflare::Scheduled' if target.nil?
+      target.dispatch_scheduled(event, js_env, js_ctx).__await__
+    end
+
+    # Await a JS Promise from inside `# await: true` code without
+    # exposing the `__await__` keyword to callers. Re-throws Promise
+    # rejections as synchronous Ruby exceptions so callers can rescue.
+    # Sinatra::Scheduled uses this to bridge per-job exceptions out of
+    # the async block boundary.
+    #
+    # Implemented as `__await__` directly so Opal compiles this method
+    # itself as async — callers in `# await: true` files that do
+    # `await_promise(p)` get the resolved value back the same way they
+    # would from a bare `p.__await__`. Rejections re-throw as Ruby
+    # exceptions thanks to ES8 `await`'s built-in throw semantics.
+    def self.await_promise(promise)
+      promise.__await__
+    end
+
+    # Resolve which app class should receive the dispatch. Priority:
+    #   1. `Cloudflare::Scheduled.app = SomeApp`     (explicit override)
+    #   2. `Rack::Handler::CloudflareWorkers.app`    (set by `run app`)
+    # Returns the class itself (not an instance), because
+    # `dispatch_scheduled` is a class method on Sinatra apps.
+    def self.resolve_app
+      candidate = @app
+      if candidate.nil? && defined?(::Rack::Handler::CloudflareWorkers)
+        candidate = ::Rack::Handler::CloudflareWorkers.app
+      end
+      return nil if candidate.nil?
+      # Sinatra app classes respond to `dispatch_scheduled` (added by
+      # Sinatra::Scheduled). Plain Rack apps would be instances and
+      # lack the class method — we return them as-is and let the
+      # caller's `dispatch_scheduled` raise NoMethodError so the
+      # mistake is visible.
+      if candidate.respond_to?(:dispatch_scheduled)
+        candidate
+      elsif candidate.respond_to?(:class) && candidate.class.respond_to?(:dispatch_scheduled)
+        candidate.class
+      else
+        candidate
+      end
+    end
+  end
+end
+
+# Auto-install the JS dispatcher hook the moment this file is loaded.
+# Sinatra extensions are evaluated by the user code that comes after,
+# so the hook must be live before the first scheduled event arrives.
+Cloudflare::Scheduled.install_dispatcher