homura-runtime 0.1.0

data/lib/cloudflare_workers/email.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+# backtick_javascript: true
+# await: true
+#
+# Phase 17 — Cloudflare Email Service (`SEND_EMAIL` binding).
+#
+#   Cloudflare::Email.new(env.SEND_EMAIL).send(
+#     to: 'u@example.com',
+#     from: 'noreply@yourdomain.com',
+#     subject: 'Hello',
+#     text: 'Plain body'
+#   ).__await__
+#
+# See https://developers.cloudflare.com/email-service/api/send-emails/workers-api/
+
+module Cloudflare
+  class Email
+    class Error < StandardError
+      attr_reader :code
+
+      def initialize(message, code: nil)
+        @code = code
+        super(message.to_s)
+      end
+    end
+
+    attr_reader :js
+
+    def initialize(js)
+      @js = js
+    end
+
+    def available?
+      js = @js
+      !!`(#{js} !== null && #{js} !== undefined && #{js} !== Opal.nil)`
+    end
+
+    # Workers `env.SEND_EMAIL.send({ to, from, subject, text?, html?, replyTo? })`.
+    # `to`: String, Array (nested), or `{ email:, name?: }`; name is forwarded to Workers as
+    # `{ email, name }` entries when present. `from` / `reply_to`: String or `{ email:, name?: }`.
+    # At least one of `text:` or `html:` is required.
+    def send(to:, from:, subject:, text: nil, html: nil, reply_to: nil)
+      js = @js
+      err_klass = Cloudflare::Email::Error
+      raise Error, 'send_email binding not bound' unless available?
+
+      raise Error, 'subject is required' if subject.nil? || subject.to_s.strip.empty?
+
+      has_text = !(text.nil? || text.to_s.empty?)
+      has_html = !(html.nil? || html.to_s.empty?)
+      raise Error, 'text or html is required' unless has_text || has_html
+
+      payload = build_send_payload(to: to, from: from, subject: subject.to_s, text: text, html: html, reply_to: reply_to)
+
+      cf = Cloudflare
+      # 多行 x-string をメソッド末尾に置くと Opal が Promise を返さない出力になることがあるため return を明示する。
+      return `(async function(binding, payload, Kernel, Err, cf) {
+        try {
+          var r = await binding.send(payload);
+          if (r == null || r === undefined) {
+            var o0 = {}; o0['message_id'] = ''; o0['cf_send_result_json'] = '"void"';
+            return cf.$js_to_ruby(o0);
+          }
+          var raw = '';
+          try { raw = JSON.stringify(r); } catch (x1) { raw = String(r); }
+          var mid = r.messageId != null ? String(r.messageId)
+            : (r.message_id != null ? String(r.message_id) : '');
+          var o = {}; o['message_id'] = mid; o['cf_send_result_json'] = raw;
+          return cf.$js_to_ruby(o);
+        } catch (e) {
+          var code = (e && e.code != null) ? String(e.code) : '';
+          var msg = (e && e.message) ? String(e.message) : String(e);
+          Kernel.$raise(Err.$new(msg, Opal.hash({ code: code })));
+        }
+      })(#{js}, #{payload}, #{Kernel}, #{err_klass}, #{cf})`
+    end
+
+    private
+
+    def build_send_payload(to:, from:, subject:, text:, html:, reply_to:)
+      obj = `({})`
+      # Cloudflare Workers API は payload の text/html/subject を JS の primitive string として期待する。
+      # Opal の String は typeof === 'object' のため、そのまま代入すると multipart の html が無視されることがある。
+      `#{obj}.subject = #{subject}.toString()`
+
+      # --- to (string | mixed array per Workers API) ---------------------
+      to_js = normalize_to_js(to)
+      `#{obj}.to = #{to_js}`
+
+      # --- from -----------------------------------------------------------
+      `#{obj}.from = #{normalize_from_js(from)}`
+
+      `#{obj}.text = #{text}.toString()` if !(text.nil? || text.to_s.empty?)
+      `#{obj}.html = #{html}.toString()` if !(html.nil? || html.to_s.empty?)
+
+      # --- replyTo (camelCase in Workers API) -----------------------------
+      rt_js = normalize_optional_reply_js(reply_to)
+      `#{obj}.replyTo = #{rt_js}` unless rt_js.nil?
+
+      obj
+    end
+
+    # Returns a JS array: mix of address strings and `{ email, name? }` objects (Workers API shape).
+    def normalize_to_js(raw)
+      entries = flatten_recipients(raw)
+      raise Error, 'to is empty' if entries.empty?
+
+      arr = `([])`
+      entries.each do |e|
+        case e
+        when String
+          `#{arr}.push(#{e})`
+        when Hash
+          js = `({})`
+          `#{js}.email = #{e[:email]}`
+          `#{js}.name = #{e[:name].to_s}` if e[:name] && !e[:name].to_s.strip.empty?
+          `#{arr}.push(#{js})`
+        end
+      end
+      arr
+    end
+
+    # Returns Ruby strings (bare address) or `{ email:, name: }` when a display name was given.
+    def flatten_recipients(raw)
+      case raw
+      when nil
+        []
+      when String
+        s = raw.strip
+        s.empty? ? [] : [s]
+      when Hash
+        em = raw[:email] || raw['email']
+        return [] if em.nil? || em.to_s.strip.empty?
+        nm = raw[:name] || raw['name']
+        if nm.nil? || nm.to_s.strip.empty?
+          [em.to_s.strip]
+        else
+          [{ email: em.to_s.strip, name: nm.to_s }]
+        end
+      when Array
+        raw.flat_map { |x| flatten_recipients(x) }
+      else
+        s = raw.to_s.strip
+        s.empty? ? [] : [s]
+      end
+    end
+
+    def normalize_from_js(raw)
+      normalize_address_js(raw)
+    end
+
+    def normalize_optional_reply_js(raw)
+      return nil if raw.nil?
+      return nil if raw.is_a?(Array) && raw.empty?
+      return normalize_optional_reply_js(raw.first) if raw.is_a?(Array)
+
+      normalize_address_js(raw)
+    end
+
+    # Returns a JS string ("a@b.com") or object { email, name }.
+    def normalize_address_js(raw)
+      case raw
+      when String
+        s = raw.strip
+        raise Error, 'from address is empty' if s.empty?
+        return s
+      when Hash
+        em = raw[:email] || raw['email']
+        nm = raw[:name] || raw['name']
+        raise Error, 'from.email is required' if em.nil? || em.to_s.strip.empty?
+        js = `({})`
+        `#{js}.email = #{em.to_s.strip}`
+        `#{js}.name = #{nm.to_s}` unless nm.nil? || nm.to_s.strip.empty?
+        js
+      else
+        normalize_address_js(raw.to_s)
+      end
+    end
+  end
+end

