terminalwire 0.3.5.alpha2 → 2.0.0

data/lib/terminalwire/v2/server/runtime.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+module Terminalwire::V2
+  module Server
+    # Drives a Server::Connection over a transport. A background **read pump**
+    # continuously drains incoming frames and routes them: responses go to the
+    # caller blocked in #request, and unsolicited control frames (resize, and
+    # later interrupt) update state / fire callbacks. This is what lets the
+    # server always know the client's terminal size, not just while it happens to
+    # be inside a request.
+    #
+    # Threading: the pump runs on its own thread; the CLI runs on the caller's
+    # thread and blocks in #request on a per-stream queue the pump fulfills.
+    class Runtime
+      # Largest payload in a single output data frame; actual frame size is
+      # min(this, available flow credit).
+      MAX_FRAME = 32 * 1024
+
+      attr_reader :connection, :program, :entitlement, :terminal
+
+      def initialize(transport:,
+                     server_min: Protocol::MIN_VERSION,
+                     server_max: Protocol::MAX_VERSION,
+                     server_capabilities: Protocol::CAPABILITIES)
+        @transport = transport
+        @connection = Connection.new(
+          server_min: server_min, server_max: server_max,
+          server_capabilities: server_capabilities
+        )
+        @terminal = Terminal.new
+        @flow = FlowController.new
+        @client_window = Protocol::DEFAULT_WINDOW
+        @waiters = {}
+        @raw_inputs = {}
+        @lock = Mutex.new
+        @ready = Queue.new
+        @signaled = false
+        @on_resize = nil
+        @interrupted = false
+      end
+
+      # Register a callback fired (on the pump thread) whenever the client's
+      # window resizes. The Terminal is already updated before it runs.
+      def on_resize(&block)
+        @on_resize = block
+      end
+
+      # Start the read pump and block until the handshake reaches ready (or fails).
+      # The calling thread is the CLI thread; an interrupt signal is raised into it.
+      def handshake
+        @cli_thread = Thread.current
+        @pump = Thread.new { pump }
+        result = @ready.pop
+        raise result if result.is_a?(Exception)
+
+        self
+      end
+
+      # Fire-and-forget: write a single control frame (welcome, exit, request,
+      # open/close). NOT flow-controlled — these are small control-plane frames.
+      def emit(frame)
+        @transport.write(Codec.encode(frame))
+        nil
+      end
+
+      # Open an output stream (:stdout/:stderr) and start its flow window at the
+      # client's advertised offer. Returns the stream id.
+      def open_output(stream)
+        sid, frame = @connection.open_stream(stream)
+        @flow.open(sid, @client_window)
+        emit(frame)
+        sid
+      end
+
+      # Write output to a stream, flow-controlled: each frame is sized to the
+      # currently available credit (blocking when the window is empty), so the
+      # server can never outrun the client. Raises if the connection dies.
+      def write_data(sid, bytes)
+        bytes = bytes.b
+        total = bytes.bytesize
+        if total.zero?
+          emit(Frames.data(sid: sid, bytes: "".b))
+          return
+        end
+
+        offset = 0
+        while offset < total
+          take = @flow.reserve(sid, [total - offset, MAX_FRAME].min)
+          emit(Frames.data(sid: sid, bytes: bytes.byteslice(offset, take)))
+          offset += take
+        end
+      end
+
+      def close_output(sid)
+        emit(@connection.close_stream(sid))
+        @flow.close(sid)
+      end
+
+      # Open a raw input stream: the client puts its terminal in `mode` (raw or
+      # cbreak) and streams keystrokes as data frames until we close it, restoring
+      # the prior mode on close. Returns the stream id.
+      def open_raw_input(mode: Protocol::Mode::RAW)
+        sid, frame = @connection.open_stream(Protocol::Stream::STDIN_RAW, mode: mode)
+        @lock.synchronize { @raw_inputs[sid] = Queue.new }
+        emit(frame)
+        sid
+      end
+
+      # Read the next keystroke chunk from a raw input stream; blocks until input
+      # arrives, returns nil when the stream is closed or the connection dies.
+      def read_raw(sid)
+        queue = @lock.synchronize { @raw_inputs[sid] }
+        return nil unless queue
+
+        value = queue.pop
+        # An interrupt and the connection's :closed both unblock this pop and can
+        # race; the interrupt is the user's intent, so it wins (-> exit 130). This
+        # makes the outcome deterministic regardless of which arrives first (the
+        # async/Falcon bridge could let :closed land before Thread#raise lands).
+        raise Interrupted if interrupted?
+
+        value == :closed ? nil : value
+      end
+
+      def close_raw_input(sid)
+        emit(@connection.close_stream(sid))
+        queue = @lock.synchronize { @raw_inputs.delete(sid) }
+        queue&.push(:closed) # unblock a pending read_raw
+      end
+
+      # Synchronous resource call: register a waiter, write the request, and block
+      # until the pump delivers the correlated response (or the connection dies).
+      def request(resource, method, params = {})
+        sid, frame = @connection.call(resource, method, params)
+        waiter = Queue.new
+        @lock.synchronize { @waiters[sid] = waiter }
+        emit(frame)
+
+        answer = waiter.pop
+        # Interrupt wins over a racing connection-closed failure (see read_raw).
+        raise Interrupted if interrupted?
+        raise answer if answer.is_a?(Exception)
+
+        unless answer[:ok]
+          error = answer[:error] || {}
+          raise ResponseError.new(error["code"] || "internal", error["message"] || "request failed")
+        end
+        answer[:value]
+      end
+
+      # Stop the pump and release the transport.
+      def close
+        @transport.close
+        @pump&.join(2)
+      end
+
+      private
+
+      def pump
+        while (bytes = @transport.read)
+          frame =
+            begin
+              Codec.decode(bytes)
+            rescue ProtocolError
+              # A single malformed frame is dropped, not fatal — one bad frame must
+              # not tear down the whole session (matches the Go client and the Elixir
+              # server). The WebSocket transport delimits messages, so the next frame
+              # is unaffected. State-machine violations from #receive stay fatal.
+              next
+            end
+          route(@connection.receive(frame))
+        end
+        # transport closed
+        shutdown(ProtocolError.new("client closed before hello"),
+                 ProtocolError.new("connection closed"))
+      rescue StandardError => e
+        shutdown(e, e)
+      end
+
+      # Release everyone blocked on the connection: handshake waiter, in-flight
+      # requests, and senders blocked on flow credit.
+      def shutdown(ready_error, waiter_error)
+        signal_ready(ready_error)
+        fail_waiters(waiter_error)
+        @flow.shutdown(waiter_error)
+        # Unblock any read_raw waiting on a dead connection.
+        @lock.synchronize { @raw_inputs.values }.each { |queue| queue.push(:closed) }
+      end
+
+      def route(directives)
+        directives.each do |kind, *rest|
+          case kind
+          when :send
+            emit(rest[0])
+          when :event
+            handle_event(rest[0], rest[1])
+          end
+        end
+      end
+
+      def handle_event(name, payload)
+        case name
+        when :ready
+          @program = payload[:program]
+          @entitlement = payload[:entitlement]
+          @terminal.apply(payload[:terminal])
+          @client_window = payload.dig(:flow, "window") || Protocol::DEFAULT_WINDOW
+          signal_ready(:ok)
+        when :incompatible
+          signal_ready(ProtocolError.new("incompatible client"))
+        when :response
+          waiter = @lock.synchronize { @waiters.delete(payload[:sid]) }
+          waiter&.push(payload)
+        when :resize
+          @terminal.resize(cols: payload[:cols], rows: payload[:rows])
+          @on_resize&.call(@terminal)
+        when :interrupt
+          # Deliver Ctrl-C into the CLI thread, like a local SIGINT — a blocked
+          # request/read/sleep unwinds and the Handler turns it into exit 130.
+          # Raise Interrupted, NOT Ruby's Interrupt: Interrupt is a SignalException,
+          # and raising one into a thread inside a Falcon worker disturbs the async
+          # reactor and kills the connection before the exit frame can flush (the
+          # client then hangs). A plain Exception subclass interrupts the same
+          # blocking calls without touching Falcon's signal machinery. Set the flag
+          # BEFORE raising so a blocked read/request that unblocks via a racing
+          # connection-close still sees the interrupt (see read_raw).
+          @lock.synchronize { @interrupted = true }
+          begin
+            @cli_thread&.raise(Interrupted.new)
+          rescue ThreadError
+            nil
+          end
+        when :window_adjust
+          @flow.grant(payload[:sid], payload[:bytes])
+        when :input
+          queue = @lock.synchronize { @raw_inputs[payload[:sid]] }
+          queue&.push(payload[:bytes])
+        end
+      end
+
+      # Signal the handshake exactly once.
+      def signal_ready(value)
+        @lock.synchronize do
+          return if @signaled
+
+          @signaled = true
+        end
+        @ready.push(value)
+      end
+
+      # Read the interrupt flag under the lock: it's written on the pump thread and
+      # read on the CLI thread, so it needs a memory barrier on both sides (not just
+      # the GVL) to be visible across threads on every Ruby runtime.
+      def interrupted?
+        @lock.synchronize { @interrupted }
+      end
+
+      # Unblock every in-flight request so callers don't hang on a dead connection.
+      def fail_waiters(error)
+        @lock.synchronize do
+          @waiters.each_value { |waiter| waiter.push(error) }
+          @waiters.clear
+        end
+      end
+    end
+  end
+end

