task_progress 0.0.1

data/sig/generated/task_progress/trees_app.rbs

@@ -0,0 +1,40 @@
+# Generated from lib/task_progress/trees_app.rb with RBS::Inline
+
+class TaskProgress
+  # A Rack app that serves handed-off trees to pages, by a Token rather than by the tree's key -
+  # what TaskProgress.for_page hands out links to. The Railtie mounts it at `/task_progress/trees`.
+  #
+  #     GET  /:token/events          Server-Sent Events, see SSE
+  #     GET  /:token/poll            the tree, polled or long-polled, see Poll
+  #     POST /:token/cancellations   path=x3k0-00af (a form, or JSON)
+  #       202  {"path": ..., "state": "requested"}   asked of whoever works on it
+  #       200  {"path": ..., "state": "moot"}        nothing left to cancel - no such task, or it ended
+  #       409  the task is not cancelable
+  #     403  a token that is forged, mangled or expired
+  #     404  a tree that is gone, or anything else
+  #
+  # Issuing the token is the authorization: it happens in an action of yours, which has decided
+  # the page may see that tree. The key itself never leaves the server
+  class TreesApp
+    @tokens: Token
+
+    @stream_store: untyped
+
+    # Checks tokens with `tokens`, and reads trees from `stream_store` - TaskProgress.stream_store
+    # unless given
+    # : (tokens: Token, ?stream_store: untyped) -> void
+    def initialize: (tokens: Token, ?stream_store: untyped) -> void
+
+    # Serves one request
+    # : (Hash[String, untyped]) -> [Integer, Hash[String, String], untyped]
+    def call: (Hash[String, untyped]) -> [ Integer, Hash[String, String], untyped ]
+
+    private
+
+    # : (String, Hash[String, untyped], untyped) -> [Integer, Hash[String, String], Array[String]]
+    def cancel: (String, Hash[String, untyped], untyped) -> [ Integer, Hash[String, String], Array[String] ]
+
+    # : (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/turbo_helper.rbs

@@ -0,0 +1,14 @@
+# Generated from lib/task_progress/turbo_helper.rb with RBS::Inline
+
+class TaskProgress
+  # View helpers, in every view once the gem is in a Rails app
+  module TurboHelper
+    # The tree a job broadcasts with `TaskProgress.broadcast(record, ...)`, kept up to date: drawn
+    # as it stood at its last frame, and subscribed to every frame after that. Needs turbo-rails,
+    # and `task_tree.css` on the page - plus `task_progress_clock.js`, for elapsed times to tick
+    #
+    #     <%= task_progress_tree @csv_import %>
+    # : (untyped, ?store: untyped) -> String
+    def task_progress_tree: (untyped, ?store: untyped) -> String
+  end
+end

data/sig/generated/task_progress/turbo_sse.rbs

