browserctl 0.12.0 → 0.13.0

data/lib/browserctl/state.rb

@@ -42,6 +42,41 @@ module Browserctl
     EXTENSION = ".bctl"
     MANIFEST_VERSION = 1
 
+    # Value object bundling everything needed to persist a state bundle. The
+    # browser-side data lives in `cookies`, `local_storage`, and
+    # `session_storage`; the manifest extras live in `origins`, `flow`, and
+    # `flow_version`; `passphrase` flips the bundle into an encrypted variant.
+    Payload = Data.define(
+      :cookies,
+      :local_storage,
+      :session_storage,
+      :origins,
+      :flow,
+      :flow_version,
+      :passphrase
+    ) do
+      def self.build(cookies: [], local_storage: {}, session_storage: {}, # rubocop:disable Metrics/ParameterLists
+                     origins: nil, flow: nil, flow_version: nil, passphrase: nil)
+        new(
+          cookies: cookies,
+          local_storage: local_storage,
+          session_storage: session_storage,
+          origins: origins,
+          flow: flow,
+          flow_version: flow_version,
+          passphrase: passphrase
+        )
+      end
+
+      def to_bundle_payload
+        {
+          cookies: cookies,
+          local_storage: local_storage,
+          session_storage: session_storage
+        }
+      end
+    end
+
     def self.path(name) = File.join(BASE_DIR, "#{name}#{EXTENSION}")
     def self.exist?(name) = File.exist?(path(name))
 
@@ -51,22 +86,24 @@ module Browserctl
       raise ArgumentError, "invalid state name #{name.inspect} — use letters, digits, _ or - (max 64 chars)"
     end
 
-    # Persist a bundle. `payload` is { cookies:, local_storage:, session_storage: }.
-    # `manifest_extras` may carry origins (override), flow, flow_version.
-    def self.save(name, payload:, origins: nil, flow: nil, flow_version: nil, passphrase: nil) # rubocop:disable Metrics/ParameterLists
+    # Persist a bundle. `payload` is a `State::Payload` value object carrying
+    # cookies, local/session storage, and the manifest extras (origins, flow,
+    # flow_version, passphrase).
+    def self.save(name, payload)
       validate_name!(name)
       FileUtils.mkdir_p(BASE_DIR)
 
+      bundle_payload = payload.to_bundle_payload
       manifest = build_manifest(
         name: name,
-        origins: origins || derive_origins(payload),
-        flow: flow,
-        flow_version: flow_version,
-        cookies: payload[:cookies] || payload["cookies"] || [],
-        encrypted: !passphrase.nil?
+        origins: payload.origins || derive_origins(bundle_payload),
+        flow: payload.flow,
+        flow_version: payload.flow_version,
+        cookies: payload.cookies || [],
+        encrypted: !payload.passphrase.nil?
       )
 
-      blob = Bundle.encode(manifest: manifest, payload: payload, passphrase: passphrase)
+      blob = Bundle.encode(manifest: manifest, payload: bundle_payload, passphrase: payload.passphrase)
       File.open(path(name), "wb", 0o600) { |f| f.write(blob) }
       manifest
     end

data/lib/browserctl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Browserctl
-  VERSION = "0.12.0"
+  VERSION = "0.13.0"
 end