data/lib/terminalwire/v2/server/session.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Terminalwire::V2
+  module Server
+    # Adapts a callback/event-loop websocket endpoint to the blocking Handler.
+    # The endpoint supplies an `on_send` sink for outgoing frames and forwards
+    # each incoming frame to #receive; the CLI runs on a background thread. This is
+    # the seam an ActionCable channel or an async-websocket Rack endpoint plugs
+    # into (see ../../../README.md).
+    #
+    #   session = Terminalwire::V2::Server::Session.start(
+    #     cli_class: MyCLI,
+    #     on_send:   ->(bytes) { websocket.send_binary(bytes) }
+    #   )
+    #   websocket.on_message { |bytes| session.receive(bytes) }
+    #   websocket.on_close   { session.close }
+    class Session
+      def self.start(cli_class:, on_send:, report: nil, verbose: false)
+        new(cli_class: cli_class, on_send: on_send, report: report, verbose: verbose).tap(&:start)
+      end
+
+      def initialize(cli_class:, on_send:, report: nil, verbose: false)
+        @transport = Transport::Queue.new(sink: on_send)
+        @handler = Handler.new(cli_class: cli_class, report: report, verbose: verbose)
+      end
+
+      def start
+        @thread = Thread.new do
+          @handler.call(transport: @transport)
+        ensure
+          # Once the worker is done (normal exit or error), close the transport so
+          # any further frames the endpoint delivers are dropped instead of piling
+          # up in the inbox behind a dead worker.
+          @transport.close
+        end
+        self
+      end
+
+      # Forward a frame received from the client.
+      def receive(bytes)
+        @transport.deliver(bytes)
+      end
+
+      # End the session and wait briefly for the worker to finish.
+      def close
+        @transport.close
+        @thread&.join(2)
+      end
+    end
+  end
+end