data/lib/cloudflare_workers/http.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+# backtick_javascript: true
+# await: true
+#
+# Phase 6 — HTTP client foundation.
+#
+# Cloudflare::HTTP.fetch wraps globalThis.fetch (V8 / Node.js / Workers)
+# and exposes a Ruby-friendly response object. Sinatra routes use
+# `.__await__` inside a `# await: true` block, the same pattern that
+# the D1/KV/R2 wrappers use for their JS Promises.
+#
+# This module is the single bridge that lets unmodified Ruby HTTP gems
+# (Net::HTTP, Faraday adapters, OpenAI clients, etc.) reach the
+# network. There is no socket-level fallback — everything ultimately
+# goes through `globalThis.fetch`, because Cloudflare Workers does not
+# expose a TCP socket API.
+
+require 'json'
+
+module Cloudflare
+  class HTTPError < StandardError
+    attr_reader :url, :method
+    def initialize(message, url: nil, method: nil)
+      @url = url
+      @method = method
+      super("[Cloudflare::HTTP] #{method || 'GET'} #{url}: #{message}")
+    end
+  end
+
+  # Lightweight response wrapper around the JS Response object.
+  # The body is read eagerly (text()) so callers see a plain Ruby
+  # String. `headers` is a frozen Hash with lowercased string keys.
+  class HTTPResponse
+    attr_reader :status, :headers, :body, :url
+
+    def initialize(status:, headers:, body:, url:)
+      @status = status
+      @headers = headers
+      @body = body
+      @url = url
+    end
+
+    def ok?
+      @status >= 200 && @status < 300
+    end
+
+    def json
+      JSON.parse(@body)
+    end
+
+    def [](name)
+      @headers[name.to_s.downcase]
+    end
+  end
+
+  module HTTP
+    DEFAULT_HEADERS = {}.freeze
+
+    # Issue an HTTP request via globalThis.fetch.
+    #
+    #   res = Cloudflare::HTTP.fetch('https://api.example.com/users',
+    #           method: 'POST',
+    #           headers: { 'content-type' => 'application/json' },
+    #           body: { name: 'kazu' }.to_json).__await__
+    #   res.status   # => 200
+    #   res.json     # => { 'id' => 1, 'name' => 'kazu' }
+    #
+    # The whole response body is awaited and returned as a String.
+    # Use `Cloudflare::HTTPResponse#body` to access raw text.
+    def self.fetch(url, method: 'GET', headers: nil, body: nil)
+      hdrs = headers || DEFAULT_HEADERS
+      method_str = method.to_s.upcase
+      js_headers = ruby_headers_to_js(hdrs)
+      js_body = body.nil? ? nil : body.to_s
+      url_str = url.to_s
+      response_klass = Cloudflare::HTTPResponse
+      err_klass = Cloudflare::HTTPError
+      headers_to_hash = method(:js_headers_to_hash)
+      _ = headers_to_hash # silence opal lint
+
+      # NOTE: the multi-line backtick below returns a Promise BECAUSE it
+      # is assigned to `js_promise` (and `js_promise.__await__` awaits
+      # it). Opal treats a multi-line x-string as a statement, not an
+      # expression — safe when assigned, but a bare multi-line backtick
+      # at end-of-method silently drops the Promise. Do NOT refactor
+      # this into `def fetch ... end` with the backtick as the last
+      # expression. See the single-line IIFE pattern used in
+      # lib/cloudflare_workers/{cache,queue,durable_object}.rb#put for
+      # the alternative that survives either position. (Phase 11B audit.)
+      js_promise = `
+        (async function() {
+          var init = { method: #{method_str}, headers: #{js_headers}, redirect: 'follow' };
+          if (#{js_body} !== nil && #{js_body} != null) { init.body = #{js_body}; }
+          var resp;
+          try {
+            resp = await globalThis.fetch(#{url_str}, init);
+          } catch (e) {
+            #{Kernel}.$$raise(#{err_klass}.$new(e.message || String(e), Opal.hash({ url: #{url_str}, method: #{method_str} })));
+          }
+          var text = '';
+          try {
+            text = await resp.text();
+          } catch (e) {
+            text = '';
+          }
+          var hash_keys = [];
+          var hash_vals = [];
+          if (resp.headers && typeof resp.headers.forEach === 'function') {
+            resp.headers.forEach(function(value, key) {
+              hash_keys.push(String(key).toLowerCase());
+              hash_vals.push(String(value));
+            });
+          }
+          return { status: resp.status|0, text: text, hkeys: hash_keys, hvals: hash_vals };
+        })()
+      `
+
+      js_result = js_promise.__await__
+      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
+
+    # Convert a Ruby Hash<String, String> into a plain JS object usable
+    # as the `headers` init for fetch().
+    def self.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
+
+    # Internal: convert JS Headers / iterable to Ruby Hash with
+    # lowercased string keys. Currently inlined in fetch() but exposed
+    # for completeness.
+    def self.js_headers_to_hash(js_headers)
+      h = {}
+      `
+        if (#{js_headers} && typeof #{js_headers}.forEach === 'function') {
+          #{js_headers}.forEach(function(value, key) {
+            #{h}.$$smap[String(key).toLowerCase()] = String(value);
+          });
+        }
+      `
+      h
+    end
+  end
+end