data/lib/browserctl/workflow/recovery_manager.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Workflow
+    # Owns the AUTH_REQUIRED recovery state machine for `load_state`.
+    #
+    # When the daemon reports AUTH_REQUIRED on a `state_load` (e.g. expired
+    # cookies in the bundle), the manager either runs the bound flow or
+    # the caller-provided override, re-saves the bundle, and reloads it
+    # with `skip_auth_check: true`.
+    #
+    # Decoupled from {ContextualPersistence} so the multi-step recovery
+    # logic has a dedicated home and a dedicated spec. The host context
+    # only needs to expose `client` (for daemon RPCs) and `invoke` (for
+    # running the bound flow); see {ContextualPersistence#load_state}.
+    class RecoveryManager
+      AUTH_REQUIRED_CODE = "AUTH_REQUIRED"
+
+      # @param context [#client, #invoke] a workflow context exposing
+      #   the daemon client and an `invoke(flow_name, page:)` entry point.
+      def initialize(context)
+        @context = context
+      end
+
+      # True when `res` is the daemon's AUTH_REQUIRED preflight signal.
+      def self.auth_required?(res)
+        (res[:code] || res["code"]) == AUTH_REQUIRED_CODE
+      end
+
+      # Run recovery for `state_name` given the daemon's initial AUTH_REQUIRED
+      # response. Returns the merged retry result (with `rotated: true`) or
+      # raises {WorkflowError} when no flow is bound and no override is
+      # supplied, or when the post-rotation reload still fails.
+      #
+      # @param state_name      [String]  the bundle name being loaded
+      # @param initial_res     [Hash]    the original AUTH_REQUIRED response
+      # @param on_auth_required [Proc, nil] optional override; when given,
+      #   it runs in lieu of invoking the suggested flow.
+      def recover(state_name, initial_res, on_auth_required: nil)
+        if on_auth_required
+          on_auth_required.call
+        else
+          invoke_bound_flow(state_name, initial_res)
+        end
+
+        rotate_and_reload(state_name)
+      end
+
+      private
+
+      attr_reader :context
+
+      def invoke_bound_flow(state_name, initial_res)
+        flow_name = initial_res[:suggested_flow] || initial_res["suggested_flow"]
+        if flow_name.nil? || flow_name.to_s.empty?
+          raise WorkflowError,
+                "state '#{state_name}' needs auth but bundle has no bound flow — " \
+                "save with `save_state('#{state_name}', flow: :NAME)` or pass on_auth_required:"
+        end
+
+        # Match the daemon's `state load` preflight: it auth-checks the first
+        # open page (insertion order). Passing that same name to the flow
+        # gives stdlib flows a `page` proxy to drive (oauth_github reads
+        # `page.url`, totp_2fa calls `page.fill`, etc.). Falls back to no
+        # page only when nothing is open — `state_save` would have errored
+        # earlier in that case, so this is a defence-in-depth nil.
+        context.invoke(flow_name, page: first_open_page)
+      end
+
+      def rotate_and_reload(state_name)
+        after_save = context.client.state_save(state_name)
+        raise WorkflowError, after_save[:error] if after_save[:error]
+
+        retry_res = context.client.state_load(state_name, skip_auth_check: true)
+        raise WorkflowError, retry_res[:error] if retry_res[:error]
+
+        retry_res.merge(rotated: true)
+      end
+
+      def first_open_page
+        res = context.client.page_list
+        pages = res[:pages] || res["pages"] || []
+        pages.first
+      end
+    end
+  end
+end

data/lib/browserctl/workflow.rb

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 
-require "timeout"
+require_relative "callable_definition"
 require_relative "client"
+require_relative "contextual_persistence"
 require_relative "errors"
 require_relative "flow_registry"
 require_relative "replay/context"
 require_relative "replay/fingerprint_matcher"
 require_relative "replay/snapshot_diff"
-require_relative "secret_resolvers"
-require_relative "session"
 
 module Browserctl
   # Workflow-file format version. Workflows are Ruby files; the schema gate
@@ -66,11 +65,15 @@ module Browserctl
     version
   end
 
-  ParamDef = Struct.new(:name, :required, :secret, :default, :secret_ref, keyword_init: true)
+  # Back-compat aliases — exposed in the public surface (flow_wrapper specs,
+  # workflow specs reference these directly).
+  ParamDef = CallableDefinition::ParamDef
+  StepDef  = CallableDefinition::StepDef
   StepResult = Struct.new(:name, :ok, :error, keyword_init: true)
-  StepDef = Struct.new(:label, :block, :retry_count, :timeout, keyword_init: true)
 
   class WorkflowContext
+    include ContextualPersistence
+
     attr_reader :client, :replay_context, :params
 
     def initialize(params, client, replay_context: nil)
@@ -79,20 +82,6 @@ module Browserctl
       @replay_context = replay_context
     end
 
-    def store(key, value)
-      res = @client.store(key.to_s, value)
-      raise WorkflowError, res[:error] if res[:error]
-
-      value
-    end
-
-    def fetch(key)
-      res = @client.fetch(key.to_s)
-      raise WorkflowError, res[:error] if res[:error]
-
-      res[:value]
-    end
-
     def method_missing(name, *args)
       return @params[name] if @params.key?(name)
 
