homura-runtime 0.1.0

data/exe/compile-erb

@@ -0,0 +1,262 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# homura ERB precompiler.
+#
+# Opal-on-Workers can't run ERB the normal way: ERB compiles its
+# templates to Ruby source and runs them via `binding.eval`, which
+# lands on `new Function($code)`, which Cloudflare Workers bans with
+# "Code generation from strings disallowed for this context".
+#
+# The workaround is to compile each ERB template to a *plain Ruby
+# method* ahead of time (in CRuby, at build time), then feed that
+# generated Ruby source into Opal alongside everything else. The
+# runtime cost is a single Proc lookup plus a couple of string
+# concatenations per tag; no eval, no new Function, no surprises.
+#
+# Usage:
+#   bin/compile-erb --input views --output build/homura_templates.rb --namespace HomuraTemplates
+# or (legacy):
+#   bin/compile-erb views/foo.erb   # writes compiled templates + Sinatra hook to stdout
+#
+# The output registers each template with `HomuraTemplates` and
+# monkey-patches `Sinatra::Templates#erb` to dispatch there.
+
+require 'fileutils'
+require 'optparse'
+
+HELP = <<~USAGE
+  Usage:
+    bin/compile-erb [--input DIR] [--output FILE] [--namespace ModuleName]
+                    [--stdout] [--] [template.erb ...]
+
+  Defaults (Phase 15-A homura):
+    --input views --output build/homura_templates.rb --namespace HomuraTemplates
+
+  With positional .erb paths and no --output: print combined Ruby to stdout (legacy).
+USAGE
+
+# Very small ERB dialect tokenizer. ERB is simple enough to parse by
+# hand and we specifically DO NOT want to pull in stdlib ERB — its
+# generated source uses `String#<<` mutation, which Opal's immutable
+# Strings reject at runtime.
+module HomuraERB
+  module_function
+
+  # Compile an ERB source string to a Ruby method body that assembles
+  # an HTML string in a local variable `_out`. The body references
+  # `@ivars` and method calls directly, so it must be run via
+  # `instance_exec` on the Sinatra instance the route was dispatched
+  # on. That gives `<%= @name %>` the usual Sinatra semantics.
+  def compile(source)
+    ruby = +"_out = ''\n"
+    cursor = 0
+    while cursor < source.length
+      open_idx = source.index('<%', cursor)
+      if open_idx.nil?
+        static = source[cursor..]
+        ruby << "_out = _out + #{static.inspect}\n" unless static.empty?
+        break
+      end
+
+      # Static text before the next `<%`
+      if open_idx > cursor
+        static = source[cursor...open_idx]
+        ruby << "_out = _out + #{static.inspect}\n"
+      end
+
+      close_idx = source.index('%>', open_idx + 2)
+      raise "Unmatched `<%` in ERB source (starting at #{open_idx})" if close_idx.nil?
+
+      inner = source[(open_idx + 2)...close_idx]
+
+      if inner.start_with?('#')
+        # `<%# comment %>` — drop
+      elsif inner.start_with?('==')
+        # `<%== expression %>` — identical to `<%= %>` in this minimal
+        # dialect (no HTML escaping yet; the author is responsible).
+        expr = inner[2..].strip
+        ruby << "_out = _out + ((#{expr})).to_s\n"
+      elsif inner.start_with?('=')
+        # `<%= expression %>`
+        expr = inner[1..].strip
+        ruby << "_out = _out + ((#{expr})).to_s\n"
+      else
+        # `<% code %>` — Ruby statement(s), emitted verbatim
+        ruby << inner.strip << "\n"
+      end
+
+      cursor = close_idx + 2
+    end
+    ruby << "_out\n"
+    ruby
+  end
+
+  # Wrap the compiled body in a `#{namespace}.register` call.
+  def wrap(template_name, compiled_body, namespace)
+    indented = compiled_body.each_line.map { |l| "    #{l}" }.join
+    <<~RUBY
+      #{namespace}.register(:#{template_name}) do |locals = {}|
+      #{indented.chomp}
+      end
+    RUBY
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Driver
+# ---------------------------------------------------------------------------
+
+def default_inputs_for(dir)
+  Dir.glob(File.join(dir, '*.erb')).sort
+end
+
+def template_name_for(path)
+  File.basename(path, '.erb').to_sym
+end
+
+def emit_header(io, namespace)
+  io.puts <<~RUBY
+    # frozen_string_literal: true
+    #
+    # Auto-generated by bin/compile-erb — DO NOT EDIT BY HAND.
+    #
+    # Run `bin/compile-erb` after modifying anything under views/ to
+    # regenerate. The Opal build command picks this file up via
+    # `-I build -r homura_templates` (or your chosen `--output` basename).
+    #
+    # Each registered template is a Proc that returns an HTML String.
+    # The Proc is `instance_exec`'d on the current Sinatra instance so
+    # `@ivars`, `params`, `request`, and any Sinatra helper remain
+    # accessible exactly as they would in a stock Sinatra route.
+    #
+    # Rendering is wired to `Sinatra::Templates#erb` further down so
+    # `erb :index` in user code dispatches here transparently. No
+    # runtime eval, no `new Function`, no Workers sandbox complaints.
+
+    module #{namespace}
+      @templates = {}
+
+      class << self
+        def register(name, &body)
+          @templates[name.to_sym] = body
+        end
+
+        def render(name, instance, locals = {})
+          body = @templates[name.to_sym]
+          raise "#{namespace}: no template registered for \#{name.inspect}" unless body
+          instance.instance_exec(locals, &body)
+        end
+
+        def registered?(name)
+          @templates.key?(name.to_sym)
+        end
+
+        def names
+          @templates.keys
+        end
+      end
+    end
+  RUBY
+end
+
+def emit_templates(io, inputs, namespace)
+  inputs.each do |path|
+    name = template_name_for(path)
+    source = File.read(path)
+    compiled = HomuraERB.compile(source)
+    io.puts
+    io.puts "# ---- #{path} -> :#{name} --------------------------------------"
+    io.puts HomuraERB.wrap(name, compiled, namespace)
+  end
+end
+
+def emit_sinatra_patch(io, namespace)
+  io.puts <<~RUBY
+
+    # ---------------------------------------------------------------------
+    # Sinatra hook: `erb :name` dispatches to #{namespace}.render.
+    # ---------------------------------------------------------------------
+    #
+    # This file is loaded by Opal via `-r homura_templates` before
+    # `app/hello.rb`, so Sinatra is not yet loaded at require time.
+    # Pull it in explicitly and reopen `Sinatra::Templates` to install
+    # our ERB dispatcher. User code's own `require 'sinatra/base'`
+    # later becomes a no-op (already cached).
+    require 'sinatra/base'
+
+    module ::Sinatra
+      module Templates
+        # homura patch: dispatch to precompiled templates when we
+        # have one. Unknown symbols raise a clear message instead of
+        # wandering into upstream Tilt, which would blow up on
+        # Workers with "Code generation from strings disallowed".
+        def erb(template, options = {}, locals = {}, &block)
+          if template.is_a?(::Symbol) && ::#{namespace}.registered?(template)
+            locals ||= {}
+            ::#{namespace}.render(template, self, locals)
+          else
+            raise "homura: erb \#{template.inspect} not precompiled; run bin/compile-erb"
+          end
+        end
+      end
+    end
+  RUBY
+end
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+if ARGV.include?('-h') || ARGV.include?('--help')
+  puts HELP
+  exit 0
+end
+
+options = {
+  input_dir: 'views',
+  output: 'build/homura_templates.rb',
+  namespace: 'HomuraTemplates',
+  stdout: false
+}
+
+parser = OptionParser.new do |op|
+  op.banner = 'Usage: bin/compile-erb [options] [--] [files...]'
+  op.on('--input DIR', 'Directory containing *.erb templates') { |d| options[:input_dir] = d }
+  op.on('--output PATH', 'Write generated Ruby to PATH') { |p| options[:output] = p }
+  op.on('--namespace NAME', 'Ruby module name for the registry') { |n| options[:namespace] = n }
+  op.on('--stdout', 'Write generated Ruby to stdout') { options[:stdout] = true }
+end
+parser.parse!
+
+positional = ARGV.dup
+namespace = options[:namespace]
+
+inputs =
+  if positional.any?
+    positional.flat_map { |a| File.directory?(a) ? Dir.glob(File.join(a, '*.erb')).sort : [a] }
+  else
+    default_inputs_for(options[:input_dir])
+  end
+
+if inputs.empty?
+  warn "bin/compile-erb: no .erb files found (under #{options[:input_dir]}/ or from args)"
+  exit 1
+end
+
+write_file = !options[:stdout] && (positional.empty? || options[:output])
+out_path = options[:output]
+
+if write_file
+  FileUtils.mkdir_p(File.dirname(out_path))
+  File.open(out_path, 'w') do |io|
+    emit_header(io, namespace)
+    emit_templates(io, inputs, namespace)
+    emit_sinatra_patch(io, namespace)
+  end
+  warn "compile-erb: wrote #{out_path} (#{inputs.size} templates)"
+else
+  emit_header($stdout, namespace)
+  emit_templates($stdout, inputs, namespace)
+  emit_sinatra_patch($stdout, namespace)
+end

