specwrk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f2753749c4fdc2460290c8ead228965ba766624fe19b52119e6769f682a7681
+  data.tar.gz: 0b773de7c6366e102fc1299630e9aeb983f8284c75f392fd733dc6a8fc714af8
+SHA512:
+  metadata.gz: 0014b21f279efc09cfd4edf3e5cc5b472ac46096966bc9f487ceeed3f1d1d20dfcf567122a13a594792e98fb33536bd8e51310814a38af96c9f6c3bf628372f0
+  data.tar.gz: 066dfcb0decca0dd8a3cb10b73acbcd6f791ff16ec1a9e2ca8ea4a56d95a5b2d23a56e88ff95dc5780c5fa3b529ea122edfb2b82fcb56c9e6b02a59545fd2a28

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.1

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-05-12
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,5 @@
+Copyright (c) Daniel Westendorf
+
+Specwrk is an Open Source project licensed under the terms of
+the LGPLv3 license.  Please see <http://www.gnu.org/licenses/lgpl-3.0.html>
+for license text.

data/README.md

@@ -0,0 +1,10 @@
+# Specwrk
+TODO!
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/dwestendorf/specwrk.
+
+## License
+
+The gem is available as open source under the terms of the [LGLPv3 License](http://www.gnu.org/licenses/lgpl-3.0.html).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/exe/specwrk

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+require "specwrk"
+require "specwrk/cli"
+
+trap("INT") do
+  if Specwrk.starting_pid == Process.pid && !Specwrk.force_quit
+    warn "Waiting for in-progress work to finish. Interrupt again to force quit (warning: at_exit hooks will be skipped if you force quit)."
+
+    Specwrk.force_quit = true
+  elsif Specwrk.starting_pid != Process.pid
+    exit(1) if Specwrk.force_quit
+    Specwrk.force_quit = true
+  end
+end
+
+Dry::CLI.new(Specwrk::CLI).call

data/lib/specwrk/cli.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+
+require "specwrk"
+require "specwrk/hookable"
+
+module Specwrk
+  module CLI
+    extend Dry::CLI::Registry
+
+    module Clientable
+      extend Hookable
+
+      on_included do |base|
+        base.option :uri, type: :string, default: ENV.fetch("SPECWRK_SRV_URI", "https://localhost:#{ENV.fetch("SPECWRK_SRV_PORT", "5138")}"), desc: "HTTP URI of the server to pull jobs from"
+        base.option :key, type: :string, default: ENV.fetch("SPECWRK_SRV_KEY", ""), aliases: ["-k"], desc: "Authentication key for accessing the server"
+        base.option :run, type: :string, default: ENV.fetch("SPECWRK_SRV_KEY", "main"), aliases: ["-r"], desc: "The run identifier for this job execution"
+        base.option :timeout, type: :integer, default: ENV.fetch("SPECWRK_TIMEOUT", "5"), aliases: ["-t"], desc: "The amount of time to wait for the server to respond"
+      end
+
+      on_setup do |uri:, key:, run:, timeout:, **|
+        ENV["SPECWRK_SRV_URI"] = uri
+        ENV["SPECWRK_SRV_KEY"] = key
+        ENV["SPECWRK_RUN"] = run
+        ENV["SPECWRK_TIMEOUT"] = timeout
+      end
+    end
+
+    module Workable
+      extend Hookable
+
+      on_included do |base|
+        base.option :id, type: :string, default: "specwrk-worker", desc: "The identifier for this worker"
+        base.option :count, type: :integer, default: 1, aliases: ["-c"], desc: "The number of worker processes you want to start"
+        base.option :output, type: :string, default: ENV.fetch("SPECWRK_OUT", ".specwrk/"), aliases: ["-o"], desc: "Directory where worker output is stored"
+      end
+
+      on_setup do |id:, count:, output:, **|
+        ENV["SPECWRK_ID"] = id
+        ENV["SPECWRK_COUNT"] = count.to_s
+        ENV["SPECWRK_OUT"] = Pathname.new(output).expand_path(Dir.pwd).to_s
+      end
+
+      def start_workers
+        @worker_pids = worker_count.times.map do |i|
+          Process.fork do
+            ENV["TEST_ENV_NUMBER"] = ENV["SPECWRK_FORKED"] = (i + 1).to_s
+            ENV["SPECWRK_ID"] = ENV["SPECWRK_ID"] + "-#{i + 1}"
+
+            require "specwrk/worker"
+
+            Specwrk::Worker.run!
+          end
+        end
+      end
+
+      def worker_count
+        @worker_count ||= [1, ENV["SPECWRK_COUNT"].to_i].max
+      end
+    end
+
+    module Servable
+      extend Hookable
+
+      on_included do |base|
+        base.option :port, type: :integer, default: ENV.fetch("SPECWRK_SRV_PORT", "5138"), aliases: ["-p"], desc: "Server port"
+        base.option :key, type: :string, aliases: ["-k"], default: ENV.fetch("SPECWRK_SRV_KEY", ""), desc: "Authentication key clients must use for access"
+        base.option :output, type: :string, default: ENV.fetch("SPECWRK_OUT", ".specwrk/"), aliases: ["-o"], desc: "Directory where worker output is stored"
+        base.option :single_run, type: :boolean, default: !ENV["SPECWRK_SRV_SINGLE_RUN"].nil?, desc: "Act on shutdown requests from clients"
+        base.option :group_by, values: %w[file timings], default: ENV.fetch("SPECWERK_SRV_GROUP_BY", "timings"), desc: "How examples will be grouped for workers; fallback to file if no timings are found"
+      end
+
+      on_setup do |output:, port:, key:, single_run:, group_by:, **|
+        ENV["SPECWRK_SRV_OUTPUT"] = Pathname.new(File.join(output, "report.json")).expand_path(Dir.pwd).to_s if output
+        ENV["SPECWRK_SRV_PORT"] = port
+        ENV["SPECWRK_SRV_KEY"] = key
+        ENV["SPECWRK_SRV_SINGLE_RUN"] = "1" if single_run
+        ENV["SPECWRK_SRV_GROUP_BY"] = group_by
+      end
+    end
+
+    class Version < Dry::CLI::Command
+      desc "Print version"
+
+      def call(*)
+        puts VERSION
+      end
+    end
+
+    class Seed < Dry::CLI::Command
+      include Clientable
+
+      desc "Seed the server with a list of specs for the run"
+
+      argument :dir, required: false, default: "spec", desc: "Relative spec directory to run against"
+
+      def call(dir:, **args)
+        self.class.setup(**args)
+
+        require "specwrk/list_examples"
+        require "specwrk/client"
+
+        examples = ListExamples.new(dir).examples
+
+        Client.wait_for_server!
+        Client.new.seed(examples)
+      rescue Errno::ECONNREFUSED
+        puts "Server at #{ENV.fetch("SPECWRK_SRV_URI", "http://localhost:5138")} is refusing connections, exiting...#{ENV["SPECWRK_FLUSH_DELIMINATOR"]}"
+      rescue Errno::ECONNRESET
+        puts "Server at #{ENV.fetch("SPECWRK_SRV_URI", "http://localhost:5138")} stopped responding to connections, exiting...#{ENV["SPECWRK_FLUSH_DELIMINATOR"]}"
+      end
+    end
+
+    class Work < Dry::CLI::Command
+      include Workable
+      include Clientable
+
+      desc "Start one or more worker processes"
+
+      def call(**args)
+        self.class.setup(**args)
+
+        start_workers
+        Process.waitall
+
+        require "specwrk/cli_reporter"
+        status = Specwrk::CLIReporter.new.report
+
+        exit(status)
+      end
+    end
+
+    class Serve < Dry::CLI::Command
+      include Servable
+
+      desc "Start a server"
+
+      def call(**args)
+        self.class.setup(**args)
+
+        require "specwrk/web"
+        require "specwrk/web/app"
+
+        Specwrk::Web::App.run!
+      end
+    end
+
+    class Start < Dry::CLI::Command
+      include Clientable
+      include Workable
+      include Servable
+
+      desc "Start a server and workers, monitor until complete"
+      argument :dir, required: false, default: "spec", desc: "Relative spec directory to run against"
+
+      def call(dir:, **args)
+        self.class.setup(**args)
+        $stdout.sync = true
+
+        web_pid = Process.fork do
+          require "specwrk/web"
+          require "specwrk/web/app"
+
+          ENV["SPECWRK_FORKED"] = "1"
+          ENV["SPECWRK_SRV_SINGLE_RUN"] = "1"
+          status "Starting queue server..."
+          Specwrk::Web::App.run!
+        end
+
+        seed_pid = Process.fork do
+          require "specwrk/list_examples"
+          require "specwrk/client"
+
+          examples = ListExamples.new(dir).examples
+
+          status "Waiting for server to respond..."
+          Client.wait_for_server!
+          status "Server responding ✓"
+          status "Seeding #{examples.length} examples..."
+          Client.new.seed(examples)
+          status "Samples seeded ✓"
+        end
+
+        wait_for_pids_exit([seed_pid])
+
+        status "Starting #{worker_count} workers..."
+        start_workers
+
+        status "#{worker_count} workers started ✓\n"
+        wait_for_pids_exit(@worker_pids)
+
+        require "specwrk/cli_reporter"
+        status = Specwrk::CLIReporter.new.report
+
+        wait_for_pids_exit([web_pid, seed_pid] + @worker_pids)
+        exit(status)
+      end
+
+      def wait_for_pids_exit(pids)
+        exited_pids = {}
+
+        loop do
+          pids.each do |pid|
+            next if exited_pids.key? pid
+
+            _, status = Process.waitpid2(pid, Process::WNOHANG)
+            exited_pids[pid] = status.exitstatus if status&.exitstatus
+          rescue Errno::ECHILD
+            exited_pids[pid] = 0
+          end
+
+          break if exited_pids.keys.length == pids.length
+          sleep 0.1
+        end
+
+        exited_pids
+      end
+
+      def status(msg)
+        print "\e[2K\r#{msg}"
+        $stdout.flush
+      end
+    end
+
+    register "version", Version, aliases: ["v", "-v", "--version"]
+    register "work", Work, aliases: ["wrk", "twerk", "w"]
+    register "serve", Serve, aliases: ["srv", "s"]
+    register "seed", Seed
+    register "start", Start
+  end
+end

data/lib/specwrk/cli_reporter.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "time"
+
+require "specwrk/client"
+
+require "rspec"
+require "rspec/core/formatters/helpers"
+require "rspec/core/formatters/console_codes"
+
+module Specwrk
+  class CLIReporter
+    def report
+      return 1 unless Client.connect?
+
+      puts "\nFinished in #{total_duration} " \
+                          "(total execution time of #{total_run_time})\n"
+
+      client.shutdown
+
+      if failure_count.positive?
+        puts colorizer.wrap(totals_line, :red)
+        1
+      elsif pending_count.positive?
+        puts colorizer.wrap(totals_line, :yellow)
+        0
+      else
+        puts colorizer.wrap(totals_line, :green)
+        0
+      end
+    rescue Specwrk::UnhandledResponseError
+      puts colorizer.wrap("No examples run.", :red)
+      1
+    end
+
+    private
+
+    def totals_line
+      summary = RSpec::Core::Formatters::Helpers.pluralize(example_count, "example") +
+        ", " + RSpec::Core::Formatters::Helpers.pluralize(failure_count, "failure")
+      summary += ", #{pending_count} pending" if pending_count > 0
+
+      summary
+    end
+
+    def stats
+      @stats ||= client.stats
+    end
+
+    def total_duration
+      Time.parse(stats.dig(:completed, :meta, :last_finished_at)) - Time.parse(stats.dig(:completed, :meta, :first_started_at))
+    end
+
+    def total_run_time
+      stats.dig(:completed, :meta, :total_run_time)
+    end
+
+    def failure_count
+      stats.dig(:completed, :meta, :failures)
+    end
+
+    def pending_count
+      stats.dig(:completed, :meta, :pending)
+    end
+
+    def example_count
+      stats.dig(:completed, :examples).length
+    end
+
+    def client
+      @client ||= Client.new
+    end
+
+    def colorizer
+      ::RSpec::Core::Formatters::ConsoleCodes
+    end
+  end
+end

data/lib/specwrk/client.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "uri"
+require "net/http"
+require "json"
+
+module Specwrk
+  class Client
+    def self.connect?
+      http = build_http
+      http.start
+      http.finish
+
+      true
+    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
+      false
+    end
+
+    def self.build_http
+      uri = URI(ENV.fetch("SPECWRK_SRV_URI", "http://localhost:5138"))
+      Net::HTTP.new(uri.host, uri.port).tap do |http|
+        http.open_timeout = ENV.fetch("SPECWRK_TIMEOUT", "5").to_i
+        http.read_timeout = ENV.fetch("SPECWRK_TIMEOUT", "5").to_i
+        http.keep_alive_timeout = 300
+      end
+    end
+
+    def self.wait_for_server!
+      timeout = Time.now + ENV.fetch("SPECWRK_TIMEOUT", "5").to_i
+      connected = false
+
+      until connected || Time.now > timeout
+        connected = connect?
+        sleep 0.1 unless connected
+      end
+
+      raise Errno::ECONNREFUSED unless connected
+    end
+
+    attr_reader :last_request_at
+
+    def initialize
+      @mutex = Mutex.new
+      @http = self.class.build_http
+      @http.start
+    end
+
+    def close
+      @mutex.synchronize { @http.finish }
+    end
+
+    def heartbeat
+      response = get "/heartbeat"
+
+      response.code == "200"
+    end
+
+    def stats
+      response = get "/stats"
+
+      if response.code == "200"
+        JSON.parse(response.body, symbolize_names: true)
+      else
+        raise UnhandledResponseError.new("#{response.code}: #{response.body}")
+      end
+    end
+
+    def shutdown
+      response = delete "/shutdown"
+
+      if response.code == "200"
+        response.body
+      else
+        raise UnhandledResponseError.new("#{response.code}: #{response.body}")
+      end
+    end
+
+    def fetch_examples
+      response = post "/pop"
+
+      case response.code
+      when "200"
+        JSON.parse(response.body, symbolize_names: true)
+      when "404"
+        raise NoMoreExamplesError
+      when "410"
+        raise CompletedAllExamplesError
+      else
+        raise UnhandledResponseError.new("#{response.code}: #{response.body}")
+      end
+    end
+
+    def complete_examples(examples)
+      response = post "/complete", body: examples.to_json
+
+      (response.code == "200") ? true : UnhandledResponseError.new("#{response.code}: #{response.body}")
+    end
+
+    def seed(examples)
+      response = post "/seed", body: examples.to_json
+
+      (response.code == "200") ? true : UnhandledResponseError.new("#{response.code}: #{response.body}")
+    end
+
+    private
+
+    def get(path, headers: default_headers, body: nil)
+      request = Net::HTTP::Get.new(path, headers)
+      request.body = body if body
+
+      make_request(request)
+    end
+
+    def post(path, headers: default_headers, body: nil)
+      request = Net::HTTP::Post.new(path, headers)
+      request.body = body if body
+
+      make_request(request)
+    end
+
+    def put(path, headers: default_headers, body: nil)
+      request = Net::HTTP::Put.new(path, headers)
+      request.body = body if body
+
+      make_request(request)
+    end
+
+    def delete(path, headers: default_headers, body: nil)
+      request = Net::HTTP::Delete.new(path, headers)
+      request.body = body if body
+
+      make_request(request)
+    end
+
+    def make_request(request)
+      @mutex.synchronize do
+        @last_request_at = Time.now
+        @http.request(request)
+      end
+    end
+
+    def default_headers
+      @default_headers ||= {}.tap do |h|
+        h["Authorization"] = "Bearer #{ENV["SPECWRK_SRV_KEY"]}" if ENV["SPECWRK_SRV_KEY"]
+        h["X-Specwrk-Run"] = ENV["SPECWRK_RUN"] if ENV["SPECWRK_RUN"]
+        h["Content-Type"] = "application/json"
+      end
+    end
+  end
+end

data/lib/specwrk/hookable.rb

@@ -0,0 +1,50 @@
+module Hookable
+  def self.extended(base)
+    base.instance_variable_set(:@included_hooks, [])
+    base.instance_variable_set(:@setup_hooks, []) # unless base.instance_variable_defined?(:@setup_hooks)
+  end
+
+  def on_included(&block)
+    included_hooks << block
+  end
+
+  def on_setup(&block)
+    setup_hooks << block
+  end
+
+  def included(base)
+    super if defined?(super)
+
+    base.extend ClassMethods
+
+    host_hooks = base.instance_variable_defined?(:@setup_hooks) ?
+                      base.instance_variable_get(:@setup_hooks) :
+                      []
+    merged = host_hooks + setup_hooks
+    base.instance_variable_set(:@setup_hooks, merged)
+
+    included_hooks.each { |blk| blk.call(base) }
+  end
+
+  def included_hooks
+    @included_hooks
+  end
+
+  def setup_hooks
+    @setup_hooks
+  end
+
+  module ClassMethods
+    def setup(**args)
+      setup_hooks.each { |blk| blk.call(**args) }
+    end
+
+    def on_setup(&block)
+      setup_hooks << block
+    end
+
+    def setup_hooks
+      @setup_hooks
+    end
+  end
+end

data/lib/specwrk/list_examples.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+require "rspec/core"
+
+module Specwrk
+  class ListExamples
+    def initialize(dir)
+      @dir = dir
+    end
+
+    def examples
+      return @examples if defined?(@examples)
+
+      @examples = []
+
+      RSpec.configuration.files_or_directories_to_run = @dir
+      RSpec::Core::Formatters.register self.class, :stop
+      RSpec.configuration.add_formatter(self)
+
+      unless RSpec::Core::Runner.new(options).run($stderr, out).zero?
+        out.tap(&:rewind).each_line { |line| $stdout.print line }
+      end
+
+      @examples
+    end
+
+    # Called as the formatter
+    def stop(group_notification)
+      group_notification.notifications.map do |notification|
+        @examples << {
+          id: notification.example.id,
+          file_path: notification.example.metadata[:file_path]
+        }
+      end
+    end
+
+    private
+
+    def out
+      @out ||= Tempfile.new.tap do |f|
+        f.define_singleton_method(:tty?) { true }
+      end
+    end
+
+    def options
+      RSpec::Core::ConfigurationOptions.new(
+        ["--dry-run", *RSpec.configuration.files_to_run]
+      )
+    end
+  end
+end