task_progress 0.0.1

data/sig/generated/task_progress/assertions.rbs

@@ -0,0 +1,36 @@
+# Generated from lib/task_progress/assertions.rb with RBS::Inline
+
+class TaskProgress
+  # Assertions for Minitest - and ActiveSupport::TestCase, which is Minitest underneath - about
+  # what work reported. Each failure shows the whole tree, see TaskProgress#outline.
+  #
+  #     class ImportTest < Minitest::Test
+  #       include TaskProgress::Assertions
+  #
+  #       def test_import
+  #         import = TaskProgress.new("Import")
+  #         Importer.new(progress: import).run
+  #         assert_task_complete import
+  #         assert_task_failed import.subtasks.first, with: /row 12/
+  #       end
+  #     end
+  module Assertions
+    def assert: (untyped, ?String) -> void
+
+    # The task is done, and everything under it ended
+    # : (TaskProgress, ?String?) -> void
+    def assert_task_complete: (TaskProgress, ?String?) -> void
+
+    # The task failed - with an error whose message matches `with`, if given
+    # : (TaskProgress, ?with: (String | Regexp)?, ?message: String?) -> void
+    def assert_task_failed: (TaskProgress, ?with: (String | Regexp)?, ?message: String?) -> void
+
+    # The task was canceled
+    # : (TaskProgress, ?String?) -> void
+    def assert_task_canceled: (TaskProgress, ?String?) -> void
+
+    # The tree, as a failure message ends with it
+    # : (TaskProgress) -> String
+    def self.tree: (TaskProgress) -> String
+  end
+end

data/sig/generated/task_progress/batch.rbs

@@ -0,0 +1,33 @@
+# Generated from lib/task_progress/batch.rb with RBS::Inline
+
+class TaskProgress
+  # The unit of commit, see below
+  class Batch < Data
+    attr_reader log(): String?
+
+    attr_reader prev(): Integer
+
+    attr_reader seq(): Integer
+
+    attr_reader at(): Float
+
+    attr_reader events(): Array[Event]
+
+    def self.new: (String? log, Integer prev, Integer seq, Float at, Array[Event] events) -> instance
+                | (log: String?, prev: Integer, seq: Integer, at: Float, events: Array[Event]) -> instance
+
+    def self.members: () -> [ :log, :prev, :seq, :at, :events ]
+
+    def members: () -> [ :log, :prev, :seq, :at, :events ]
+  end
+
+  # The unit of commit: everything one transaction changed, in order. `seq` counts batches,
+  # not events, and `prev` names the batch it follows - so a reader that sees a `prev` other
+  # than the `seq` it last saw knows it missed something. `prev` 0 means "from the start",
+  # which is also how a squashed replay announces itself
+  class Batch
+    # Whether it starts over from nothing, as a squash does
+    # : () -> bool
+    def reset?: () -> bool
+  end
+end

data/sig/generated/task_progress/branch.rbs

@@ -0,0 +1,47 @@
+# Generated from lib/task_progress/branch.rb with RBS::Inline
+
+class TaskProgress
+  # An output for one subtree, which it sees as a tree of its own: the branch's node becomes the
+  # root, `[*branch, "x3k0"]` becomes `["x3k0"]`, and batches that do not touch the branch are left
+  # out. That is a Mount run backwards - a Mount fed from a Branch grafts the subtree back whole.
+  #
+  # Since batches get left out, a branch numbers its own: `log` is the log's id with the branch
+  # path appended, and its `prev`/`seq` follow on from each other just like the log's do.
+  #
+  # Pruning an ancestor takes the branch's node away. Usually for good, since a pruned path is
+  # never given out again - and the branch then sends one last reset with nothing in it, and
+  # falls silent. But a Mount starting over (a remote that restarted, a stream resynced) prunes
+  # its subtree and puts the same tasks back in the same batch: the branch's node comes back,
+  # and the branch starts over with it.
+  #
+  # Its first batch always starts from nothing, `prev` 0: one for a node that comes into being
+  # after the branch was made carries the node's `open`
+  class Branch
+    # The output the branch feeds
+    attr_reader output: output
+
+    # The branch's task, in the whole tree
+    attr_reader path: path
+
+    # The log id its batches carry: the log's, with the path appended
+    attr_reader id: String
+
+    @seq: Integer
+
+    @gone: bool
+
+    @started: bool
+
+    # The log id of the branch at `path`
+    # : (String, path) -> String
+    def self.id: (String, path) -> String
+
+    # For an output, the branch at `path` of the log `log_id`, numbering on from `seq`
+    # : (output, path, String, Integer, ?started: bool) -> void
+    def initialize: (output, path, String, Integer, ?started: bool) -> void
+
+    # Passes on what of the batch is in the branch, moved to its root
+    # : (Batch, Log) -> void
+    def call: (Batch, Log) -> void
+  end
+end

