terminalwire 0.3.5.alpha2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c61087330d6c3ad29504c44b4ee3ac3d3a49b481f4ba0e42aa889017a125d8b
-  data.tar.gz: 9a8f93609cf71329b003d3f995e48caf77b73bf8b1097fb6cce433bd9868cbc9
+  metadata.gz: 3a3b1a0d008654c84320fb1300e080d289e6b620b1526556427b8bdf493286dc
+  data.tar.gz: 0ef9c8b606d22d79d44e258ae2d38fc19a4cfcb18d92ce106b0e3fc33806e408
 SHA512:
-  metadata.gz: '0306186b973039130168de5a56c89931e139d34ff3a83c7e32a11bf31d984c44253bd2b3a8c52752539861106033acabbe54502ad935537c02a07213a956da33'
-  data.tar.gz: 1af32080f60c605f682fd0e671f1f1484d12492b4e828e16a581469589ffc87fdc70cf0f0609110bef84437eb805e0057f6749ce18c2b6842afef886dd447b39
+  metadata.gz: 75d87cd218444227f5e1a5c17e65ed887e28992810dfe249050e22b159b636b77a40fca4fbf3346f60467526a4c4603060e67f0819c1ff9e4afa1ff105246417
+  data.tar.gz: 613575a6abb5e75498be37aaaf94e970997545d780dce942293c129d5b99848e18d9cd0757f738481d38efb09d903533c5eb10e833714797b93196c9f1c4afed

data/lib/terminalwire/v2/codec.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "msgpack"
+
+module Terminalwire::V2
+  # Pure bytes <-> frame conversion. A frame is a Hash with string keys (the wire
+  # shape). No I/O, no transport — this is the sans-IO seam the conformance corpus
+  # exercises directly.
+  module Codec
+    # Largest valid stream id: a signed 64-bit max. Go decodes sids into int64, so
+    # anything above this would wrap to a negative (colliding) sid there; bounding
+    # it here keeps all three impls' sid validity identical.
+    MAX_SID = (1 << 63) - 1
+
+    module_function
+
+    # @param frame [Hash] a frame with string keys
+    # @return [String] MessagePack bytes (binary encoding)
+    def encode(frame)
+      raise ProtocolError, "frame must be a Hash, got #{frame.class}" unless frame.is_a?(Hash)
+
+      MessagePack.pack(frame)
+    end
+
+    # @param bytes [String] MessagePack bytes for exactly one frame
+    # @return [Hash] the decoded frame with string keys
+    # @raise [ProtocolError] if the bytes are not a well-formed frame
+    def decode(bytes)
+      obj =
+        begin
+          MessagePack.unpack(bytes)
+        rescue StandardError => e
+          raise ProtocolError, "malformed msgpack: #{e.message}"
+        end
+
+      raise ProtocolError, "frame must be a map" unless obj.is_a?(Hash)
+      # 't' must be a NON-EMPTY type string. Go and Elixir reject "" at the codec;
+      # Ruby used to let it through to the state machine. An empty type is not a
+      # valid frame — reject it here so all three behave identically.
+      raise ProtocolError, "frame missing string 't'" unless obj["t"].is_a?(String) && !obj["t"].empty?
+      # 'sid' must be a non-negative integer that fits in a signed 64-bit int (see
+      # MAX_SID): real sids are small and server-allocated, and the range bound keeps
+      # the three impls aligned (Go would otherwise wrap a uint64 sid to a negative).
+      sid = obj["sid"]
+      unless sid.is_a?(Integer) && sid >= 0 && sid <= MAX_SID
+        raise ProtocolError, "frame missing integer 'sid'"
+      end
+
+      obj
+    end
+  end
+end

