browserctl 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e27f4db200c9e26aaad474df3f55c1a7c91d602724d900d462a969ce4506ba9f
-  data.tar.gz: fba2acf3be3adf3a3a5ca9b42026abfcbfbeea7a8f8d48e51cd455b710fb403c
+  metadata.gz: ff8250901d49ad1038c686f51d303f2139fe673c708746804cdb59e1239890fe
+  data.tar.gz: b47c1e8dbf9093ffe43001d8cacf02c490c887fb5e58336449f1b7aedebfda0b
 SHA512:
-  metadata.gz: 8ac208ae09f276efbf624ed297ef725d5144ec9c13624127f7f949491b0156f7a712ee22dc45cbe218addfe88227e7aa9676feaa105ef1813743b30ac3d5cd29
-  data.tar.gz: e5de1ed64d9d88e69c59a6de15bcfefaeb17b28cb578a8f6cddc2f5c97a8ee6d752c92efb6eff5d533d5923bfdcf6f29464a9f8bf06400953f6f874681c75689
+  metadata.gz: e11c9a8300e7ec744e70ad5f33b645c9afc59e4e5212696045e899f4f2da017d1e4589f750db65b004d8e8208092d6a031724474a2a8feb48f249ed1daa83262
+  data.tar.gz: 1a48cb05e7d92ab6dfd2de777abd0d8904a30b27c8d03fdaee2c00d1b5b734a9f8499be90ea30db686022a5c0d9ad7532ea1c1f148f0e1047a0583a954048dd8

data/CHANGELOG.md

