task_progress 0.0.1

data/lib/task_progress/mount.rb

@@ -0,0 +1,448 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+require "rbconfig"
+
+class TaskProgress
+  # Grafts a tree that lives elsewhere under one node of this one. The remote root lands on the
+  # mount node itself and its `["x3k0"]` on `[*mount, "x3k0"]`, so mounting is prefixing, and
+  # a relay through several processes prefixes once per hop.
+  #
+  # The mount node is sealed: only its Mount writes under it, so a remote can never touch a
+  # node outside its prefix - nor rename or reweigh the mount, which stay the parent's to set.
+  # Each remote batch is re-committed here as one batch, or dropped whole if it does not apply.
+  # A batch that does not follow the last one (a gap) marks the subtree stale, and it stays so
+  # until a batch with `prev` 0 replaces it whole.
+  #
+  # Fed from a stream (see #follow_stream) it goes by the latest writer instead: a batch with
+  # `prev` 0 from a log it has not seen is a new run - a job retried, a worker that took over -
+  # and replaces the subtree whole, even one that had finished, while what the old writer still
+  # sends is ignored
+  class Mount
+    # The log the mount node lives in
+    attr_reader :log #: Log
+    # The mount node
+    attr_reader :path #: path
+
+    # @rbs @control: IO?
+    # @rbs @last_seq: Integer?
+    # @rbs @control_lock: Thread::Mutex
+    # @rbs @pid_lock: Thread::Mutex
+    # @rbs @source: String?
+    # @rbs @stale: bool
+    # @rbs @remote_ended: bool
+    # @rbs @controlled: bool
+    # @rbs @reaped: bool
+    # @rbs @own: bool
+    # @rbs @following: bool
+    # @rbs @forward: (^(String) -> void)?
+    # @rbs @reader: StreamReader?
+    # @rbs @follower: Thread?
+    # @rbs @stopping: bool
+    # @rbs @silent: bool
+    # @rbs @gave_up: bool
+    # @rbs @generation: Integer
+
+    # For the node at `path` - see TaskProgress#mount, which opens one. Unless `own`, the
+    # remote's root names and weighs the mount node too - for a tree that is nothing but a mount,
+    # as TaskProgress.follow makes
+    #: (Log, path, ?own: bool) -> void
+    def initialize(log, path, own: true)
+      @log = log
+      @path = path
+      @own = own
+      @following = false
+      @forward = nil
+      @reader = nil
+      @follower = nil
+      @stopping = false
+      @silent = false
+      @gave_up = false
+      @generation = 0
+      @control = nil
+      @control_lock = Mutex.new
+      @pid_lock = Mutex.new
+      @source = nil
+      @last_seq = nil
+      @stale = false
+      @remote_ended = false
+      @controlled = false
+      @reaped = false
+    end
+
+    # The mount node, as a task of this tree
+    #: () -> TaskProgress
+    def task = TaskProgress.handle(@log, @path)
+
+    # Whether a batch went missing, and the subtree waits for a fresh squash
+    #: () -> bool
+    def stale? = @stale
+
+    # Takes a Batch, its Hash form, or a line of NDJSON. Returns :applied, :gap, :rejected, or
+    # :duplicate for one already applied - redelivery is ordinary after a reconnect or a replay.
+    # Following a stream, a batch from a writer another has since replaced is :superseded
+    #: (Batch | Hash[untyped, untyped] | String) -> Symbol
+    def <<(batch)
+      batch = coerce(batch) or return :rejected
+      starting_over = false
+      # Judged and applied in one transaction: a cancel or another batch arriving at the same
+      # moment comes wholly before this one or wholly after it
+      # It happened when the remote committed it. A pipe or a port is fresh news, so its clock is
+      # moved onto ours by the gap between the two; a stream hands on what may have been written
+      # long ago, by a machine whose clock is taken to agree with ours
+      at = (@following && batch.at.positive?) ? batch.at : nil
+      outcome = @log.transaction(at:) do |tx|
+        node = tx.state[@path] or next :rejected
+        source = @source
+        last_seq = @last_seq
+        new_run = batch.reset? && !source.nil? && batch.log != source
+        # A run given up on as lost that turns out alive is taken back, from a fresh squash
+        starting_over = @following && batch.reset? && (new_run || @gave_up)
+        if node.finished? && !starting_over
+          # Ended here - what the remote sent on its way out changes nothing. A lost run that
+          # speaks again gets read afresh, see above
+          next (@following && @gave_up && batch.log == source) ? :gap : :rejected
+        end
+        if batch.log == source && last_seq && batch.seq <= last_seq && !starting_over
+          # Said again - after a reconnect, a replay, or a resync to a snapshot it has since passed
+          next :duplicate
+        elsif @following && !batch.reset? && batch.log != source
+          next :superseded
+        elsif !batch.reset? && (batch.log != source || batch.prev != last_seq)
+          mark_stale(tx)
+          next :gap
+        end
+        offset = (!@following && batch.at.positive?) ? tx.at - batch.at : 0.0
+        events = translate(batch.events, offset) or next :rejected
+        events.unshift(Event.new(path: @path, op: :prune)) if batch.reset?
+        events.unshift(Event.new(path: @path, op: :put, value: fresh(tx.state))) if new_run || starting_over
+        events.each { tx << it }
+        tx << Event.new(path: @path, op: :meta, value: {stale: false}) if @stale
+        # Known before the batch is delivered, so an output that sees the mount end can tell who ended it
+        @remote_ended = false if starting_over
+        @remote_ended ||= batch.events.any? { it.path.empty? && (ENDINGS.include?(it.op) || (it.op == :put && FINISHED.include?(it.value[:status]))) }
+        @source = batch.log
+        @last_seq = batch.seq
+        @stale = false
+        @silent = false
+        @gave_up = false
+        :applied
+      end
+      # The run before may have ended, and its cancel went with it
+      arm_cancel if outcome == :applied && starting_over
+      outcome
+    rescue ArgumentError
+      :rejected
+    end
+
+    # Reads NDJSON batches off an IO until EOF
+    #: (IO) -> self
+    def read(io)
+      Wire.each_batch(io) { self << it }
+      self
+    end
+
+    # Runs a command with TASK_PROGRESS_FD pointing at a pipe, follows it until it exits, and
+    # returns its Process::Status. A child that exits without finishing its root fails the mount.
+    #
+    # A second pipe, TASK_PROGRESS_CONTROL_FD, carries cancel requests the other way, so tasks in
+    # the child can be canceled from here - see #request_cancel; TaskProgress.cli reads it. When
+    # the mount itself is canceled, the child is asked to cancel its root, and is sent TERM if it
+    # is still running `grace` seconds later. Interrupted (Ctrl-C, a timeout), it terminates the
+    # child at once
+    #: (*untyped command, ?grace: Integer | Float, **untyped options) -> Process::Status?
+    def spawn(*command, grace: 5, **options)
+      reader, writer = IO.pipe
+      control_reader, @control = IO.pipe
+      env = command.first.is_a?(Hash) ? command.shift : {} #: Hash[String, String]
+      status = nil
+      @reaped = false
+      pid = Process.spawn({**env, "TASK_PROGRESS_FD" => "3", "TASK_PROGRESS_CONTROL_FD" => "4"}, *command,
+        3 => writer, 4 => control_reader, **options)
+      writer.close
+      control_reader.close
+      @controlled = true
+      task.on_cancel { stop(pid, grace) unless @remote_ended }
+      read(reader)
+      status = reap(pid)
+      fail!("#{File.basename(command.first.to_s)} exited with #{status.exitstatus || status.termsig}") if status && !status.success?
+      fail!("#{File.basename(command.first.to_s)} exited without finishing") unless finished?
+      status
+    rescue Interrupt => e
+      cancel!(TaskProgress.interrupted_by(e))
+      raise
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      fail!(e)
+      raise
+    ensure
+      @controlled = false
+      @control_lock.synchronize { @control&.close unless @control&.closed? }
+      reader&.close
+      writer&.close unless writer&.closed?
+      if pid && status.nil?
+        signal(pid, :TERM)
+        reap(pid)
+      end
+    end
+
+    # Follows the tree a StreamOutput writes to `stream` at `key` - what TaskProgress.handoff and
+    # TaskProgress.adopt write - on a thread of its own, checking every `poll` seconds. Cancel
+    # requests go back to the writer through the stream, and canceling the mount asks the writer
+    # to cancel its root.
+    #
+    # It also minds whether the writer is alive. Once one has been, a writer that stops beating
+    # marks the subtree stale, and fails the mount if it stays silent for `give_up_after`
+    # seconds - unless a new run comes along later and replaces it, as a retried job does. A
+    # tree nobody has taken up yet is waiting, not silent. Following ends once the mount is done
+    # or canceled, or the log is closed - a failed one is kept an eye on, for a retry
+    #
+    # With `watch: false` it takes what is there once, and leaves catching up again to
+    # #catch_up - for a tree read once, see TaskProgress.fetch
+    #: (untyped, String, ?poll: Integer | Float, ?give_up_after: Integer | Float, ?watch: bool) -> self
+    def follow_stream(stream, key, poll: 1, give_up_after: 60, watch: true)
+      @following = true
+      @controlled = true
+      @reader = StreamReader.new(stream, key)
+      @forward = ->(line) { stream.append(StreamOutput.control_key(key), line) }
+      arm_cancel
+      catch_up
+      # Read once, a tree that is under way with nobody beating for it can only be a lost one
+      mark_stale if !watch && @log.snapshot[@path]&.status == :active && !@reader&.alive?
+      return self unless watch
+      @log.on_close { stop_following }
+      @follower = Thread.new do
+        Thread.current.report_on_exception = false
+        watch(poll, give_up_after)
+      end
+      self
+    end
+
+    # Takes what the stream has for it - waiting up to `timeout` seconds when it has nothing yet -
+    # and returns how many batches it applied. #follow_stream does this over and over
+    #: (?timeout: (Integer | Float)?) -> Integer
+    def catch_up(timeout: nil) # :nodoc:
+      reader = @reader or raise ArgumentError, "Not following a stream - see #follow_stream"
+      reader.read(timeout:).count do |batch|
+        outcome = self << batch
+        reader.resync! if outcome == :gap
+        outcome == :applied
+      end
+    end
+
+    # Stops following, see #follow_stream - closing the log does it
+    #: () -> void
+    def stop_following # :nodoc:
+      @stopping = true
+      @follower&.join unless @follower == Thread.current
+    end
+
+    # Passes a cancel request on to the child, for the task at `path` in its own tree. Returns
+    # :forwarded, or :moot when there is no child to ask any more - it has exited, or this mount
+    # was never spawned. Whether the child cancels anything shows up the stream, if it does
+    #: (path, ?String?) -> (:forwarded | :moot)
+    def request_cancel(path, reason = nil) # :nodoc:
+      # Over a stream, a request names the run it is for, so it cannot reach another one by mistake
+      line = JSON.generate({cancel: path, reason:, run: (@source if @following)}.compact) + "\n"
+      if (forward = @forward)
+        forward.call(line)
+        return :forwarded
+      end
+      @control_lock.synchronize do
+        control = @control
+        return :moot if control.nil? || control.closed?
+        control.write_nonblock(line) # a child too stuck to read its requests is past asking
+      end
+      :forwarded
+    rescue IO::WaitWritable, IOError, SystemCallError
+      :moot
+    end
+
+    private
+
+    # The parent may still end the subtree - when the remote went away, say. From outside, end
+    # the mount's own task: `mount.task.done!`
+    #: () -> self
+    def done!
+      finish(:done) { |tx| tx << Event.new(path: @path, op: :done) }
+    end
+
+    # Fails the mount, and cancels what the remote left open under it
+    #: (?(Exception | String)?, **bool | Integer) -> self
+    def fail!(error = nil, **extra)
+      finish(:cancel) do |tx|
+        tx << Event.new(path: @path, op: :fail, value: Wire.error_to_h(error || "#{tx.state[@path]&.name} failed").merge(extra))
+      end
+    end
+
+    # Cancels the mount, and what the remote left open under it
+    #: (?String?) -> self
+    def cancel!(reason = nil)
+      finish(:cancel) { |tx| tx << Event.new(path: @path, op: :cancel, value: (TaskProgress.utf8(reason.to_s) if reason)) }
+    end
+
+    # Whether the mount node has ended
+    #: () -> bool
+    def finished? = task.finished?
+
+    #: (Integer | Float, Integer | Float) -> void
+    def watch(poll, give_up_after)
+      reader = @reader or return
+      beating = false
+      silent_since = nil #: Float?
+      until @stopping
+        begin
+          catch_up(timeout: poll)
+          status = @log.snapshot[@path]&.status
+          break if status == :done || status == :canceled
+          if reader.alive?
+            beating = true
+            silent_since = nil
+            speaks_again if @silent
+            # Given up on, and alive after all: read it afresh
+            reader.resync! if @gave_up
+          elsif beating && status != :failed
+            since = silent_since ||= Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            @silent = true
+            mark_stale
+            if Process.clock_gettime(Process::CLOCK_MONOTONIC) - since >= give_up_after
+              @gave_up = true
+              fail!("Lost touch with whoever was working on it")
+              beating = false
+            end
+          end
+        rescue => e
+          # The stream is away for a moment, say - keep trying, and say so
+          @log.on_error.call(e, self)
+          sleep(poll)
+        end
+      end
+    end
+
+    # Canceling the mount asks the remote to cancel its root - the run there is now, once
+    #: () -> void
+    def arm_cancel
+      generation = @generation += 1
+      task.on_cancel { |reason| request_cancel([], reason) if generation == @generation && !@remote_ended }
+    end
+
+    # The writer beats again, and nothing went missing meanwhile
+    #: () -> void
+    def speaks_again
+      @silent = false
+      return unless @stale
+      @stale = false
+      @log.append(Event.new(path: @path, op: :meta, value: {stale: false}))
+    end
+
+    # The mount node as a new run finds it: its own name and weight, nothing done yet
+    #: (State) -> Hash[Symbol, untyped]
+    def fresh(state)
+      node = state[@path] or return {name: "", status: :pending}
+      {name: node.name, weight: node.weight, cancelable: (node.cancelable if @own), status: :pending}.compact
+    end
+
+    # Ending the mount ends what the remote left open under it too, as Task#done! and #fail! do
+    #: (Symbol) { (Transaction) -> void } -> self
+    def finish(closing)
+      @log.transaction do |tx|
+        next if tx.state[@path]&.finished?
+        tx.state.open_under(@path).reverse_each { tx << Event.new(path: it, op: closing) }
+        yield tx
+      end
+      self
+    end
+
+    #: (Batch | Hash[untyped, untyped] | String) -> Batch?
+    def coerce(batch)
+      case batch
+      when Batch then batch
+      when Hash then Wire.from_h(batch)
+      when String then Wire.parse(batch)
+      end
+    end
+
+    # In the transaction given, or one of its own
+    #: (?Transaction?) -> void
+    def mark_stale(tx = nil)
+      return if @stale
+      @stale = true
+      event = Event.new(path: @path, op: :meta, value: {stale: true})
+      tx ? tx << event : @log.append(event)
+    end
+
+    # The remote's events, moved under the mount - or nil if one would land too deep
+    #: (Array[Event], Float) -> Array[Event]?
+    def translate(events, offset)
+      events.map do |event|
+        path = [*@path, *event.path]
+        return nil if path.length > Wire::MAX_DEPTH
+        value = (event.op == :put) ? rebased(event.value, offset) : event.value
+        # Without a control pipe nothing carries a cancel back to the remote, so none of its own
+        # tasks can be offered for cancelling from here
+        value = value.except(:cancelable) if !@controlled && %i[open meta put].include?(event.op)
+        next Event.new(path:, op: event.op, value:) unless event.path.empty?
+        next Event.new(path:, op: (event.op == :open) ? :meta : event.op, value:) unless @own
+        case event.op
+        when :open, :meta then Event.new(path:, op: :meta, value: value.except(:name, :weight))
+        when :put then Event.new(path:, op: :put, value: own_put(value))
+        else Event.new(path:, op: event.op, value:)
+        end
+      end
+    end
+
+    # Asks the child to cancel its root, and sends TERM if it has not exited `grace` seconds on
+    #: (Integer, Integer | Float) -> void
+    def stop(pid, grace)
+      request_cancel([], task.message)
+      Thread.new do
+        sleep(grace)
+        signal(pid, :TERM)
+      end
+    end
+
+    # The pid is only ever signaled while it is still ours: reaping and signaling share a lock, so
+    # a signal can never reach another process that was given the pid after ours exited
+    #: (Integer, Symbol) -> void
+    def signal(pid, name)
+      @pid_lock.synchronize { Process.kill(name, pid) unless @reaped }
+    rescue Errno::ESRCH
+      nil
+    end
+
+    #: (Integer) -> Process::Status?
+    def reap(pid)
+      # Never waiting with the lock held, which would keep `stop` from sending TERM to a child
+      # that will not exit by itself - but reaping only with it, so a signal cannot slip in between
+      loop do
+        status = @pid_lock.synchronize do
+          _, exited = Process.wait2(pid, Process::WNOHANG)
+          @reaped = true if exited
+          exited
+        end
+        return status if status
+        sleep(0.02)
+      end
+    rescue Errno::ECHILD
+      @reaped = true
+      nil
+    end
+
+    TIMES = %i[opened_at started_at finished_at].freeze #: Array[Symbol]
+    ENDINGS = %i[done fail cancel].freeze #: Array[Symbol]
+    FINISHED = %i[done failed canceled].freeze #: Array[Symbol]
+    private_constant :TIMES, :ENDINGS, :FINISHED
+
+    #: (Hash[Symbol, untyped], Float) -> Hash[Symbol, untyped]
+    def rebased(value, offset)
+      return value if offset.zero?
+      value.merge(value.slice(*TIMES).compact.transform_values { it + offset })
+    end
+
+    #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+    def own_put(value)
+      node = @log.snapshot[@path] or return value
+      value.merge(name: node.name, weight: node.weight, cancelable: node.cancelable).compact
+    end
+  end
+end