data/lib/terminalwire/v2/conformance.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+require "base64"
+require "pathname"
+
+module Terminalwire::V2
+  # Loads the language-neutral conformance corpus and resolves its typed sentinels
+  # into native Ruby values. The Go and Elixir runners do the equivalent. This is
+  # what lets one corpus validate every implementation.
+  #
+  # Two file shapes live in the corpus:
+  #   * simple vector tables (negotiate/roundtrip/golden/validate/flow) — YAML/JSON,
+  #     with `$bin` base64 + `bytes_hex` sentinels;
+  #   * "tapes" (session) — S-expressions (see Sexp): recorded client<->server
+  #     interactions. Sexp is used for the tapes because it is trivial and
+  #     unambiguous to parse in every language and reads like a transcript.
+  module Conformance
+    module_function
+
+    def root
+      Pathname.new(ENV.fetch("TERMINALWIRE_CORPUS") do
+        File.expand_path("../../../conformance", __dir__)
+      end)
+    end
+
+    def vectors_dir
+      root.join("vectors")
+    end
+
+    # Load every vector file in a category, dispatching by extension, and return a
+    # flat array of cases with sentinels resolved to native values. Fails LOUDLY
+    # when the corpus is absent rather than silently running zero cases.
+    def load(category)
+      unless vectors_dir.directory?
+        raise "conformance corpus not found at #{vectors_dir} — set TERMINALWIRE_CORPUS " \
+              "to the corpus directory (it ships in terminalwire/protocol). Without it " \
+              "the corpus specs would silently run zero cases."
+      end
+      Dir.glob(vectors_dir.join(category, "*.{yml,yaml,json,sexp}")).sort.flat_map do |path|
+        case File.extname(path)
+        when ".sexp" then Sexp.load(File.read(path))      # tapes (bin already resolved)
+        when ".json" then resolve(JSON.parse(File.read(path)))
+        else resolve(YAML.safe_load_file(path))
+        end
+      end
+    end
+
+    # Recursively resolve { "$bin" => base64 } sentinels into binary strings.
+    def resolve(value)
+      case value
+      when Hash
+        if value.size == 1 && value.key?("$bin")
+          Base64.decode64(value.fetch("$bin")).b
+        else
+          value.transform_values { |v| resolve(v) }
+        end
+      when Array
+        value.map { |v| resolve(v) }
+      else
+        value
+      end
+    end
+
+    # "a1 74 ff" -> binary string
+    def hex_to_bytes(hex)
+      hex.split.map { |byte| Integer(byte, 16) }.pack("C*")
+    end
+
+    # A tiny S-expression reader + tape interpreter. The whole grammar:
+    #   list = "(" form* ")" ;  atom = token | "string" | :keyword | number | true|false|nil ; ; comment
+    # Data mapping (unambiguous by each list's shape):
+    #   (type :k v ...) FRAME -> {"t"=>type, k=>v}   (:k v ...) MAP -> {k=>v}
+    #   (a b c) LIST -> [a,b,c]                       (bin "b64") -> bytes
+    # A tape file is (tape NAME (ROLE ...config) <transcript>...). The transcript is
+    # flat and reads like a recording; #interpret groups it into the step shape the
+    # runners consume ({recv|do, emit:[...], reject} / {process, out:[...], exit, stdout}).
+    module Sexp
+      module_function
+
+      def load(text)
+        read_all(text).map { |form| interpret(form) }
+      end
+
+      def read_all(text)
+        toks = tokenize(text)
+        forms = []
+        forms << read_form(toks) until toks.empty?
+        forms
+      end
+
+      def tokenize(str)
+        toks = []
+        i = 0
+        n = str.length
+        while i < n
+          c = str[i]
+          if c == ";"
+            i += 1 while i < n && str[i] != "\n"
+          elsif c =~ /\s/
+            i += 1
+          elsif c == "(" || c == ")"
+            toks << c
+            i += 1
+          elsif c == '"'
+            j = i + 1
+            buf = +""
+            while j < n && str[j] != '"'
+              if str[j] == "\\"
+                buf << { "n" => "\n", "t" => "\t", "r" => "\r" }.fetch(str[j + 1], str[j + 1])
+                j += 2
+              else
+                buf << str[j]
+                j += 1
+              end
+            end
+            toks << [:str, buf]
+            i = j + 1
+          else
+            j = i
+            j += 1 while j < n && !"() \t\r\n;\"".include?(str[j])
+            toks << [:tok, str[i...j]]
+            i = j
+          end
+        end
+        toks
+      end
+
+      def read_form(toks)
+        t = toks.shift
+        if t == "("
+          list = []
+          list << read_form(toks) until toks.first == ")"
+          toks.shift
+          list
+        elsif t.is_a?(Array) && t[0] == :str
+          t[1]
+        else
+          atom(t[1])
+        end
+      end
+
+      def atom(text)
+        case text
+        when "true" then true
+        when "false" then false
+        when "nil" then nil
+        else
+          if text.start_with?(":") then text[1..].to_sym
+          elsif text.match?(/\A-?\d+\z/) then text.to_i
+          elsif text.match?(/\A-?\d+\.\d+\z/) then text.to_f
+          else text
+          end
+        end
+      end
+
+      def value(form)
+        return form unless form.is_a?(Array)
+        return [] if form.empty?
+
+        head = form[0]
+        if head.is_a?(Symbol)
+          to_map(form)
+        elsif head == "bin"
+          Base64.decode64(form[1]).b
+        elsif form[1..].any? { |e| e.is_a?(Symbol) }
+          { "t" => head }.merge(to_map(form[1..]))
+        else
+          form.map { |e| value(e) }
+        end
+      end
+
+      def to_map(pairs)
+        h = {}
+        pairs.each_slice(2) { |k, v| h[k.to_s] = value(v) }
+        h
+      end
+
+      def interpret(form)
+        _tape, name, config_form, *transcript = form
+        role = config_form[0]
+        config = to_map(config_form[1..])
+        steps = role == "client" ? group_client(transcript) : group_server(transcript)
+        { "name" => name, "role" => role, "config" => config, "tape" => steps }
+      end
+
+      def group_server(forms)
+        steps = []
+        forms.each do |f|
+          case f[0]
+          when "recv" then steps << { "recv" => value(f[1]), "emit" => [] }
+          when "do" then steps << { "do" => action(f[1]), "emit" => [] }
+          when "send" then steps.last["emit"] << { "send" => value(f[1]) }
+          when "event"
+            ev = { "event" => f[1].to_s }
+            ev["data"] = to_map(f[2..]) unless f[2..].empty?
+            steps.last["emit"] << ev
+          when "reject" then steps.last["reject"] = true
+          end
+        end
+        steps
+      end
+
+      def group_client(forms)
+        steps = []
+        forms.each do |f|
+          case f[0]
+          when "process" then steps << { "process" => value(f[1]), "out" => [] }
+          when "out" then steps.last["out"] << value(f[1])
+          when "exit" then steps.last["exit"] = f[1]
+          when "stdout" then steps.last["stdout"] = f[1]
+          end
+        end
+        steps
+      end
+
+      def action(form)
+        head = form[0]
+        rest = form[1..]
+        if rest.length == 1 && !rest[0].is_a?(Symbol) && !rest[0].is_a?(Array)
+          { head => rest[0] }
+        else
+          { head => to_map(rest) }
+        end
+      end
+    end
+  end
+end

