hastci 0.1.0

data/lib/hastci/adapters/rspec/runner.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "rspec/core"
+
+module HastCI
+  module Adapters
+    module RSpec
+      class Runner
+        DEFAULT_CLOCK = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        private_constant :DEFAULT_CLOCK
+
+        def initialize(
+          argv:,
+          session:,
+          err:,
+          out:,
+          clock: DEFAULT_CLOCK,
+          configuration: ::RSpec.configuration,
+          world: ::RSpec.world
+        )
+          @session = session
+          @err = err
+          @out = out
+          @clock = clock
+
+          @options = ::RSpec::Core::ConfigurationOptions.new(argv)
+          @configuration = configuration
+          @world = world
+        end
+
+        def run
+          ::RSpec::Core::Runner.disable_autorun!
+          setup
+          return @configuration.reporter.exit_early(exit_code) if @world.wants_to_quit
+
+          run_specs(@world.ordered_example_groups).tap do
+            persist_example_statuses
+          end
+        end
+
+        private
+
+        def setup
+          configure
+          return if @world.wants_to_quit
+
+          @configuration.load_spec_files
+        ensure
+          @world.announce_filters
+        end
+
+        def configure
+          @configuration.error_stream = @err
+          @configuration.output_stream = @out if @configuration.output_stream == $stdout
+          @options.configure(@configuration)
+        end
+
+        def exit_code(examples_passed = false)
+          return @configuration.error_exit_code || @configuration.failure_exit_code if @world.non_example_failure
+          return @configuration.failure_exit_code unless examples_passed
+
+          0
+        end
+
+        def persist_example_statuses
+          return if @configuration.dry_run
+          return unless (path = @configuration.example_status_persistence_file_path)
+
+          ::RSpec::Core::ExampleStatusPersister.persist(@world.all_examples, path)
+        rescue SystemCallError => e
+          ::RSpec.warning "Could not write example statuses to #{path} (configured as " \
+                          "`config.example_status_persistence_file_path`) due to a " \
+                          "system error: #{e.inspect}. Please check that the config " \
+                          "option is set to an accessible, valid file path", call_site: nil
+        end
+
+        def run_specs(example_groups)
+          examples_count = @world.example_count(example_groups)
+          examples_passed = @configuration.reporter.report(examples_count) do |reporter|
+            @configuration.with_suite_hooks do
+              return @configuration.failure_exit_code if examples_count == 0 && @configuration.fail_if_no_examples
+
+              seed_if_needed(example_groups)
+              run_tasks(example_groups, reporter)
+            end
+          end
+
+          exit_code(examples_passed)
+        end
+
+        def seed_if_needed(example_groups)
+          return unless @session.seeder?
+
+          @session.seed(tasks: ordered_task_names(example_groups))
+        end
+
+        def run_tasks(example_groups, reporter)
+          groups_by_file = group_example_groups_by_file(example_groups)
+          all_passed = true
+          tasks_completed = 0
+
+          @session.each_task do |task|
+            break if stop_if_quitting!
+
+            result = run_task(task, groups_by_file, reporter)
+            @session.ack(result)
+            all_passed &&= result.passed?
+            tasks_completed += 1
+
+            HastCI.logger.debug("[HastCI] Task done: #{task.name} (#{result.status}, #{result.duration_s.round(2)}s)")
+
+            break if stop_if_quitting!
+          end
+
+          HastCI.logger.info("[HastCI] Completed #{tasks_completed} tasks")
+          all_passed
+        end
+
+        def run_task(task, groups_by_file, reporter)
+          groups = groups_by_file.fetch(task.name) do
+            available_files = groups_by_file.keys.sort.first(10).join(", ")
+            available_suffix = (groups_by_file.size > 10) ? " (and #{groups_by_file.size - 10} more)" : ""
+            raise HastCI::Error,
+              "Unknown spec file: #{task.name}. " \
+              "Available: #{available_files}#{available_suffix}. " \
+              "This may indicate a mismatch between seeded tasks and loaded specs."
+          end
+
+          before_failed = reporter.failed_examples.length
+          start_time = @clock.call
+
+          group_passed = groups.map { |group| group.run(reporter) }.all?
+
+          duration_s = @clock.call - start_time
+          after_failed = reporter.failed_examples.length
+          new_failures = reporter.failed_examples[before_failed...after_failed]
+
+          status = (group_passed && new_failures.empty?) ? :passed : :failed
+
+          HastCI::TaskResult.new(
+            task_id: task.id,
+            status: status,
+            duration_s: duration_s,
+            logs: build_logs(new_failures)
+          )
+        end
+
+        def build_logs(failed_examples)
+          {
+            summary: summary_for(failed_examples),
+            failures: failed_examples.map { |example| failure_payload(example) }
+          }
+        end
+
+        def summary_for(failed_examples)
+          return "passed" if failed_examples.empty?
+
+          "failed: #{failed_examples.length}"
+        end
+
+        def failure_payload(example)
+          exception = example.exception
+
+          {
+            file: example.metadata[:file_path],
+            line: example.metadata[:line_number],
+            message: exception&.message,
+            backtrace: Array(exception&.backtrace)
+          }
+        end
+
+        def ordered_task_names(example_groups)
+          example_groups.map { |group| normalize_path(group.metadata.fetch(:file_path)) }.uniq
+        end
+
+        def group_example_groups_by_file(example_groups)
+          example_groups.group_by { |group| normalize_path(group.metadata.fetch(:file_path)) }
+        end
+
+        def stop_if_quitting!
+          return false unless @world.wants_to_quit
+
+          @session.request_stop!(:user_interrupt)
+          true
+        end
+
+        def normalize_path(path)
+          path = path.sub(%r{\A\./}, "")
+          pathname = Pathname.new(path)
+          return path unless pathname.absolute?
+
+          begin
+            pathname.relative_path_from(Pathname.pwd).to_s
+          # :nocov:
+          rescue ArgumentError
+            # Different drive on Windows or cannot relativize
+            path
+          end
+          # :nocov:
+        end
+      end
+    end
+  end
+end

