protocol-htty 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c222bcf565b63477735114b057e88c45508674629d78646c0fa73ab34b1abbd9
-  data.tar.gz: fd7405a11f04ee961c218473951ef8f0051dde6f0c581c2ecc129a87f9fbfe37
+  metadata.gz: 87a3aa4c350c134deb40265ae418e15fbd1158b70a8cf4c21e1748de514ca867
+  data.tar.gz: 506e9101a8df67e75aed817e3227919e06dc00ee5aa8d58d62c6d7139ae8d1ea
 SHA512:
-  metadata.gz: 0cf629cde9cb0d76603be89e9290335087a540c92be10e0f433732e6f323306ec8ddd7ba5cbe104ea0b7ef9ac57983bd3b0017005742c4065af1ecceebeca34d
-  data.tar.gz: db74e7230fdd22dbc18f1f4e85526856d3ebdd9eb550c1f7c3fdd6c3e84fcfc45d9ccb97559f813c9985d39d693e0ba2ef21d28a337086f94f76367c8de6dbfc
+  metadata.gz: 82d2c3b0fbbd56482711a10da4dad9e0e86177168d1cbc198d126e1d0c347e27dd3123e5d3982f9884e7bc2ee8b8f1be429164f06f16d5c3dde65ff5424750e3
+  data.tar.gz: cb61305b1df49d733cc5b4e0755d2d8962813eafc1e3fb2137122014643b7b7a90bfd44e2490edd428eb32b8bb9a7e31745bfeaa8b8b847ea1ad39d5c2f8aa25

data/lib/protocol/htty/stream.rb

@@ -7,86 +7,125 @@ require "io/stream"
 
 module Protocol
 	module HTTY
-		# Transport an opaque byte stream over HTTY chunks.
+		# Transport an opaque byte stream after the HTTY bootstrap handshake.
 		class Stream
-			# Since base64 encoding adds 33% overhead, we can fit 3KB of binary data into a single HTTY chunk without exceeding the typical MTU of 4KB:
-			PACKET_SIZE = 1024*3
-			
-			# Create a stream on top of HTTY framed input and output.
-			# @parameter input [IO | IO::Stream] The source of framed HTTY chunks.
-			# @parameter output [IO | IO::Stream | Nil] The sink for framed HTTY chunks.
-			# @parameter packet_size [Integer] The maximum payload size for each chunk.
-			def initialize(input, output = input, packet_size: PACKET_SIZE)
-				@framer = Framer.new(::IO::Stream(input), ::IO::Stream(output))
-				@packet_size = packet_size
-				@buffer = +"".b
+			ESC = "\e"
+			DCS = "#{ESC}P"
+			ST = "#{ESC}\\"
+			BOOTSTRAP_PREFIX = "+H"
+			RAW_MODE = "raw"
+			
+			HTTP2_FRAME_HEADER_SIZE = 9
+			
+			def self.open(input, output, bootstrap: nil, mode: RAW_MODE)
+				stream = self.new(input, output)
+				
+				case bootstrap
+				when :write
+					stream.write_bootstrap(mode)
+				when :read
+					actual_mode = stream.read_bootstrap
+					
+					unless actual_mode == mode
+						raise ProtocolError, "Expected HTTY bootstrap mode #{mode.inspect}, got #{actual_mode.inspect}"
+					end
+				end
+				
+				return stream
+			end
+			
+			# Create a stream on top of raw byte-preserving endpoints.
+			# @parameter input [IO] The readable endpoint.
+			# @parameter output [IO] The writable endpoint.
+			def initialize(input, output)
+				@input = input
+				@output = ::IO::Stream(output)
+				@frame_remaining = nil
 				@local_closed = false
-				@remote_closed = false
 			end
 			
-			attr :framer
+			attr :input
+			attr :output
 			
-			# Return the writable IO object used by the underlying framer.
-			# @returns [IO | IO::Stream] The output side of the framed transport.
+			# Return the underlying output stream.
 			def io