data/lib/cloudflare_workers/multipart.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+# backtick_javascript: true
+#
+# Phase 11A — multipart/form-data receive pipeline.
+#
+# Why a bespoke parser instead of Rack::Multipart::Parser?
+#
+# Rack's parser does work on Opal in principle (strscan is in stdlib),
+# but it relies on Tempfile — which is a stub on Workers since there is
+# no writable filesystem. It also assumes the request body is a true
+# binary ByteString, whereas on Workers we have to cross the JS/Ruby
+# boundary and Opal Strings are JS Strings (UTF-16 code units). The
+# correct way to pass bytes through that boundary is to encode each
+# byte as a single `char code 0-255` latin1 character, then `unescape
+# / String.fromCharCode.apply` back into a Uint8Array when we need
+# raw bytes again (e.g. R2.put).
+#
+# This module exposes:
+#
+#   Cloudflare::Multipart.parse(body_binstr, content_type)
+#     → Hash[String => Cloudflare::UploadedFile | String]
+#
+#   Cloudflare::UploadedFile
+#     #filename      — original filename from the Content-Disposition header
+#     #content_type  — part Content-Type (defaults to application/octet-stream)
+#     #name          — form field name
+#     #size          — byte length
+#     #bytes_binstr  — the latin1-encoded byte string (1 char = 1 byte)
+#     #to_uint8_array — JS Uint8Array suitable for fetch body / R2.put
+#     #read          — returns bytes_binstr, mirroring Tempfile#read
+#     #rewind        — no-op (content is fully in-memory, there is no
+#                       writable filesystem on Workers)
+#
+# Also installs `Rack::Request#post?`-path hook: when the Sinatra route
+# calls `params['file']`, `Rack::Request#POST` delegates to
+# `Cloudflare::Multipart.rack_params(env)` which parses once, caches on
+# the env, and hydrates `params` with UploadedFile / String values.
+
+module Cloudflare
+  # Struct-ish wrapper for an uploaded file part. Identical shape to
+  # the `{:filename, :type, :name, :tempfile, :head}` Hash Rack's
+  # parser returns, plus extras for the Workers use case.
+  class UploadedFile
+    attr_reader :filename, :content_type, :name, :head, :bytes_binstr
+
+    def initialize(filename:, content_type:, name:, head: '', bytes_binstr: '')
+      @filename = filename
+      @content_type = content_type || 'application/octet-stream'
+      @name = name
+      @head = head
+      @bytes_binstr = bytes_binstr || ''
+    end
+
+    # Byte length of the part (not the JS string length — they're the
+    # same here because we use latin1 1-byte-per-char encoding).
+    def size
+      @bytes_binstr.length
+    end
+    alias_method :bytesize, :size
+
+    # Convenience accessor matching the CRuby Rack shape.
+    def type
+      @content_type
+    end
+
+    # Read the full byte string. Mirrors Tempfile#read.
+    def read
+      @bytes_binstr
+    end
+
+    def rewind
+      self
+    end
+
+    def close
+      self
+    end
+
+    # Convert the latin1 byte-string to a real JS Uint8Array. Used to
+    # feed raw bytes to `env.BUCKET.put`, `globalThis.fetch(body: ...)`,
+    # `Blob`, etc. without re-encoding through UTF-8.
+    #
+    # NOTE: single-line backtick x-string so Opal emits it as an
+    # expression (multi-line x-strings compile to raw statements and
+    # would silently return `undefined`). Same gotcha documented
+    # elsewhere in this codebase (see lib/cloudflare_workers.rb).
+    def to_uint8_array
+      `(function(s) { var len = s.length; var out = new Uint8Array(len); for (var i = 0; i < len; i++) { out[i] = s.charCodeAt(i) & 0xff; } return out; })(#{@bytes_binstr})`
+    end
+
+    # Convert to a JS Blob for fetch/Response bodies.
+    def to_blob
+      u8 = to_uint8_array
+      ct = @content_type
+      `new Blob([#{u8}], { type: #{ct} })`
+    end
+
+    # Rack-friendly Hash view. Match the exact shape Rack::Multipart
+    # produces so gems that do `params['file'][:filename]` keep working.
+    def to_h
+      {
+        filename: @filename,
+        type:     @content_type,
+        name:     @name,
+        head:     @head,
+        tempfile: self
+      }
+    end
+    alias_method :to_hash, :to_h
+
+    # `#[]` so `file[:filename]` works on the UploadedFile itself
+    # (some gems use the Hash shape, some grab the file object —
+    # support both access patterns to reduce downstream surprises).
+    def [](key)
+      to_h[key.to_sym]
+    end
+  end
+
+  module Multipart
+    CRLF = "\r\n"
+
+    # Extract the multipart boundary from a Content-Type header.
+    # Matches `boundary=AaB03x`, `boundary="weird boundary"`,
+    # and whitespace/case variants. Quoted forms are preserved as-is
+    # so `boundary="foo bar"` → `foo bar` (internal whitespace kept),
+    # while unquoted forms stop at the next delimiter.
+    def self.parse_boundary(content_type)
+      return nil if content_type.nil?
+      ct = content_type.to_s
+      return nil unless ct.downcase.include?('multipart/')
+      # Prefer the quoted form. The quoted value may contain any byte
+      # except a literal `"` (RFC 2046 §5.1.1 bans `"` in the value).
+      if (m = ct.match(/boundary="([^"]+)"/i))
+        return m[1]
+      end
+      if (m = ct.match(/boundary=([^;,\s]+)/i))
+        return m[1]
+      end
+      nil
+    end
+
+    # Parse a multipart/form-data payload.
+    #
+    # @param body_binstr [String] latin1 byte string (1 char = 1 byte)
+    # @param content_type [String] the request Content-Type header
+    # @return [Hash] keys are form-field names (strings); values are
+    #   either UploadedFile (for file parts) or String (for plain
+    #   text fields).
+    def self.parse(body_binstr, content_type)
+      boundary = parse_boundary(content_type)
+      return {} if boundary.nil?
+      return {} if body_binstr.nil? || body_binstr.empty?
+
+      sep       = '--' + boundary
+      term      = '--' + boundary + '--'
+      sep_line  = sep + CRLF
+      sep_last  = sep + CRLF  # the very first boundary may skip the leading CRLF
+      body      = body_binstr.to_s
+
+      # Skip any preamble before the first boundary.
+      start_idx = body.index(sep)
+      return {} if start_idx.nil?
+      cursor = start_idx + sep.length
+      # consume possible CRLF right after the first boundary
+      if body[cursor, 2] == CRLF
+        cursor += 2
+      end
+
+      parts = {}
+
+      loop do
+        # Find the next boundary after cursor.
+        # Each part ends with CRLF before the next "--boundary" line,
+        # or "--boundary--" for the terminator.
+        next_sep = body.index(CRLF + sep, cursor)
+        break if next_sep.nil?
+
+        part = body[cursor...next_sep]
+
+        # Split headers / body on the first blank line (CRLF CRLF).
+        headers_end = part.index(CRLF + CRLF)
+        if headers_end
+          raw_headers = part[0...headers_end]
+          raw_body    = part[(headers_end + 4)..-1] || ''
+        else
+          raw_headers = part
+          raw_body    = ''
+        end
+
+        disposition = nil
+        ctype       = nil
+        raw_headers.split(CRLF).each do |line|
+          name, value = line.split(':', 2)
+          next if name.nil? || value.nil?
+          name = name.strip.downcase
+          value = value.strip
+          case name
+          when 'content-disposition' then disposition = value
+          when 'content-type'        then ctype = value
+          end
+        end
+
+        if disposition
+          field_name = extract_disposition_param(disposition, 'name')
+          filename   = extract_disposition_param(disposition, 'filename')
+          if field_name
+            if filename && !filename.empty?
+              parts[field_name] = UploadedFile.new(
+                name: field_name,
+                filename: filename,
+                content_type: ctype,
+                head: raw_headers,
+                bytes_binstr: raw_body
+              )
+            else
+              parts[field_name] = raw_body
+            end
+          end
+        end
+
+        cursor = next_sep + CRLF.length + sep.length
+        # Check whether this is the terminator `--boundary--`
+        if body[cursor, 2] == '--'
+          break
+        end
+        if body[cursor, 2] == CRLF
+          cursor += 2
+        end
+      end
+
+      parts
+    end
+
+    # Extract a quoted or bare parameter from a Content-Disposition value.
+    # Handles `name="file"; filename="pic.png"` and RFC 5987
+    # `filename*=UTF-8''pic.png` (best-effort URL decoding).
+    #
+    # The `(^|[;\s])` prefix is load-bearing: without it, looking up
+    # `name` would also match inside `filename*=...` (substring "name*=")
+    # and mis-attribute the filename to the form-field name. RFC 7578
+    # places each parameter after `;` (with optional whitespace), so the
+    # prefix is free.
+    def self.extract_disposition_param(disposition, key)
+      k = Regexp.escape(key)
+      # filename*=charset'lang'encoded  (RFC 5987)
+      star_re = /(?:^|[;\s])#{k}\*\s*=\s*([^;]+)/i
+      if (m = disposition.match(star_re))
+        raw = m[1].strip
+        parts = raw.split("'", 3)
+        encoded = parts[2] || parts[0]
+        return decode_rfc5987(encoded)
+      end
+      # Quoted `key="value"`
+      q_re = /(?:^|[;\s])#{k}\s*=\s*"((?:\\"|[^"])*)"/i
+      if (m = disposition.match(q_re))
+        return m[1].gsub('\\"', '"')
+      end
+      # Bare `key=value`
+      b_re = /(?:^|[;\s])#{k}\s*=\s*([^;]+)/i
+      if (m = disposition.match(b_re))
+        return m[1].strip
+      end
+      nil
+    end
+
+    def self.decode_rfc5987(s)
+      `decodeURIComponent(#{s.to_s})`
+    rescue StandardError
+      s
+    end
+
+    # Rack::Request integration — parse the multipart body once per
+    # request, cache on the env, hydrate Sinatra's `params` Hash.
+    #
+    # Called lazily from our patched Rack::Request#POST.
+    def self.rack_params(env)
+      cached = env['cloudflare.multipart']
+      return cached if cached
+
+      ct = env['CONTENT_TYPE']
+      return ({}) unless ct && ct.to_s.downcase.include?('multipart/')
+
+      io = env['rack.input']
+      return ({}) if io.nil?
+
+      # `rack.input` is normally a StringIO wrapping the body_binstr
+      # we staged in src/worker.mjs. Read the full body; it's already
+      # resolved server-side (Workers doesn't stream request bodies
+      # back into Opal).
+      if io.respond_to?(:rewind)
+        begin
+          io.rewind
+        rescue
+          # some stubs don't support rewind — ignore
+        end
+      end
+      body = io.respond_to?(:read) ? io.read.to_s : ''
+
+      parsed = parse(body, ct)
+      env['cloudflare.multipart'] = parsed
+      parsed
+    end
+  end
+end
+
+# --------------------------------------------------------------------
+# Rack::Request hook — expose multipart parts via `params[name]`.
+# --------------------------------------------------------------------
+#
+# Sinatra's `params` is the result of `Rack::Request#params`, which
+# merges GET + POST data. `#POST` on the upstream Rack gem uses
+# `Rack::Multipart.extract_multipart` — which fails on Workers (no
+# Tempfile). We reopen Rack::Request and override #POST to use the
+# bespoke Cloudflare::Multipart parser for multipart requests, falling
+# back to the gem implementation for everything else.
+
+require 'rack/request'
+
+module Rack
+  class Request
+    alias_method :__homura_original_POST, :POST unless method_defined?(:__homura_original_POST)
+
+    def POST
+      ct = env['CONTENT_TYPE']
+      if ct && ct.to_s.downcase.include?('multipart/')
+        ::Cloudflare::Multipart.rack_params(env)
+      else
+        __homura_original_POST
+      end
+    end
+  end
+end