data/lib/terminalwire/v2/server/stream_router.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Terminalwire::V2
+  module Server
+    # A stand-in for a global IO stream ($stdout/$stderr/$stdin) that dispatches
+    # every call to a **fiber-local** target, falling back to the real stream when
+    # no command is currently redirecting on this fiber.
+    #
+    # This is what makes redirection concurrency-safe: instead of mutating the
+    # process-global $stdout per command (which interleaves when two run at once),
+    # we install ONE router as $stdout for the whole process and let each fiber
+    # point its own target at its own client. `Thread.current[]` is fiber-local in
+    # Ruby, so this isolates both threaded servers (Puma) and fiber-per-request
+    # servers (Falcon).
+    class StreamRouter
+      # @param key [Symbol] fiber-local key, e.g. :terminalwire_stdout
+      # @param fallback [IO] the real stream to use when no redirect is active
+      def initialize(key, fallback)
+        @key = key
+        @fallback = fallback
+      end
+
+      # The stream this fiber's calls should go to right now.
+      def __target__ = Thread.current[@key] || @fallback
+
+      # Set/clear the fiber-local target. Returns the previous value so callers
+      # can restore exactly (supporting nesting).
+      def __bind__(target)
+        previous = Thread.current[@key]
+        Thread.current[@key] = target
+        previous
+      end
+
+      def __restore__(previous) = Thread.current[@key] = previous
+
+      # Delegate everything to the current target. We forward the common methods
+      # explicitly (fast path + clear intent) and method_missing the long tail so
+      # the router is a faithful IO stand-in for whatever a CLI library calls.
+      %i[print puts write << printf p flush sync sync= gets getpass read
+         each_line each tty? isatty winsize fileno print_line].each do |m|
+        define_method(m) do |*args, &block|
+          __target__.public_send(m, *args, &block)
+        end
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        __target__.respond_to?(name, include_private) || super
+      end
+
+      def method_missing(name, *args, &block)
+        target = __target__
+        if target.respond_to?(name)
+          target.public_send(name, *args, &block)
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/terminalwire/v2/server/terminal.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Terminalwire::V2
+  module Server
+    # The server's live model of the client's terminal. See ../../../TERMINAL.md.
+    #
+    # Two orthogonal parts, deliberately not conflated:
+    #   * three Streams (stdin/stdout/stderr), each independently tty/pipe/file/null
+    #   * one Device (the controlling terminal): size, term, color, encoding, mode
+    #
+    # Seeded from the hello `terminal` block; the device's size/mode are updated by
+    # control frames. Thread-safe: the read pump writes while the CLI reads.
+    class Terminal
+      # A standard stream and what it's connected to. Kind is fixed for the
+      # session (a stream doesn't turn from a pipe into a tty mid-run).
+      Stream = Data.define(:kind) do
+        def tty?  = kind == "tty"
+        def pipe? = kind == "pipe"
+        def file? = kind == "file"
+        def null? = kind == "null"
+      end
+
+      attr_reader :stdin, :stdout, :stderr
+
+      def initialize(stdin: "tty", stdout: "tty", stderr: "tty",
+                     cols: 80, rows: 24, xpixels: 0, ypixels: 0,
+                     term: "", color: "none", encoding: "UTF-8", mode: "cooked")
+        @stdin = Stream.new(kind: stdin)
+        @stdout = Stream.new(kind: stdout)
+        @stderr = Stream.new(kind: stderr)
+        @cols = cols
+        @rows = rows
+        @xpixels = xpixels
+        @ypixels = ypixels
+        @term = term
+        @color = color
+        @encoding = encoding
+        @mode = mode
+        @mutex = Mutex.new
+      end
+
+      # Device attributes.
+      def cols     = @mutex.synchronize { @cols }
+      def rows     = @mutex.synchronize { @rows }
+      def xpixels  = @mutex.synchronize { @xpixels }
+      def ypixels  = @mutex.synchronize { @ypixels }
+      def term     = @mutex.synchronize { @term }
+      def encoding = @mutex.synchronize { @encoding }
+      def color    = @mutex.synchronize { @color }
+      def mode     = @mutex.synchronize { @mode }
+
+      def color? = color != "none"
+
+      # A controlling terminal device exists iff some stream is a tty.
+      def device? = @stdin.tty? || @stdout.tty? || @stderr.tty?
+
+      # IO#winsize convention: [rows, cols].
+      def winsize = @mutex.synchronize { [@rows, @cols] }
+
+      # Look up a stream by name (:stdin/:stdout/:stderr).
+      def stream(name)
+        { stdin: @stdin, stdout: @stdout, stderr: @stderr }.fetch(name.to_sym)
+      end
+
+      # Apply a wire `terminal` block (string keys) from a hello frame.
+      def apply(block)
+        return if block.nil?
+
+        @stdin  = Stream.new(kind: block.dig("stdin", "kind") || @stdin.kind)
+        @stdout = Stream.new(kind: block.dig("stdout", "kind") || @stdout.kind)
+        @stderr = Stream.new(kind: block.dig("stderr", "kind") || @stderr.kind)
+
+        device = block["device"]
+        return if device.nil?
+
+        @mutex.synchronize do
+          @cols = device["cols"] if device["cols"]
+          @rows = device["rows"] if device["rows"]
+          @xpixels = device["xpixels"] if device["xpixels"]
+          @ypixels = device["ypixels"] if device["ypixels"]
+          @term = device["term"] if device["term"]
+          @color = device["color"] if device["color"]
+          @encoding = device["encoding"] if device["encoding"]
+          @mode = device["mode"] if device["mode"]
+        end
+      end
+
+      # Apply a resize control frame.
+      def resize(cols:, rows:, xpixels: nil, ypixels: nil)
+        @mutex.synchronize do
+          @cols = cols if cols
+          @rows = rows if rows
+          @xpixels = xpixels if xpixels
+          @ypixels = ypixels if ypixels
+        end
+      end
+    end
+  end
+end

