homura-runtime 0.1.0

data/lib/cloudflare_workers/auto_await/analyzer.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require 'parser/current'
+require 'parser/source/tree_rewriter'
+
+module CloudflareWorkers
+  module AutoAwait
+    class Analyzer
+      def initialize(registry, debug: false)
+        @registry = registry
+        @debug = debug
+        @await_nodes = []
+        @env = {}
+        @method_returns = {}
+      end
+
+      def process(source, filename = '(auto-await)')
+        buffer = Parser::Source::Buffer.new(filename)
+        buffer.source = source
+        parser = Parser::CurrentRuby.new
+        ast = parser.parse(buffer)
+        @await_nodes = []
+        @env = {}
+        process_node(ast)
+        [buffer, @await_nodes]
+      end
+
+      private
+
+      def process_node(node)
+        return unless node.is_a?(Parser::AST::Node)
+
+        if node.type == :def
+          process_def(node)
+          return
+        end
+        if node.type == :block
+          process_block(node)
+          return
+        end
+
+        # Bottom-up traversal: process children first so helper-factory
+        # sends (e.g. bare +db+) populate @env before their parent
+        # send (e.g. +db.execute(...)+) is checked by should_await?.
+        node.children.each { |child| process_node(child) if child.is_a?(Parser::AST::Node) }
+        case node.type
+        when :lvasgn
+          process_lvasgn(node)
+        when :ivasgn
+          process_ivasgn(node)
+        when :send
+          process_send(node)
+        end
+      end
+
+      def process_lvasgn(node)
+        name, value = *node
+        cls = infer_class(value)
+        if cls
+          @env[name] = cls
+        else
+          @env.delete(name)
+        end
+      end
+
+      def process_ivasgn(node)
+        _name, value = *node
+        cls = infer_class(value)
+        # instance variable tracking is best-effort; skip storing for now
+      end
+
+      def process_def(node)
+        method_name = node.children[0]
+        saved_env = @env
+        @env = @registry.helper_factories.dup
+
+        node.children[1..-1].each { |child| process_node(child) if child.is_a?(Parser::AST::Node) }
+
+        body = node.children[2]
+        return_cls = infer_class(body)
+        @method_returns[method_name] = return_cls if return_cls
+
+        @env = saved_env
+      end
+
+      def process_block(node)
+        call_node, args_node, body = *node
+        saved_env = @env
+        @env = @env.dup
+
+        block_param_bindings(call_node, args_node).each do |name, cls|
+          @env[name] = cls
+        end
+
+        process_node(call_node) if call_node.is_a?(Parser::AST::Node)
+        process_node(body) if body.is_a?(Parser::AST::Node)
+      ensure
+        @env = saved_env
+      end
+
+      def process_send(node)
+        receiver, method_name = *node
+        if receiver.nil? && (factory_cls = @registry.helper_factories[method_name])
+          @env[method_name] = factory_cls
+        end
+        if should_await?(node)
+          @await_nodes << node
+          debug "await target: #{node.loc.expression.source}"
+        end
+      end
+
+      def should_await?(node)
+        return false unless node.type == :send
+        receiver, method_name = *node
+        if receiver
+          recv_cls = infer_class(receiver)
+          return true if recv_cls && @registry.async?(recv_cls, method_name)
+        end
+        # Receiver-less calls (implicit self) — check helpers.
+        helpers = @registry.async_helpers[method_name]
+        return true if helpers && !helpers.empty?
+        false
+      end
+
+      def infer_class(node)
+        return nil unless node.is_a?(Parser::AST::Node)
+        case node.type
+        when :send
+          receiver, method_name = *node
+          if receiver.nil?
+            return @env[method_name] if @env.key?(method_name)
+            return @method_returns[method_name] if @method_returns.key?(method_name)
+          end
+          infer_send_class(node)
+        when :index
+          infer_index_class(node)
+        when :lvar
+          @env[node.children[0]]
+        when :ivar
+          nil
+        when :const
+          const_path(node)
+        else
+          nil
+        end
+      end
+
+      def infer_send_class(node)
+        receiver, method_name = *node
+        if method_name == :new && receiver&.type == :const
+          return const_path(receiver)
+        end
+        if receiver
+          if method_name == :[]
+            key_node = node.children[2]
+            if key_node&.type == :str
+              key = key_node.children[0]
+              mapped = @registry.async_accessors[[env_name(receiver), key.to_sym]]
+              return mapped if mapped
+            end
+          end
+          accessor_cls = infer_env_accessor(receiver, method_name)
+          return accessor_cls if accessor_cls
+          recv_cls = infer_class(receiver)
+          if recv_cls
+            factory = @registry.factory?(recv_cls, method_name)
+            return recv_cls if factory
+            ret = @registry.taint_return_class(recv_cls, method_name)
+            return ret if ret
+          end
+        else
+          return @method_returns[method_name] if @method_returns.key?(method_name)
+        end
+        nil
+      end
+
+      def block_param_bindings(call_node, args_node)
+        return {} unless durable_object_define_call?(call_node)
+        return {} unless args_node&.type == :args
+
+        arg_names = args_node.children.filter_map do |arg|
+          next unless arg&.type == :arg
+          arg.children[0]
+        end
+        return {} if arg_names.empty?
+
+        bindings = { arg_names[0] => 'Cloudflare::DurableObjectState' }
+        bindings[arg_names[1]] = 'Cloudflare::DurableObjectRequest' if arg_names.length > 1
+        bindings
+      end
+
+      def durable_object_define_call?(call_node)
+        return false unless call_node&.type == :send
+
+        receiver, method_name = *call_node
+        method_name == :define && const_path(receiver) == 'Cloudflare::DurableObject'
+      end
+
+      def infer_index_class(node)
+        recv_cls = infer_class(node.children[0])
+        return nil unless recv_cls
+        @registry.taint_return_class(recv_cls, :[]) || recv_cls
+      end
+
+      def infer_env_accessor(receiver_node, method_name)
+        if env_node?(receiver_node)
+          return nil unless method_name.to_s =~ /^[A-Z]/
+          lvar = env_name(receiver_node)
+          mapped = @registry.async_accessors[[lvar, method_name.to_sym]]
+          return mapped if mapped
+        end
+        if receiver_node.type == :send
+          recv, meth = *receiver_node
+          if meth == :[] && env_node?(recv)
+            key_node = receiver_node.children[2]
+            if key_node&.type == :str
+              key = key_node.children[0]
+              mapped = @registry.async_accessors[[env_name(recv), key.to_sym]]
+              return mapped if mapped
+            end
+            lvar = env_name(recv)
+            mapped = @registry.async_accessors[[lvar, method_name.to_sym]]
+            return mapped if mapped
+          elsif env_node?(recv)
+            return nil unless method_name.to_s =~ /^[A-Z]/
+            lvar = env_name(recv)
+            mapped = @registry.async_accessors[[lvar, method_name.to_sym]]
+            return mapped if mapped
+          end
+          parent_cls = infer_env_accessor(recv, meth) if recv&.type == :send
+          return parent_cls if parent_cls
+        elsif receiver_node.type == :lvar
+          lvar = receiver_node.children[0]
+          mapped = @registry.async_accessors[[lvar, method_name.to_sym]]
+          return mapped if mapped
+        end
+        nil
+      end
+
+      def env_node?(node)
+        return false unless node&.type == :send
+        node.children[0].nil? && node.children[1] == :env
+      end
+
+      def env_name(node)
+        :env
+      end
+
+      def const_path(node)
+        parts = []
+        n = node
+        while n&.type == :const
+          parts.unshift(n.children[1])
+          n = n.children[0]
+        end
+        parts.join('::')
+      end
+
+      def debug(msg)
+        puts "[auto-await] #{msg}" if @debug
+      end
+    end
+  end
+end

