zeridion-flare 0.2.0

data/lib/zeridion_flare/worker/job_context.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Zeridion
+  module Flare
+    # Context handed to every job's #perform during execution. Constructed by
+    # the worker runtime — never built by application code.
+    #
+    # Lives at Zeridion::Flare::JobContext (not under ::Worker) to mirror the
+    # top-level JobContext in the reference SDK, so a `ctx` parameter reads the
+    # same across languages.
+    class JobContext
+      # @return [String] unique id of this job execution.
+      attr_reader :job_id
+
+      # @return [String] the routing job_type for this execution.
+      attr_reader :job_type
+
+      # @return [Integer] 1-based attempt counter.
+      attr_reader :attempt
+
+      # @return [Integer] max attempts configured for this job.
+      attr_reader :max_attempts
+
+      # @return [Time, nil] when the job was originally enqueued (offset-aware).
+      #   nil if the server sent an unparseable timestamp — parsing never raises
+      #   into dispatch.
+      attr_reader :enqueued_at
+
+      # @return [Logger] logger pre-bound with this job's fields so handler logs
+      #   auto-correlate.
+      attr_reader :logger
+
+      # @return [Worker::CancellationToken] the cooperative cancellation handle.
+      attr_reader :cancellation
+
+      def initialize(job_id:, job_type:, attempt:, max_attempts:, enqueued_at:, logger:, cancellation:,
+                     progress_slot:)
+        @job_id = job_id
+        @job_type = job_type
+        @attempt = attempt
+        @max_attempts = max_attempts
+        @enqueued_at = enqueued_at
+        @logger = logger
+        @cancellation = cancellation
+        @progress_slot = progress_slot
+      end
+
+      # @return [Boolean] true once cancellation has been requested (server
+      #   "cancel", host shutdown, or timeout). Check this in long handlers.
+      def cancelled?
+        @cancellation.cancelled?
+      end
+
+      # Raise Worker::JobCancelledError if cancellation has been requested.
+      def check_cancellation!
+        @cancellation.check!
+      end
+
+      # Report progress (0.0–1.0) for the dashboard. Clamp-only last-write-wins:
+      # the latest value rides the next heartbeat. nil / NaN / <= 0 are dropped
+      # (no beat carries them); > 1 is clamped to 1.0. Never raises.
+      #
+      # @param fraction [Numeric]
+      # @return [void]
+      def report_progress(fraction)
+        @progress_slot.set(fraction)
+        nil
+      end
+
+      # Parse a server RFC-3339 timestamp defensively. Accepts both `Z` and a
+      # numeric offset. Returns nil (never raises) on a malformed value so a bad
+      # timestamp can't kill dispatch.
+      #
+      # @param raw [String, nil]
+      # @return [Time, nil]
+      def self.parse_timestamp(raw)
+        return nil if raw.nil? || raw.to_s.empty?
+
+        Time.iso8601(raw.to_s)
+      rescue ArgumentError, TypeError
+        begin
+          Time.parse(raw.to_s)
+        rescue ArgumentError, TypeError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/zeridion_flare/worker/job_definition.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Zeridion
+  module Flare
+    module Worker
+      # Resolved, immutable metadata for one registered job class — the Ruby
+      # analog of the reference SDK's JobTypeInfo. Built by the Registry from a
+      # job class's `flare_options`. `recurring?` distinguishes the two #perform
+      # arities (payload vs payloadless).
+      class JobDefinition
+        attr_reader :job_type, :job_class, :queue, :max_attempts, :timeout_seconds,
+                    :cron, :timezone, :payload_struct
+
+        def initialize(job_type:, job_class:, queue:, max_attempts:, timeout_seconds:,
+                       cron: nil, timezone: nil, payload_struct: nil)
+          @job_type = job_type
+          @job_class = job_class
+          @queue = queue
+          @max_attempts = max_attempts
+          @timeout_seconds = timeout_seconds
+          @cron = cron
+          @timezone = timezone
+          @payload_struct = payload_struct
+          freeze
+        end
+
+        def recurring?
+          !@cron.nil?
+        end
+
+        # Build from a class that included Zeridion::Flare::Job.
+        def self.from_payload_class(klass)
+          new(
+            job_type: klass.flare_job_type,
+            job_class: klass,
+            queue: klass.flare_queue,
+            max_attempts: klass.flare_max_attempts,
+            timeout_seconds: klass.flare_timeout,
+            payload_struct: klass.flare_payload_struct,
+          )
+        end
+
+        # Build from a class that included Zeridion::Flare::RecurringJob.
+        def self.from_recurring_class(klass)
+          new(
+            job_type: klass.flare_job_type,
+            job_class: klass,
+            queue: klass.flare_queue,
+            max_attempts: klass.flare_max_attempts,
+            timeout_seconds: klass.flare_timeout,
+            cron: klass.flare_cron,
+            timezone: klass.flare_timezone,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/zeridion_flare/worker/pool.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Zeridion
+  module Flare
+    module Worker
+      # Bounded-concurrency job pool: `concurrency` long-lived worker threads
+      # draining a work queue, gated by a permit SizedQueue so the runtime can
+      # read free slots in O(1) for the poll `capacity`.
+      #
+      # Contract: the caller MUST #acquire a permit BEFORE #submit-ting a job,
+      # and the pool releases that permit when the job's block returns (success
+      # or error). This keeps `free_slots` honest: it never schedules more than
+      # `concurrency` jobs, and `capacity` reflects true free slots.
+      class Pool
+        def initialize(concurrency:)
+          @concurrency = concurrency
+          @work = Thread::Queue.new
+          # Pre-fill the permit queue: `concurrency` available slots.
+          @permits = Thread::SizedQueue.new(concurrency)
+          concurrency.times { @permits.push(:permit) }
+          @threads = []
+          @started = false
+        end
+
+        # Spawn the worker threads. Idempotent.
+        def start
+          return self if @started
+
+          @started = true
+          @concurrency.times do |i|
+            @threads << Thread.new do
+              if Thread.current.respond_to?(:name=)
+                Thread.current.name = "flare-job-#{i}"
+              end
+              loop do
+                task = @work.pop
+                break if task == :__stop__
+
+                begin
+                  task.call
+                ensure
+                  release
+                end
+              end
+            end
+          end
+          self
+        end
+
+        # @return [Integer] current free slots (O(1)).
+        def free_slots
+          @permits.size
+        end
+
+        # Try to reserve a slot without blocking. Returns true if a permit was
+        # taken (the caller must then #submit and the pool will release it), or
+        # false if the pool is saturated.
+        def try_acquire
+          @permits.pop(true)
+          true
+        rescue ThreadError
+          false
+        end
+
+        # Enqueue a job block onto a worker thread. A permit must already be
+        # held (via #try_acquire). The pool releases the permit after the block
+        # runs.
+        def submit(&block)
+          @work.push(block)
+          nil
+        end
+
+        # @return [Integer] number of jobs currently executing.
+        def in_flight
+          @concurrency - free_slots
+        end
+
+        # Drain: stop accepting new work and wait up to `timeout` seconds for
+        # in-flight jobs to finish, then tear down the threads. Returns true if
+        # all threads exited within the timeout, false if some were still
+        # running (the caller decides what to do — we do NOT kill them, since a
+        # Thread#kill mid-Net::HTTP can corrupt the socket).
+        def shutdown(timeout:)
+          deadline = monotonic_now + timeout.to_f
+          # Tell each thread to exit once it has finished its current job and
+          # drained any queued work.
+          @concurrency.times { @work.push(:__stop__) }
+
+          all_joined = true
+          @threads.each do |t|
+            remaining = deadline - monotonic_now
+            remaining = 0 if remaining.negative?
+            all_joined = false if t.join(remaining).nil?
+          end
+          all_joined
+        end
+
+        # Are all worker threads dead? Used by tests to assert clean teardown.
+        def all_threads_dead?
+          @threads.none?(&:alive?)
+        end
+
+        private
+
+        def release
+          @permits.push(:permit)
+        rescue ThreadError
+          # Permit queue closed during shutdown — nothing to release.
+          nil
+        end
+
+        def monotonic_now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+    end
+  end
+end

data/lib/zeridion_flare/worker/progress_slot.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Zeridion
+  module Flare
+    module Worker
+      # Holds the latest progress value for one in-flight job. Clamp-only,
+      # last-write-wins (decision D3): the server enforces monotonicity, so the
+      # client never adds its own "non-decreasing" guard. Values that are nil,
+      # NaN, <= 0, or otherwise out of range are dropped — #get then returns nil
+      # and the heartbeat omits the `progress` key entirely.
+      #
+      # A value > 1 is clamped to 1.0 (the protocol says clamp the high end but
+      # treat <= 0 / NaN as unset). Mutex-guarded so a free-threaded Ruby
+      # (3.13+ `--mjit`/`--yjit` no-GVL builds) sees a consistent value across
+      # the handler thread (which writes) and the heartbeat thread (which reads).
+      class ProgressSlot
+        def initialize
+          @mutex = Mutex.new
+          @value = nil
+        end
+
+        # Record a progress value. nil / NaN / <= 0 → drop (slot unchanged).
+        # > 1 → clamp to 1.0. Otherwise store as-is.
+        def set(value)
+          return if value.nil?
+          return unless value.is_a?(Numeric)
+
+          f = value.to_f
+          return if f.nan?
+          return if f <= 0.0
+
+          f = 1.0 if f > 1.0
+          @mutex.synchronize { @value = f }
+        end
+
+        # @return [Float, nil] the latest clamped progress, or nil if never set.
+        def get
+          @mutex.synchronize { @value }
+        end
+      end
+    end
+  end
+end

data/lib/zeridion_flare/worker/recurring_job.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Zeridion
+  module Flare
+    # Mixin marking a class as a payloadless recurring (cron) job:
+    #
+    #   class NightlyCleanup
+    #     include Zeridion::Flare::RecurringJob
+    #     flare_options cron: "0 3 * * *", queue: "maintenance", timezone: "UTC"
+    #
+    #     def perform(ctx)
+    #       return if ctx.cancelled?
+    #       PurgeExpired.run
+    #     end
+    #   end
+    #
+    # The server runs the schedule and enqueues an execution per tick; the worker
+    # announces the schedule (including `timezone`) at register time and then
+    # dispatches the resulting jobs to `#perform(ctx)` — note the single-arg
+    # signature (no payload).
+    #
+    # `cron` is required (a recurring job with no schedule never fires). job_type
+    # defaults to the class FQN.
+    module RecurringJob
+      def self.included(base)
+        base.extend(ClassMacros)
+        base.include(InstanceShape)
+        Worker::Registry.register_recurring(base)
+      end
+
+      module ClassMacros
+        # @param cron [String] required cron expression (e.g. "0 3 * * *")
+        # @param job_type [String, nil] explicit routing type (default: class FQN)
+        # @param queue [String]
+        # @param timezone [String] IANA tz for the cron (default "UTC")
+        # @param max_attempts [Integer]
+        # @param timeout [Integer] seconds
+        def flare_options(cron: nil, job_type: nil, queue: nil, timezone: nil, max_attempts: nil, timeout: nil)
+          @flare_cron = cron unless cron.nil?
+          @flare_job_type = job_type unless job_type.nil?
+          @flare_queue = queue unless queue.nil?
+          @flare_timezone = timezone unless timezone.nil?
+          @flare_max_attempts = max_attempts unless max_attempts.nil?
+          @flare_timeout = timeout unless timeout.nil?
+          nil
+        end
+
+        def flare_cron
+          @flare_cron
+        end
+
+        def flare_job_type
+          @flare_job_type || name ||
+            raise(ArgumentError, "anonymous recurring job class needs an explicit flare_options(job_type:)")
+        end
+
+        def flare_queue
+          @flare_queue || "default"
+        end
+
+        def flare_timezone
+          @flare_timezone || "UTC"
+        end
+
+        def flare_max_attempts
+          @flare_max_attempts || 3
+        end
+
+        def flare_timeout
+          @flare_timeout || 1800
+        end
+      end
+
+      module InstanceShape
+        def perform(_ctx)
+          raise NotImplementedError, "#{self.class.name} must implement #perform(ctx)"
+        end
+      end
+    end
+  end
+end

data/lib/zeridion_flare/worker/recurring_schedule.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Zeridion
+  module Flare
+    module Worker
+      # One cron schedule announced at register time. This is the single typed
+      # wire DTO in the worker — everything else stays loose string-keyed Hashes.
+      #
+      # The full 6-field shape from the frozen protocol, including `timezone`
+      # (absence ⇒ server-default TZ, which runs non-UTC crons at the wrong
+      # local time). `#to_wire` drops nil fields — Ruby's JSON.generate emits
+      # `null` for nil values, and the server treats a present-but-null field
+      # differently from an omitted one, so compaction is load-bearing.
+      RecurringSchedule = Data.define(
+        :job_type,
+        :cron_expression,
+        :queue,
+        :timezone,
+        :max_attempts,
+        :timeout_seconds,
+      ) do
+        # Build from a JobDefinition. queue/timezone/max_attempts/timeout_seconds
+        # are always populated from the definition's resolved options, so they
+        # are sent; only genuinely-absent optionals would be nil.
+        def self.from_definition(definition)
+          new(
+            job_type: definition.job_type,
+            cron_expression: definition.cron,
+            queue: definition.queue,
+            timezone: definition.timezone,
+            max_attempts: definition.max_attempts,
+            timeout_seconds: definition.timeout_seconds,
+          )
+        end
+
+        # Snake-case Hash with nil fields removed (so JSON.generate never emits
+        # `"queue": null` etc.).
+        def to_wire
+          {
+            "job_type" => job_type,
+            "cron_expression" => cron_expression,
+            "queue" => queue,
+            "timezone" => timezone,
+            "max_attempts" => max_attempts,
+            "timeout_seconds" => timeout_seconds,
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/zeridion_flare/worker/registry.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Zeridion
+  module Flare
+    module Worker
+      # The job registry. Two roles:
+      #
+      #   1. A process-global accumulator (Registry.register_payload /
+      #      register_recurring, called from the Job / RecurringJob `included`
+      #      hooks) that records every job class as it is defined — no
+      #      ObjectSpace scan.
+      #
+      #   2. A per-Worker lookup instance (Registry.new(definitions)) that maps
+      #      job_type → JobDefinition and exposes the distinct queues / job_types
+      #      for poll + register.
+      #
+      # Duplicate job_type at registration raises DuplicateJobTypeError so a
+      # routing collision surfaces at boot, not at dispatch.
+      class Registry
+        # ── Process-global accumulator ──────────────────────────────────────
+
+        @global_classes = []
+        @global_mutex = Mutex.new
+
+        class << self
+          def register_payload(klass)
+            @global_mutex.synchronize { @global_classes << [:payload, klass] }
+          end
+
+          def register_recurring(klass)
+            @global_mutex.synchronize { @global_classes << [:recurring, klass] }
+          end
+
+          # Snapshot every class declared so far, resolved to JobDefinitions,
+          # and de-duplicated by job_type (raising on collision). Returns a
+          # Registry instance the Worker uses for the rest of its life.
+          def from_declared
+            snapshot = @global_mutex.synchronize { @global_classes.dup }
+            definitions = snapshot.map do |(kind, klass)|
+              case kind
+              when :payload   then JobDefinition.from_payload_class(klass)
+              when :recurring then JobDefinition.from_recurring_class(klass)
+              end
+            end
+            new(definitions)
+          end
+
+          # Test seam: forget all globally-declared classes. Not part of the
+          # public API — used only so unit tests don't bleed registrations.
+          def reset_declared!
+            @global_mutex.synchronize { @global_classes = [] }
+          end
+        end
+
+        # ── Per-worker instance ─────────────────────────────────────────────
+
+        def initialize(definitions)
+          @by_type = {}
+          definitions.each do |definition|
+            if @by_type.key?(definition.job_type)
+              raise DuplicateJobTypeError, definition.job_type
+            end
+
+            @by_type[definition.job_type] = definition
+          end
+          @by_type.freeze
+        end
+
+        # @return [JobDefinition, nil]
+        def lookup(job_type)
+          @by_type[job_type]
+        end
+
+        # @return [Array<JobDefinition>]
+        def all
+          @by_type.values
+        end
+
+        def empty?
+          @by_type.empty?
+        end
+
+        # Distinct served queues across every registered job.
+        def queues
+          @by_type.values.map(&:queue).uniq
+        end
+
+        # Every registered job_type (what poll restricts to).
+        def job_types
+          @by_type.values.map(&:job_type)
+        end
+
+        # The recurring schedules to announce at register time.
+        def recurring_schedules
+          @by_type.values.select(&:recurring?).map { |d| RecurringSchedule.from_definition(d) }
+        end
+      end
+    end
+  end
+end