hastci 0.1.0

data/lib/hastci/config.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module HastCI
+  class Config
+    DEFAULT_API_BASE_URL = "https://hastci.com/api"
+    DEFAULT_CLAIM_BATCH_SIZE = 10
+    DEFAULT_HEARTBEAT_INTERVAL = 15
+    DEFAULT_SEEDING_TIMEOUT = 300
+    DEFAULT_LOG_LEVEL = "INFO"
+    VALID_LOG_LEVELS = %w[DEBUG INFO WARN ERROR FATAL].freeze
+
+    private_constant :DEFAULT_API_BASE_URL, :DEFAULT_CLAIM_BATCH_SIZE, :DEFAULT_HEARTBEAT_INTERVAL,
+      :DEFAULT_SEEDING_TIMEOUT, :DEFAULT_LOG_LEVEL, :VALID_LOG_LEVELS
+
+    attr_reader :api_key, :api_base_url, :api_max_retries,
+      :run_key, :worker_id, :commit_sha,
+      :claim_batch_size, :heartbeat_interval, :seeding_timeout, :log_level, :debug
+
+    def self.load_from_env(env)
+      if env["GITHUB_ACTIONS"] == "true"
+        from_github_actions(env)
+      else
+        from_generic_ci(env)
+      end
+    rescue KeyError => e
+      raise ConfigurationError, "Missing required env var: #{e.key}"
+    end
+
+    def self.from_github_actions(env)
+      run_id = env.fetch("GITHUB_RUN_ID")
+      run_attempt = env.fetch("GITHUB_RUN_ATTEMPT")
+      commit_sha = env.fetch("GITHUB_SHA")
+      node_index = env.fetch("CI_NODE_INDEX")
+
+      new(
+        api_key: env.fetch("HASTCI_API_KEY"),
+        api_base_url: env.fetch("HASTCI_API_URL", DEFAULT_API_BASE_URL),
+        api_max_retries: env["HASTCI_API_MAX_RETRIES"]&.to_i,
+        run_key: "gha-#{run_id}-#{run_attempt}-#{commit_sha}",
+        worker_id: "gha-worker-#{node_index}",
+        commit_sha: commit_sha,
+        claim_batch_size: env.fetch("HASTCI_CLAIM_BATCH_SIZE", DEFAULT_CLAIM_BATCH_SIZE).to_i,
+        heartbeat_interval: env.fetch("HASTCI_HEARTBEAT_INTERVAL", DEFAULT_HEARTBEAT_INTERVAL).to_i,
+        seeding_timeout: env.fetch("HASTCI_SEEDING_TIMEOUT", DEFAULT_SEEDING_TIMEOUT).to_i,
+        log_level: env.fetch("HASTCI_LOG_LEVEL", DEFAULT_LOG_LEVEL),
+        debug: env["HASTCI_DEBUG"] == "true"
+      )
+    end
+
+    def self.from_generic_ci(env)
+      worker_id = env["HASTCI_WORKER_ID"] ||
+        (env["CI_NODE_INDEX"] && "worker-#{env["CI_NODE_INDEX"]}") ||
+        "worker-#{SecureRandom.hex(4)}"
+
+      new(
+        api_key: env.fetch("HASTCI_API_KEY"),
+        api_base_url: env.fetch("HASTCI_API_URL", DEFAULT_API_BASE_URL),
+        api_max_retries: env["HASTCI_API_MAX_RETRIES"]&.to_i,
+        run_key: env.fetch("HASTCI_RUN_KEY"),
+        worker_id: worker_id,
+        commit_sha: env["HASTCI_COMMIT_SHA"],
+        claim_batch_size: env.fetch("HASTCI_CLAIM_BATCH_SIZE", DEFAULT_CLAIM_BATCH_SIZE).to_i,
+        heartbeat_interval: env.fetch("HASTCI_HEARTBEAT_INTERVAL", DEFAULT_HEARTBEAT_INTERVAL).to_i,
+        seeding_timeout: env.fetch("HASTCI_SEEDING_TIMEOUT", DEFAULT_SEEDING_TIMEOUT).to_i,
+        log_level: env.fetch("HASTCI_LOG_LEVEL", DEFAULT_LOG_LEVEL),
+        debug: env["HASTCI_DEBUG"] == "true"
+      )
+    end
+
+    private_class_method :from_github_actions, :from_generic_ci
+
+    def initialize(
+      api_key:,
+      api_base_url:,
+      api_max_retries:,
+      run_key:,
+      worker_id:,
+      commit_sha:,
+      claim_batch_size:,
+      heartbeat_interval:,
+      seeding_timeout:,
+      log_level:,
+      debug: false
+    )
+      raise ConfigurationError, "worker_id cannot be blank" if worker_id.nil? || worker_id.empty?
+      raise ConfigurationError, "claim_batch_size must be positive" if claim_batch_size <= 0
+      raise ConfigurationError, "heartbeat_interval must be positive" if heartbeat_interval <= 0
+      raise ConfigurationError, "seeding_timeout must be positive" if seeding_timeout <= 0
+
+      @api_key = api_key
+      @api_base_url = api_base_url
+      @api_max_retries = api_max_retries
+      @run_key = run_key
+      @worker_id = worker_id
+      @commit_sha = commit_sha
+      @claim_batch_size = claim_batch_size
+      @heartbeat_interval = heartbeat_interval
+      @seeding_timeout = seeding_timeout
+      @log_level = normalize_log_level(log_level)
+      @debug = debug
+    end
+
+    private
+
+    def normalize_log_level(level)
+      normalized = level.to_s.upcase
+      VALID_LOG_LEVELS.include?(normalized) ? normalized : DEFAULT_LOG_LEVEL
+    end
+  end
+end