data/sig/generated/task_progress/buffered_output.rbs

@@ -0,0 +1,38 @@
+# Generated from lib/task_progress/buffered_output.rb with RBS::Inline
+
+class TaskProgress
+  # Puts a thread between the log and a slow output. The first batch goes through at once,
+  # and whatever piles up while the output works (or during `interval` after it) goes out
+  # squashed into one - so a database write a few times a second keeps up with any number of
+  # workers, and never holds one of them up
+  class BufferedOutput
+    @output: output
+
+    @interval: Integer | Float
+
+    @queue: Thread::Queue[Batch]
+
+    @log: Log?
+
+    @squasher: Squasher
+
+    @thread: Thread
+
+    # For the slow output, sending to it at most every `interval` seconds
+    # : (output, ?interval: Integer | Float) -> void
+    def initialize: (output, ?interval: Integer | Float) -> void
+
+    # Takes one batch, to deliver from its own thread
+    # : (Batch, Log) -> void
+    def call: (Batch, Log) -> void
+
+    # Delivers what is still queued, then stops
+    # : () -> void
+    def close: () -> void
+
+    private
+
+    # : () -> void
+    def run: () -> void
+  end
+end

data/sig/generated/task_progress/cancellations_app.rbs

@@ -0,0 +1,41 @@
+# Generated from lib/task_progress/cancellations_app.rb with RBS::Inline
+
+class TaskProgress
+  # A Rack app that takes the cancel buttons HTMLRenderer draws, for a tree that lives in another
+  # process - a job broadcasting with TaskProgress.broadcast. It cannot cancel anything itself:
+  # it checks the request's token, and leaves the request in the store the job watches. The job
+  # decides, as it does for any request (see TaskProgress#request_cancel), and the cancel comes
+  # back in its next frame.
+  #
+  # A Turbo form submission is answered with an empty Turbo Stream, which changes nothing on the
+  # page - the frame that follows does. Anything else gets 202 and a little JSON
+  class CancellationsApp
+    # How long a request waits for its run to take it up
+    REQUEST_TTL: Integer
+
+    @store: TurboStreamOutput::_Store
+
+    @tokens: Token
+
+    # Leaves requests in `store`, for tokens `tokens` issued
+    # : (store: TurboStreamOutput::_Store, tokens: Token) -> void
+    def initialize: (store: TurboStreamOutput::_Store, tokens: Token) -> void
+
+    # Takes a POST with `path` - the task's ids joined with a dash - and `token`, as a form or JSON
+    # : (Hash[String, untyped]) -> [Integer, Hash[String, String], Array[String]]
+    def call: (Hash[String, untyped]) -> [ Integer, Hash[String, String], Array[String] ]
+
+    # Where a request to cancel the task at `path` waits, for the tree stored under `key`
+    # : (String, path) -> String
+    def self.request_key: (String, path) -> String
+
+    # The request's parameters, from a form or JSON
+    # : (Hash[String, untyped]) -> Hash[String, untyped]
+    def self.params: (Hash[String, untyped]) -> Hash[String, untyped]
+
+    private
+
+    # : (Integer, Hash[Symbol, untyped]) -> [Integer, Hash[String, String], Array[String]]
+    def respond: (Integer, Hash[Symbol, untyped]) -> [ Integer, Hash[String, String], Array[String] ]
+  end
+end