data/lib/cloudflare_workers/ai.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+# backtick_javascript: true
+# await: true
+#
+# Phase 10 — Workers AI binding wrapper.
+#
+# `Cloudflare::AI.run(model, inputs, binding: env['cloudflare.AI'])`
+# wraps `env.AI.run(model, inputs, options)` and returns a Ruby Hash so
+# Sinatra routes can call:
+#
+#     ai = env['cloudflare.AI']
+#     out = Cloudflare::AI.run(
+#             '@cf/google/gemma-4-26b-a4b-it',
+#             { messages: [
+#                 { role: 'system', content: 'You are a helpful assistant.' },
+#                 { role: 'user',   content: 'こんにちは' }
+#             ] },
+#             binding: ai
+#           ).__await__
+#     out['response']  # => "..."
+#
+# Streaming (`stream: true`) returns the raw JS ReadableStream wrapped
+# in `Cloudflare::AI::Stream` so a route can hand it to a Server-Sent
+# Events response. See `lib/cloudflare_workers.rb#build_js_response`
+# for the SSE / ReadableStream pass-through.
+
+require 'json'
+
+module Cloudflare
+  class AIError < StandardError
+    attr_reader :model, :operation
+    def initialize(message, model: nil, operation: nil)
+      @model = model
+      @operation = operation
+      super("[Cloudflare::AI] model=#{model || '?'} op=#{operation || 'run'}: #{message}")
+    end
+  end
+
+  module AI
+    # Default REST options forwarded to env.AI.run as the third argument.
+    DEFAULT_OPTIONS = {}.freeze
+
+    # Run a Workers AI model. Returns a JS Promise that resolves to a
+    # Ruby Hash for non-streaming calls, or to a Cloudflare::AI::Stream
+    # wrapping the JS ReadableStream for streaming calls.
+    #
+    # @param model [String] catalog model id, e.g. '@cf/google/gemma-4-26b-a4b-it'
+    # @param inputs [Hash] model inputs (messages / prompt / max_tokens / etc.)
+    # @param binding [JS object] env.AI binding (required)
+    # @param options [Hash] gateway / extra options forwarded as the 3rd arg
+    def self.run(model, inputs, binding: nil, options: nil)
+      # Use a JS-side null check because `binding` may be a raw JS object
+      # (env.AI), which has no Ruby `#nil?` method on the prototype.
+      bound = !`(#{binding} == null)`
+      raise AIError.new('AI binding not bound (env.AI is null)', model: model) unless bound
+      js_inputs = ruby_to_js(inputs)
+      js_options = options ? ruby_to_js(options) : `({})`
+      ai_binding = binding
+      err_klass = Cloudflare::AIError
+      stream_klass = Cloudflare::AI::Stream
+      # Streaming may be requested either via `inputs[:stream]` (the
+       # newer Workers AI shape) or `options: { stream: true }` (the
+       # 3rd-arg "options" contract). Accept both so callers can use
+       # whichever idiom matches the model docs they're following.
+      streaming = (inputs.is_a?(Hash) && (inputs[:stream] == true || inputs['stream'] == true)) ||
+                  (options.is_a?(Hash) && (options[:stream] == true || options['stream'] == true))
+      cf = Cloudflare
+
+      # NOTE: multi-line backtick → Promise works HERE because the
+      # value is assigned to `js_promise` (Opal emits the statement AND
+      # keeps the returned value alive through the local). Do NOT
+      # refactor this so the backtick is the method's last expression
+      # or the Promise will be silently dropped (same pitfall
+      # documented in lib/cloudflare_workers/{cache,queue}.rb —
+      # Phase 11B audit).
+      js_promise = `
+        (async function() {
+          var out;
+          try {
+            out = await #{ai_binding}.run(#{model}, #{js_inputs}, #{js_options});
+          } catch (e) {
+            #{Kernel}.$raise(#{err_klass}.$new(e && e.message ? e.message : String(e), Opal.hash({ model: #{model}, operation: 'run' })));
+          }
+          return out;
+        })()
+      `
+
+      js_result = js_promise.__await__
+
+      if streaming
+        # Workers AI returns a ReadableStream<Uint8Array> when stream:true.
+        # Wrap it so the Sinatra route can return it as an SSE body.
+        stream_klass.new(js_result)
+      else
+        cf.js_to_ruby(js_result)
+      end
+    end
+
+    # Convert a Ruby value (Hash / Array / String / Numeric / true / false / nil)
+    # into a plain JS object suitable for env.AI.run inputs.
+    def self.ruby_to_js(val)
+      if val.is_a?(Hash)
+        obj = `({})`
+        val.each do |k, v|
+          ks = k.to_s
+          jv = ruby_to_js(v)
+          `#{obj}[#{ks}] = #{jv}`
+        end
+        obj
+      elsif val.is_a?(Array)
+        arr = `([])`
+        val.each do |v|
+          jv = ruby_to_js(v)
+          `#{arr}.push(#{jv})`
+        end
+        arr
+      elsif val.is_a?(Symbol)
+        val.to_s
+      else
+        val
+      end
+    end
+
+    # Streaming wrapper. Holds the raw JS ReadableStream<Uint8Array>
+    # returned by env.AI.run when `stream: true` is set. Sinatra routes
+    # return this from a route body and `build_js_response` recognises
+    # it via duck-typing (`#sse_stream?`) to pass the stream straight
+    # into `new Response(stream, …)`.
+    #
+    # Phase 11A: unified with Cloudflare::SSEStream so both stream
+    # types go through the same `response_headers` path in
+    # `build_js_response`. The AI::Stream wraps a pre-existing JS
+    # ReadableStream (produced by env.AI.run), whereas SSEStream
+    # produces its own. The adapter doesn't need to care — it just
+    # calls `#js_stream` and `#response_headers`.
+    class Stream
+      attr_reader :js_stream
+
+      def initialize(js_stream, headers: nil)
+        @js_stream = js_stream
+        @extra_headers = headers || {}
+      end
+
+      def sse_stream?
+        true
+      end
+
+      # Merged SSE headers — same shape as SSEStream#response_headers,
+      # so build_js_response can pass the stream through without a
+      # special AI branch. Reference Cloudflare::SSEStream lazily so
+      # this file still loads if stream.rb hasn't been required yet
+      # (Phase 11A load-order flip: ai.rb currently loads first).
+      def response_headers
+        defaults = defined?(::Cloudflare::SSEStream) ?
+          ::Cloudflare::SSEStream::DEFAULT_HEADERS :
+          { 'content-type' => 'text/event-stream; charset=utf-8',
+            'cache-control' => 'no-cache, no-transform',
+            'x-accel-buffering' => 'no' }
+        defaults.merge(@extra_headers)
+      end
+
+      def each; end
+      def close; end
+    end
+  end
+
+  # Generic JS->Ruby for the common Workers AI response shape:
+  #   { response: "...", usage: { prompt_tokens: ... } }
+  # Recursively converts nested objects + arrays.
+  def self.js_to_ruby(js_val)
+    return nil if `#{js_val} == null`
+    return js_val if `typeof #{js_val} === 'string' || typeof #{js_val} === 'number' || typeof #{js_val} === 'boolean'`
+    if `Array.isArray(#{js_val})`
+      out = []
+      len = `#{js_val}.length`
+      i = 0
+      while i < len
+        out << js_to_ruby(`#{js_val}[#{i}]`)
+        i += 1
+      end
+      return out
+    end
+    if `typeof #{js_val} === 'object'`
+      h = {}
+      keys = `Object.keys(#{js_val})`
+      len = `#{keys}.length`
+      i = 0
+      while i < len
+        k = `#{keys}[#{i}]`
+        h[k] = js_to_ruby(`#{js_val}[#{k}]`)
+        i += 1
+      end
+      return h
+    end
+    js_val
+  end
+end