@@ -0,0 +1,69 @@
+# Generated from lib/task_progress/turbo_sse.rb with RBS::Inline
+
+class TaskProgress
+  # A Rack body streaming a tree as Turbo Streams over Server-Sent Events, for a page that shows
+  # it with `<turbo-stream-source src="...">` - Turbo with no Action Cable, and no JavaScript of
+  # your own. Every frame replaces the whole tree by morphing, at most every `interval` seconds
+  # however fast the tree changes; a reconnect starts with the whole tree, so nothing is ever
+  # missed for good. Given a subtask, it streams that branch alone.
+  #
+  #   TaskProgress::TurboSSE.response(task, renderer:, source: "progress-source")
+  #
+  # Once the task finishes it sends the last frame, removes the element with the id `source` -
+  # the `<turbo-stream-source>`, so the browser does not reconnect to a finished stream - and ends.
+  # Without a `source` the browser reconnects every `reconnect` seconds, and gets the last frame
+  # each time. Given a key, it follows the tree handed off there, as SSE does
+  class TurboSSE
+    # What a Turbo SSE response is sent with - the same as an SSE one
+    HEADERS: Hash[String, String]
+
+    @close: bool
+
+    @reconnect: Integer | Float
+
+    @source: String?
+
+    @heartbeat: Integer | Float
+
+    @interval: Integer | Float
+
+    @renderer: TurboStreamOutput::_Renderer
+
+    @task: TaskProgress
+
+    # A whole Rack response: status, headers and this body - or a 404, for a key with nothing at it
+    # : (TaskProgress | String, **untyped) -> [Integer, Hash[String, String], TurboSSE | Array[String]]
+    def self.response: (TaskProgress | String, **untyped) -> [ Integer, Hash[String, String], TurboSSE | Array[String] ]
+
+    # Streams `task`, drawn by `renderer` - an HTMLRenderer, or anything that answers `id` and
+    # `render(snapshot, from)`, `from` being the task's path. `source` is the id of the
+    # `<turbo-stream-source>` to remove at the end
+    # : (TaskProgress | String, renderer: TurboStreamOutput::_Renderer, ?stream_store: untyped, ?interval: Integer | Float, ?heartbeat: Integer | Float, ?reconnect: Integer | Float, ?source: String?) -> void
+    def initialize: (TaskProgress | String, renderer: TurboStreamOutput::_Renderer, ?stream_store: untyped, ?interval: Integer | Float, ?heartbeat: Integer | Float, ?reconnect: Integer | Float, ?source: String?) -> void
+
+    # Yields the stream a chunk at a time, until the task finishes - as a Rack body does
+    # : () { (String) -> void } -> void
+    def each: () { (String) -> void } -> void
+
+    # Stops following a tree it followed by its key - Rack calls it when the response is over
+    # : () -> void
+    def close: () -> void
+
+    private
+
+    # Finished, or pruned away - which is as finished as it will ever be
+    # : () -> bool
+    def ended?: () -> bool
+
+    # : () -> String
+    def frame: () -> String
+
+    # : (State) -> String
+    def render: (State) -> String
+
+    # An unnamed event - what `<turbo-stream-source>` listens for. A line of SSE ends at a CR as
+    # much as at a LF, and task names and messages - curl's and ffmpeg's, say - are full of CRs
+    # : (String) -> String
+    def message: (String) -> String
+  end
+end

data/sig/generated/task_progress/turbo_stream_output.rbs

@@ -0,0 +1,51 @@
+# Generated from lib/task_progress/turbo_stream_output.rb with RBS::Inline
+
+class TaskProgress
+  # Draws the whole tree as HTML on every batch, as a Turbo Stream that replaces it in the page by
+  # morphing, and hands that to `to` - in Rails, Turbo::StreamsChannel, which reaches every
+  # page subscribed with `turbo_stream_from`, whichever process the tree lives in. Put it behind a
+  # BufferedOutput, as TaskProgress.broadcast does, and a spammy job is drawn a few times a second.
+  #
+  # The whole tree, every time: a Turbo Stream has no seq and no gaps to notice, so a page that
+  # missed a frame - or joined late - is set right by the next one. Morphing touches only what
+  # differs, so a bar's width eases rather than jumps.
+  #
+  # With a `store`, the latest frame is also written under `key`, for a page to draw the tree
+  # before the first broadcast reaches it - see TurboHelper#task_progress_tree
+  class TurboStreamOutput
+    interface _Renderer
+      def render: (State snapshot, ?path from) -> String
+
+      def id: () -> String
+    end
+
+    interface _Store
+      def read: (String key) -> untyped
+
+      def write: (String key, untyped value, **untyped) -> void
+
+      def delete: (String key) -> void
+    end
+
+    # The store key the latest frame is written under
+    attr_reader key: String
+
+    @renderer: _Renderer
+
+    @to: ^(String) -> void
+
+    @store: _Store?
+
+    # Draws with `renderer`, and hands each frame - a `<turbo-stream>` element - to `to`
+    # : (renderer: _Renderer, to: ^(String) -> void, ?store: _Store?, ?key: String) -> void
+    def initialize: (renderer: _Renderer, to: ^(String) -> void, ?store: _Store?, ?key: String) -> void
+
+    # Draws the tree as it stands - the batch only says it changed
+    # : (Batch, Log) -> void
+    def call: (Batch, Log) -> void
+
+    # A Turbo Stream that replaces the element `target` with `html`, morphing it
+    # : (String, String) -> String
+    def self.frame: (String, String) -> String
+  end
+end

data/sig/generated/task_progress/version.rbs

@@ -0,0 +1,6 @@
+# Generated from lib/task_progress/version.rb with RBS::Inline
+
+class TaskProgress
+  # The gem's version
+  VERSION: String
+end

data/sig/generated/task_progress/wire.rbs