data/sig/generated/task_progress/event.rbs

@@ -0,0 +1,20 @@
+# Generated from lib/task_progress/event.rb with RBS::Inline
+
+class TaskProgress
+  class Event < Data
+    attr_reader path: path
+    attr_reader op: Symbol
+    attr_reader value: untyped
+    def self.new: (path: path, op: Symbol, ?value: untyped) -> instance
+    def with: (?path: path, ?op: Symbol, ?value: untyped) -> instance
+  end
+
+  class Event
+    # An event for the node at `path` - its path is frozen, so the event can be shared
+    # : (path: path, op: Symbol, ?value: untyped) -> void
+    def initialize: (path: path, op: Symbol, ?value: untyped) -> void
+  end
+
+  # Every op there is - see Event
+  OPS: Array[Symbol]
+end

data/sig/generated/task_progress/execution_log_output.rbs

@@ -0,0 +1,93 @@
+# Generated from lib/task_progress/execution_log_output.rb with RBS::Inline
+
+class TaskProgress
+  # For a CI log, or anything else that is read top to bottom after the fact: one finished
+  # line per thing worth saying, never a redraw, each line led by the overall percent and
+  # the time since the root opened.
+  #
+  #     [ 42%  1m02s] Import › Rows: row 12000
+  #     [ 50%  1m10s] ✓ Import › Rows  8.1s
+  #     [ 50%  1m11s] ✗ Import › Engine: watermarking failed
+  #     [ 50%  1m12s] ⊘ Import › Publish: Ctrl-C
+  #
+  # A task finishing, failing or being canceled, and a line it `puts`, go out at once and every
+  # time - though of a task and the ones under it ending in one batch, only the task says so. The
+  # rest - notes and counts - are only ever the latest news, so it says at most one of those
+  # per `interval`, the newest. With nothing to say for `heartbeat` it says it is still
+  # going, so a CI runner watching for output does not take a long quiet step for a hang
+  class ExecutionLogOutput
+    @ended: Set[path]
+
+    @thread: Thread?
+
+    @closed: bool
+
+    @said_at: Float
+
+    @pending: [ path, String? ]?
+
+    @log: Log?
+
+    @wake: Thread::ConditionVariable
+
+    @lock: Thread::Mutex
+
+    @clock: ^() -> Float
+
+    @heartbeat: Integer | Float
+
+    @interval: Integer | Float
+
+    @io: IO | StringIO
+
+    # Writes to `io`: news at most every `interval` seconds, and that it is still going after `heartbeat` seconds of quiet
+    # : (?IO | StringIO, ?interval: Integer | Float, ?heartbeat: Integer | Float, ?clock: ^() -> Float) -> void
+    def initialize: (?IO | StringIO, ?interval: Integer | Float, ?heartbeat: Integer | Float, ?clock: ^() -> Float) -> void
+
+    # Takes one batch, see Log#add_output
+    # : (Batch, Log) -> void
+    def call: (Batch, Log) -> void
+
+    # Says what is still pending, and stops
+    # : () -> void
+    def close: () -> void
+
+    private
+
+    # : () -> void
+    def run: () -> void
+
+    # : (?flush: bool) -> void
+    def close_locked: (?flush: bool) -> void
+
+    # : () -> void
+    def say_pending: () -> void
+
+    # : (State, String) -> void
+    def say: (State, String) -> void
+
+    ENDINGS: Array[Symbol]
+
+    PUT_ENDINGS: Hash[Symbol, Symbol]
+
+    # A squashed batch - from BufferedOutput, a stream, a mount catching up - says a task ended by
+    # putting it whole, finished. Said once, like the ending it stands for
+    # : (Event) -> Event?
+    def ending_put: (Event) -> Event?
+
+    # : (State, Event) -> String
+    def ending: (State, Event) -> String
+
+    # The task's name, after the names of every task it is under
+    # : (State, path) -> String
+    def names: (State, path) -> String
+
+    # : (Node) -> String
+    def count: (Node) -> String
+
+    # A task that reported nothing before it finished started when it finished, as far as the
+    # tree knows - so it took as long as it was open
+    # : (Node?) -> String
+    def took: (Node?) -> String
+  end
+end