@@ -10,6 +10,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.0](https://github.com/patrick204nqh/browserctl/compare/v0.9.0...v0.10.0) (2026-05-09)
+
+
+### Features
+
+* Browserctl::Flow class + DSL ([#82](https://github.com/patrick204nqh/browserctl/issues/82)) ([93282ed](https://github.com/patrick204nqh/browserctl/commit/93282edfc1358a371377c9ffbedf7cf1f6e7f567))
+
 ## [0.9.0](https://github.com/patrick204nqh/browserctl/compare/v0.8.4...v0.9.0) (2026-05-09)
 
 

data/lib/browserctl/errors.rb

@@ -27,4 +27,10 @@ module Browserctl
 
   class WorkflowError < Error; def self.default_code = "workflow_error" end
   class SecretResolverError < WorkflowError; def self.default_code = "secret_resolver_error" end
+
+  class FlowError < WorkflowError; def self.default_code = "flow_error" end
+  class FlowParamError < FlowError; def self.default_code = "flow_param_error" end
+  class FlowPreconditionError < FlowError; def self.default_code = "flow_precondition_failed" end
+  class FlowStepError < FlowError; def self.default_code = "flow_step_failed" end
+  class FlowPostconditionError < FlowError; def self.default_code = "flow_postcondition_failed" end
 end

data/lib/browserctl/flow.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "timeout"
+require_relative "errors"
+require_relative "secret_resolvers"
+
+module Browserctl
+  FlowParamDef    = Struct.new(:name, :required, :secret, :default, :secret_ref, keyword_init: true)
+  FlowStepDef     = Struct.new(:label, :block, :retry_count, :timeout, keyword_init: true)
+  FlowConditionDef = Struct.new(:kind, :label, :block, keyword_init: true)
+
+  class FlowContext
+    attr_reader :page, :client, :params
+
+    def initialize(page:, params:, client: nil)
+      @page   = page
+      @client = client
+      @params = params
+    end
+
+    def method_missing(name, *args)
+      return @params[name] if args.empty? && @params.key?(name)
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @params.key?(name) || super
+    end
+  end
+
+  class Flow
+    SEMVER_RE = /\A\d+\.\d+\.\d+\z/
+
+    attr_reader :name,
+                :version_string,
+                :description,
+                :param_defs,
+                :steps,
+                :preconditions,
+                :postconditions,
+                :produces_state_block,
+                :min_browserctl_version
+
+    def initialize(name)
+      @name                   = name.to_s
+      @version_string         = "0.0.0"
+      @description            = nil
+      @param_defs             = {}
+      @steps                  = []
+      @preconditions          = []
+      @postconditions         = []
+      @produces_state_block   = nil
+      @min_browserctl_version = nil
+    end
+
+    def version(value)
+      validate_semver!(value, label: "version")
+      @version_string = value.to_s
+    end
+
+    def requires_browserctl(value)
+      validate_semver!(value, label: "requires_browserctl")
+      @min_browserctl_version = value.to_s
+    end
+
+    def desc(text)
+      @description = text.to_s
+    end
+
+    def param(name, required: false, secret: false, default: nil, secret_ref: nil)
+      secret = true if secret_ref
+      @param_defs[name] = FlowParamDef.new(
+        name: name,
+        required: required,
+        secret: secret,
+        default: default,
+        secret_ref: secret_ref
+      )
+    end
+
+    def step(label, retry_count: 0, timeout: nil, &block)
+      raise ArgumentError, "flow step '#{label}' requires a block" unless block
+
+      @steps << FlowStepDef.new(label: label, block: block, retry_count: retry_count, timeout: timeout)
+    end
+
+    def precondition(label = "precondition", &block)
+      raise ArgumentError, "precondition '#{label}' requires a block" unless block
+
+      @preconditions << FlowConditionDef.new(kind: :precondition, label: label, block: block)
+    end
+
+    def postcondition(label = "postcondition", &block)
+      raise ArgumentError, "postcondition '#{label}' requires a block" unless block
+
+      @postconditions << FlowConditionDef.new(kind: :postcondition, label: label, block: block)
+    end
+
+    def produces_state(&block)
+      raise ArgumentError, "produces_state requires a block" unless block
+
+      @produces_state_block = block
+    end
+
+    def run(page: nil, client: nil, **params)
+      ctx = FlowContext.new(page: page, client: client, params: resolve_params(params))
+
+      run_conditions(ctx, @preconditions, error_class: FlowPreconditionError)
+      run_steps(ctx)
+      run_conditions(ctx, @postconditions, error_class: FlowPostconditionError)
+
+      produce_state(ctx)
+    end
+
+    private
+
+    def validate_semver!(value, label:)
+      return if value.to_s.match?(SEMVER_RE)
+
+      raise ArgumentError, "#{label} must be MAJOR.MINOR.PATCH (got #{value.inspect})"
+    end
+
+    def resolve_params(provided)
+      @param_defs.each_with_object({}) do |(name, defn), out|
+        val = if defn.secret_ref
+                SecretResolverRegistry.resolve(defn.secret_ref)
+              elsif provided.key?(name)
+                provided[name]
+              else
+                defn.default
+              end
+
+        raise FlowParamError, "flow '#{@name}' requires param '#{name}'" if defn.required && val.nil?
+
+        out[name] = val
+      end
+    end
+
+    def run_conditions(ctx, conditions, error_class:)
+      conditions.each do |cond|
+        result = ctx.instance_exec(&cond.block)
+        next if result
+
+        raise error_class,
+              "flow '#{@name}' #{cond.kind} '#{cond.label}' returned #{result.inspect}"
+      rescue FlowError
+        raise
+      rescue StandardError => e
+        raise error_class,
+              "flow '#{@name}' #{cond.kind} '#{cond.label}' raised: #{e.message}"
+      end
+    end
+
+    def run_steps(ctx)
+      @steps.each { |defn| run_step(ctx, defn) }
+    end
+
+    def run_step(ctx, defn)
+      last_error = nil
+      (defn.retry_count + 1).times do
+        execute_step_block(ctx, defn)
+        return
+      rescue StandardError => e
+        last_error = e
+      end
+      raise FlowStepError,
+            "flow '#{@name}' step '#{defn.label}' failed: #{last_error.message}"
+    end
+
+    def execute_step_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 FlowStepError,
+            "flow '#{@name}' step '#{defn.label}' timed out after #{defn.timeout}s"
+    end
+
+    def produce_state(ctx)
+      return nil unless @produces_state_block
+
+      ctx.instance_exec(&@produces_state_block)
+    end
+  end
+
+  def self.flow(name, &block)
+    raise ArgumentError, "Browserctl.flow requires a block" unless block
+
+    Flow.new(name).tap { |f| f.instance_exec(&block) }
+  end
+end

data/lib/browserctl/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Patrick
@@ -190,6 +190,7 @@ files:
 - lib/browserctl/driver/cdp.rb
 - lib/browserctl/driver/cdp_page.rb
 - lib/browserctl/errors.rb
+- lib/browserctl/flow.rb
 - lib/browserctl/logger.rb
 - lib/browserctl/policy.rb
 - lib/browserctl/recording.rb