data/lib/hastci/api_client.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+
+module HastCI
+  class ApiClient
+    DEFAULT_MAX_RETRIES = 5
+    DEFAULT_INITIAL_BACKOFF = 0.5
+    DEFAULT_MAX_BACKOFF = 30
+    DEFAULT_KEEP_ALIVE_TIMEOUT = 30
+    DEFAULT_OPEN_TIMEOUT = 10
+    DEFAULT_READ_TIMEOUT = 60
+    DEFAULT_WRITE_TIMEOUT = 30
+
+    private_constant :DEFAULT_MAX_RETRIES, :DEFAULT_INITIAL_BACKOFF, :DEFAULT_MAX_BACKOFF,
+      :DEFAULT_KEEP_ALIVE_TIMEOUT, :DEFAULT_OPEN_TIMEOUT, :DEFAULT_READ_TIMEOUT, :DEFAULT_WRITE_TIMEOUT
+
+    # Separate connections allow concurrent operations without blocking.
+    # E.g., heartbeat can continue while the main thread waits on a claim.
+    CONNECTION_DEFAULT = :default
+    CONNECTION_HEARTBEAT = :heartbeat
+    CONNECTION_ACK = :ack
+
+    private_constant :CONNECTION_DEFAULT, :CONNECTION_HEARTBEAT, :CONNECTION_ACK
+
+    def initialize(config:, sleeper: Kernel.method(:sleep), max_retries: nil, random: Random.new)
+      @config = config
+      @max_retries = max_retries || config.api_max_retries || DEFAULT_MAX_RETRIES
+      @sleeper = sleeper
+      @random = random
+
+      @base_url = URI.parse(config.api_base_url)
+      @api_key = config.api_key
+
+      @connections = {}
+      @connection_mutexes = Hash.new { |h, k| h[k] = Mutex.new }
+      @global_mutex = Mutex.new
+    end
+
+    def disconnect!
+      @global_mutex.synchronize do
+        @connections.each_value do |conn|
+          conn&.finish if conn&.started?
+        rescue IOError
+        end
+        @connections.clear
+      end
+    end
+
+    def init_run(
+      run_key: @config.run_key,
+      worker_id: @config.worker_id,
+      commit_sha: @config.commit_sha
+    )
+      response = ensure_hash_response(
+        post_json("/runs/init", {
+          run_key: run_key,
+          worker_id: worker_id,
+          commit_sha: commit_sha
+        }),
+        context: "/runs/init"
+      )
+
+      {
+        run_id: fetch_required(response, "run_id", context: "/runs/init"),
+        status: fetch_required(response, "status", context: "/runs/init").to_sym,
+        role: fetch_required(response, "role", context: "/runs/init").to_sym
+      }
+    end
+
+    def seed(run_id:, tasks:)
+      post_json("/runs/#{run_id}/seed", {
+        tasks: tasks.map { |name| {name: name} }
+      })
+    end
+
+    def run_status(run_id:)
+      response = ensure_hash_response(get_json("/runs/#{run_id}/status"), context: "/runs/status")
+
+      {
+        status: fetch_required(response, "status", context: "/runs/status").to_sym
+      }
+    end
+
+    def claim(
+      run_key: @config.run_key,
+      worker_id: @config.worker_id,
+      batch: @config.claim_batch_size
+    )
+      response = ensure_hash_response(
+        post_json("/tasks/claim?batch=#{batch}", {
+          run_key: run_key,
+          worker_id: worker_id
+        }),
+        context: "/tasks/claim"
+      )
+
+      tasks = Array(response.fetch("tasks", [])).map do |task_data|
+        Task.new(
+          id: fetch_required(task_data, "id", context: "/tasks/claim"),
+          name: fetch_required(task_data, "name", context: "/tasks/claim")
+        )
+      end
+
+      ClaimResult.new(
+        tasks: tasks,
+        queue_state: response["queue_state"]&.to_sym,
+        remaining: response["remaining"],
+        should_stop: response["should_stop"]
+      )
+    end
+
+    def ack(task_id:, status:, duration_s:, logs:)
+      post_json("/tasks/#{task_id}/ack", {
+        status: status.to_s,
+        duration_s: duration_s,
+        logs: logs
+      }, pool: CONNECTION_ACK)
+    end
+
+    def heartbeat(
+      run_key: @config.run_key,
+      worker_id: @config.worker_id
+    )
+      post_json("/workers/heartbeat", {
+        run_key: run_key,
+        worker_id: worker_id
+      }, pool: CONNECTION_HEARTBEAT)
+
+      nil
+    end
+
+    private
+
+    def get_json(path, pool: CONNECTION_DEFAULT)
+      uri = build_uri(path)
+      request = Net::HTTP::Get.new(uri)
+      request["Authorization"] = "Bearer #{@api_key}"
+
+      execute_request(request, pool: pool)
+    end
+
+    def post_json(path, body, pool: CONNECTION_DEFAULT)
+      uri = build_uri(path)
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request["Authorization"] = "Bearer #{@api_key}"
+      request.body = JSON.generate(body)
+
+      execute_request(request, pool: pool)
+    end
+
+    def build_uri(path)
+      base = @base_url.to_s.chomp("/")
+      relative_path = path.delete_prefix("/")
+      URI.parse("#{base}/#{relative_path}")
+    end
+
+    def execute_request(request, pool:)
+      request_id = SecureRandom.hex(4) if @config.debug
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) if @config.debug
+      log_request(request, request_id) if @config.debug
+
+      with_retry(pool) do |attempt|
+        log_retry(request_id, attempt) if @config.debug && attempt > 0
+
+        response = nil
+        mutex = connection_mutex(pool)
+        mutex.synchronize do
+          connection = ensure_connection!(pool)
+          response = connection.request(request)
+        end
+
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time if @config.debug
+        log_response(response, request_id, elapsed) if @config.debug
+        parse_response(response)
+      end
+    end
+
+    def log_request(request, request_id)
+      HastCI.logger.debug("[#{request_id}] #{request.method} #{request.path}")
+      return unless request.body
+
+      body_preview = if request.body.length > 200
+        "#{request.body[0, 200]}... (#{request.body.length} bytes)"
+      else
+        request.body
+      end
+      HastCI.logger.debug("[#{request_id}] Body: #{body_preview}")
+    end
+
+    def log_response(response, request_id, elapsed_s)
+      HastCI.logger.debug("[#{request_id}] Response: #{response.code} (#{(elapsed_s * 1000).round}ms)")
+    end
+
+    def log_retry(request_id, attempt)
+      HastCI.logger.debug("[#{request_id}] Retry attempt #{attempt}")
+    end
+
+    def ensure_connection!(pool)
+      conn = @connections[pool]
+      @connections[pool] = create_connection if conn.nil? || !conn.started?
+      @connections[pool]
+    end
+
+    def connection_mutex(pool)
+      @global_mutex.synchronize do
+        @connection_mutexes[pool]
+      end
+    end
+
+    def create_connection
+      http = Net::HTTP.new(@base_url.host, @base_url.port)
+      http.use_ssl = @base_url.scheme == "https"
+      http.open_timeout = DEFAULT_OPEN_TIMEOUT
+      http.read_timeout = DEFAULT_READ_TIMEOUT
+      http.write_timeout = DEFAULT_WRITE_TIMEOUT
+      http.keep_alive_timeout = DEFAULT_KEEP_ALIVE_TIMEOUT
+      http.start
+      http
+    end
+
+    def parse_response(response)
+      status = response.code.to_i
+
+      return parse_success_response(response) if status.between?(200, 299)
+
+      raise_for_status(response, status)
+    end
+
+    def ensure_hash_response(response, context:)
+      return response if response.is_a?(Hash)
+
+      raise FatalApiError.new("Invalid response for #{context}", response_body: response)
+    end
+
+    def fetch_required(hash, key, context:)
+      hash.fetch(key)
+    rescue KeyError
+      raise FatalApiError.new("Missing key in #{context} response: #{key}", response_body: hash)
+    end
+
+    def parse_success_response(response)
+      body = response.body.to_s
+
+      return {} if body.strip.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      raise FatalApiError.new("Invalid JSON response", response_body: body)
+    end
+
+    def raise_for_status(response, status)
+      body = response.body
+
+      case status
+      when 410
+        raise QueueDrained.new("Queue drained", status_code: status, response_body: body)
+      when 400..499
+        raise FatalApiError.new("API error: #{status}", status_code: status, response_body: body)
+      when 500..599
+        raise RetryableError.new("Server error: #{status}", status_code: status, response_body: body)
+      else
+        raise FatalApiError.new("Unexpected response: #{status}", status_code: status, response_body: body)
+      end
+    end
+
+    def with_retry(pool)
+      attempt = 0
+
+      begin
+        yield(attempt)
+      rescue RetryableError, Errno::ECONNREFUSED, Errno::ETIMEDOUT, Errno::ECONNRESET,
+        Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, IOError => e
+        attempt += 1
+        if attempt > @max_retries
+          raise RetryExhaustedError.new(
+            "Network error after #{@max_retries} retries: #{e.message}",
+            original_error: e
+          )
+        end
+
+        reset_connection(pool)
+        @sleeper.call(backoff_time(attempt))
+        retry
+      end
+    end
+
+    def reset_connection(pool)
+      mutex = connection_mutex(pool)
+      mutex.synchronize do
+        conn = @connections[pool]
+        begin
+          conn&.finish if conn&.started?
+        rescue IOError
+        end
+        @connections[pool] = nil
+      end
+    end
+
+    def backoff_time(retry_count)
+      base = DEFAULT_INITIAL_BACKOFF * (2**(retry_count - 1))
+      jitter = @random.rand * 0.5 * base
+      [base + jitter, DEFAULT_MAX_BACKOFF].min
+    end
+  end
+end

