hastci 0.1.0

data/lib/hastci/task_buffer.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module HastCI
+  class TaskBuffer
+    DEFAULT_POLL_INTERVAL = 0.5
+    SHUTDOWN_TIMEOUT = 5
+
+    private_constant :DEFAULT_POLL_INTERVAL, :SHUTDOWN_TIMEOUT
+
+    def initialize(min_size:, max_size:, fetcher:, error_collector:, poll_interval: DEFAULT_POLL_INTERVAL,
+      on_cancelled: nil, sleeper: HastCI::DEFAULT_SLEEPER)
+      @min_size = min_size
+      @max_size = max_size
+      @fetcher = fetcher
+      @error_collector = error_collector
+      @poll_interval = poll_interval
+      @on_cancelled = on_cancelled
+      @sleeper = sleeper
+
+      @queue = SizedQueue.new(max_size)
+      @thread = nil
+      @running = false
+      @mutex = Mutex.new
+      @prefetch_condition = ConditionVariable.new
+      @drained = false
+      @cancelled = false
+    end
+
+    def start
+      @mutex.synchronize do
+        return if @running
+
+        @running = true
+        @drained = false
+        @cancelled = false
+        @thread = Thread.new { prefetch_loop }
+      end
+    end
+
+    def stop
+      @mutex.synchronize do
+        return unless @running
+
+        @running = false
+        @prefetch_condition.signal
+      end
+
+      @thread.join(SHUTDOWN_TIMEOUT)
+      @queue.close
+    end
+
+    def running?
+      @mutex.synchronize { @running }
+    end
+
+    def next_task
+      error = @error_collector.first_error
+      raise error if error
+
+      task = @queue.pop
+
+      if task.nil?
+        error = @error_collector.first_error
+        raise error if error
+
+        return nil
+      end
+
+      signal_prefetch_if_needed
+      task
+    end
+
+    def size
+      @queue.size
+    end
+
+    def drained?
+      @drained && @queue.empty?
+    end
+
+    def cancelled?
+      @mutex.synchronize { @cancelled }
+    end
+
+    private
+
+    def signal_prefetch_if_needed
+      @mutex.synchronize do
+        @prefetch_condition.signal if @queue.size < @min_size
+      end
+    end
+
+    def prefetch_loop
+      loop do
+        should_continue = @mutex.synchronize { @running && !@drained && !@error_collector.first_error }
+        break unless should_continue
+
+        fetch_batch
+      end
+    ensure
+      @queue.close
+    end
+
+    def fetch_batch
+      wait_for_prefetch_signal
+
+      should_fetch = @mutex.synchronize { @running && !@drained }
+      return unless should_fetch
+
+      capacity = available_capacity
+
+      result = safe_fetch(capacity)
+      return unless result
+
+      process_fetch_result(result, requested_capacity: capacity)
+    end
+
+    def wait_for_prefetch_signal
+      @mutex.synchronize do
+        while @running && !@drained && @queue.size >= @min_size
+          @prefetch_condition.wait(@mutex, @poll_interval)
+        end
+      end
+    end
+
+    def safe_fetch(capacity)
+      @fetcher.call(capacity)
+    rescue QueueDrained
+      handle_queue_drained
+    rescue RetryExhaustedError => e
+      handle_fatal_fetch_error(e, "Prefetch failed after retries")
+    rescue FatalApiError => e
+      handle_fatal_fetch_error(e, "Fatal error during prefetch")
+    rescue RetryableError => e
+      handle_transient_fetch_error(e)
+    rescue => e
+      handle_fatal_fetch_error(e, "Unexpected error during prefetch")
+    end
+
+    def process_fetch_result(result, requested_capacity:)
+      return handle_stop_signal if result.cancelled?
+      return handle_empty_response if result.empty?
+      return handle_overflow(result, requested_capacity: requested_capacity) if result.tasks.size > requested_capacity
+
+      push_tasks(result.tasks)
+    end
+
+    def handle_queue_drained
+      @mutex.synchronize { @drained = true }
+      @queue.close
+      nil
+    end
+
+    def handle_fatal_fetch_error(error, message)
+      @error_collector.report(error)
+      @queue.close
+      HastCI.logger.error("#{message}: #{error.message}")
+      nil
+    end
+
+    def handle_transient_fetch_error(error)
+      HastCI.logger.warn("Prefetch failed (will retry): #{error.message}")
+      @sleeper.call(@poll_interval)
+      nil
+    end
+
+    def handle_stop_signal
+      @mutex.synchronize do
+        @cancelled = true
+        @drained = true
+      end
+      @on_cancelled&.call
+      @queue.close
+    end
+
+    def handle_empty_response
+      @sleeper.call(@poll_interval)
+    end
+
+    def handle_overflow(result, requested_capacity:)
+      error = FatalApiError.new(
+        "Server returned #{result.tasks.size} tasks but buffer only has capacity for #{requested_capacity}"
+      )
+      @error_collector.report(error)
+      @queue.close
+      HastCI.logger.error("Task overflow: #{error.message}")
+    end
+
+    def available_capacity
+      @max_size - @queue.size
+    end
+
+    def push_tasks(tasks)
+      tasks.each do |task|
+        break unless running?
+
+        begin
+          @queue.push(task, true)
+        # :nocov:
+        rescue ThreadError, ClosedQueueError
+          break
+        end
+        # :nocov:
+      end
+    end
+  end
+end

