ratatui_ruby-tea 0.2.0 → 0.3.1

data/lib/ratatui_ruby/tea/command/cancellation_token.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    module Command
+      # Cooperative cancellation mechanism for long-running commands.
+      #
+      # Long-running commands block the event loop. Commands that poll, stream, or wait
+      # indefinitely prevent clean shutdown. Killing threads mid-operation corrupts state.
+      #
+      # This class signals cancellation requests. Commands check +cancelled?+ periodically
+      # and stop gracefully. The runtime calls +cancel!+ when shutdown begins.
+      #
+      # Use it to implement WebSocket handlers, database pollers, or any command that loops.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   class PollerCommand
+      #     include Tea::Command::Custom
+      #
+      #     def call(out, token)
+      #       until token.cancelled?
+      #         data = fetch_batch
+      #         out.put(:batch, data)
+      #         sleep 5
+      #       end
+      #       out.put(:poller_stopped)
+      #     end
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      class CancellationToken
+        # Number of times +cancel!+ has been called. :nodoc:
+        #
+        # Exposed for testing thread-safety. Not part of the public API.
+        attr_reader :cancel_count
+
+        # Creates a new cancellation token in the non-cancelled state.
+        def initialize
+          @cancel_count = 0
+          @mutex = Mutex.new
+        end
+
+        # Signals cancellation. Thread-safe.
+        #
+        # Call this to request the command stop. The command checks +cancelled?+
+        # and stops at the next safe point.
+        #
+        # === Example
+        #
+        #--
+        # SPDX-SnippetBegin
+        # SPDX-FileCopyrightText: 2026 Kerrick Long
+        # SPDX-License-Identifier: MIT-0
+        #++
+        #   token = CancellationToken.new
+        #   token.cancel!
+        #   token.cancelled?  # => true
+        #--
+        # SPDX-SnippetEnd
+        #++
+        def cancel!
+          @mutex.synchronize do
+            current = @cancel_count
+            sleep 0 # Force context switch (enables thread-safety testing)
+            @cancel_count = current + 1
+          end
+        end
+
+        # Checks if cancellation was requested. Thread-safe.
+        #
+        # Commands call this periodically in their main loop. When it returns
+        # <tt>true</tt>, the command should clean up and exit.
+        #
+        # === Example
+        #
+        #--
+        # SPDX-SnippetBegin
+        # SPDX-FileCopyrightText: 2026 Kerrick Long
+        # SPDX-License-Identifier: MIT-0
+        #++
+        #   until token.cancelled?
+        #     do_work
+        #     sleep 1
+        #   end
+        #--
+        # SPDX-SnippetEnd
+        #++
+        def cancelled?
+          @cancel_count > 0
+        end
+
+        # Null object for commands that ignore cancellation.
+        #
+        # Some commands complete quickly and do not check for cancellation.
+        # Pass this when the command signature requires a token but the
+        # command does not use it.
+        #
+        # Ractor-shareable. Calling <tt>cancel!</tt> does nothing.
+        class NoneToken < Data.define(:cancelled?)
+          # Does nothing. Ignores cancellation requests.
+          #
+          # === Example
+          #
+          #--
+          # SPDX-SnippetBegin
+          # SPDX-FileCopyrightText: 2026 Kerrick Long
+          # SPDX-License-Identifier: MIT-0
+          #++
+          #   CancellationToken::NONE.cancel!  # => nil (no effect)
+          #--
+          # SPDX-SnippetEnd
+          #++
+          def cancel!
+            nil
+          end
+        end
+
+        # Singleton null token. Always returns <tt>cancelled? == false</tt>.
+        NONE = NoneToken.new(cancelled?: false)
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/tea/command/custom.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    module Command
+      # Mixin for user-defined custom commands.
+      #
+      # Custom commands extend Tea with side effects: WebSockets, gRPC, database polls,
+      # background tasks. The runtime dispatches them in threads and routes results
+      # back as messages.
+      #
+      # Include this module to identify your class as a command. The runtime uses
+      # +tea_command?+ to distinguish commands from plain models. Override
+      # +tea_cancellation_grace_period+ if your cleanup takes longer than 100 milliseconds.
+      #
+      # Use it to build real-time features, long-polling connections, or background workers.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   class WebSocketCommand
+      #     include RatatuiRuby::Tea::Command::Custom
+      #
+      #     def initialize(url)
+      #       @url = url
+      #     end
+      #
+      #     def call(out, token)
+      #       ws = WebSocket::Client.new(@url)
+      #       ws.on_message { |msg| out.put(:ws_message, msg) }
+      #       ws.connect
+      #
+      #       until token.cancelled?
+      #         ws.ping
+      #         sleep 1
+      #       end
+      #
+      #       ws.close
+      #     end
+      #
+      #     # WebSocket close handshake needs extra time
+      #     def tea_cancellation_grace_period
+      #       5.0
+      #     end
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      module Custom
+        # Brand predicate for command identification.
+        #
+        # The runtime calls this to distinguish commands from plain models.
+        # Returns <tt>true</tt> unconditionally.
+        #
+        # You do not need to override this method.
+        def tea_command?
+          true
+        end
+
+        # Cleanup time after cancellation is requested. In seconds.
+        #
+        # When the runtime cancels your command (app exit, navigation, explicit cancel),
+        # it calls <tt>token.cancel!</tt> and waits this long for your command to stop.
+        # If your command does not exit within this window, it is force-killed.
+        #
+        # *This is NOT a lifetime limit.* Your command runs indefinitely until cancelled.
+        # A WebSocket open for 15 minutes is fine. This timeout only applies to the
+        # cleanup phase after cancellation is requested.
+        #
+        # Override this method to specify how long your cleanup takes:
+        #
+        # - <tt>0.5</tt> — Quick HTTP abort, no cleanup needed
+        # - <tt>2.0</tt> — Default, suitable for most commands
+        # - <tt>5.0</tt> — WebSocket close handshake with remote server
+        # - <tt>Float::INFINITY</tt> — Never force-kill (database transactions)
+        #
+        # === Example
+        #
+        #--
+        # SPDX-SnippetBegin
+        # SPDX-FileCopyrightText: 2026 Kerrick Long
+        # SPDX-License-Identifier: MIT-0
+        #++
+        #   # Database transactions should never be interrupted mid-write
+        #   def tea_cancellation_grace_period
+        #     Float::INFINITY
+        #   end
+        #--
+        # SPDX-SnippetEnd
+        #++
+        def tea_cancellation_grace_period
+          0.1
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/tea/command/outlet.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require "ratatui_ruby"
+
+module RatatuiRuby
+  module Tea
+    module Command
+      # Messaging gateway for custom commands.
+      #
+      # Custom commands run in background threads. They produce results that the
+      # main loop consumes.
+      #
+      # Managing queues and message formats manually is tedious. It scatters queue
+      # logic across your codebase and makes mistakes easy.
+      #
+      # This class wraps the queue with a clean API. Call +put+ to send tagged
+      # messages. Debug mode validates Ractor-shareability.
+      #
+      # Use it to send results from HTTP requests, WebSocket streams, or database polls.
+      #
+      # === Example (One-Shot)
+      #
+      # Commands run in their own thread. Blocking calls work fine:
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   class FetchUserCommand
+      #     include Tea::Command::Custom
+      #
+      #     def initialize(user_id)
+      #       @user_id = user_id
+      #     end
+      #
+      #     def call(out, _token)
+      #       response = Net::HTTP.get(URI("https://api.example.com/users/#{@user_id}"))
+      #       user = JSON.parse(response)
+      #       out.put(:user_fetched, Ractor.make_shareable(user: user))
+      #     rescue => e
+      #       out.put(:user_fetch_failed, error: e.message.freeze)
+      #     end
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      #
+      # === Example (Long-Running)
+      #
+      # Commands that loop check the cancellation token:
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   class PollerCommand
+      #     include Tea::Command::Custom
+      #
+      #     def call(out, token)
+      #       until token.cancelled?
+      #         data = fetch_batch
+      #         out.put(:batch, Ractor.make_shareable(data))
+      #         sleep 5
+      #       end
+      #       out.put(:poller_stopped)
+      #     end
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      class Outlet
+        # Creates an outlet for the given queue.
+        #
+        # The runtime provides the queue. Custom commands receive the outlet as
+        # their first argument.
+        #
+        # [queue] A <tt>Thread::Queue</tt> or compatible object.
+        def initialize(queue)
+          @queue = queue
+        end
+
+        # Sends a tagged message to the runtime.
+        #
+        # Builds an array <tt>[tag, *payload]</tt> and pushes it to the queue.
+        # The update function pattern-matches on the tag.
+        #
+        # Debug mode validates Ractor-shareability. It raises <tt>Error::Invariant</tt>
+        # if the message is not shareable. Production skips this check.
+        #
+        # [tag] Symbol identifying the message type.
+        # [payload] Additional arguments. Freeze them or use <tt>Ractor.make_shareable</tt>.
+        #
+        # === Example
+        #
+        #--
+        # SPDX-SnippetBegin
+        # SPDX-FileCopyrightText: 2026 Kerrick Long
+        # SPDX-License-Identifier: MIT-0
+        #++
+        #   out.put(:user_fetched, user: Ractor.make_shareable(user))
+        #   out.put(:error, message: "Connection failed".freeze)
+        #   out.put(:progress, percent: 42)  # Integers are always shareable
+        #--
+        # SPDX-SnippetEnd
+        #++
+        def put(tag, *payload)
+          message = [tag, *payload].freeze
+
+          if RatatuiRuby::Debug.enabled? && !Ractor.shareable?(message)
+            raise RatatuiRuby::Error::Invariant,
+              "Message is not Ractor-shareable: #{message.inspect}\n" \
+                "Use Ractor.make_shareable or Object#freeze."
+          end
+
+          @queue << message
+        end
+      end
+    end
+  end
+end