data/sig/generated/task_progress/fold.rbs

@@ -0,0 +1,25 @@
+# Generated from lib/task_progress/fold.rb with RBS::Inline
+
+class TaskProgress
+  # Siblings drawn as one row, see below
+  class Fold < Data
+    attr_reader status(): Symbol
+
+    attr_reader count(): Integer
+
+    def self.new: (Symbol status, Integer count) -> instance
+                | (status: Symbol, count: Integer) -> instance
+
+    def self.members: () -> [ :status, :count ]
+
+    def members: () -> [ :status, :count ]
+  end
+
+  # Siblings drawn as one row - "✓ 9,812 more done", "· 340 more waiting" - so a task with ten
+  # thousand children draws as a handful of rows. See State#rows, which makes them
+  class Fold
+    # What the row says
+    # : () -> String
+    def name: () -> String
+  end
+end

data/sig/generated/task_progress/html_renderer.rbs

@@ -0,0 +1,71 @@
+# Generated from lib/task_progress/html_renderer.rb with RBS::Inline
+
+class TaskProgress
+  # Draws a tree as HTML - the same rows, with the same classes, as the browser client's renderers
+  # draw, so `task_tree.css` styles both and a page can move from one to the other unchanged.
+  # This is what TurboStreamOutput sends, and what TurboSSE streams.
+  #
+  # Elapsed times are `<task-progress-clock>` elements (`task_progress_clock.js`), which tick on
+  # between frames; everything else is as it was when the tree was drawn. A cancelable task gets
+  # a cancel button that is a plain form, posting the task's path and `cancel_token` to
+  # `cancel_url` - so it needs no JavaScript, and Turbo submits it without leaving the page.
+  #
+  # To draw rows your own way, subclass it and override `row`, or hand TurboStreamOutput anything
+  # that answers `id` and `render(snapshot, from = [])` - say, an object that renders a partial
+  class HTMLRenderer
+    # A circle with a cross in it, drawn in the row's text color - the same in every font
+    CANCEL_ICON: String
+
+    GLYPHS: Hash[Symbol, String]
+
+    # The id of the element the tree is drawn in - what a Turbo Stream targets
+    attr_reader id: String
+
+    @clock: ^() -> Float
+
+    @cancel_token: String?
+
+    @cancel_url: String?
+
+    # Draws into an element with the id `id`. Without a `cancel_url`, no task offers a cancel
+    # button. `clock` is for tests to pin down
+    # : (id: String, ?cancel_url: String?, ?cancel_token: String?, ?clock: ^() -> Float) -> void
+    def initialize: (id: String, ?cancel_url: String?, ?cancel_token: String?, ?clock: ^() -> Float) -> void
+
+    # The whole tree in its element - or the subtree at `from`, drawn as a tree of its own
+    # : (State, ?path) -> String
+    def render: (State, ?path) -> String
+
+    # One task's row, `depth` levels in
+    # : (State, path, Node, ?depth: Integer) -> String
+    def row: (State, path, Node, ?depth: Integer) -> String
+
+    # Siblings folded into one row, see State#rows - drawn as a row like any other, so the
+    # columns line up
+    # : (path, Fold, ?depth: Integer) -> String
+    def fold: (path, Fold, ?depth: Integer) -> String
+
+    private
+
+    # : (String?) -> String
+    def h: (String?) -> String
+
+    # : (Node) -> String
+    def message: (Node) -> String
+
+    # The rate over the run so far, and the time left at it
+    # : (Node) -> String?
+    def pace: (Node) -> String?
+
+    # : (path, Node, Integer, bool) -> String
+    def measure: (path, Node, Integer, bool) -> String
+
+    # Ticks on in the browser between frames, from the time the tree was drawn
+    # : (Node) -> String
+    def clock: (Node) -> String
+
+    # The cancel column is there on every row, so the bars line up
+    # : (path, Node) -> String
+    def cancel: (path, Node) -> String
+  end
+end