data/lib/hastci/task_result.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module HastCI
+  class TaskResult
+    attr_reader :task_id, :status, :duration_s, :logs
+
+    def initialize(task_id:, status:, duration_s:, logs:)
+      @task_id = task_id
+      @status = status
+      @duration_s = duration_s
+      @logs = logs
+      freeze
+    end
+
+    def passed?
+      status == :passed
+    end
+
+    def failed?
+      status == :failed
+    end
+
+    def ==(other)
+      other.is_a?(TaskResult) &&
+        other.task_id == task_id &&
+        other.status == status &&
+        other.duration_s == duration_s &&
+        other.logs == logs
+    end
+
+    alias_method :eql?, :==
+
+    def hash
+      [task_id, status, duration_s, logs].hash
+    end
+  end
+end

data/lib/hastci/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# :nocov:
+module HastCI
+  VERSION = "0.1.0"
+end
+# :nocov:

data/lib/hastci.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "logger"
+require "zeitwerk"
+
+require_relative "hastci/version"
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect("hastci" => "HastCI", "rspec" => "RSpec", "cli" => "CLI")
+loader.setup
+
+module HastCI
+  DEFAULT_SLEEPER = Kernel.method(:sleep)
+
+  def self.logger
+    @logger ||= Logger.new($stderr)
+  end
+
+  def self.logger=(logger)
+    @logger = logger
+  end
+
+  # Run RSpec tests through the HastCI distributed runner.
+  #
+  # @param argv [Array<String>] RSpec command-line arguments
+  # @param env [Hash] Environment variables (default: ENV)
+  # @param err [IO] Error output stream (default: $stderr)
+  # @param out [IO] Output stream (default: $stdout)
+  # @return [Integer] Exit code (0 = success)
+  def self.run_rspec(argv:, env: ENV, err: $stderr, out: $stdout)
+    CLI.run(argv: argv, env: env, err: err, out: out) do |session, argv, err, out|
+      Adapters::RSpec::Runner.new(argv: argv, session: session, err: err, out: out).run
+    end
+  end
+end

data/sig/hastci.rbs

@@ -0,0 +1,4 @@
+module HastCI
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/spec/pacts/hastci_rspec-hastci_api.json