data/lib/hastci/configuration_error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HastCI
+  class ConfigurationError < Error; end
+end

data/lib/hastci/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HastCI
+  class Error < StandardError; end
+end

data/lib/hastci/error_collector.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module HastCI
+  class ErrorCollector
+    def initialize
+      @mutex = Mutex.new
+      @errors = []
+    end
+
+    def report(error)
+      @mutex.synchronize { @errors << error unless @errors.any? }
+    end
+
+    def first_error
+      @mutex.synchronize { @errors.first }
+    end
+  end
+end

data/lib/hastci/exit_codes.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module HastCI
+  module ExitCodes
+    SUCCESS = 0
+    TEST_FAILURES = 1
+    CONFIGURATION_ERROR = 2
+    API_ERROR = 3
+    NETWORK_ERROR = 4
+    CANCELLED = 5
+    INTERNAL_ERROR = 6
+  end
+end

data/lib/hastci/fatal_api_error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HastCI
+  class FatalApiError < ApiError; end
+end

data/lib/hastci/heartbeat.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module HastCI
+  class Heartbeat
+    SHUTDOWN_TIMEOUT = 5
+    MAX_CONSECUTIVE_FAILURES = 5
+
+    private_constant :SHUTDOWN_TIMEOUT, :MAX_CONSECUTIVE_FAILURES
+
+    def initialize(api_client:, error_collector: nil, interval: 15)
+      @api_client = api_client
+      @error_collector = error_collector
+      @interval = interval
+      @running = false
+      @thread = nil
+      @mutex = Mutex.new
+      @stop_condition = ConditionVariable.new
+      @consecutive_failures = 0
+    end
+
+    def start
+      @mutex.synchronize do
+        return if @running
+
+        @running = true
+        @thread = Thread.new { run_loop }
+      end
+    end
+
+    def stop
+      @mutex.synchronize do
+        return unless @running
+
+        @running = false
+        @stop_condition.signal
+      end
+
+      @thread.join(SHUTDOWN_TIMEOUT)
+    end
+
+    def running?
+      @mutex.synchronize { @running }
+    end
+
+    private
+
+    def run_loop
+      while running? && !fatal_error
+        send_heartbeat
+        wait_for_next_heartbeat
+      end
+    end
+
+    def wait_for_next_heartbeat
+      @mutex.synchronize do
+        return unless @running
+
+        @stop_condition.wait(@mutex, @interval)
+      end
+    end
+
+    def fatal_error
+      @error_collector&.first_error
+    end
+
+    def send_heartbeat
+      @api_client.heartbeat
+      @consecutive_failures = 0
+    rescue RetryExhaustedError, FatalApiError => e
+      @error_collector&.report(e)
+      HastCI.logger.error("Heartbeat failed: #{e.message}")
+    rescue RetryableError, Errno::ECONNREFUSED, Errno::ETIMEDOUT,
+      Errno::ECONNRESET, Net::OpenTimeout, Net::ReadTimeout => e
+      @consecutive_failures += 1
+      HastCI.logger.warn("Heartbeat failed (#{@consecutive_failures}/#{MAX_CONSECUTIVE_FAILURES}): #{e.class} - #{e.message}")
+
+      if @consecutive_failures >= MAX_CONSECUTIVE_FAILURES
+        error = FatalApiError.new("Heartbeat failed #{MAX_CONSECUTIVE_FAILURES} consecutive times")
+        @error_collector&.report(error)
+        HastCI.logger.error("Heartbeat: max consecutive failures reached")
+      end
+    end
+  end
+end