data/lib/cloudflare_workers/auto_await/transformer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'parser/source/tree_rewriter'
+
+module CloudflareWorkers
+  module AutoAwait
+    class Transformer
+      def self.transform(source, await_nodes, buffer)
+        rewriter = Parser::Source::TreeRewriter.new(buffer)
+        await_nodes.each do |node|
+          range = node.loc.expression
+          next unless range
+          rewriter.replace(range, "#{range.source}.__await__")
+        end
+        rewriter.process
+      end
+    end
+  end
+end

data/lib/cloudflare_workers/cache.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+# backtick_javascript: true
+# await: true
+#
+# Phase 11B — Cloudflare Cache API wrapper.
+#
+# The Cache API (`caches.default`, `caches.open(name)`) is an edge
+# cache local to the colo that serves a request. Unlike KV, there is
+# no binding; the `caches` global is always present on Workers.
+#
+# Semantics are HTTP-level: the cache key is a Request (method, URL,
+# headers — Vary-aware), and the value is a full Response with
+# headers, status, and body. `cache.match(req)` returns a Response or
+# nil; `cache.put(req, resp)` stores it. This wrapper exposes the
+# subset that matters for Ruby routes:
+#
+#   cache = Cloudflare::Cache.default
+#   resp  = cache.match(request.url).__await__
+#   if resp
+#     # serve from cache
+#   else
+#     # compute…
+#     cache.put(request.url, body, headers: { 'cache-control' => 'public, max-age=60' }).__await__
+#   end
+#
+# The Sinatra helper `cache_get(url_or_request) { block }` (exposed
+# through user-side `helpers do ... end`) wraps the match/compute/put
+# dance so routes can write:
+#
+#   get '/demo/cache/heavy' do
+#     cache_get(request.url, ttl: 60, content_type: 'application/json') do
+#       compute_expensive_value.to_json
+#     end
+#   end
+#
+# Both the helper and the low-level API await under the hood, so
+# routes only need a single `.__await__` at the call site if they use
+# the raw wrapper directly.
+#
+# LIMITATION — on Cloudflare Workers, `cache.put` only honours the
+# key URL's scheme/host/path, and the URL must have an HTTP(S)
+# scheme. In `wrangler dev`'s local mode the cache is a noop unless
+# `--local` is combined with miniflare's cache (>= wrangler 3.x
+# defaults). We document this in the README and the helper logs a
+# single console.warn on the first noop put so misconfiguration is
+# visible rather than silent.
+
+module Cloudflare
+  class CacheError < StandardError
+    attr_reader :operation
+    def initialize(message, operation: nil)
+      @operation = operation
+      super("[Cloudflare::Cache] op=#{operation || 'match'}: #{message}")
+    end
+  end
+
+  # Wrapper around a JS Cache object (caches.default or a named cache).
+  class Cache
+    attr_reader :js_cache, :name
+
+    # caches.default — the shared cache that every Worker gets for free.
+    # Returns a fresh wrapper each call; the underlying JS object is a
+    # singleton per isolate.
+    def self.default
+      Cache.new(`(typeof caches !== 'undefined' && caches ? caches.default : null)`, 'default')
+    end
+
+    # caches.open(name) — named cache partitions. Returns a JS Promise
+    # resolving to a wrapped Cache. Following Workers conventions, the
+    # wrapper itself holds the resolved JS Cache so subsequent calls
+    # don't re-open the handle.
+    def self.open(name)
+      name_str = name.to_s
+      js_promise = `(typeof caches !== 'undefined' && caches && caches.open ? caches.open(#{name_str}) : Promise.resolve(null))`
+      js_cache = js_promise.__await__
+      Cache.new(js_cache, name_str)
+    end
+
+    def initialize(js_cache, name = 'default')
+      @js_cache = js_cache
+      @name = name.to_s
+    end
+
+    # True when the underlying JS cache is present. In unusual runtimes
+    # (tests / non-Workers hosts) `caches` may be undefined. We check
+    # Ruby-nil first because Opal's `nil` marshals to an object (not
+    # JS null) so a bare `#{js} != null` would be truthy — this is the
+    # same pitfall `Cloudflare::AI.run` documents for `env.AI`.
+    def available?
+      js = @js_cache
+      # Opal marshals Ruby `nil` to a runtime sentinel (`Opal.nil`),
+      # not JS null / undefined. Compare against the sentinel
+      # explicitly so a Cache built with Ruby `nil` reports itself as
+      # unavailable (which the non-Workers tests rely on).
+      !!`(#{js} !== null && #{js} !== undefined && #{js} !== Opal.nil)`
+    end
+
+    # Look up a Request (or URL String) in the cache. Returns a JS
+    # Promise resolving to a Cloudflare::HTTPResponse (populated with
+    # body text + headers) or nil.
+    def match(request_or_url)
+      js = @js_cache
+      response_klass = Cloudflare::HTTPResponse
+      err_klass = Cloudflare::CacheError
+      req = request_to_js(request_or_url)
+      # Copilot review PR #9 (fourth pass): `request_or_url.to_s` is
+      # correct for a String URL but produces "#<Cloudflare::HTTPResponse:...>"
+      # for the HTTPResponse wrapper and "[object Request]" for a raw
+      # JS Request. Derive the URL from the same shapes supported by
+      # `request_to_js` so the `url` field on the returned
+      # HTTPResponse is always a real URL.
+      url_str = if request_or_url.is_a?(String)
+                  request_or_url
+                elsif defined?(Cloudflare::HTTPResponse) && request_or_url.is_a?(Cloudflare::HTTPResponse)
+                  request_or_url.url.to_s
+                elsif `(#{request_or_url} != null && typeof #{request_or_url} === 'object' && typeof #{request_or_url}.url === 'string')`
+                  `String(#{request_or_url}.url)`
+                else
+                  request_or_url.to_s
+                end
+
+      # Single-line backtick IIFE — see `put` for the Opal multi-line
+      # x-string quirk that silently drops the returned Promise.
+      js_promise = `(async function(js, req, Kernel, err_klass) { if (js == null || js === Opal.nil) return null; var cached; try { cached = await js.match(req); } catch (e) { Kernel.$raise(err_klass.$new(e && e.message ? e.message : String(e), Opal.hash({ operation: 'match' }))); } if (cached == null) return null; var text = ''; try { text = await cached.text(); } catch (_) { text = ''; } var hk = []; var hv = []; if (cached.headers && typeof cached.headers.forEach === 'function') { cached.headers.forEach(function(v, k) { hk.push(String(k).toLowerCase()); hv.push(String(v)); }); } return { status: cached.status|0, text: text, hkeys: hk, hvals: hv }; })(#{js}, #{req}, #{Kernel}, #{err_klass})`
+      js_result = js_promise.__await__
+      return nil if `#{js_result} == null`
+
+      hkeys = `#{js_result}.hkeys`
+      hvals = `#{js_result}.hvals`
+      h = {}
+      i = 0
+      len = `#{hkeys}.length`
+      while i < len
+        h[`#{hkeys}[#{i}]`] = `#{hvals}[#{i}]`
+        i += 1
+      end
+      response_klass.new(
+        status:  `#{js_result}.status`,
+        headers: h,
+        body:    `#{js_result}.text`,
+        url:     url_str
+      )
+    end
+
+    # Store a Response for the given Request/URL.
+    #
+    #   cache.put(request.url, body_str,
+    #             status: 200,
+    #             headers: { 'content-type' => 'application/json',
+    #                        'cache-control' => 'public, max-age=60' }).__await__
+    #
+    # Returns a JS Promise that resolves to nil. Workers refuses to
+    # store responses without a cacheable status / cache-control; we
+    # surface that as a CacheError rather than silently succeeding.
+    def put(request_or_url, body, status: 200, headers: {})
+      js = @js_cache
+      err_klass = Cloudflare::CacheError
+      req = request_to_js(request_or_url)
+      hdrs = ruby_headers_to_js(headers)
+      body_str = body.to_s
+      status_int = status.to_i
+
+      # Single-line backtick IIFE — multi-line form is parsed by Opal
+      # as a statement (not an expression), so the returned Promise
+      # gets dropped and the caller's `__await__` receives `undefined`
+      # instead of waiting for `cache.put` to resolve. That was the
+      # silent bug: the inner `await` ran, but the outer await had
+      # already proceeded. See lib/cloudflare_workers/scheduled.rb for
+      # the same Opal multi-line x-string constraint.
+      # Warn ONCE per isolate on a nil cache. Non-Workers runtimes
+      # hit `Cache.new(nil, ...)` intentionally (tests, safe fall-back
+      # for routes that can run without caching) and repeated warn
+      # output would drown signal in noise — Copilot review PR #9.
+      `(async function(js, req, body_str, status_int, hdrs, Kernel, err_klass) { if (js == null || js === Opal.nil) { try { if (!globalThis.__HOMURA_CACHE_NOOP_WARNED__) { globalThis.__HOMURA_CACHE_NOOP_WARNED__ = true; globalThis.console.warn('[Cloudflare::Cache] caches.default unavailable; skipping put (this is expected in non-Workers runtimes). Further warnings suppressed.'); } } catch (_) {} return null; } try { var resp = new Response(String(body_str), { status: status_int, headers: hdrs }); await js.put(req, resp); } catch (e) { try { globalThis.console.error('[Cloudflare::Cache] put threw:', e && e.stack || e); } catch (_) {} Kernel.$raise(err_klass.$new(e && e.message ? e.message : String(e), Opal.hash({ operation: 'put' }))); } return null; })(#{js}, #{req}, #{body_str}, #{status_int}, #{hdrs}, #{Kernel}, #{err_klass})`
+    end
+
+    # Remove a Request/URL from the cache. Returns a JS Promise
+    # resolving to a boolean — true if an entry was removed.
+    def delete(request_or_url)
+      js = @js_cache
+      err_klass = Cloudflare::CacheError
+      req = request_to_js(request_or_url)
+      # Single-line IIFE — see `put` for the Opal multi-line quirk.
+      `(async function(js, req, Kernel, err_klass) { if (js == null || js === Opal.nil) return false; try { var deleted = await js.delete(req); return deleted ? true : false; } catch (e) { Kernel.$raise(err_klass.$new(e && e.message ? e.message : String(e), Opal.hash({ operation: 'delete' }))); } return false; })(#{js}, #{req}, #{Kernel}, #{err_klass})`
+    end
+
+    private
+
+    # Normalise supported inputs to a JS `Request` suitable as a
+    # cache key:
+    #
+    #   - `String` URL                       → `new Request(url)`
+    #   - `Cloudflare::HTTPResponse`         → `new Request(resp.url)`
+    #     (the Phase 6 wrapper exposes a `.url` attr; we reuse its URL
+    #     as the cache key so `cache.put(response, ...)` reads natural.)
+    #   - raw JS `Request` / `Response` / any JS object carrying a
+    #     string `.url` property     → passed through unchanged.
+    #
+    # Anything else (integers, Hashes, etc.) is rejected with
+    # `ArgumentError` so callers don't silently build an invalid
+    # `Request('12345')`.
+    # (Copilot review PR #9: previous docstring advertised HTTPResponse
+    # support but the impl only covered JS Request-like objects — both
+    # the docs AND the code now line up.)
+    def request_to_js(request_or_url)
+      if request_or_url.is_a?(String)
+        return `new Request(#{request_or_url})`
+      end
+      if defined?(Cloudflare::HTTPResponse) && request_or_url.is_a?(Cloudflare::HTTPResponse)
+        url_str = request_or_url.url.to_s
+        return `new Request(#{url_str})`
+      end
+      if `(#{request_or_url} != null && typeof #{request_or_url} === 'object' && typeof #{request_or_url}.url === 'string')`
+        return request_or_url
+      end
+      raise ArgumentError, "Cloudflare::Cache request must be a String URL, Cloudflare::HTTPResponse, or JS Request (got #{request_or_url.class})"
+    end
+
+    def ruby_headers_to_js(hash)
+      js_obj = `({})`
+      (hash || {}).each do |k, v|
+        ks = k.to_s
+        vs = v.to_s
+        `#{js_obj}[#{ks}] = #{vs}`
+      end
+      js_obj
+    end
+  end
+
+  # Module-level alias so calling code reads naturally:
+  #   resp = Cloudflare::Cache.default.match(url).__await__
+  # mirrors Phase 3's `Cloudflare::D1Database` / `Cloudflare::KVNamespace`
+  # "the wrapper IS the API" pattern.
+end