-				@framer.output
+				@output
+			end
+			
+			def write_bootstrap(mode = RAW_MODE)
+				@output.write("#{DCS}#{BOOTSTRAP_PREFIX}#{mode}#{ST}")
+				@output.flush
+			end
+			
+			def read_bootstrap
+				while payload = read_payload
+					next unless payload.start_with?(BOOTSTRAP_PREFIX)
+					mode = payload.delete_prefix(BOOTSTRAP_PREFIX)
+					
+					unless mode == RAW_MODE
+						raise ProtocolError, "Unsupported HTTY bootstrap mode: #{mode.inspect}"
+					end
+					
+					return mode
+				end
+				
+				return nil
 			end
 			
 			# Read application bytes from the HTTY transport.
-			# @parameter length [Integer | Nil] The exact number of bytes to read, or `nil` for all buffered bytes.
-			# @returns [String | Nil] The requested bytes, an empty binary string for `0`, or `nil` if more data is required or the remote side is closed.
 			def read(length = nil)
-				return +"".b if length == 0
-				
-				fill(length)
+				if length == 0
+					@frame_remaining = nil if @frame_remaining == 0
+					return +"".b
+				end
 				
-				return nil if @buffer.empty? && @remote_closed
-				return nil if @buffer.empty?
-				return nil if length && @buffer.bytesize < length && !@remote_closed
+				requested_length = length
+				length = [length, @frame_remaining].min if length && @frame_remaining && @frame_remaining > 0
+				buffer = read_exact(length)
 				
-				if length
-					return @buffer.slice!(0, length)
-				else
-					return @buffer.slice!(0, @buffer.bytesize)
+				if buffer && requested_length == HTTP2_FRAME_HEADER_SIZE && !@frame_remaining
+					if buffer.bytesize == HTTP2_FRAME_HEADER_SIZE
+						frame_length = self.class.frame_length(buffer)
+						@frame_remaining = frame_length if frame_length > 0
+					end
+				elsif buffer && @frame_remaining
+					@frame_remaining -= buffer.bytesize
+					@frame_remaining = nil if @frame_remaining <= 0
 				end
+				
+				return buffer
 			end
 			
-			# Write application bytes as one or more HTTY chunks.
-			# @parameter data [String | Array(Integer)] The opaque bytes to send.
+			# Write application bytes after bootstrap.
 			# @returns [self]
 			# @raises [IOError] If the local side of the transport is closed.
-			def write(data)
+			def write(data, flush: false)
 				raise IOError, "HTTY stream is closed for writing!" if @local_closed
 				
-				data = data.to_s.b
-				
-				until data.empty?
-					chunk = data.byteslice(0, @packet_size)
-					@framer.write_chunk(chunk)
-					data = data.byteslice(chunk.bytesize..)
-				end
-				
-				@framer.flush
+				@output.write(data.to_s.b)
+				@output.flush if flush
 				
 				return self
 			end
 			
-			# Flush any buffered output through the underlying framer.
+			# Flush any buffered output through the underlying stream.
 			# @returns [void]
 			def flush
-				@framer.flush
+				@output.flush
 			end
 			
 			# Close the local write side of this stream abstraction.
 			# HTTY does not define a close packet, and closing this object does not close the underlying terminal IO.
 			# @returns [void]
-			def close
+			def close_write(error = nil)
 				unless @local_closed
 					@local_closed = true
-					@framer.flush
+					@output.flush
 				end
 			end
 			
+			alias close close_write
+			
 			# Check whether the local side of the transport is closed.
 			# @returns [bool] True if local writes have been closed.
 			def closed?
@@ -96,28 +135,72 @@ module Protocol
 			# Check whether the remote side may still provide more data.
 			# @returns [bool] True if the remote side has not sent or implied a close.
 			def readable?
-				!@remote_closed
+				!(@input.respond_to?(:closed?) && @input.closed?)
 			end
 			
 			private
 			
-			def fill(length)
-				while needs_more_data?(length)
-					chunk = @framer.read_chunk
+			def self.frame_length(buffer)
+				length_high, length_low = buffer.unpack("Cn")
+				return (length_high << 16) | length_low
+			end
+			
+			def read_exact(length)
+				return @input.read if length.nil?
+				
+				buffer = +"".b
+				
+				while buffer.bytesize < length
+					chunk = read_some(length - buffer.bytesize)
+					break unless chunk
 					
-					unless chunk
-						@remote_closed = true
-						break
-					end
-					@buffer << chunk
+					buffer << chunk.b
 				end