data/lib/task_progress/ndjson_output.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class TaskProgress
+  # One batch per line, for a Mount at the other end of a pipe. Each line goes out in one
+  # write, so a reader never sees a batch half-written unless the writer died writing it -
+  # and Wire.each_batch drops that one
+  class NDJSONOutput
+    # @rbs @io: IO | StringIO
+
+    # Writes to `io`, which it makes sync
+    #: (IO | StringIO) -> void
+    def initialize(io)
+      @io = io
+      @io.sync = true
+    end
+
+    # Writes the batch as one line
+    #: (Batch, Log) -> void
+    def call(batch, _log)
+      @io.write(Wire.dump(batch) + "\n")
+    end
+  end
+end

data/lib/task_progress/node.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class TaskProgress
+  # One task, as the tree holds it, see below
+  Node = Struct.new(
+    :name, #: String
+    :total, #: Integer?
+    :count, #: Integer
+    :percent, #: Integer | Float
+    :weight, #: Float
+    :expect, #: Integer?
+    :indeterminate, #: bool?
+    :unit, #: String?
+    :cancelable, #: bool?
+    :attempt, #: Integer?
+    :message, #: String?
+    :status, #: Symbol
+    :error, #: Hash[Symbol, untyped]?
+    :stale, #: bool?
+    :opened_at, #: Float
+    :started_at, #: Float?
+    :finished_at, #: Float?
+    :children, #: Array[String]
+    :sealed, #: Mount?
+    :autofinish #: bool?
+  )
+
+  # One task, as the tree holds it - what an output or a renderer reads: its name, status, count
+  # and the rest of State::FIELDS. `children` (their ids), `sealed` (the Mount that feeds it) and
+  # `autofinish` are the tree's own bookkeeping, and never go over the wire
+  class Node
+    # Ended by a `done`, `fail` or `cancel` of its own - whatever is still open under it
+    #: () -> bool
+    def finished? = status == :done || status == :failed || status == :canceled
+
+    # As a `put` carries it: State::FIELDS, without what is at its default
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      State::FIELDS.to_h { [it, self[it]] }.compact.tap do |h|
+        h.delete(:stale) unless stale
+        h.delete(:indeterminate) unless indeterminate
+        h.delete(:cancelable) unless cancelable
+        h.delete(:weight) if weight == 1.0 # rubocop:disable Lint/FloatComparison -- the default, set exactly, never computed
+      end
+    end
+
+    # A copy whose list of children can change without changing this one
+    #: () -> Node
+    def deep_dup = dup.tap { it.children = children.dup }
+  end
+end