@@ -121,66 +110,6 @@ module Browserctl
       res
     end
 
-    def save_session(session_name, encrypt: false)
-      res = @client.session_save(session_name, encrypt: encrypt)
-      raise WorkflowError, res[:error] if res[:error]
-
-      res
-    end
-
-    # Persists the daemon's current cookies + storage as a .bctl bundle.
-    # Optional flow binding lets `load_state` auto-rotate when the bundle
-    # is detected as needing authentication.
-    def save_state(name, flow: nil, origins: nil, encrypt: false)
-      passphrase = encrypt ? ENV.fetch("BROWSERCTL_STATE_PASSPHRASE", nil) : nil
-      res = @client.state_save(name.to_s,
-                               flow: flow&.to_s, origins: origins, passphrase: passphrase)
-      raise WorkflowError, res[:error] if res[:error]
-
-      res
-    end
-
-    # Restores a .bctl bundle. When the daemon detects AUTH_REQUIRED before
-    # applying (e.g. expired cookies in the payload), this rotates the bound
-    # flow and retries — no caller code change required.
-    #
-    # @param on_auth_required [Proc, nil] override the auto-rotate path. The
-    #   block runs in the workflow context, in lieu of invoking the manifest's
-    #   bound flow. Use this when the recovery procedure is bespoke.
-    def load_state(name, on_auth_required: nil)
-      res = @client.state_load(name.to_s)
-      return res unless auth_required_response?(res)
-
-      recover_auth_required_state(name.to_s, res, on_auth_required)
-    end
-    DEPRECATED_LOAD_SESSION_FALLBACK = <<~MSG
-      [browserctl] DEPRECATION: `load_session(name, fallback:, expired_if:)` is superseded by
-      `load_state(name)` with a flow-bound bundle (`save_state(name, flow: :name)`).
-      `load_session` will be removed in v0.12. See docs/concepts/state.md.
-    MSG
-
-    def load_session(session_name, fallback: nil, expired_if: nil)
-      warn DEPRECATED_LOAD_SESSION_FALLBACK if fallback || expired_if
-      validate_expired_if!(expired_if)
-      fallback_name = fallback&.to_s
-      res = @client.session_load(session_name)
-
-      if res[:error]
-        raise WorkflowError, res[:error] unless fallback_name
-
-        invoke(fallback_name)
-        return load_after_fallback(session_name, fallback_name)
-      end
-
-      return res if expired_if.nil? || !call_expired_if(expired_if, session_name)
-
-      recover_expired_session(session_name, fallback_name, expired_if)
-    end
-
-    def list_sessions
-      @client.session_list[:sessions]
-    end
-
     def ask(prompt)
       $stderr.print("[browserctl] #{prompt} ")
       $stdin.gets.chomp
@@ -229,95 +158,6 @@ module Browserctl
 
     private
 