data/lib/terminalwire/v2/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Terminalwire::V2
+  class Error < StandardError; end
+
+  # Raised into the CLI thread to deliver a client Ctrl-C, like a local SIGINT —
+  # but NOT a SignalException (Ruby's Interrupt). Raising the real Interrupt into a
+  # thread inside a Falcon worker disturbs the async reactor and kills the
+  # connection; a plain Exception subclass interrupts blocking calls without that.
+  # Subclasses Exception (not StandardError) so user CLI code's `rescue
+  # StandardError` can't swallow it — only the Handler catches it -> exit 130.
+  class Interrupted < Exception; end
+
+  # Raised when bytes off the wire are not a well-formed frame.
+  class ProtocolError < Error; end
+
+  # Raised on the server side when a `response` came back with ok: false.
+  class ResponseError < Error
+    attr_reader :code
+
+    def initialize(code, message)
+      @code = code
+      super("#{code}: #{message}")
+    end
+  end
+end

data/lib/terminalwire/v2/frames.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Terminalwire::V2
+  # Builders for each frame type. Keep frame construction in one place so the wire
+  # shape is defined once. All builders return a Hash with string keys.
+  module Frames
+    module_function
+
+    def hello(protocol:, capabilities:, program:, entitlement:, terminal: DEFAULT_TERMINAL, flow: DEFAULT_FLOW)
+      {
+        "t" => Protocol::Type::HELLO, "sid" => Protocol::CONTROL_SID,
+        "protocol" => protocol, "capabilities" => capabilities,
+        "program" => program, "entitlement" => entitlement,
+        "terminal" => terminal, "flow" => flow
+      }
+    end
+
+    # The client's initial flow-control offer: how many bytes of output it will
+    # accept per stream before the server must wait for a window_adjust.
+    DEFAULT_FLOW = { "window" => Protocol::DEFAULT_WINDOW }.freeze
+
+    # Client -> server: extend the output window for a stream by `bytes`.
+    def window_adjust(sid:, bytes:)
+      { "t" => Protocol::Type::WINDOW_ADJUST, "sid" => sid, "bytes" => bytes }
+    end
+
+    # The client's terminal at connect time (structured per TERMINAL.md: per-stream
+    # kinds + a device block); resize/mode frames update the device thereafter.
+    DEFAULT_TERMINAL = {
+      "stdin" => { "kind" => "tty" },
+      "stdout" => { "kind" => "tty" },
+      "stderr" => { "kind" => "tty" },
+      "device" => {
+        "cols" => 80, "rows" => 24, "xpixels" => 0, "ypixels" => 0,
+        "term" => "", "color" => "none", "encoding" => "UTF-8", "mode" => "cooked"
+      }
+    }.freeze
+
+    # Generic async terminal signal (client -> server). resize/interrupt are the
+    # named variants; collapsing them into one frame type keeps the protocol small.
+    def signal(name, payload = {})
+      { "t" => Protocol::Type::SIGNAL, "sid" => Protocol::CONTROL_SID, "name" => name }.merge(payload)
+    end
+
+    def resize(cols:, rows:)
+      signal(Protocol::Signal::RESIZE, { "cols" => cols, "rows" => rows })
+    end
+
+    def interrupt
+      signal(Protocol::Signal::INTERRUPT)
+    end
+
+    def welcome(protocol:, capabilities:)
+      {
+        "t" => Protocol::Type::WELCOME, "sid" => Protocol::CONTROL_SID,
+        "protocol" => protocol, "capabilities" => capabilities
+      }
+    end
+
+    def incompatible(supported:, message:)
+      # Normalize to string keys so every wire frame is uniformly string-keyed
+      # (the negotiator hands us a symbol-keyed Ruby hash).
+      min = supported[:min] || supported["min"]
+      max = supported[:max] || supported["max"]
+      {
+        "t" => Protocol::Type::INCOMPATIBLE, "sid" => Protocol::CONTROL_SID,
+        "supported" => { "min" => min, "max" => max }, "message" => message
+      }
+    end
+
+    def exit(status:)
+      { "t" => Protocol::Type::EXIT, "sid" => Protocol::CONTROL_SID, "status" => status }
+    end
+
+    def open(sid:, stream:, mode: nil)
+      frame = { "t" => Protocol::Type::OPEN, "sid" => sid, "stream" => stream }
+      frame["mode"] = mode if mode # input streams carry the line-discipline mode
+      frame
+    end
+
+    def data(sid:, bytes:)
+      { "t" => Protocol::Type::DATA, "sid" => sid, "bytes" => bytes.b }
+    end
+
+    def close(sid:)
+      { "t" => Protocol::Type::CLOSE, "sid" => sid }
+    end
+
+    def request(sid:, resource:, method:, params: {})
+      {
+        "t" => Protocol::Type::REQUEST, "sid" => sid,
+        "resource" => resource, "method" => method, "params" => params
+      }
+    end
+
+    def response_ok(sid:, value:)
+      { "t" => Protocol::Type::RESPONSE, "sid" => sid, "ok" => true, "value" => value }
+    end
+
+    def response_error(sid:, code:, message:)
+      {
+        "t" => Protocol::Type::RESPONSE, "sid" => sid, "ok" => false,
+        "error" => { "code" => code, "message" => message }
+      }
+    end
+  end
+end