data/lib/task_progress/poll.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "digest"
+require "json"
+require "uri"
+
+class TaskProgress
+  # The tree over plain GETs, for where Server-Sent Events do not get through - a proxy that
+  # buffers, a host that cuts long responses, a client that is not a browser. Every answer is
+  # the whole tree, squashed into one batch with `prev` 0, and its ETag says which tree that is:
+  # a client that sends it back in `If-None-Match` gets a 304 until something changes.
+  #
+  # Asked with `?wait=N`, it holds the request up to N seconds (`max_wait` at most) for a change
+  # before saying 304 - long polling, which holds a server thread for that long, but answers
+  # the moment there is news. `followPollingAt` in `task_tree.js` does all of this.
+  #
+  #     # Rack
+  #     TaskProgress::Poll.response(task, env)
+  #     # Rails
+  #     status, headers, body = TaskProgress::Poll.response(task, request.env)
+  #     render json: body.first, status:, headers:
+  #
+  # Given a key instead of a task - a tree handed off with TaskProgress.handoff - it reads that
+  # tree from the stream, following it for as long as a long poll waits, and answers 404 for a
+  # key with nothing at it
+  module Poll
+    # What a poll is answered with
+    HEADERS = {"content-type" => "application/json", "cache-control" => "no-cache"}.freeze #: Hash[String, String]
+
+    # A whole Rack response for the task's tree - its subtree, for a subtask - or for the tree
+    # handed off at a key, in `stream`
+    #: (TaskProgress | String, ?Hash[String, untyped], ?stream_store: untyped, ?max_wait: Integer | Float) -> [Integer, Hash[String, String], Array[String]]
+    def self.response(source, env = {}, stream_store: TaskProgress.stream_store, max_wait: 25)
+      waiting = wait(env, max_wait)
+      return answer(source, env, waiting) if source.is_a?(TaskProgress)
+      waiting.positive? ? TaskProgress.follow(source, stream_store:) { answer(it, env, waiting) } : answer(TaskProgress.fetch(source, stream_store:), env, 0.0)
+    rescue KeyError
+      [404, HEADERS, [JSON.generate({error: "Nothing to follow"})]]
+    end
+
+    #: (TaskProgress, Hash[String, untyped], Float) -> [Integer, Hash[String, String], Array[String]]
+    def self.answer(task, env, waiting)
+      seen = seen(env)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + waiting
+      loop do
+        seq = task.log.seq
+        batch = task.log.squashed(task.path)
+        tag = etag(batch)
+        return [200, HEADERS.merge("etag" => tag), [Wire.dump(batch)]] unless seen.include?(tag) || seen.include?("*")
+        left = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        # A task pruned away is as finished as it will ever be - its answer is a tree with nothing in it
+        node = task.log.snapshot[task.path]
+        return [304, HEADERS.merge("etag" => tag), []] if left <= 0 || node.nil? || node.finished?
+        task.log.wait_for_change(seq, left)
+      end
+    end
+    private_class_method :answer
+
+    # Which tree a squash is: the same tree, however many batches it took, gets the same tag. Times
+    # are left out - a tree read from a stream has them moved onto this clock, a little differently
+    # every read, and they never change without something else changing with them
+    #: (Batch) -> String
+    def self.etag(batch)
+      ops = batch.events.map { [it.path, it.op, (it.op == :put) ? it.value.except(*TIMES) : it.value] }
+      %("#{Digest::SHA256.hexdigest(JSON.generate(ops))[0, 24]}")
+    end
+
+    TIMES = %i[opened_at started_at finished_at].freeze #: Array[Symbol]
+    private_constant :TIMES
+
+    # The tags a client already has. A proxy that compresses the answer makes the tag weak, W/"..."
+    #: (Hash[String, untyped]) -> Array[String]
+    def self.seen(env) = env["HTTP_IF_NONE_MATCH"].to_s.split(",").map { it.strip.delete_prefix("W/") }
+    private_class_method :seen
+
+    # The seconds asked for in `?wait=`, up to `max_wait`
+    #: (Hash[String, untyped], Integer | Float) -> Float
+    def self.wait(env, max_wait)
+      asked = URI.decode_www_form(env["QUERY_STRING"].to_s).to_h["wait"]
+      Float(asked.to_s, exception: false).to_f.clamp(0.0, max_wait.to_f)
+    rescue ArgumentError
+      0.0
+    end
+    private_class_method :wait
+  end
+end