-    def auth_required_response?(res)
-      (res[:code] || res["code"]) == "AUTH_REQUIRED"
-    end
-
-    def recover_auth_required_state(name, initial_res, on_auth_required)
-      if on_auth_required
-        on_auth_required.call
-      else
-        flow_name = initial_res[:suggested_flow] || initial_res["suggested_flow"]
-        unless flow_name && !flow_name.to_s.empty?
-          raise WorkflowError,
-                "state '#{name}' needs auth but bundle has no bound flow — " \
-                "save with `save_state('#{name}', flow: :NAME)` or pass on_auth_required:"
-        end
-
-        # Match the daemon's `state load` preflight: it auth-checks the first
-        # open page (insertion order). Passing that same name to the flow
-        # gives stdlib flows a `page` proxy to drive (oauth_github reads
-        # `page.url`, totp_2fa calls `page.fill`, etc.). Falls back to no
-        # page only when nothing is open — `state_save` would have errored
-        # earlier in that case, so this is a defence-in-depth nil.
-        invoke(flow_name, page: first_open_page)
-      end
-
-      after_save = @client.state_save(name)
-      raise WorkflowError, after_save[:error] if after_save[:error]
-
-      retry_res = @client.state_load(name, skip_auth_check: true)
-      raise WorkflowError, retry_res[:error] if retry_res[:error]
-
-      retry_res.merge(rotated: true)
-    end
-
-    def first_open_page
-      res = @client.page_list
-      pages = res[:pages] || res["pages"] || []
-      pages.first
-    end
-
-    def validate_expired_if!(expired_if)
-      return unless expired_if
-
-      unless expired_if.lambda?
-        raise ArgumentError,
-              "expired_if: must be a lambda (-> { }), not a Proc — " \
-              "bare return inside a Proc unwinds the caller"
-      end
-
-      return if expired_if.arity.zero?
-
-      raise ArgumentError,
-            "expired_if: lambda must take zero arguments (got #{expired_if.arity}) — " \
-            "use -> { page(:name).url... } to access pages via the workflow context"
-    end
-
-    def call_expired_if(expired_if, session_name)
-      expired_if.call
-    rescue WorkflowError, StandardError => e
-      raise WorkflowError, "expired_if check failed for session '#{session_name}': #{e.message}"
-    end
-
-    def recover_expired_session(session_name, fallback_name, expired_if)
-      unless fallback_name
-        raise WorkflowError,
-              "session '#{session_name}' is expired; provide fallback: to auto-recover"
-      end
-
-      invoke(fallback_name)
-      res = load_after_fallback(session_name, fallback_name)
-
-      if call_expired_if(expired_if, session_name)
-        raise WorkflowError,
-              "session '#{session_name}' still expired after running fallback '#{fallback_name}'"
-      end
-
-      res
-    end
-
-    def load_after_fallback(session_name, fallback)
-      res = @client.session_load(session_name)
-      return res unless res[:error]
-
-      msg = "session '#{session_name}' still unavailable after running fallback '#{fallback}'"
-      unless Session.exist?(session_name)
-        msg += "\n  Hint: '#{fallback}' did not call save_session(\"#{session_name}\") — add it as the last step."
-      end
-      raise WorkflowError, msg
-    end
-
     def invoke_stack
       @invoke_stack ||= []
     end
@@ -356,6 +196,21 @@ module Browserctl
   class PageProxy
     attr_accessor :replay_context
 
+    # Declarative wrapper for `unwrap @client.METHOD(@name, ...)` one-liners.
+    # Forwards positional + keyword args verbatim. Pass `extract:` to return
+    # a single key from the client response instead of unwrapping.
+    def self.delegate_unwrap(method_name, extract: nil)
+      if extract
+        define_method(method_name) do |*args, **kwargs|
+          @client.public_send(method_name, @name, *args, **kwargs)[extract]
+        end
+      else
+        define_method(method_name) do |*args, **kwargs|
+          unwrap @client.public_send(method_name, @name, *args, **kwargs)
+        end
+      end
+    end
+
     def initialize(name, client, replay_context: nil, matcher: nil)
       @name           = name
       @client         = client
@@ -363,7 +218,20 @@ module Browserctl
       @matcher        = matcher || Replay::FingerprintMatcher.new
     end
 
-    def navigate(url) = unwrap @client.navigate(@name, url)
+    delegate_unwrap :navigate
+    delegate_unwrap :snapshot
+    delegate_unwrap :screenshot
+    delegate_unwrap :wait
+    delegate_unwrap :delete_cookies
+    delegate_unwrap :press
+    delegate_unwrap :storage_set
+    delegate_unwrap :dialog_accept
+    delegate_unwrap :dialog_dismiss
+
+    delegate_unwrap :devtools,    extract: :devtools_url
+    delegate_unwrap :url,         extract: :url
+    delegate_unwrap :evaluate,    extract: :result
+    delegate_unwrap :storage_get, extract: :value
 
     def fill(selector = nil, value = nil, ref: nil)
       with_selector_fallback(:fill, selector, ref) do |sel, r|
@@ -377,24 +245,6 @@ module Browserctl
       end
     end
 