data/lib/terminalwire/v2/mux.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Terminalwire::V2
+  # Allocates stream ids and correlates in-flight requests to their responses.
+  # The starting id is injectable so recorded vectors replay deterministically.
+  class Mux
+    def initialize(start: 1)
+      raise ArgumentError, "start must be >= 1 (0 is the control stream)" if start < 1
+
+      @next = start
+      @pending = {}
+      # The runtime allocates/registers from the caller thread while the read
+      # pump resolves from its own thread, so the registry is mutex-guarded.
+      @mutex = Mutex.new
+    end
+
+    # Allocate a fresh stream id.
+    def allocate
+      @mutex.synchronize do
+        sid = @next
+        @next += 1
+        sid
+      end
+    end
+
+    # Mark a request stream as awaiting a response, stashing caller context.
+    def register(sid, context = nil)
+      @mutex.synchronize { @pending[sid] = context }
+    end
+
+    def pending?(sid)
+      @mutex.synchronize { @pending.key?(sid) }
+    end
+
+    # Resolve a pending request, returning (and removing) its context.
+    def resolve(sid)
+      @mutex.synchronize do
+        raise ProtocolError, "response for unknown stream #{sid}" unless @pending.key?(sid)
+
+        @pending.delete(sid)
+      end
+    end
+
+    def pending_count
+      @mutex.synchronize { @pending.size }
+    end
+  end
+end