data/lib/cloudflare_workers/async_registry.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module CloudflareWorkers
+  class AsyncRegistry
+    class Builder
+      def initialize(registry)
+        @registry = registry
+      end
+
+      def async_class(class_name, except: [:new])
+        @registry.async_classes[class_name] = except.to_set
+      end
+
+      def async_method(class_name, method_name)
+        (@registry.async_methods[class_name] ||= Set.new) << method_name
+      end
+
+      def async_factory(class_name, method_name)
+        (@registry.async_factories[class_name] ||= Set.new) << method_name
+      end
+
+      def taint_return(class_name, method_name, return_class_name)
+        (@registry.taint_returns[class_name] ||= {})[method_name] = return_class_name
+      end
+
+      def async_accessor(lvar_name, accessor_name, class_name)
+        @registry.async_accessors[[lvar_name.to_sym, accessor_name.to_sym]] = class_name
+      end
+
+      def async_helper(method_name, class_name)
+        (@registry.async_helpers[method_name.to_sym] ||= Set.new) << class_name
+      end
+
+      def helper_factory(method_name, class_name)
+        @registry.helper_factories[method_name.to_sym] = class_name
+      end
+    end
+
+    class << self
+      def register_async_source(&block)
+        builder = Builder.new(instance)
+        builder.instance_eval(&block)
+      end
+
+      def instance
+        @instance ||= new
+      end
+
+      def reset!
+        @instance = new
+      end
+
+      def async?(class_name, method_name)
+        instance.async?(class_name, method_name)
+      end
+
+      def factory?(class_name, method_name)
+        instance.factory?(class_name, method_name)
+      end
+
+      def taint_return_class(class_name, method_name)
+        instance.taint_return_class(class_name, method_name)
+      end
+
+      def tainted_class?(class_name)
+        instance.tainted_class?(class_name)
+      end
+
+      def auto_load_gem_async_sources(debug: false)
+        return unless defined?(Gem) && Gem.respond_to?(:loaded_specs)
+
+        loaded = 0
+        Gem.loaded_specs.each_value do |spec|
+          next if spec.full_gem_path.nil?
+
+          lib_dir = File.join(spec.full_gem_path, 'lib')
+          next unless Dir.exist?(lib_dir)
+
+          Dir.glob(File.join(lib_dir, '**', '*.rb')).each do |path|
+            next unless File.read(path, 8192).include?('register_async_source')
+
+            require_path = path.sub(Regexp.new("^#{Regexp.escape(lib_dir)}/"), '').sub(/\.rb\z/, '')
+            begin
+              require require_path
+              loaded += 1
+              puts "[auto-await] loaded async source from #{spec.name}: #{require_path}" if debug
+            rescue LoadError, StandardError => e
+              warn "[auto-await] Warning: failed to load async source from #{spec.name}/#{require_path}: #{e.message}" if debug
+            end
+          end
+        end
+
+        puts "[auto-await] auto-loaded #{loaded} async source file(s)" if debug && loaded.positive?
+      end
+    end
+
+    attr_reader :async_classes, :async_methods, :async_factories, :taint_returns, :async_accessors, :async_helpers, :helper_factories
+
+    def initialize
+      @async_classes = {}
+      @async_methods = {}
+      @async_factories = {}
+      @taint_returns = {}
+      @async_accessors = {}
+      @async_helpers = {}
+      @helper_factories = {}
+    end
+
+    def async?(class_name, method_name)
+      return false if method_name == :new
+      methods = @async_methods[class_name]
+      return true if methods&.include?(method_name)
+      except = @async_classes[class_name]
+      return true if except && !except.include?(method_name.to_s) && !except.include?(method_name.to_sym)
+      false
+    end
+
+    def factory?(class_name, method_name)
+      @async_factories[class_name]&.include?(method_name)
+    end
+
+    def taint_return_class(class_name, method_name)
+      @taint_returns[class_name]&.[](method_name)
+    end
+
+    def tainted_class?(class_name)
+      @async_classes.key?(class_name) ||
+        @async_methods.key?(class_name) ||
+        @async_factories.key?(class_name) ||
+        @taint_returns.key?(class_name)
+    end
+  end
+end
+
+# Phase 17.5 — Auto-Await: register runtime gem async sources.
+# Each binding declares which methods return Promises so the
+# build-time analyzer can insert .__await__ automatically.
+CloudflareWorkers::AsyncRegistry.register_async_source do
+  async_method 'Cloudflare::D1Database', :execute
+  async_method 'Cloudflare::D1Database', :get_first_row
+  async_method 'Cloudflare::D1Database', :execute_insert
+  async_method 'Cloudflare::D1Database', :execute_batch
+  taint_return 'Cloudflare::D1Database', :prepare, 'Cloudflare::D1Statement'
+  taint_return 'Cloudflare::D1Database', :[], 'Cloudflare::D1Statement'
+
+  async_method 'Cloudflare::D1Statement', :all
+  async_method 'Cloudflare::D1Statement', :first
+  async_method 'Cloudflare::D1Statement', :run
+
+  async_method 'Cloudflare::KVNamespace', :get
+  async_method 'Cloudflare::KVNamespace', :get_with_metadata
+  async_method 'Cloudflare::KVNamespace', :put
+  async_method 'Cloudflare::KVNamespace', :delete
+  async_method 'Cloudflare::KVNamespace', :list
+
+  async_method 'Cloudflare::R2Bucket', :get
+  async_method 'Cloudflare::R2Bucket', :get_binary
+  async_method 'Cloudflare::R2Bucket', :put
+  async_method 'Cloudflare::R2Bucket', :delete
+  async_method 'Cloudflare::R2Bucket', :list
+  async_method 'Cloudflare::R2Bucket', :head
+
+  async_method 'Cloudflare::AI', :run
+  taint_return 'Cloudflare::AI', :run_stream, 'Cloudflare::AI::Stream'
+
+  async_method 'Cloudflare::Cache', :match
+  async_method 'Cloudflare::Cache', :put
+  async_method 'Cloudflare::Cache', :delete
+
+  async_factory 'Cloudflare::Email', :new
+  async_method 'Cloudflare::Email', :send
+
+  async_method 'Cloudflare::Queue', :send
+  async_method 'Cloudflare::Queue', :send_batch
+
+  async_factory 'Cloudflare::DurableObjectNamespace', :new
+  taint_return 'Cloudflare::DurableObjectNamespace', :get, 'Cloudflare::DurableObjectStub'
+  taint_return 'Cloudflare::DurableObjectNamespace', :get_by_name, 'Cloudflare::DurableObjectStub'
+  taint_return 'Cloudflare::DurableObjectState', :storage, 'Cloudflare::DurableObjectStorage'
+  async_method 'Cloudflare::DurableObjectStub', :fetch
+
+  async_method 'Cloudflare::DurableObjectStorage', :get
+  async_method 'Cloudflare::DurableObjectStorage', :put
+  async_method 'Cloudflare::DurableObjectStorage', :delete
+  async_method 'Cloudflare::DurableObjectStorage', :list
+  async_method 'Cloudflare::DurableObjectStorage', :transaction
+
+  async_method 'Cloudflare::HTTP', :fetch
+
+  async_method 'Faraday::Connection', :get
+  async_method 'Faraday::Connection', :post
+  async_method 'Faraday::Connection', :put
+  async_method 'Faraday::Connection', :delete
+  async_method 'Faraday::Connection', :patch
+  async_method 'Faraday::Connection', :head
+end