@@ -0,0 +1,385 @@
+{
+  "consumer": {
+    "name": "HastCI RSpec"
+  },
+  "provider": {
+    "name": "HastCI API"
+  },
+  "interactions": [
+    {
+      "description": "a request to initialize a run",
+      "providerState": "a valid API key",
+      "request": {
+        "method": "post",
+        "path": "/runs/init",
+        "headers": {
+          "Authorization": "Bearer test-api-key",
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "run_key": "test-run-key",
+          "worker_id": "worker-0",
+          "commit_sha": "abc123"
+        },
+        "matchingRules": {
+          "$.body.run_key": {
+            "match": "type"
+          },
+          "$.body.worker_id": {
+            "match": "type"
+          },
+          "$.body.commit_sha": {
+            "match": "type"
+          }
+        }
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "run_id": "run-uuid-123",
+          "status": "seeding",
+          "role": "seeder"
+        },
+        "matchingRules": {
+          "$.body.run_id": {
+            "match": "type"
+          },
+          "$.body.status": {
+            "match": "regex",
+            "regex": "^(seeding|ready|draining)$"
+          },
+          "$.body.role": {
+            "match": "regex",
+            "regex": "^(seeder|participant)$"
+          }
+        }
+      }
+    },
+    {
+      "description": "a request to initialize a run with invalid credentials",
+      "providerState": "an invalid API key",
+      "request": {
+        "method": "post",
+        "path": "/runs/init",
+        "headers": {
+          "Authorization": "Bearer invalid-api-key",
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "run_key": "test-run-key",
+          "worker_id": "worker-0",
+          "commit_sha": "abc123"
+        },
+        "matchingRules": {
+          "$.body.run_key": {
+            "match": "type"
+          },
+          "$.body.worker_id": {
+            "match": "type"
+          },
+          "$.body.commit_sha": {
+            "match": "type"
+          }
+        }
+      },
+      "response": {
+        "status": 401,
+        "headers": {
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "error": "Unauthorized"
+        },
+        "matchingRules": {
+          "$.body.error": {
+            "match": "type"
+          }
+        }
+      }
+    },
+    {
+      "description": "a request for run status",
+      "providerState": "a run exists",
+      "request": {
+        "method": "get",
+        "path": "/runs/run-123/status",
+        "headers": {
+          "Authorization": "Bearer test-api-key"
+        }
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "status": "ready"
+        },
+        "matchingRules": {
+          "$.body.status": {
+            "match": "regex",
+            "regex": "^(seeding|ready|draining)$"
+          }
+        }
+      }
+    },
+    {
+      "description": "a request to seed tasks",
+      "providerState": "a run exists",
+      "request": {
+        "method": "post",
+        "path": "/runs/run-123/seed",
+        "headers": {
+          "Authorization": "Bearer test-api-key",
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "tasks": [
+            {
+              "name": "spec/models/user_spec.rb"
+            },
+            {
+              "name": "spec/models/post_spec.rb"
+            }
+          ]
+        }
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "seeded": 2,
+          "status": "ready"
+        }
+      }
+    },
+    {
+      "description": "a request to claim tasks",
+      "providerState": "tasks are available",
+      "request": {
+        "method": "post",
+        "path": "/tasks/claim",
+        "query": "batch=10",
+        "headers": {
+          "Authorization": "Bearer test-api-key",
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "run_key": "test-run-key",
+          "worker_id": "worker-0"
+        }
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "tasks": [
+            {
+              "id": "task-1",
+              "name": "spec/models/user_spec.rb"
+            },
+            {
+              "id": "task-2",
+              "name": "spec/models/post_spec.rb"
+            }
+          ],
+          "queue_state": "ready",
+          "remaining": {
+            "queued": 10,
+            "assigned": 2,
+            "completed": 5
+          }
+        },
+        "matchingRules": {
+          "$.body.tasks[0].id": {
+            "match": "type"
+          },
+          "$.body.tasks[1].id": {
+            "match": "type"
+          },
+          "$.body.remaining.queued": {
+            "match": "type"
+          },
+          "$.body.remaining.assigned": {
+            "match": "type"
+          },
+          "$.body.remaining.completed": {
+            "match": "type"
+          }
+        }
+      }
+    },
+    {
+      "description": "a request to claim tasks from empty queue",
+      "providerState": "queue is empty but not drained",
+      "request": {
+        "method": "post",
+        "path": "/tasks/claim",
+        "query": "batch=10",
+        "headers": {
+          "Authorization": "Bearer test-api-key",
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "run_key": "test-run-key",
+          "worker_id": "worker-0"
+        }
+      },
+      "response": {
+        "status": 204,
+        "headers": {
+        },
+        "body": ""
+      }
+    },
+    {
+      "description": "a request to claim from drained queue",
+      "providerState": "queue is drained",
+      "request": {
+        "method": "post",
+        "path": "/tasks/claim",
+        "query": "batch=10",
+        "headers": {
+          "Authorization": "Bearer test-api-key"
+        },
+        "body": {
+          "run_key": "test-run-key",
+          "worker_id": "worker-0"
+        }
+      },
+      "response": {
+        "status": 410,
+        "headers": {
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "queue_state": "drained"
+        }
+      }
+    },
+    {
+      "description": "a request to ack a task",
+      "providerState": "a task exists",
+      "request": {
+        "method": "post",
+        "path": "/tasks/task-123/ack",
+        "headers": {
+          "Authorization": "Bearer test-api-key",
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "status": "passed",
+          "duration_s": 1.5,
+          "logs": {
+            "summary": "1 example, 0 failures",
+            "failures": [
+        ]
+          }
+        }
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "ok": true
+        }
+      }
+    },
+    {
+      "description": "a heartbeat request",
+      "providerState": "a worker exists",
+      "request": {
+        "method": "post",
+        "path": "/workers/heartbeat",
+        "headers": {
+          "Authorization": "Bearer test-api-key",
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "run_key": "test-run-key",
+          "worker_id": "worker-0"
+        }
+      },
+      "response": {
+        "status": 204,
+        "headers": {
+        },
+        "body": ""
+      }
+    },
+    {
+      "description": "a request for a non-existent resource",
+      "providerState": "resource not found",
+      "request": {
+        "method": "get",
+        "path": "/runs/invalid-run/status",
+        "headers": {
+          "Authorization": "Bearer test-api-key"
+        }
+      },
+      "response": {
+        "status": 404,
+        "headers": {
+        }
+      }
+    },
+    {
+      "description": "a request that causes server error",
+      "providerState": "server error",
+      "request": {
+        "method": "post",
+        "path": "/runs/init",
+        "headers": {
+          "Authorization": "Bearer test-api-key",
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "run_key": "test-run-key",
+          "worker_id": "worker-0",
+          "commit_sha": "abc123"
+        }
+      },
+      "response": {
+        "status": 500,
+        "headers": {
+        }
+      }
+    },
+    {
+      "description": "a request that returns 302",
+      "providerState": "unexpected redirect",
+      "request": {
+        "method": "post",
+        "path": "/runs/init",
+        "headers": {
+          "Authorization": "Bearer test-api-key",
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "run_key": "test-run-key",
+          "worker_id": "worker-0",
+          "commit_sha": "abc123"
+        }
+      },
+      "response": {
+        "status": 302,
+        "headers": {
+        }
+      }
+    }
+  ],
+  "metadata": {
+    "pactSpecification": {
+      "version": "2.0.0"
+    }
+  }
+}