data/lib/terminalwire/v2/negotiator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Terminalwire::V2
+  # Pure handshake negotiation: given what the client speaks and what the server
+  # supports, decide the agreed protocol version and capability set. This is a
+  # function, not a state machine, so it is trivially testable and identical
+  # across languages (see conformance/vectors/negotiate).
+  module Negotiator
+    module_function
+
+    # @return [Hash] either
+    #   { decision: "welcome", protocol: Integer, capabilities: Array<String> }
+    #   or
+    #   { decision: "incompatible", supported: { min:, max: } }
+    def negotiate(client_protocol:, client_capabilities:, server_min:, server_max:, server_capabilities:)
+      if client_protocol < server_min
+        return {
+          decision: "incompatible",
+          supported: { min: server_min, max: server_max }
+        }
+      end
+
+      agreed = [client_protocol, server_max].min
+      # Intersection, preserving the client's advertised order.
+      capabilities = client_capabilities & server_capabilities
+
+      { decision: "welcome", protocol: agreed, capabilities: capabilities }
+    end
+  end
+end

data/lib/terminalwire/v2/protocol.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Terminalwire::V2
+  # Wire-level constants for the v2 protocol. See ../../PROTOCOL.md.
+  module Protocol
+    # Frame protocol version this implementation speaks.
+    VERSION = 2
+
+    # Range of protocol versions this implementation can negotiate.
+    MIN_VERSION = 2
+    MAX_VERSION = 2
+
+    # The reserved control stream id.
+    CONTROL_SID = 0
+
+    # Capabilities advertised by a fully-featured client/server. Negotiation
+    # intersects the two sides' sets, so a peer only uses a feature the other
+    # advertises. ADD a capability here when you add an optional feature; that is
+    # the additive-change path (old peers simply won't list it, and the feature
+    # stays dormant for them).
+    #
+    # NOTE: negotiation records the intersection, but the server does NOT currently
+    # refuse a request() for a capability the client didn't advertise — Context
+    # issues file/directory/browser/env/terminal-query requests regardless, and the
+    # CLIENT is the enforcement point (it rejects an un-granted or un-negotiated op).
+    # Don't rely on this list as a server-side gate; it isn't one yet.
+    CAPABILITIES = %w[
+      stdio file directory browser env
+      signal flow raw-input terminal-query
+    ].freeze
+
+    # Output stream names (open.stream).
+    module Stream
+      STDOUT    = "stdout"
+      STDERR    = "stderr"
+      STDIN_RAW = "stdin-raw"
+    end
+
+    # Terminal line-discipline modes the client applies to its real terminal while
+    # a raw input stream / secret read is open (see ../../TERMINAL.md §5).
+    module Mode
+      COOKED = "cooked" # line editing + echo + signal keys (default)
+      NOECHO = "noecho" # cooked, echo off (passwords)
+      CBREAK = "cbreak" # char-at-a-time, echo ON, signal keys ON (single-key y/n)
+      RAW    = "raw"    # char-at-a-time, echo off, signals delivered as bytes (TUIs)
+    end
+
+    # Frame types.
+    module Type
+      HELLO        = "hello"
+      WELCOME      = "welcome"
+      INCOMPATIBLE = "incompatible"
+      EXIT         = "exit"
+      OPEN         = "open"
+      DATA         = "data"
+      CLOSE        = "close"
+      REQUEST       = "request"
+      RESPONSE      = "response"
+      SIGNAL        = "signal"
+      WINDOW_ADJUST = "window_adjust"
+    end
+
+    # Names carried by a `signal` frame (client -> server, async terminal events).
+    module Signal
+      RESIZE    = "resize"
+      INTERRUPT = "interrupt"
+    end
+
+    # Default initial per-output-stream flow-control window (bytes) the client
+    # grants the server. Must be >= the server's output chunk size so a single
+    # chunk can never exceed an empty window and deadlock.
+    DEFAULT_WINDOW = 256 * 1024
+
+    # Hard ceiling on a flow window (bytes). A window can never grow past this no
+    # matter what a peer offers or grants — the credit ledger clamps to it (see
+    # Window). This bounds how much output a server may buffer ahead of a slow or
+    # hostile client: without it, a client could offer/grant an enormous window and
+    # dissolve backpressure entirely, ballooning the server's transport buffers. 64×
+    # the default offer — ample for any terminal stream, far below a memory hazard.
+    MAX_WINDOW = 16 * 1024 * 1024
+
+    # Error codes carried on a `response` with ok: false.
+    module ErrorCode
+      DENIED    = "denied"
+      NOT_FOUND = "not_found"
+      IO        = "io"
+      PROTOCOL  = "protocol"
+      INTERNAL  = "internal"
+    end
+  end
+end