data/lib/task_progress/publishing_output.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class TaskProgress
+  # Hands each batch, as its JSON-ready Hash, to anything with `publish(event_name, payload)`
+  # - a Sossego::Stream, for one. A reader turns it back into a Batch with Wire.from_h, or
+  # feeds it to a Mount as it is
+  class PublishingOutput
+    # @rbs!
+    #   interface _Publisher
+    #     def publish: (String event_name, Hash[Symbol, untyped] payload) -> void
+    #   end
+
+    # @rbs @target: _Publisher
+    # @rbs @event_name: String
+
+    # Publishes to `target` - a Sossego stream, or anything with `publish(event_name, payload)`
+    #: (_Publisher, ?event_name: String) -> void
+    def initialize(target, event_name: "task_progress")
+      @target = target
+      @event_name = event_name
+    end
+
+    # Publishes the batch as a JSON-ready Hash
+    #: (Batch, Log) -> void
+    def call(batch, _log)
+      @target.publish(@event_name, Wire.to_h(batch))
+    end
+  end
+end

data/lib/task_progress/ractor_output.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class TaskProgress
+  # Sends each batch to a Ractor::Port, as a deep frozen copy - for a tree built inside a
+  # Ractor and mounted outside it: `mount << port.receive`. Ruby 4.0 and up only
+  class RactorOutput
+    # @rbs @port: untyped - a Ractor::Port, which RBS does not know yet
+
+    # Sends to a `Ractor::Port`. Raises NotImplementedError before Ruby 4.0
+    #: (untyped) -> void
+    def initialize(port)
+      raise NotImplementedError, "TaskProgress supports Ractors from Ruby 4.0 - on #{RUBY_VERSION} they crash the VM" unless RACTORS
+      @port = port
+    end
+
+    # Sends a deep frozen copy of the batch to the port
+    #: (Batch, Log) -> void
+    def call(batch, _log)
+      @port.send(::Ractor.make_shareable(batch, copy: true))
+    end
+  end
+end