data/lib/terminalwire/v2/server/thor.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Terminalwire::V2
+  module Server
+    # Thor integration. Including this in a Thor CLI routes all of Thor's I/O —
+    # say, ask, yes?, and bare puts/print/gets inside commands — through the
+    # Terminalwire Context instead of the server's real $stdin/$stdout. This is
+    # what lets you keep writing an ordinary Thor CLI while it runs on the client.
+    #
+    # Thor needs this dedicated adapter (rather than the generic Server.redirect)
+    # because its shell captures the output streams at construction instead of
+    # reading the $stdout/$stderr globals at call time. The byte plumbing is the
+    # shared Server::IO.
+    module Thor
+      # Bare puts/print/gets inside Thor commands. Defined in a module so Thor's
+      # method_added hook never sees them and they are not registered as commands.
+      module Helpers
+        def puts(*args) = shell.context.puts(*args.flatten.map(&:to_s))
+        def print(*args) = args.each { |arg| shell.context.print(arg.to_s) }
+        def warn(*args) = args.each { |arg| shell.context.warn(arg.to_s) }
+        def gets = shell.context.gets
+        def getpass = shell.context.getpass
+        def context = shell.context
+        # The client-side resources, exposed on the CLI instance like v1 (so a Thor
+        # command can call `browser.launch(url)`, `file.read(path)`, `env("HOME")`).
+        def browser = shell.context.browser
+        def file = shell.context.file
+        def directory = shell.context.directory
+        def env(name) = shell.context.env(name)
+        def client = shell.context
+      end
+
+      class Shell < ::Thor::Shell::Basic
+        attr_reader :context
+
+        def initialize(context, *args, **kwargs, &block)
+          @context = context
+          super(*args, **kwargs, &block)
+        end
+
+        protected
+
+        def stdout = @stdout ||= Server::IO.new(@context, :stdout)
+        def stderr = @stderr ||= Server::IO.new(@context, :stderr)
+
+        # Override Thor's line-editor input (which hardcodes $stdin) to read from
+        # the client through the context. Fixes ask, yes?, no?, and passwords.
+        def ask_simply(statement, color, options)
+          default = options[:default]
+          message = [statement, ("(#{default})" if default), nil].uniq.join(" ")
+          stdout.print(prepare_message(message, *Array(color)))
+
+          result = options.fetch(:echo, true) ? context.gets : context.getpass
+          return unless result
+
+          result = result.strip
+          default && result == "" ? default : result
+        end
+      end
+
+      def self.included(base)
+        base.extend ClassMethods
+        base.include Helpers
+      end
+
+      module ClassMethods
+        # Dispatch a CLI invocation with a Terminalwire-backed shell.
+        def terminalwire(arguments:, context:)
+          dispatch(nil, arguments.dup, nil, shell: Shell.new(context)) do |instance|
+            yield instance if block_given?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/terminalwire/v2/transport/memory.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module Terminalwire::V2
+  module Transport
+    # A blocking in-memory duplex transport. Two ends share a pair of queues, so
+    # one end's #write is the other end's #read. Used for tests and in-process
+    # wiring; production uses a WebSocket-backed transport with the same interface
+    # (#read -> bytes/nil, #write(bytes), #close).
+    class Memory
+      EOF = :__eof__
+
+      def self.pair
+        a = ::Queue.new
+        b = ::Queue.new
+        [new(read_queue: a, write_queue: b), new(read_queue: b, write_queue: a)]
+      end
+
+      def initialize(read_queue:, write_queue:)
+        @read_queue = read_queue
+        @write_queue = write_queue
+      end
+
+      # @return [String, nil] the next frame's bytes, or nil once closed.
+      def read
+        value = @read_queue.pop
+        value == EOF ? nil : value
+      end
+
+      def write(bytes)
+        @write_queue.push(bytes)
+      end
+
+      def close
+        @write_queue.push(EOF)
+      end
+    end
+  end
+end