data/lib/hastci/pact.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module HastCI
+  module Pact
+    PACT_FILENAME = "hastci_rspec-hastci_api.json"
+
+    def self.contract_path
+      File.expand_path("../../spec/pacts/#{PACT_FILENAME}", __dir__)
+    end
+  end
+end

data/lib/hastci/queue_drained.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HastCI
+  class QueueDrained < ApiError; end
+end

data/lib/hastci/retry_exhausted_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module HastCI
+  class RetryExhaustedError < ApiError
+    attr_reader :original_error
+
+    def initialize(message, status_code: nil, response_body: nil, original_error: nil)
+      @original_error = original_error
+      super(message, status_code: status_code, response_body: response_body)
+    end
+  end
+end

data/lib/hastci/retryable_error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HastCI
+  class RetryableError < ApiError; end
+end

data/lib/hastci/session.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module HastCI
+  class Session
+    DEFAULT_POLL_INTERVAL = 0.5
+    DEFAULT_BUFFER_MIN_SIZE = 3
+    DEFAULT_BUFFER_MAX_SIZE = 10
+    DEFAULT_SEEDING_POLL_INTERVAL = 1.0
+
+    STOP_REASONS = %i[user_interrupt server_cancelled].freeze
+
+    private_constant :DEFAULT_POLL_INTERVAL, :DEFAULT_BUFFER_MIN_SIZE, :DEFAULT_BUFFER_MAX_SIZE,
+      :DEFAULT_SEEDING_POLL_INTERVAL
+
+    def self.run(config:, **options)
+      session = new(config: config, **options)
+
+      begin
+        yield session
+      ensure
+        begin
+          cleanup_result = session.cleanup
+        ensure
+          session.shutdown!
+        end
+      end
+
+      cleanup_result
+    end
+
+    def initialize(
+      config:,
+      api_client: nil,
+      ack_worker: nil,
+      task_buffer: nil,
+      poll_interval: DEFAULT_POLL_INTERVAL,
+      buffer_min_size: DEFAULT_BUFFER_MIN_SIZE,
+      buffer_max_size: DEFAULT_BUFFER_MAX_SIZE,
+      sleeper: Kernel.method(:sleep),
+      seeding_poll_interval: DEFAULT_SEEDING_POLL_INTERVAL,
+      error_collector: ErrorCollector.new
+    )
+      @config = config
+      @api_client = api_client || ApiClient.new(config: config)
+      @ack_worker = ack_worker
+      @task_buffer = task_buffer
+      @poll_interval = poll_interval
+      @buffer_min_size = buffer_min_size
+      @buffer_max_size = buffer_max_size
+      @sleeper = sleeper
+      @seeding_poll_interval = seeding_poll_interval
+      @error_collector = error_collector
+
+      @run_id = nil
+      @status = nil
+      @role = nil
+      @heartbeat = nil
+
+      @stop_reason = nil
+      @stop_mutex = Mutex.new
+    end
+
+    attr_reader :run_id, :status, :role, :error_collector, :config
+
+    def first_error
+      @error_collector.first_error
+    end
+
+    def request_stop!(reason)
+      raise ArgumentError, "Invalid stop reason: #{reason}" unless STOP_REASONS.include?(reason)
+
+      should_stop_buffer = false
+      @stop_mutex.synchronize do
+        return if @stop_reason
+
+        @stop_reason = reason
+        should_stop_buffer = user_initiated_stop?(reason)
+      end
+
+      @task_buffer&.stop if should_stop_buffer
+    end
+
+    def stopping?
+      @stop_mutex.synchronize { !@stop_reason.nil? }
+    end
+
+    def stop_reason
+      @stop_mutex.synchronize { @stop_reason }
+    end
+
+    def cancelled?
+      stop_reason == :server_cancelled
+    end
+
+    def start!
+      connect! unless @run_id
+      start_heartbeat!
+
+      unless seeder?
+        wait_for_ready!
+        return if stopping?
+      end
+
+      start_task_buffer!
+    end
+
+    def connect!
+      run_state = @api_client.init_run
+
+      @run_id = run_state.fetch(:run_id)
+      @status = run_state.fetch(:status)
+      @role = run_state.fetch(:role)
+
+      HastCI.logger.info("[HastCI] Connected: run_id=#{@run_id} role=#{@role}")
+
+      @ack_worker ||= AckWorker.new(api_client: @api_client, error_collector: @error_collector)
+      @ack_worker.start
+
+      self
+    end
+
+    def start_task_buffer!
+      return if stopping?
+
+      @task_buffer ||= build_task_buffer
+      @task_buffer.start
+    end
+
+    def wait_for_ready!
+      return unless @status == :seeding
+
+      HastCI.logger.info("[HastCI] Waiting for seeding (timeout: #{@config.seeding_timeout}s)...")
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @config.seeding_timeout
+
+      while @status == :seeding
+        return if stopping?
+
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+          raise FatalApiError, "Timed out waiting for seeding to complete (#{@config.seeding_timeout}s). " \
+            "The seeder may have failed."
+        end
+
+        run_state = @api_client.run_status(run_id: @run_id)
+        @status = run_state.fetch(:status)
+
+        break unless @status == :seeding
+
+        @sleeper.call(@seeding_poll_interval)
+      end
+
+      HastCI.logger.info("[HastCI] Seeding complete, status=#{@status}")
+    end
+
+    def seeder?
+      role == :seeder
+    end
+
+    def seed(tasks:)
+      ensure_connected!
+
+      HastCI.logger.info("[HastCI] Seeding #{tasks.size} tasks...")
+      @api_client.seed(run_id: run_id, tasks: tasks)
+      HastCI.logger.info("[HastCI] Seeding complete")
+    end
+
+    def each_task
+      return enum_for(:each_task) unless block_given?
+
+      ensure_connected!
+
+      loop do
+        return if stopping?
+
+        check_for_fatal_error!
+
+        task = @task_buffer.next_task
+        return if task.nil?
+
+        yield task
+      end
+    end
+
+    def ack(result)
+      ensure_connected!
+
+      @ack_worker.enqueue(result)
+    end
+
+    def flush_acks!(timeout: 10)
+      return true unless @ack_worker
+
+      @ack_worker.flush(timeout: timeout)
+    end
+
+    def disconnect!
+      @task_buffer&.stop
+      @ack_worker&.stop
+      @api_client.disconnect!
+    end
+
+    def start_heartbeat!
+      return if @heartbeat
+
+      @heartbeat = Heartbeat.new(
+        api_client: @api_client,
+        interval: @config.heartbeat_interval,
+        error_collector: @error_collector
+      )
+      @heartbeat.start
+    end
+
+    def cleanup
+      flush_ok = flush_acks!(timeout: 10)
+      HastCI.logger.info("[HastCI] Cleanup: flush_ok=#{flush_ok}")
+
+      {
+        flush_ok: flush_ok,
+        first_error: first_error,
+        stop_reason: stop_reason
+      }
+    end
+
+    def shutdown!
+      @heartbeat&.stop
+      disconnect!
+    end
+
+    private
+
+    def build_task_buffer
+      TaskBuffer.new(
+        min_size: @buffer_min_size,
+        max_size: @buffer_max_size,
+        fetcher: lambda { |limit|
+          batch_size = [limit, @config.claim_batch_size].min
+          @api_client.claim(batch: batch_size)
+        },
+        error_collector: @error_collector,
+        poll_interval: @poll_interval,
+        on_cancelled: -> { request_stop!(:server_cancelled) }
+      )
+    end
+
+    def check_for_fatal_error!
+      error = @error_collector.first_error
+      raise error if error
+    end
+
+    def ensure_connected!
+      return if run_id
+
+      raise HastCI::Error, "Session is not connected. Call #connect! first."
+    end
+
+    def user_initiated_stop?(reason)
+      reason == :user_interrupt
+    end
+  end
+end

data/lib/hastci/task.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module HastCI
+  class Task
+    attr_reader :id, :name
+
+    def initialize(id:, name:)
+      @id = id
+      @name = name
+      freeze
+    end
+
+    def ==(other)
+      other.is_a?(Task) && other.id == id && other.name == name
+    end
+
+    alias_method :eql?, :==
+
+    def hash
+      [id, name].hash
+    end
+  end
+end