data/lib/hastci/api_error.rb

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

data/lib/hastci/claim_result.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module HastCI
+  class ClaimResult
+    attr_reader :tasks, :queue_state, :remaining, :should_stop
+
+    def initialize(tasks:, queue_state:, remaining: nil, should_stop: nil)
+      @tasks = tasks
+      @queue_state = queue_state
+      @remaining = remaining
+      @should_stop = should_stop
+      freeze
+    end
+
+    def drained?
+      queue_state == :drained
+    end
+
+    def empty?
+      tasks.empty?
+    end
+
+    def cancelled?
+      should_stop == true
+    end
+  end
+end

data/lib/hastci/cli.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module HastCI
+  class CLI
+    def self.run(argv:, env:, err:, out:, &runner_block)
+      config = Config.load_from_env(env)
+      configure_logging(config, err)
+
+      runner_exit_code = ExitCodes::SUCCESS
+      interrupted = false
+
+      cleanup_result = HastCI::Session.run(config: config) do |session|
+        setup_interrupt_handler(session, err) { interrupted = true }
+
+        session.start!
+
+        runner_exit_code = if session.stopping?
+          ExitCodes::SUCCESS
+        else
+          runner_block.call(session, argv, err, out)
+        end
+      end
+
+      print_errors(cleanup_result, err: err)
+
+      final_exit_code(
+        runner_exit_code: runner_exit_code,
+        cleanup_result: cleanup_result,
+        interrupted: interrupted
+      )
+    rescue HastCI::Error => e
+      err.puts(e.message)
+      exit_code_for_error(e)
+    rescue Interrupt
+      err.puts("\nInterrupted - shutting down...")
+      ExitCodes::CANCELLED
+    end
+
+    def self.print_errors(cleanup_result, err:)
+      err.puts("Failed to flush ACKs. Exiting with error.") unless cleanup_result[:flush_ok]
+      err.puts(cleanup_result[:first_error].message) if cleanup_result[:first_error]
+      err.puts("Run was cancelled by the server.") if cleanup_result[:stop_reason] == :server_cancelled
+    end
+    private_class_method :print_errors
+
+    def self.final_exit_code(runner_exit_code:, cleanup_result:, interrupted:)
+      return ExitCodes::CANCELLED if interrupted
+
+      stop_reason = cleanup_result[:stop_reason]
+      first_error = cleanup_result[:first_error]
+      flush_ok = cleanup_result[:flush_ok]
+
+      return ExitCodes::CANCELLED if stop_reason == :server_cancelled
+      return exit_code_for_error(first_error) if first_error
+      return ExitCodes::NETWORK_ERROR unless flush_ok
+      return ExitCodes::TEST_FAILURES if runner_exit_code != ExitCodes::SUCCESS
+
+      ExitCodes::SUCCESS
+    end
+    private_class_method :final_exit_code
+
+    def self.exit_code_for_error(error)
+      case error
+      when ConfigurationError
+        ExitCodes::CONFIGURATION_ERROR
+      when RetryableError, RetryExhaustedError
+        ExitCodes::NETWORK_ERROR
+      when ApiError
+        ExitCodes::API_ERROR
+      else
+        ExitCodes::INTERNAL_ERROR
+      end
+    end
+    private_class_method :exit_code_for_error
+
+    def self.configure_logging(config, err)
+      HastCI.logger = Logger.new(err)
+      HastCI.logger.level = Logger.const_get(config.log_level)
+    end
+    private_class_method :configure_logging
+
+    # :nocov:
+    def self.setup_interrupt_handler(session, err, &on_interrupt)
+      handler = lambda do |signal|
+        if session.stopping?
+          err.puts("\nForce quit!")
+          exit!(1)
+        else
+          on_interrupt&.call
+          session.request_stop!(:user_interrupt)
+          err.puts("\nReceived #{signal} - shutting down after current task...")
+        end
+      end
+
+      trap("INT") { handler.call("SIGINT") }
+      trap("TERM") { handler.call("SIGTERM") }
+    end
+    private_class_method :setup_interrupt_handler
+    # :nocov:
+  end
+end