ruby_llm-browser 0.1.0

data/lib/ruby_llm/browser/rails/actor_record.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    module Rails
+      # A durable mutex per actor. Locking an empty set of operations cannot serialize
+      # the first two reservations, so reservations first write this shared row.
+      class ActorRecord < ActiveRecord::Base
+        self.table_name = "ruby_llm_browser_actors"
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/rails/approval_record.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    module Rails
+      # Durable row for a host-issued single-use {RubyLLM::Browser::Approval}.
+      #
+      # Only {ActiveRecordApprovalStore#consume_once} mutates a consumed approval, and it
+      # does so inside a row-locked transaction so two workers cannot both consume the
+      # same grant.
+      class ApprovalRecord < ActiveRecord::Base
+        self.table_name = "ruby_llm_browser_approvals"
+
+        # Approval timestamps come from the host clock, not from ActiveRecord.
+        self.record_timestamps = false
+
+        def to_approval
+          Approval.new(
+            id: id, actor_id: actor_id, run_id: run_id, url: url,
+            action_digest: action_digest, action: self.class.load_action(action),
+            page_revision: page_revision, operation_id: operation_id, session_id: session_id,
+            issued_at: self.class.to_time(issued_at), expires_at: self.class.to_time(expires_at),
+            consumed_at: self.class.to_time(consumed_at), revoked: revoked
+          )
+        end
+
+        def self.load_action(value)
+          return nil if value.nil?
+
+          value.is_a?(String) ? JSON.parse(value) : value
+        end
+
+        def self.dump_action(action)
+          return nil if action.nil?
+
+          Redactor.canonical_json(action)
+        end
+
+        def self.to_time(value)
+          case value
+          when nil then nil
+          when Time then value
+          else value.respond_to?(:to_time) ? value.to_time : value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/rails/operation_job.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    module Rails
+      # Active Job wrapper for one bounded browser operation.
+      #
+      # The job is deliberately *not* a scheduler: it never reserves a second operation
+      # and never retries an effectful call. The host reserves (or attaches to) a durable
+      # operation with {.enqueue} and this job attaches to that exact row. On delivery it
+      # leases the row (bumping its fence), refuses the wrong actor or an already-terminal
+      # operation, and runs the read-only operation through the {Engine}. A duplicated or
+      # resumed delivery finds a non-`:reserved` row and returns without a remote call; a
+      # worker that lost the lease is refused as stale.
+      #
+      # The context (backend, source policy, stores, budget, consent) is host-supplied and
+      # cannot be serialized, so the job builds it from a configured factory:
+      #
+      #   RubyLLM::Browser::Rails.context_factory = lambda do |actor_id:, run_id:|
+      #     RubyLLM::Browser::Context.new(
+      #       actor_id: actor_id, run_id: run_id, backend: qualified_backend,
+      #       source_policy: host_policy, operation_store: RubyLLM::Browser::Rails.operation_store
+      #     )
+      #   end
+      class OperationJob < ActiveJob::Base
+        # Do not write URLs, instructions or host-pinned schemas into Active Job logs.
+        self.log_arguments = false
+        class << self
+          # ->(actor_id:, run_id:) { RubyLLM::Browser::Context }
+          attr_accessor :context_factory
+
+          # Overrides the module store for this job class. Defaults to the module store.
+          attr_accessor :operation_store
+
+          # Reserves (or attaches to) the durable operation for +idempotency_key+ and
+          # enqueues exactly one job for it. A second call with the same key attaches to
+          # the same operation instead of reserving a new one.
+          #
+          # @return [Operation] the reserved or attached operation
+          def enqueue(actor_id:, run_id:, kind:, url:, budget:, idempotency_key: nil,
+                      instruction: nil, schema: nil, max_bytes: nil, store: nil, now: nil)
+            configured_store = operation_store || RubyLLM::Browser::Rails.operation_store
+            store ||= configured_store
+            raise InvalidInput, "enqueue must use the job's operation store" unless store.equal?(configured_store)
+            now ||= RubyLLM::Browser::Rails.clock.call
+            unless %w[inspect extract].include?(kind.to_s)
+              raise InvalidInput, "browser jobs support inspect and extract only"
+            end
+            candidate = Operation.new(
+              id: Operation.generate_id, actor_id: actor_id, run_id: run_id, budget: budget,
+              state: :reserved, idempotency_key: idempotency_key, created_at: now, updated_at: now,
+              request_digest: request_digest(kind: kind, url: url, instruction: instruction,
+                                             schema: schema, max_bytes: max_bytes, budget: budget)
+            )
+            operation = store.attach_or_reserve(candidate)
+            perform_later(
+              operation_id: operation.id, actor_id: actor_id, run_id: run_id, kind: kind.to_s,
+              url: url, instruction: instruction, schema: schema, max_bytes: max_bytes
+            )
+            operation
+          end
+
+          # Binds an idempotency key to the exact host-issued payload and budget.
+          def request_digest(kind:, url:, instruction:, schema:, max_bytes:, budget:)
+            Redactor.digest(kind: kind.to_s, url: url, instruction: instruction, schema: schema,
+                            max_bytes: max_bytes, budget: budget.to_h)
+          end
+        end
+
+        queue_as { RubyLLM::Browser::Rails.job_queue }
+
+        def perform(operation_id:, actor_id:, run_id:, kind:, url:, instruction: nil,
+                    schema: nil, max_bytes: nil)
+          operation = store.fetch(operation_id)
+          return :missing if operation.nil?
+
+          assert_scope!(operation, actor_id, run_id)
+          digest = self.class.request_digest(kind: kind, url: url, instruction: instruction,
+                                             schema: schema, max_bytes: max_bytes, budget: operation.budget)
+          if operation.request_digest && operation.request_digest != digest
+            raise NotAuthorized, "job payload does not match the reserved request"
+          end
+          return :cancelled if operation.state == :cancelled
+          return :terminal if operation.terminal?
+          return :attached unless operation.state == :reserved
+
+          leased = store.lease(operation_id, actor_id: actor_id, run_id: run_id, now: now)
+          return :cancelled if leased.state == :cancelled
+
+          result = run(kind, leased, url: url, instruction: instruction, schema: schema,
+                                     max_bytes: max_bytes)
+
+          # Keep unknown action/start results, even when cleanup later closes a session.
+          final = settled(operation_id)
+          return :cancelled if final == :cancelled
+
+          result.ok? ? (final || result.to_h) : result.to_h
+        rescue InvalidInput => e
+          raise unless fenced?(e)
+
+          :fenced_out
+        end
+
+        private
+
+        # Reports the durable state if the host cancelled or another worker fenced this
+        # one while the operation was running; otherwise returns nil so the engine's own
+        # result is used.
+        def settled(operation_id)
+          final = store.fetch(operation_id)
+          case final&.state
+          when :cancelled then :cancelled
+          when :cleanup_pending then :cleanup_pending
+          when :unknown then :unknown
+          end
+        end
+
+        def run(kind, operation, url:, instruction:, schema:, max_bytes:)
+          context = build_context(operation)
+          unless context.is_a?(Context) && context.operation_store.equal?(store)
+            raise InvalidInput, "job context must use the job's operation store"
+          end
+          engine = Engine.new(context: context)
+          case kind.to_s
+          when "inspect"
+            engine.inspect(url: url, instruction: instruction, max_bytes: max_bytes, operation: operation)
+          when "extract"
+            engine.extract(url: url, schema: schema, instruction: instruction,
+                                       max_bytes: max_bytes, operation: operation)
+          else
+            raise InvalidInput, "unknown browser operation kind #{kind.inspect}"
+          end
+        end
+
+        def build_context(operation)
+          factory = self.class.context_factory || RubyLLM::Browser::Rails.context_factory
+          raise InvalidInput, "no RubyLLM::Browser context factory is configured" if factory.nil?
+
+          factory.call(actor_id: operation.actor_id, run_id: operation.run_id)
+        end
+
+        def assert_scope!(operation, actor_id, run_id)
+          return if operation.actor_id == actor_id && operation.run_id == run_id
+
+          raise NotAuthorized, "operation #{operation.id} belongs to a different actor or run"
+        end
+
+        def fenced?(error)
+          error.message.include?("stale") || error.message.include?("fenced") ||
+            error.message.include?("cancelled")
+        end
+
+        def store
+          self.class.operation_store || RubyLLM::Browser::Rails.operation_store
+        end
+
+        def now
+          RubyLLM::Browser::Rails.clock.call
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/rails/operation_record.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    module Rails
+      # Durable row for one browser operation.
+      #
+      # The record is a projection of {RubyLLM::Browser::Operation}: the store is the
+      # only writer, and every write goes through a transaction that checks the fence
+      # token, so a stale, duplicated or cancelled worker cannot overwrite newer state.
+      class OperationRecord < ActiveRecord::Base
+        self.table_name = "ruby_llm_browser_operations"
+
+        # The domain object owns its own timestamps (driven by the injected clock), so
+        # ActiveRecord must not overwrite them on save.
+        self.record_timestamps = false
+
+        # Rebuilds the immutable domain object from persisted columns.
+        def to_operation
+          Operation.new(
+            id: id, actor_id: actor_id, run_id: run_id, state: state.to_sym,
+            session_id: session_id, idempotency_key: idempotency_key,
+            steps: steps, bytes: bytes, fence: fence, error_code: error_code,
+            budget: self.class.load_budget(budget),
+            cancel_requested: cancel_requested,
+            request_digest: request_digest,
+            created_at: self.class.to_time(created_at), updated_at: self.class.to_time(updated_at)
+          )
+        end
+
+        def self.load_budget(value)
+          case value
+          when Budget then value
+          when String then Budget.new(**JSON.parse(value, symbolize_names: true))
+          when Hash then Budget.new(**value.to_h { |key, nested| [ key.to_sym, nested ] })
+          else raise InvalidInput, "stored operation budget is missing or malformed"
+          end
+        end
+
+        def self.dump_budget(budget)
+          Redactor.canonical_json(budget.to_h)
+        end
+
+        # ActiveRecord hands back +ActiveSupport::TimeWithZone+, which is not a +Time+.
+        # The domain objects insist on real +Time+ values.
+        def self.to_time(value)
+          case value
+          when nil then nil
+          when Time then value
+          else value.respond_to?(:to_time) ? value.to_time : value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/rails/reaper.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    module Rails
+      # Durable cleanup and reconciliation sweep for the Rails adapter.
+      #
+      # The reaper is the safety net for operations whose worker died, whose start or end
+      # outcome is unknown, or that exceeded their wall-clock budget. It never invents
+      # success: it asks the backend to reconcile, attempts a real session close, and
+      # leaves `unknown` / `cleanup_pending` visible (with the reservation held) until
+      # closure or provider expiry is confirmed.
+      #
+      #   RubyLLM::Browser::Rails::Reaper.new(backend: qualified_backend).sweep
+      #
+      # Closing or re-marking an operation bumps its fence, so a surviving worker that
+      # resumes after the sweep is refused as stale.
+      class Reaper
+        # @param backend [RubyLLM::Browser::Backend] used to reconcile and close sessions
+        # @param store [RubyLLM::Browser::OperationStore] defaults to the module store
+        # @param ttl_seconds [Numeric, nil] optional idle TTL in addition to the budget
+        def initialize(backend:, store: nil, clock: nil, logger: nil, ttl_seconds: nil)
+          @backend = backend
+          @store = store || RubyLLM::Browser::Rails.operation_store
+          @clock = clock || RubyLLM::Browser::Rails.clock
+          @logger = logger || RubyLLM::Browser.logger
+          @ttl_seconds = ttl_seconds
+          if ttl_seconds && !(ttl_seconds.is_a?(Numeric) && ttl_seconds.finite? && ttl_seconds.positive?)
+            raise InvalidInput, "reaper TTL must be a positive finite number"
+          end
+        end
+
+        # Sweeps every open operation once.
+        #
+        # @return [Hash] counts keyed by outcome (`:checked`, `:closed`, `:cleanup_pending`,
+        #   `:unknown`, `:kept`) plus `:at`
+        def sweep(now: nil)
+          time = now || @clock.call
+          summary = Hash.new(0)
+          @store.open_operations.each do |operation|
+            summary[:checked] += 1
+            summary[reap(operation, time)] += 1
+          end
+          summary[:at] = time
+          summary
+        end
+
+        private
+
+        def reap(operation, now)
+          return :kept unless reapable?(operation, now)
+
+          operation = @store.lease(operation.id, actor_id: operation.actor_id,
+                                  run_id: operation.run_id, now: now)
+          return close(operation, now) if never_started?(operation)
+
+          case @backend.reconcile(operation, now: now)
+          when :closed then close(operation, now)
+          else
+            if operation.session_id
+              close_remote?(operation, now) ? close(operation, now) : mark_cleanup_pending(operation, now)
+            else
+              write(operation, :unknown, now, error_code: SessionUnknown.code)
+              :unknown
+            end
+          end
+        rescue StandardError
+          @logger&.warn { "browser reaper could not reconcile an operation" }
+          :failed
+        end
+
+        def reapable?(operation, now)
+          operation.cancel_requested? || operation.cleanup_pending? || operation.expired?(now) || idle?(operation, now)
+        end
+
+        def idle?(operation, now)
+          return false if @ttl_seconds.nil?
+
+          last = operation.updated_at || operation.created_at
+          !last.nil? && (now - last) >= @ttl_seconds
+        end
+
+        # A reserved operation with no session never reached the provider.
+        def never_started?(operation)
+          operation.session_id.nil? && operation.state == :reserved
+        end
+
+        def close_remote?(operation, now)
+          return false if operation.session_id.nil?
+
+          session = Session.new(id: operation.session_id)
+          @backend.end_session(session, operation: operation, now: now)
+        rescue StandardError
+          false
+        end
+
+        def close(operation, now)
+          if operation.session_id
+            @store.confirm_closed(operation, session_id: operation.session_id, now: now)
+          else
+            write(operation, :closed, now)
+          end
+          :closed
+        end
+
+        def mark_cleanup_pending(operation, now)
+          write(operation, :cleanup_pending, now, error_code: CleanupPending.code)
+          :cleanup_pending
+        end
+
+        def write(operation, target, now, error_code: :keep)
+          @store.update(operation.advance(target, now: now, error_code: error_code))
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/rails/schema.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    module Rails
+      # Canonical table definitions for the durable Rails adapter.
+      #
+      # This is a plain-Ruby equivalent of the install generator's migration, so tests
+      # and non-migrated fixtures can create the schema directly:
+      #
+      #   RubyLLM::Browser::Rails::Schema.create!(ActiveRecord::Base.connection)
+      module Schema
+        OPERATIONS_TABLE = "ruby_llm_browser_operations"
+        APPROVALS_TABLE = "ruby_llm_browser_approvals"
+
+        module_function
+
+        # Creates any missing tables. Existing tables are left untouched, so this is
+        # safe to call from a test harness or a boot task.
+        def create!(connection = ActiveRecord::Base.connection)
+          unless connection.table_exists?("ruby_llm_browser_actors")
+            connection.create_table("ruby_llm_browser_actors", id: :string) do |table|
+              table.integer :sequence, null: false, default: 0
+            end
+          end
+          create_operations!(connection) unless connection.table_exists?(OPERATIONS_TABLE)
+          create_approvals!(connection) unless connection.table_exists?(APPROVALS_TABLE)
+          true
+        end
+
+        def create_operations!(connection)
+          connection.create_table(OPERATIONS_TABLE, id: false) do |table|
+            table.string :id, null: false, primary_key: true
+            table.string :actor_id, null: false
+            table.string :run_id, null: false
+            table.string :state, null: false
+            table.string :session_id
+            table.string :idempotency_key
+            table.string :request_digest
+            table.integer :steps, null: false, default: 0
+            table.integer :bytes, null: false, default: 0
+            table.integer :fence, null: false, default: 0
+            table.string :error_code
+            table.boolean :cancel_requested, null: false, default: false
+            table.text :budget, null: false
+            table.datetime :created_at
+            table.datetime :updated_at
+
+            table.index [ :actor_id, :run_id, :idempotency_key ], unique: true,
+                                                                 name: "index_ruby_llm_browser_operations_on_idempotency",
+                                                                 where: "idempotency_key IS NOT NULL"
+            table.index %i[actor_id state], name: "index_ruby_llm_browser_operations_on_actor_state"
+            table.index :state, name: "index_ruby_llm_browser_operations_on_state"
+          end
+        end
+
+        def create_approvals!(connection)
+          connection.create_table(APPROVALS_TABLE, id: false) do |table|
+            table.string :id, null: false, primary_key: true
+            table.string :actor_id, null: false
+            table.string :run_id, null: false
+            table.string :url, null: false
+            table.string :action_digest, null: false
+            table.text :action
+            table.string :page_revision
+            table.string :operation_id
+            table.string :session_id
+            table.datetime :issued_at, null: false
+            table.datetime :expires_at, null: false
+            table.datetime :consumed_at
+            table.boolean :revoked, null: false, default: false
+            table.datetime :created_at
+            table.datetime :updated_at
+
+            table.index %i[actor_id run_id], name: "index_ruby_llm_browser_approvals_on_actor_run"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/rails.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# Optional Rails 8 / ActiveRecord / Active Job adapter for RubyLLM::Browser.
+#
+#   # config/initializers/ruby_llm_browser.rb
+#   require "ruby_llm/browser/rails"
+#
+#   RubyLLM::Browser::Rails.context_factory = lambda do |actor_id:, run_id:|
+#     RubyLLM::Browser::Context.new(
+#       actor_id: actor_id, run_id: run_id, backend: qualified_backend,
+#       source_policy: host_policy,
+#       operation_store: RubyLLM::Browser::Rails.operation_store
+#     )
+#   end
+#
+# This file is *not* loaded by `require "ruby_llm/browser"`. The Gem core stays
+# Rails-free; only hosts that opt in load ActiveRecord and Active Job.
+require "ruby_llm/browser"
+
+require "json"
+require "active_record"
+require "active_job"
+
+require_relative "rails/schema"
+require_relative "rails/actor_record"
+require_relative "rails/operation_record"
+require_relative "rails/approval_record"
+require_relative "rails/active_record_operation_store"
+require_relative "rails/active_record_approval_store"
+require_relative "rails/operation_job"
+require_relative "rails/reaper"
+
+module RubyLLM
+  module Browser
+    # Durable, multi-worker adapter for hosts that run Rails (or plain ActiveRecord +
+    # Active Job). It provides an ActiveRecord operation/approval store, a scoped
+    # Active Job, and a cleanup reaper. It never guesses provider truth and never starts
+    # a session the core would refuse.
+    module Rails
+      class << self
+        # ->(actor_id:, run_id:) { RubyLLM::Browser::Context }, supplied by the host.
+        attr_accessor :context_factory
+
+        # Returns the current UTC time used by the adapter.
+        def clock
+          @clock ||= -> { Time.now.utc }
+        end
+        attr_writer :clock
+
+        # The Active Job queue name. Defaults to `:default`.
+        def job_queue
+          @job_queue || :default
+        end
+        attr_writer :job_queue
+
+        # Durable operation store. Defaults to an {ActiveRecordOperationStore}.
+        def operation_store
+          @operation_store ||= ActiveRecordOperationStore.new
+        end
+        attr_writer :operation_store
+
+        # Durable approval store. Defaults to an {ActiveRecordApprovalStore}.
+        def approval_store
+          @approval_store ||= ActiveRecordApprovalStore.new
+        end
+        attr_writer :approval_store
+
+        # Restores process defaults. Primarily a test helper.
+        def reset!
+          @context_factory = nil
+          @clock = nil
+          @job_queue = nil
+          @operation_store = nil
+          @approval_store = nil
+        end
+      end
+    end
+  end
+end