data/sig/generated/task_progress/journal.rbs

@@ -0,0 +1,25 @@
+# Generated from lib/task_progress/journal.rb with RBS::Inline
+
+class TaskProgress
+  # The changes one transaction made, so that it can be undone whole
+  class Journal
+    @saved: Hash[path, [ Node, Integer ]?]
+
+    # : () -> void
+    def initialize: () -> void
+
+    # Remembers the node as it was before the transaction first touched it - nil for one it opened.
+    # A shallow copy, and how many children it had: a transaction only ever adds children at the
+    # end, or swaps the list for a new one, so that is enough to put the list back - and a parent
+    # of a hundred thousand tasks is not copied whole every time one of them moves
+    # : (path, Node?) -> void
+    def touch: (path, Node?) -> void
+
+    # Every path it touched, opened or removed
+    # : () -> Array[path]
+    def paths: () -> Array[path]
+
+    # : (Hash[path, Node]) -> void
+    def rollback: (Hash[path, Node]) -> void
+  end
+end

data/sig/generated/task_progress/log.rbs

@@ -0,0 +1,140 @@
+# Generated from lib/task_progress/log.rb with RBS::Inline
+
+class TaskProgress
+  # The sequencer. Every change to a tree goes through `transaction`, which applies its events
+  # under the one lock and commits them as a numbered Batch - so the lock is what puts the
+  # changes from many threads into one order, and a batch is what crosses a process, a Ractor
+  # or the wire as one piece.
+  #
+  # Outputs get the batches strictly in order, but outside that lock: a worker never waits on
+  # another's output while it holds the tree. Delivery is synchronous to whoever committed, so
+  # a slow output slows its committer down - wrap it in BufferedOutput when it must not
+  class Log
+    # The id its batches carry - ten lower case characters, unless given
+    attr_reader id: String
+
+    # The seq of the last batch it committed
+    attr_reader seq: Integer
+
+    # The stream key the tree is written to or read from, when it is - see TaskProgress.handoff
+    attr_reader key: String?
+
+    # Lower case only, like the task ids, so neither can clash with another on a filesystem that
+    # ignores case (macOS, Windows) should one ever end up in a file name
+    ID_CHARS: Array[String]
+
+    @clock: ^() -> Float
+
+    @random: Random
+
+    @lock: Thread::Mutex
+
+    @delivery: Thread::Mutex
+
+    @state: State
+
+    @outputs: Array[output]
+
+    @outbox: Array[[ Batch, Array[output] ]]
+
+    @snapshot: State?
+
+    @touched: Set[path]
+
+    @on_cancel: Hash[path, Array[^(String?) -> void]]
+
+    @on_error: ^(Exception, untyped) -> void
+
+    @changed: Thread::ConditionVariable
+
+    @closers: Array[^() -> void]
+
+    # An empty log. `clock` gives the time to stamp batches with, and `random` draws task ids - both for tests to pin down
+    # : (?id: String | Symbol, ?key: String?, ?clock: ^() -> Float, ?random: Random) -> void
+    def initialize: (?id: String | Symbol, ?key: String?, ?clock: ^() -> Float, ?random: Random) -> void
+
+    # Hears about an output that raised, with the error and the output; it warns by default
+    attr_accessor on_error: ^(Exception, untyped) -> void
+
+    # Runs the block under the lock, collecting what it adds with `tx.<<`; it commits as one
+    # batch, or not at all if the block raises. A transaction opened inside another one on the
+    # same fiber joins it. The block holds the lock throughout - keep it short, and never wait
+    # in it on another thread that writes to this log. `at` is the time it happens at - now,
+    # unless it relays what happened elsewhere, earlier
+    # : [T] (?at: Float?) { (Transaction) -> T } -> T
+    def transaction: [T] (?at: Float?) { (Transaction) -> T } -> T
+
+    # Commits the events as one batch
+    # : (*Event) -> void
+    def append: (*Event) -> void
+
+    # An output is anything with `call(batch, log)`. Unless `replay: false`, it first gets the
+    # tree so far as one squashed batch, `prev` 0, and then every batch after it. With a `path`
+    # it gets only that subtree, as a tree of its own - see Branch
+    # : (?output?, ?replay: bool, ?path: path) ?{ (Batch, Log) -> void } -> output
+    def add_output: (?output?, ?replay: bool, ?path: path) ?{ (Batch, Log) -> void } -> output
+
+    # Takes the output as it was given to `add_output`. It hears nothing more once this returns -
+    # save a batch being delivered to it on another thread just then
+    # : (output) -> void
+    def remove_output: (output) -> void
+
+    # Calls the block with the reason once the task at `path` is canceled - at once, if it already
+    # was. A task that ends any other way drops it. The block runs on whichever thread delivers
+    # the cancel, after it has been committed: keep it short, and let it unblock the work (close a
+    # connection, raise into a thread) rather than do the work
+    # : (path) { (String?) -> void } -> void
+    def on_cancel: (path) { (String?) -> void } -> void
+
+    # A frozen copy of the tree, safe to read from anywhere - and from inside an output too,
+    # since outputs run outside the lock
+    # : () -> State
+    def snapshot: () -> State
+
+    # The tree so far as one batch of puts - what a late reader starts from. With a `path`, the
+    # subtree there, rooted at `[]` the way a Branch would send it
+    # : (?path) -> Batch
+    def squashed: (?path) -> Batch
+
+    # Waits up to `timeout` seconds for a batch after `seq` to commit, and returns the seq then
+    # : (Integer, Integer | Float) -> Integer
+    def wait_for_change: (Integer, Integer | Float) -> Integer
+
+    # Runs the block when the log is closed - to stop a thread that feeds it, or flush an output
+    # : () { () -> void } -> void
+    def on_close: () { () -> void } -> void
+
+    # Stops what was started for the tree - following a stream, beating, buffering - for when
+    # nobody needs it any more. The tree itself stays as it is
+    # : () -> void
+    def close: () -> void
+
+    # Its id and seq
+    # : () -> String
+    def inspect: () -> String
+
+    private
+
+    # : () -> Transaction?
+    def current: () -> Transaction?
+
+    # Thread#[] is fiber-local and, unlike Fiber storage, a new thread or fiber does not inherit
+    # it - which is what we want, since only the fiber that took the lock may join
+    # : (Transaction?) -> void
+    def current=: (Transaction?) -> void
+
+    # : (Batch) -> void
+    def call_cancel_callbacks: (Batch) -> void
+
+    # : (Transaction) -> void
+    def commit_locked: (Transaction) -> void
+
+    # One deliverer at a time, taking the outbox in order. A commit made from inside an output
+    # finds its own fiber already delivering, and leaves its batch for the loop it is inside of
+    #
+    # Each batch goes to all its outputs with interrupts held off, so one can never reach some
+    # outputs and not others. An interrupt waits for the batch in hand, not for the whole outbox
+    # : () -> void
+    def deliver: () -> void
+  end
+end

data/sig/generated/task_progress/memory_cache.rbs

@@ -0,0 +1,28 @@
+# Generated from lib/task_progress/memory_cache.rb with RBS::Inline
+
+class TaskProgress
+  # A store kept in this process, for where `Rails.cache` is not to hand - tests, a Rack app that
+  # runs its jobs in-process. Anything with `read`, `write` and `delete` will do as a store; this
+  # is the smallest one, and is safe to share between threads
+  class MemoryCache
+    @entries: Hash[String, untyped]
+
+    @lock: Thread::Mutex
+
+    # An empty store
+    # : () -> void
+    def initialize: () -> void
+
+    # What was written under `key`, or nil
+    # : (String) -> untyped
+    def read: (String) -> untyped
+
+    # Keeps `value` under `key`; options, such as `expires_in:`, are taken and ignored
+    # : (String, untyped, **untyped) -> void
+    def write: (String, untyped, **untyped) -> void
+
+    # Forgets what is under `key`
+    # : (String) -> void
+    def delete: (String) -> void
+  end
+end