data/lib/terminalwire/v2/transport/queue.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module Terminalwire::V2
+  module Transport
+    # A queue-backed transport for callback-driven servers (ActionCable, async
+    # websocket Rack endpoints, etc.). The endpoint pushes each received frame
+    # with #deliver; the blocking Runtime consumes them via #read. Outgoing frames
+    # are handed to the sink callable. This bridges an event-loop/callback world to
+    # the synchronous server runtime.
+    class Queue
+      CLOSED = Object.new
+
+      def initialize(sink:)
+        @sink = sink
+        @inbox = ::Queue.new
+        @mutex = Mutex.new
+        @closed = false
+      end
+
+      # Called by the websocket endpoint when a frame arrives from the client.
+      def deliver(bytes)
+        @mutex.synchronize { @inbox << bytes unless @closed }
+      end
+
+      def read
+        value = @inbox.pop
+        value.equal?(CLOSED) ? nil : value
+      end
+
+      def write(bytes)
+        @sink.call(bytes)
+      end
+
+      def close
+        @mutex.synchronize do
+          next if @closed
+
+          @closed = true
+          @inbox << CLOSED
+        end
+      end
+    end
+  end
+end

data/lib/terminalwire/v2/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Self-contained (full module nesting) so the gemspec can require just this file
+# without loading the rest of the library or assuming Terminalwire is defined.
+module Terminalwire
+  module V2
+    VERSION = "2.0.0"
+  end
+end

data/lib/terminalwire/v2/window.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Terminalwire::V2
+  # The flow-control credit rule, as a pure ledger — no threads, no I/O. This is
+  # the *protocol* part of flow control: how much output may be in flight, and how
+  # window_adjust extends it. The blocking behaviour when credit runs out is an
+  # implementation concern layered on top (see Server::FlowController); the rule
+  # itself is deterministic and identical across implementations, so it is
+  # exercised by the language-neutral flow corpus in ../../conformance.
+  class Window
+    attr_reader :available
+
+    def initialize(size)
+      @available = size > Protocol::MAX_WINDOW ? Protocol::MAX_WINDOW : size
+    end
+
+    # The number of bytes that may be sent right now toward a request for `want`:
+    # min(want, available). Decrements the window by that amount and returns it.
+    def take(want)
+      amount = want < @available ? want : @available
+      amount = 0 if amount.negative?
+      @available -= amount
+      amount
+    end
+
+    # Extend the window (a window_adjust arrived), clamped to the protocol ceiling
+    # (Protocol::MAX_WINDOW) so a peer can't grow the window without bound.
+    def grant(bytes)
+      @available += bytes
+      @available = Protocol::MAX_WINDOW if @available > Protocol::MAX_WINDOW
+    end
+  end
+end