-    def snapshot(**)              = unwrap @client.snapshot(@name, **)
-    def screenshot(**)            = unwrap @client.screenshot(@name, **)
-    def wait(sel, timeout: 30)    = unwrap @client.wait(@name, sel, timeout: timeout)
-    def delete_cookies             = unwrap @client.delete_cookies(@name)
-    def devtools                   = @client.devtools(@name)[:devtools_url]
-    def url                        = @client.url(@name)[:url]
-    def evaluate(expr)             = @client.evaluate(@name, expr)[:result]
-
-    def storage_get(key, store: "local")
-      @client.storage_get(@name, key, store: store)[:value]
-    end
-
-    def storage_set(key, value, store: "local")
-      unwrap @client.storage_set(@name, key, value, store: store)
-    end
-
-    def press(key) = unwrap @client.press(@name, key)
-
     def hover(selector = nil, ref: nil)
       with_selector_fallback(:hover, selector, ref) do |sel, r|
         @client.hover(@name, sel, ref: r)
@@ -413,9 +263,6 @@ module Browserctl
       end
     end
 
-    def dialog_accept(text: nil) = unwrap @client.dialog_accept(@name, text: text)
-    def dialog_dismiss           = unwrap @client.dialog_dismiss(@name)
-
     private
 
     # Issues the wrapped command. If the daemon returns selector_not_found
@@ -461,32 +308,24 @@ module Browserctl
     end
   end
 
-  class WorkflowDefinition
-    attr_reader :name, :description, :param_defs, :steps
-
-    def initialize(name)
-      @name = name
-      @description = nil
-      @param_defs  = {}
-      @steps       = []
-    end
-
-    def desc(text)
-      @description = text
-    end
-
-    def param(name, required: false, secret: false, default: nil, secret_ref: nil)
-      secret = true if secret_ref
-      @param_defs[name] =
-        ParamDef.new(name: name, required: required, secret: secret, default: default, secret_ref: secret_ref)
-    end
-
-    def step(label, retry_count: 0, timeout: nil, &block)
-      @steps << StepDef.new(label: label, block: block, retry_count: retry_count, timeout: timeout)
+  class WorkflowDefinition < CallableDefinition
+    def callable_kind
+      :workflow
     end
 
+    # Definition-time guard: composing a flow into a workflow would copy
+    # flow steps that may close over `page` (a flow-only DSL) into a
+    # context that doesn't expose it. Cross-kind composition is rejected
+    # here rather than failing later inside an `instance_exec`.
     def compose(workflow_name)
-      source = Browserctl.lookup_workflow(workflow_name.to_s)
+      name = workflow_name.to_s
+      if Browserctl.lookup_flow(name)
+        raise ArgumentError,
+              "workflow '#{@name}' cannot compose flow '#{name}': flows return state, " \
+              "workflows share state — composition across kinds is not supported"
+      end
+
+      source = Browserctl.lookup_workflow(name)
       raise WorkflowError, "workflow '#{workflow_name}' not found for composition" unless source
 
       @steps.concat(source.steps)
@@ -499,6 +338,14 @@ module Browserctl
 
     private
 
+    def missing_param_error(name)
+      WorkflowError.new("required param '#{name}' missing")
+    end
+
+    def step_timeout_error(defn)
+      WorkflowError.new("step '#{defn.label}' timed out after #{defn.timeout}s")
+    end
+
     def execute_steps(ctx)
       @steps.map { |defn| run_step(ctx, defn) }.each do |r|
         raise WorkflowError, "step '#{r.name}' failed: #{r.error}" unless r.ok
@@ -508,36 +355,13 @@ module Browserctl
     def run_step(ctx, defn)
       last_error = nil
       (defn.retry_count + 1).times do
-        execute_block(ctx, defn)
+        execute_step_block(ctx, defn)
         return StepResult.new(name: defn.label, ok: true)
       rescue StandardError => e
         last_error = e
       end
       StepResult.new(name: defn.label, ok: false, error: last_error.message)
     end