@@ -0,0 +1,102 @@
+# Generated from lib/task_progress/wire.rb with RBS::Inline
+
+class TaskProgress
+  # A batch as JSON, one object per line:
+  #
+  #     {"v":1,"log":"k7p2qd9z4m","prev":11,"seq":12,"at":1730000000.123,"ops":[[["x3k0","00af"],"set",40],[["x3k0"],"note","Reading"]]}
+  #
+  # The reading side is meant for a writer we do not trust - a subprocess parsing hostile input,
+  # a stream relayed from elsewhere - so nothing it sends is taken at its word: a batch with
+  # anything wrong in it is dropped whole, numbers are clamped, strings scrubbed and cut, paths
+  # bounded, and nothing in an error is ever turned into a class
+  module Wire
+    # The version of the format every batch carries as `v`. A reader takes only its own: a batch
+    # from a newer writer is dropped, as a garbled one would be, rather than half understood
+    VERSION: Integer
+
+    # The longest line a reader takes - see the MANUAL for what every limit is for
+    LINE_LIMIT: Integer
+
+    # Where a string is cut
+    TEXT_LIMIT: Integer
+
+    # How much of a backtrace is kept
+    BACKTRACE_LINES: Integer
+
+    # How many causes of an error are kept
+    CAUSES: Integer
+
+    # How deep a path may go
+    MAX_DEPTH: Integer
+
+    # What a task id may be: lower case letters and digits, 16 at most
+    SEGMENT: Regexp
+
+    # The most events one batch may carry
+    MAX_OPS: Integer
+
+    # The largest count or total - what a JavaScript number holds exactly
+    MAX_COUNT: Integer
+
+    # What a `put` may say a task's status is
+    STATUSES: Array[String]
+
+    # The batch as a JSON-ready Hash
+    # : (Batch) -> Hash[Symbol, untyped]
+    def self.to_h: (Batch) -> Hash[Symbol, untyped]
+
+    # The batch as one line of JSON, without the newline
+    # : (Batch) -> String
+    def self.dump: (Batch) -> String
+
+    # A Batch, or nil when the line is anything but a valid one
+    # : (String) -> Batch?
+    def self.parse: (String) -> Batch?
+
+    # A Batch from its Hash form - string or symbol keys - or nil if anything in it is wrong
+    # : (untyped) -> Batch?
+    def self.from_h: (untyped) -> Batch?
+
+    # Reads batches until EOF. An overlong line is skipped, as is a garbled one, and a line
+    # cut off by a writer that died is never yielded
+    # : (IO, ?limit: Integer) { (Batch) -> void } -> void
+    def self.each_batch: (IO, ?limit: Integer) { (Batch) -> void } -> void
+
+    # An exception - its class, message, backtrace and causes - or a message, as an error Hash
+    # : (Exception | String | untyped, ?Integer) -> Hash[Symbol, untyped]
+    def self.error_to_h: (Exception | String | untyped, ?Integer) -> Hash[Symbol, untyped]
+
+    # Every string that leaves or enters goes through here: valid UTF-8, and cut
+    # : (untyped) -> String?
+    def self.text: (untyped) -> String?
+
+    # : (untyped) -> Event?
+    private def self.event: (untyped) -> Event?
+
+    # : (untyped) -> path?
+    private def self.path: (untyped) -> path?
+
+    # : (Symbol, untyped) -> untyped
+    private def self.value: (Symbol, untyped) -> untyped
+
+    # : (untyped, ?stale: bool) -> (Hash[Symbol, untyped] | :invalid)
+    private def self.attributes: (untyped, ?stale: bool) -> (Hash[Symbol, untyped] | :invalid)
+
+    # : (untyped) -> (Hash[Symbol, untyped] | :invalid)
+    private def self.node: (untyped) -> (Hash[Symbol, untyped] | :invalid)
+
+    # : (untyped) -> Integer?
+    private def self.count: (untyped) -> Integer?
+
+    # : (untyped) -> Float?
+    private def self.time: (untyped) -> Float?
+
+    # Finite integers and floats only - not a Rational, nor a Complex that has no Float to give,
+    # nor the Infinity that `1e999` parses to, which no JSON could ever be written with again
+    # : (untyped) -> Float?
+    private def self.number: (untyped) -> Float?
+
+    # : (Hash[untyped, untyped], ?Integer) -> Hash[Symbol, untyped]
+    private def self.error: (Hash[untyped, untyped], ?Integer) -> Hash[Symbol, untyped]
+  end
+end