+				
+				return nil if buffer.empty?
+				return buffer
 			end
 			
-			def needs_more_data?(length)
-				return false if @remote_closed
-				return @buffer.empty? unless length
+			def read_some(length)
+				if @input.respond_to?(:readpartial)
+					@input.readpartial(length)
+				else
+					@input.read(length)
+				end
+			rescue EOFError, Errno::EIO
+				return nil
+			end
+			
+			def read_payload
+				while prefix = read_some(1)
+					next unless prefix == ESC
+					
+					marker = read_some(1)
+					return nil unless marker
+					next unless marker == "P"
+					
+					return consume_packet
+				end
+				
+				return nil
+			end
+			
+			def consume_packet
+				buffer = +""
+				
+				while chunk = read_some(1)
+					if chunk == ESC
+						terminator = read_some(1)
+						return buffer if terminator == "\\"
+						
+						buffer << chunk
+						buffer << terminator if terminator
+					else
+						buffer << chunk
+					end
+				end
 				
-				@buffer.bytesize < length
+				raise EOFError, "Incomplete HTTY chunk!"
 			end
 		end
 	end

data/lib/protocol/htty/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module HTTY
-		VERSION = "0.1.0"
+		VERSION = "0.3.0"
 	end
 end

data/lib/protocol/htty.rb

@@ -5,5 +5,4 @@
 
 require_relative "htty/version"
 require_relative "htty/error"
-require_relative "htty/framer"
 require_relative "htty/stream"

data/readme.md

@@ -1,6 +1,6 @@
 # Protocol::HTTY
 