-
-    def execute_block(ctx, defn)
-      if defn.timeout
-        ::Timeout.timeout(defn.timeout) { ctx.instance_exec(&defn.block) }
-      else
-        ctx.instance_exec(&defn.block)
-      end
-    rescue ::Timeout::Error
-      raise WorkflowError, "step '#{defn.label}' timed out after #{defn.timeout}s"
-    end
-
-    def resolve_params(provided)
-      @param_defs.each_with_object({}) do |(name, defn), out|
-        val = if defn.secret_ref
-                SecretResolverRegistry.resolve(defn.secret_ref)
-              else
-                provided[name] || defn.default
-              end
-        raise WorkflowError, "required param '#{name}' missing" if defn.required && val.nil?
-
-        out[name] = val
-      end
-    end
   end
 
   @registry_mutex = Mutex.new

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Patrick
@@ -138,7 +138,6 @@ files:
 - bin/browserd
 - bin/setup
 - examples/cloudflare_hitl.rb
-- examples/session_reuse.rb
 - examples/test_automation_practices/advanced/ab_testing.rb
 - examples/test_automation_practices/advanced/broken_images.rb
 - examples/test_automation_practices/advanced/file_download.rb
@@ -165,6 +164,7 @@ files:
 - examples/the_internet/dynamic_loading.rb
 - examples/the_internet/login.rb
 - lib/browserctl.rb
+- lib/browserctl/callable_definition.rb
 - lib/browserctl/client.rb
 - lib/browserctl/commands/ask.rb
 - lib/browserctl/commands/cli_output.rb
@@ -176,24 +176,24 @@ files:
 - lib/browserctl/commands/flow.rb
 - lib/browserctl/commands/init.rb
 - lib/browserctl/commands/migrate.rb
+- lib/browserctl/commands/output_format.rb
 - lib/browserctl/commands/page.rb
-- lib/browserctl/commands/record.rb
+- lib/browserctl/commands/recording.rb
 - lib/browserctl/commands/resume.rb
 - lib/browserctl/commands/screenshot.rb
-- lib/browserctl/commands/session.rb
 - lib/browserctl/commands/snapshot.rb
 - lib/browserctl/commands/state.rb
 - lib/browserctl/commands/storage.rb
 - lib/browserctl/commands/trace.rb
 - lib/browserctl/commands/workflow.rb
 - lib/browserctl/constants.rb
+- lib/browserctl/contextual_persistence.rb
 - lib/browserctl/crash_report.rb
 - lib/browserctl/detectors.rb
 - lib/browserctl/detectors/auth_required.rb
-- lib/browserctl/driver.rb
-- lib/browserctl/driver/base.rb
 - lib/browserctl/driver/cdp.rb
 - lib/browserctl/driver/cdp_page.rb
+- lib/browserctl/encryption_service.rb
 - lib/browserctl/error/codes.rb
 - lib/browserctl/error/exit_codes.rb
 - lib/browserctl/error/suggested_actions.rb
@@ -211,6 +211,10 @@ files:
 - lib/browserctl/migrations.rb
 - lib/browserctl/policy.rb
 - lib/browserctl/recording.rb
+- lib/browserctl/recording/log_writer.rb
+- lib/browserctl/recording/redactor.rb
+- lib/browserctl/recording/state.rb
+- lib/browserctl/recording/workflow_renderer.rb
 - lib/browserctl/redactor.rb
 - lib/browserctl/replay/context.rb
 - lib/browserctl/replay/fingerprint_matcher.rb
@@ -235,13 +239,11 @@ files:
 - lib/browserctl/server/handlers/navigation.rb
 - lib/browserctl/server/handlers/observation.rb
 - lib/browserctl/server/handlers/page_lifecycle.rb
-- lib/browserctl/server/handlers/session.rb
 - lib/browserctl/server/handlers/state.rb
 - lib/browserctl/server/handlers/storage.rb
 - lib/browserctl/server/idle_watcher.rb
 - lib/browserctl/server/page_session.rb
 - lib/browserctl/server/snapshot_builder.rb
-- lib/browserctl/session.rb
 - lib/browserctl/snapshot/annotator.rb
 - lib/browserctl/snapshot/extractor.rb
 - lib/browserctl/snapshot/fingerprint.rb
@@ -258,6 +260,7 @@ files:
 - lib/browserctl/workflow/flow_wrapper.rb
 - lib/browserctl/workflow/promoter.rb
 - lib/browserctl/workflow/promotion_ledger.rb
+- lib/browserctl/workflow/recovery_manager.rb
 homepage: https://github.com/patrick204nqh/browserctl
 licenses:
 - MIT