-`protocol-htty` defines a small, terminal-safe framing layer for carrying an opaque byte stream over TTY side channels.
+`protocol-htty` defines a small, terminal-safe bootstrap for carrying a raw HTTP/2 byte stream over terminal-attached sessions.
 
 [![Development Status](https://github.com/socketry/protocol-htty/workflows/Test/badge.svg)](https://github.com/socketry/protocol-htty/actions?workflow=Test)
 
@@ -10,34 +10,46 @@ Traditional terminal user interfaces are useful, but they are also a poor fit fo
 
 In practice, this means TUIs often force applications into compromises: text-heavy layouts, ad-hoc protocols, and bespoke escape-sequence behavior that is hard to standardise across runtimes and terminals.
 
-HTTY exists to keep the portability and deployment advantages of terminal workflows while avoiding the need to build an entire application model out of terminal control codes. Instead of asking the terminal stream itself to represent higher-level UI state, HTTY provides a small framing layer that can carry a normal plaintext HTTP/2 connection alongside terminal traffic, enabling applications to attach browser surfaces to a normal terminal session over HTTY.
+HTTY exists to keep the portability and deployment advantages of terminal workflows while avoiding the need to build an entire application model out of terminal control codes. Instead of asking the terminal stream itself to represent higher-level UI state, HTTY provides a small bootstrap that can hand a terminal session over to a normal plaintext HTTP/2 connection, enabling applications to attach browser surfaces to a normal terminal session over HTTY.
 
 ## Design
 
-HTTY does not model application requests, regions, or resources. It transports the two directions of a single plaintext HTTP/2 (`h2c`) connection over terminal-safe chunks without introducing a second session protocol.
+HTTY does not model application requests, regions, or resources. It transports the two directions of a single plaintext HTTP/2 (`h2c`) connection over a raw terminal-attached byte stream without introducing a second session protocol.
 
-Each chunk is encoded as a DCS sequence:
+HTTY v1 begins with one DCS bootstrap sequence:
 
 ``` text
-ESC P HTTY;1;BASE64_CHUNK ESC \
+ESC P + H raw ESC \
 ```
 
-The framing layer intentionally stays small so it can be reimplemented in other runtimes.
+After that bootstrap has been consumed, the session carries plain `h2c` bytes. The takeover layer intentionally stays small so it can be reimplemented in other runtimes.
 
 ## Usage
 
 Please see the [project documentation](https://socketry.github.io/protocol-htty/) for more details.
 
-  - [Getting Started](https://socketry.github.io/protocol-htty/guides/getting-started/index) - This guide explains how to get started with `protocol-htty` for terminal-safe HTTP/2 byte stream transport.
+  - [Getting Started](https://socketry.github.io/protocol-htty/guides/getting-started/index) - This guide explains how to get started with `protocol-htty` for DCS-bootstrapped raw HTTP/2 byte stream transport.
 
-  - [HTTY Specification](https://socketry.github.io/protocol-htty/guides/specification/index) - This document specifies HTTY as a terminal-safe framing layer for carrying a plaintext HTTP/2 (`h2c`) byte stream over terminal side channels.
+  - [HTTY Specification](https://socketry.github.io/protocol-htty/guides/specification/index) - This document specifies HTTY as a DCS-bootstrapped raw-mode takeover transport for carrying a plaintext HTTP/2 (`h2c`) connection over terminal-attached sessions.
 
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/protocol-htty/releases/index) for all releases.
 
+### v0.3.0
+
+  - Change `Protocol::HTTY::Stream` to take explicit input and output endpoints using `Stream.new(input, output)` and `Stream.open(input, output, **options)`.
+  - Read HTTY input without buffering ahead, preserving HTTP/2 frame boundaries by reading only the announced frame payload length.
+
+### v0.2.0
+
+  - Add `Protocol::HTTY::Stream.open(stream, **options)` as the preferred constructor for bootstrapping HTTY over an existing stream.
+  - Inline HTTY bootstrap encoding and decoding into `Protocol::HTTY::Stream`, keeping the public API focused on the single raw byte-stream abstraction used by HTTP/2.
+
 ### v0.1.0
 
+  - Initial release.
+
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,3 +1,15 @@
 # Releases
 
+## v0.3.0
+
+  - Change `Protocol::HTTY::Stream` to take explicit input and output endpoints using `Stream.new(input, output)` and `Stream.open(input, output, **options)`.
+  - Read HTTY input without buffering ahead, preserving HTTP/2 frame boundaries by reading only the announced frame payload length.
+
+## v0.2.0
+
+  - Add `Protocol::HTTY::Stream.open(stream, **options)` as the preferred constructor for bootstrapping HTTY over an existing stream.
+  - Inline HTTY bootstrap encoding and decoding into `Protocol::HTTY::Stream`, keeping the public API focused on the single raw byte-stream abstraction used by HTTP/2.
+
 ## v0.1.0
+
+  - Initial release.

data/test/protocol/htty/bootstrap.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "stringio"
+require "protocol/htty"
+
+class OneByteInput
+	def initialize(data)
+		@data = data.b
+		@offset = 0
+	end
+	
+	def read(length = nil)
+		return nil if @offset >= @data.bytesize
+		
+		length = [length || @data.bytesize, 1].min
+		chunk = @data.byteslice(@offset, length)
+		@offset += chunk.bytesize
+		
+		return chunk
+	end
+end
+
+describe Protocol::HTTY::Stream do
+	let(:input) {StringIO.new}
+	let(:output) {StringIO.new}
+	let(:stream) {subject.new(input, output)}
+	
+	it "writes the HTTY raw bootstrap" do
+		stream.write_bootstrap
+		
+		expect(output.string).to be == "\eP+Hraw\e\\"
+	end
+	
+	it "reads the HTTY raw bootstrap" do
+		input.string = "hello\eP+Hraw\e\\world"
+		input.rewind
+		
+		mode = stream.read_bootstrap
+		
+		expect(mode).to be == "raw"
+	end
+	
+	it "reads a bootstrap split across one-byte reads" do
+		stream = subject.new(OneByteInput.new("hello\eP+Hraw\e\\"), StringIO.new)
+		
+		expect(stream.read_bootstrap).to be == "raw"
+	end
+	
+	it "preserves bytes after the HTTY bootstrap" do
+		input.string = "\eP+Hraw\e\\world"
+		input.rewind
+		
+		stream.read_bootstrap
+		
+		expect(stream.read(5)).to be == "world"
+	end
+	
+	it "raises on unsupported bootstrap modes" do
+		input.string = "\eP+Hframed\e\\"
+		input.rewind
+		
+		expect do
+			stream.read_bootstrap
+		end.to raise_exception(Protocol::HTTY::ProtocolError)
+	end
+	
+	it "raises on incomplete bootstraps" do
+		input.string = "\eP+Hraw"
+		input.rewind
+		
+		expect do
+			stream.read_bootstrap
+		end.to raise_exception(EOFError)
+	end
+	
+	it "ignores unrelated DCS payloads before the bootstrap" do
+		input.string = "\ePfoo\e\\\eP+Hraw\e\\"
+		input.rewind
+		
+		expect(stream.read_bootstrap).to be == "raw"
+	end
+	
+	it "ignores implementation-specific reset markers before the bootstrap" do
+		input.string = "\eP+reset:token\e\\\eP+Hraw\e\\"
+		input.rewind
+		
+		expect(stream.read_bootstrap).to be == "raw"
+	end
+end

data/test/protocol/htty/pty.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "open3"
+require "pty"
+require "rbconfig"
+require "timeout"
+require "protocol/http2"
+require "protocol/http2/client"
+require "protocol/http2/stream"
+require "protocol/htty"
+require "protocol/htty/fixtures"
+
+class PTYStream
+	def initialize(input, output)
+		@input = input
+		@output = output
+		@buffer = +"".b
+	end
+	
+	attr :input
+	attr :output
+	
+	def read(length)
+		while @buffer.bytesize < length
+			@buffer << @input.readpartial(4096).b
+		end
+		
+		data = @buffer.byteslice(0, length)
+		@buffer = @buffer.byteslice(length, @buffer.bytesize) || +"".b
+		
+		return data
+	rescue EOFError, Errno::EIO
+		raise EOFError, "PTY closed"
+	end
+	
+	def write(data)
+		@output.write(data)
+	end
+	
+	def flush
+		@output.flush
+	end
+	
+	def close
+		@input.close rescue nil
+		@output.close rescue nil
+	end
+	
+	def closed?
+		@input.closed?
+	end
+end
+
+class ResponseStream < Protocol::HTTP2::Stream
+	attr :response_headers
+	attr :body
+	
+	def initialize(...)
+		super
+		@response_headers = []
+		@body = +"".b
+	end
+	
+	def process_headers(frame)
+		@response_headers = super
+	end
+	
+	def process_data(frame)
+		data = super
+		@body << data.b if data
+		return data
+	end
+end
+
+class Client < Protocol::HTTP2::Client
+	def create_stream(id = next_stream_id)
+		ResponseStream.create(self, id)
+	end
+end
+
+describe "HTTY over a real PTY" do
+	let(:root) {File.expand_path("../../..", __dir__)}
+	let(:ruby_load_path) {File.join(root, "lib")}
+	
+	def spawn_fixture(name)
+		environment = {"RUBYLIB" => ruby_load_path}
+		
+		PTY.spawn(environment, RbConfig.ruby, Protocol::HTTY::Fixtures.executable_path(name))
+	end
+	
+	def with_fixture(name)
+		input, output, pid = spawn_fixture(name)
+		input.binmode
+		output.binmode
+		
+		stream = PTYStream.new(input, output)
+		
+		yield stream
+	ensure
+		stream&.close
+		Process.wait(pid) rescue nil
+	end
+	
+	it "ignores terminal noise before the bootstrap" do
+		Timeout.timeout(5) do
+			with_fixture("bootstrap") do |stream|
+				framer = Protocol::HTTY::Stream.new(stream.input, stream.output)
+				
+				expect(framer.read_bootstrap).to be == "raw"
+				expect(stream.read(3)).to be == "RAW"
+			end
+		end
+	end
+	
+	it "delivers the HTTP/2 connection preface after raw takeover" do
+		Timeout.timeout(5) do
+			with_fixture("raw_preface") do |stream|
+				framer = Protocol::HTTY::Stream.new(stream.input, stream.output)
+				
+				expect(framer.read_bootstrap).to be == "raw"
+				
+				stream.write(Protocol::HTTP2::CONNECTION_PREFACE)
+				stream.flush
+				
+				expect(stream.read(10)).to be == "PREFACE_OK"
+			end
+		end
+	end
+	
+	it "runs an HTTP/2 session until command-side GOAWAY" do
+		Timeout.timeout(5) do
+			with_fixture("http2_server") do |stream|
+				stream = Protocol::HTTY::Stream.new(stream.input, stream.output)
+				stream.read_bootstrap
+				
+				framer = Protocol::HTTP2::Framer.new(stream)
+				client = Client.new(framer)
+				client.send_connection_preface
+				
+				request = client.create_stream
+				request.send_headers(
+					[[":method", "GET"], [":path", "/"], [":scheme", "http"], [":authority", "htty.local"]],
+					Protocol::HTTP2::END_STREAM
+				)
+				
+				goaway = false
+				
+				until goaway
+					begin
+						frame = client.read_frame
+						goaway = frame.is_a?(Protocol::HTTP2::GoawayFrame)
+					rescue Protocol::HTTP2::GoawayError
+						goaway = true
+					end
+				end
+				
+				expect(request.response_headers.to_h[":status"]).to be == "200"
+				expect(request.body).to be == "OK\n"
+			end
+		end
+	end
+	
+	it "treats command exit after bootstrap without GOAWAY as an abort" do
+		Timeout.timeout(5) do
+			with_fixture("abort_after_bootstrap") do |stream|
+				stream = Protocol::HTTY::Stream.new(stream.input, stream.output)
+				expect(stream.read_bootstrap).to be == "raw"
+				
+				framer = Protocol::HTTP2::Framer.new(stream)
+				
+				expect do
+					framer.read_frame
+				end.to raise_exception(EOFError)
+			end
+		end
+	end
+	
+	it "recovers the surrounding shell after an aborted session" do
+		client = File.join(root, "examples/pty/client.rb")
+		
+		output, error, status = Timeout.timeout(10) do
+			Open3.capture3(
+				{"HTTY_SHELL" => "bash", "HTTY_FAIL_ON" => "5"},
+				RbConfig.ruby,
+				client,
+				chdir: root
+			)
+		end
+		
+		combined_output = "#{output}#{error}"
+		
+		expect(status).to be(:success?)
+		expect(combined_output).to be(:include?, "[htty] session 5 failed")
+		expect(combined_output).to be(:include?, "[htty] bootstrap detected \u2013 session 6")
+		expect(combined_output).to be(:include?, "session 10 \u2013 status: 200")
+	end
+end

data/test/protocol/htty/stream.rb

@@ -10,41 +10,49 @@ require "protocol/htty"
 
 describe Protocol::HTTY::Stream do
 	let(:writer) {StringIO.new}
-	let(:stream) {subject.new(StringIO.new, writer, packet_size: 8)}
+	let(:stream) {subject.open(StringIO.new, writer)}
 	
-	it "chunks opaque payload into HTTY chunks" do
+	it "writes raw bytes after bootstrap" do
+		stream.write_bootstrap
 		stream.write(Protocol::HTTP2::CONNECTION_PREFACE)
+		stream.flush
 		
-		expect(writer.string.scan(/\ePHTTY;1;/).size).to be > 1
+		expect(writer.string).to be == "\eP+Hraw\e\\#{Protocol::HTTP2::CONNECTION_PREFACE}"
 	end
 	
-	it "reads back opaque bytes from HTTY chunks" do
-		stream.write(Protocol::HTTP2::CONNECTION_PREFACE)
+	it "consumes the bootstrap before reading raw bytes" do
+		writer.write("\eP+Hraw\e\\#{Protocol::HTTP2::CONNECTION_PREFACE}")
 		writer.rewind
-		
-		reader = subject.new(writer, StringIO.new)
+
+		reader = subject.open(writer, StringIO.new, bootstrap: :read)
 		
 		expect(reader.read(Protocol::HTTP2::CONNECTION_PREFACE.bytesize)).to be == Protocol::HTTP2::CONNECTION_PREFACE
-		reader.close
-		expect(reader.read).to be_nil
+		expect(reader.read).to be == ""
 	end
 	
-	it "returns all buffered bytes when length is omitted" do
-		stream.write("hello")
+	it "writes the bootstrap when opened in write mode" do
+		writer = StringIO.new
+		stream = subject.open(StringIO.new, writer, bootstrap: :write)
+		
+		expect(writer.string).to be == "\eP+Hraw\e\\"
 		stream.close
+	end
+	
+	it "returns all bytes when length is omitted" do
+		writer.write("hello")
 		writer.rewind
 		
-		reader = subject.new(writer, StringIO.new)
+		reader = subject.open(writer, StringIO.new)
 		
 		expect(reader.read).to be == "hello"
-		expect(reader.read).to be_nil
+		expect(reader.read).to be == ""
 	end
 	
 	it "exposes the underlying output stream" do
 		expect(stream.io).to be(:is_a?, ::IO::Stream::Buffered)
 	end
 	
-	it "flushes through the underlying framer" do
+	it "flushes through the underlying stream" do
 		stream.write("hello")
 		
 		expect do
@@ -65,11 +73,29 @@ describe Protocol::HTTY::Stream do
 		
 		expect(writer).not.to be(:closed?)
 	end
+
+	it "close_write closes writes but preserves readability" do
+		stream.close_write
+
+		expect(stream).to be(:closed?)
+		expect(stream).to be(:readable?)
+		expect(writer).not.to be(:closed?)
+	end
 	
 	it "reports when the remote side is still readable" do
 		expect(stream).to be(:readable?)
 	end
 	
+	it "reads HTTP/2 frame headers and payloads without reading ahead" do
+		header = [0, 5, 0, 0, 1].pack("CnCCN")
+		input = StringIO.new("#{header}helloextra")
+		reader = subject.open(input, StringIO.new)
+		
+		expect(reader.read(9)).to be == header
+		expect(reader.read(16)).to be == "hello"
+		expect(reader.read(5)).to be == "extra"
+	end
+	
 	it "rejects writes after the local side is closed" do
 		stream.close
 		
@@ -80,7 +106,7 @@ describe Protocol::HTTY::Stream do
 	
 	it "wraps raw IO handles using IO::Stream" do
 		Tempfile.create("protocol-htty") do |file|
-			io_stream = subject.new(file, file).io
+			io_stream = subject.open(file, file).io
 			
 			expect(io_stream).to be(:is_a?, ::IO::Stream::Buffered)
 			io_stream.close
@@ -89,7 +115,7 @@ describe Protocol::HTTY::Stream do
 	
 	it "does not close wrapped raw IO handles when closed" do
 		Tempfile.create("protocol-htty") do |file|
-			wrapped_stream = subject.new(file, file)
+			wrapped_stream = subject.open(file, file)
 			
 			wrapped_stream.close
 			

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-htty
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -38,20 +38,6 @@ cert_chain:
   -----END CERTIFICATE-----
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: base64
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: protocol-http2
   requirement: !ruby/object:Gem::Requirement
@@ -72,28 +58,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.13.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.13.0
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - lib/protocol/htty.rb
 - lib/protocol/htty/error.rb
-- lib/protocol/htty/framer.rb
 - lib/protocol/htty/stream.rb
 - lib/protocol/htty/version.rb
 - license.md
 - readme.md
 - releases.md
 - test/protocol/htty.rb
-- test/protocol/htty/framer.rb
+- test/protocol/htty/bootstrap.rb
+- test/protocol/htty/pty.rb
 - test/protocol/htty/stream.rb
 homepage: https://github.com/socketry/protocol-htty
 licenses:

data/lib/protocol/htty/framer.rb

@@ -1,112 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2026, by Samuel Williams.
-
-require "base64"
-require "protocol/http2/framer"
-
-module Protocol
-	module HTTY
-		# Encode and decode HTTY chunks on top of byte-oriented IO objects.
-		class Framer
-			ESC = "\e"
-			DCS = "#{ESC}P"
-			ST = "#{ESC}\\"
-			PREFIX = "HTTY;1;"
-			
-			# Create a framer around the given input and output streams.
-			# @parameter input [Interface(:read)] The stream to read framed packets from.
-			# @parameter output [Interface(:write, :flush) | Nil] The stream to write framed packets to.
-			def initialize(input, output = input)
-				@input = input
-				@output = output
-			end
-			
-			attr :input
-			attr :output
-			
-			# Write a single HTTY chunk to the output stream.
-			# @parameter payload [String | Array(Integer)] The opaque bytes to encode.
-			# @returns [void]
-			def write_chunk(payload)
-				encoded = Base64.strict_encode64(payload.to_s.b)
-				@output.write("#{DCS}#{PREFIX}#{encoded}#{ST}")
-			end
-			
-			# Read the next HTTY chunk from the input stream.
-			# Non-HTTY terminal output is ignored until a valid chunk prefix is found.
-			# @returns [String | Nil] The decoded payload, or `nil` on end of stream.
-			# @raises [ProtocolError] If the chunk prefix or chunk structure is invalid.
-			# @raises [ArgumentError] If the packet payload is not valid base64.
-			# @raises [EOFError] If the chunk terminator is missing.
-			def read_chunk
-				while payload = read_payload
-					if payload.start_with?("HTTY;") && !payload.start_with?(PREFIX)
-						raise ProtocolError, "Unsupported HTTY chunk version: #{payload.inspect}"
-					end
-					
-					next unless payload.start_with?(PREFIX)
-					encoded = payload.delete_prefix(PREFIX)
-					return Base64.strict_decode64(encoded)
-				end
-				
-				return nil
-			end
-			
-			# Flush the output stream if it supports flushing.
-			# @returns [void]
-			def flush
-				@output.flush if @output.respond_to?(:flush)
-			end
-			
-			# Close the wrapped input and output streams.
-			# If input and output are the same object, it is only closed once.
-			# @returns [void]
-			def close
-				@output.close if @output.respond_to?(:close)
-				@input.close if !@input.equal?(@output) && @input.respond_to?(:close)
-			end
-			
-			# Check whether the output stream has been closed.
-			# @returns [bool] True if the output stream reports that it is closed.
-			def closed?
-				@output.respond_to?(:closed?) && @output.closed?
-			end
-			
-			private
-			
-			def read_payload
-				while prefix = @input.read(1)
-					next unless prefix == ESC
-					
-					marker = @input.read(1)
-					return nil unless marker
-					next unless marker == "P"
-					
-					return consume_packet
-				end
-				
-				return nil
-			end
-			
-			def consume_packet
-				buffer = +""
-				
-				while chunk = @input.read(1)
-					if chunk == ESC
-						terminator = @input.read(1)
-						return buffer if terminator == "\\"
-						
-						buffer << chunk
-						buffer << terminator if terminator
-					else
-						buffer << chunk
-					end
-				end
-				
-				raise EOFError, "Incomplete HTTY chunk!"
-			end
-		end
-	end
-end

data/test/protocol/htty/framer.rb

@@ -1,64 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2026, by Samuel Williams.
-
-require "stringio"
-require "protocol/http2/framer"
-require "protocol/htty"
-
-describe Protocol::HTTY::Framer do
-	let(:input) {StringIO.new}
-	let(:output) {StringIO.new}
-	let(:framer) {subject.new(input, output)}
-	
-	it "writes terminal-safe chunks" do
-		framer.write_chunk(Protocol::HTTP2::CONNECTION_PREFACE)
-		
-		expect(output.string).to be == "\ePHTTY;1;UFJJICogSFRUUC8yLjANCg0KU00NCg0K\e\\"
-	end
-	
-	it "reads terminal-safe chunks" do
-		input.string = "hello\ePHTTY;1;UFJJICogSFRUUC8yLjANCg0KU00NCg0K\e\\world"
-		input.rewind
-		
-		chunk = framer.read_chunk
-		
-		expect(chunk).to be == Protocol::HTTP2::CONNECTION_PREFACE
-	end
-	
-	it "raises on malformed chunks" do
-		input.string = "\ePHTTY;1\e\\"
-		input.rewind
-		
-		expect do
-			framer.read_chunk
-		end.to raise_exception(Protocol::HTTY::ProtocolError)
-	end
-	
-	it "raises on incomplete chunks" do
-		input.string = "\ePHTTY;1;QUJD"
-		input.rewind
-		
-		expect do
-			framer.read_chunk
-		end.to raise_exception(EOFError)
-	end
-	
-	it "closes distinct input and output streams" do
-		framer.close
-		
-		expect(input).to be(:closed?)
-		expect(output).to be(:closed?)
-		expect(framer).to be(:closed?)
-	end
-	
-	it "handles escaped bytes inside an invalid chunk payload" do
-		input.string = "\ePHTTY;1;QUJD\eXRA==\e\\"
-		input.rewind
-		
-		expect do
-			framer.read_chunk
-		end.to raise_exception(ArgumentError)
-	end
-end