100% documentation coverage.

Author: samuel-williams-shopify

gems.rb

@@ -14,6 +14,8 @@
 	gem "bake-modernize"
 	gem "bake-releases"
 
+	gem "agent-context"
+	
 	gem "utopia-project"
 end
 

lib/protocol/websocket/coder.rb

@@ -7,6 +7,7 @@
 
 module Protocol
 	module WebSocket
+		# @namespace
 		module Coder
 			# The default coder for WebSocket messages.
 			DEFAULT = JSON::DEFAULT

lib/protocol/websocket/coder/json.rb

@@ -10,6 +10,8 @@ module WebSocket
 		module Coder
 			# A JSON coder that uses the standard JSON library.
 			class JSON
+				# Initialize a new JSON coder.
+				# @parameter options [Hash] Options to pass to the JSON library when parsing or generating.
 				def initialize(**options)
 					@options = options
 				end

lib/protocol/websocket/error.rb

@@ -41,6 +41,9 @@ class Error < HTTP::Error
 
 		# Raised by stream or connection handlers, results in GOAWAY frame which signals termination of the current connection. You *cannot* recover from this exception, or any exceptions subclassed from it.
 		class ProtocolError < Error
+			# Initialize a protocol error with an optional status code.
+			# @parameter message [String] The error message.
+			# @parameter code [Integer] The WebSocket status code associated with the error.
 			def initialize(message, code = PROTOCOL_ERROR)
 				super(message)
 

lib/protocol/websocket/extension/compression.rb

@@ -9,6 +9,7 @@
 
 module Protocol
 	module WebSocket
+		# @namespace
 		module Extension
 			# Provides support for the permessage-deflate extension.
 			module Compression

lib/protocol/websocket/extension/compression/deflate.rb

@@ -9,6 +9,7 @@ module Protocol
 	module WebSocket
 		module Extension
 			module Compression
+				# Compresses outgoing WebSocket frames using the DEFLATE algorithm.
 				class Deflate
 					# Client writing to server.
 					def self.client(parent, client_max_window_bits: 15, client_no_context_takeover: false, **options)
@@ -28,6 +29,13 @@ def self.server(parent, server_max_window_bits: 15, server_no_context_takeover:
 						)
 					end
 
+					# Initialize a new deflate compressor.
+					# @parameter parent [Object] The parent framer to wrap.
+					# @parameter level [Integer] The compression level. Defaults to `Zlib::DEFAULT_COMPRESSION`.
+					# @parameter memory_level [Integer] The memory level for compression. Defaults to `Zlib::DEF_MEM_LEVEL`.
+					# @parameter strategy [Integer] The compression strategy. Defaults to `Zlib::DEFAULT_STRATEGY`.
+					# @parameter window_bits [Integer] The window size in bits for the DEFLATE algorithm.
+					# @parameter context_takeover [Boolean] Whether to reuse the compression context across messages.
 					def initialize(parent, level: Zlib::DEFAULT_COMPRESSION, memory_level: Zlib::DEF_MEM_LEVEL, strategy: Zlib::DEFAULT_STRATEGY, window_bits: 15, context_takeover: true, **options)
 						@parent = parent
 
@@ -46,13 +54,20 @@ def initialize(parent, level: Zlib::DEFAULT_COMPRESSION, memory_level: Zlib::DEF
 						@context_takeover = context_takeover
 					end
 
+					# @returns [String] A string representation including window bits and context takeover settings.
 					def to_s
 						"#<#{self.class} window_bits=#{@window_bits} context_takeover=#{@context_takeover}>"
 					end
 
+					# @attribute [Integer] The window size in bits used for compression.
 					attr :window_bits
+					# @attribute [Boolean] Whether the compression context is reused across messages.
 					attr :context_takeover
 
+					# Pack a text frame, optionally compressing the buffer.
+					# @parameter buffer [String] The text payload to pack.
+					# @parameter compress [Boolean] Whether to compress the buffer. Defaults to `true`.
+					# @returns [Frame] The packed (and optionally compressed) text frame.
 					def pack_text_frame(buffer, compress: true, **options)
 						if compress
 							buffer = self.deflate(buffer)
@@ -67,6 +82,10 @@ def pack_text_frame(buffer, compress: true, **options)
 						return frame
 					end
 
+					# Pack a binary frame, optionally compressing the buffer.
+					# @parameter buffer [String] The binary payload to pack.
+					# @parameter compress [Boolean] Whether to compress the buffer. Defaults to `false`.
+					# @returns [Frame] The packed (and optionally compressed) binary frame.
 					def pack_binary_frame(buffer, compress: false, **options)
 						if compress
 							buffer = self.deflate(buffer)

lib/protocol/websocket/extension/compression/inflate.rb

@@ -9,6 +9,7 @@ module Protocol
 	module WebSocket
 		module Extension
 			module Compression
+				# Decompresses incoming WebSocket frames using the DEFLATE algorithm.
 				class Inflate
 					# Client reading from server.
 					def self.client(parent, server_max_window_bits: 15, server_no_context_takeover: false, **options)
@@ -28,6 +29,10 @@ def self.server(parent, client_max_window_bits: 15, client_no_context_takeover:
 
 					TRAILER = [0x00, 0x00, 0xff, 0xff].pack("C*")
 
+					# Initialize a new inflate decompressor.
+					# @parameter parent [Object] The parent framer to wrap.
+					# @parameter context_takeover [Boolean] Whether to reuse the decompression context across messages.
+					# @parameter window_bits [Integer] The window size in bits for the DEFLATE algorithm.
 					def initialize(parent, context_takeover: true, window_bits: 15)
 						@parent = parent
 
@@ -42,13 +47,19 @@ def initialize(parent, context_takeover: true, window_bits: 15)
 						@context_takeover = context_takeover
 					end
 
+					# @returns [String] A string representation including window bits and context takeover settings.
 					def to_s
 						"#<#{self.class} window_bits=#{@window_bits} context_takeover=#{@context_takeover}>"
 					end
 
+					# @attribute [Integer] The window size in bits used for decompression.
 					attr :window_bits
+					# @attribute [Boolean] Whether the decompression context is reused across messages.
 					attr :context_takeover
 
+					# Unpack and decompress frames into a buffer.
+					# @parameter frames [Array(Frame)] The frames to unpack.
+					# @returns [String] The decompressed payload buffer.
 					def unpack_frames(frames, **options)
 						buffer = @parent.unpack_frames(frames, **options)
 

lib/protocol/websocket/extensions.rb

@@ -8,7 +8,13 @@
 
 module Protocol
 	module WebSocket
+		# Manages WebSocket extensions negotiated during the handshake.
 		module Extensions
+			# Parse a list of extension header values into name and argument pairs.
+			# @parameter headers [Array(String)] The raw extension header values.
+			# @yields {|name, arguments| ...} Each parsed extension.
+			# 	@parameter name [String] The name of the extension.
+			# 	@parameter arguments [Array] The key-value argument pairs.
 			def self.parse(headers)
 				return to_enum(:parse, headers) unless block_given?
 
@@ -23,27 +29,39 @@ def self.parse(headers)
 				end
 			end
 
+			# Manages extensions on the client side, offering and accepting server responses.
 			class Client
+				# Create a default client with permessage-deflate compression enabled.
+				# @returns [Client] A new client with the default compression extension.
 				def self.default
 					self.new([
 						[Extension::Compression, {}]
 					])
 				end
 
+				# Initialize a new client extension manager.
+				# @parameter extensions [Array] The list of extensions to offer, each as `[klass, options]`.
 				def initialize(extensions = [])
 					@extensions = extensions
 					@accepted = []
 				end
 
+				# @attribute [Array] The list of extensions to offer.
 				attr :extensions
+				# @attribute [Array] The extensions accepted after negotiation.
 				attr :accepted
 
+				# Build a lookup table of extensions keyed by their name.
+				# @returns [Hash] A hash mapping extension names to their `[klass, options]` pairs.
 				def named
 					@extensions.map do |extension|
 						[extension.first::NAME, extension]
 					end.to_h
 				end
 
+				# Yield extension offer headers for each registered extension.
+				# @yields {|header| ...} Each offer header string.
+				# 	@parameter header [Array(String)] The extension offer header tokens.
 				def offer
 					@extensions.each do |extension, options|
 						if header = extension.offer(**options)
@@ -52,6 +70,9 @@ def offer
 					end
 				end
 
+				# Accept server extension responses and record the negotiated extensions.
+				# @parameter headers [Array(String)] The `Sec-WebSocket-Extensions` response header values.
+				# @returns [Array] The accepted extensions as `[klass, options]` pairs.
 				def accept(headers)
 					named = self.named
 
@@ -69,34 +90,50 @@ def accept(headers)
 					return @accepted
 				end
 
+				# Apply all accepted extensions to the given connection as a client.
+				# @parameter connection [Connection] The WebSocket connection to configure.
 				def apply(connection)
 					@accepted.each do |(klass, options)|
 						klass.client(connection, **options)
 					end
 				end
 			end
 
+			# Manages extensions on the server side, negotiating client offers and applying the agreed extensions.
 			class Server
+				# Create a default server with permessage-deflate compression enabled.
+				# @returns [Server] A new server with the default compression extension.
 				def self.default
 					self.new([
 						[Extension::Compression, {}]
 					])
 				end
 
+				# Initialize a new server extension manager.
+				# @parameter extensions [Array] The list of supported extensions, each as `[klass, options]`.
 				def initialize(extensions)
 					@extensions = extensions
 					@accepted = []
 				end
 
+				# @attribute [Array] The list of supported extensions.
 				attr :extensions
+				# @attribute [Array] The extensions accepted after negotiation.
 				attr :accepted
 
+				# Build a lookup table of extensions keyed by their name.
+				# @returns [Hash] A hash mapping extension names to their `[klass, options]` pairs.
 				def named
 					@extensions.map do |extension|
 						[extension.first::NAME, extension]
 					end.to_h
 				end
 
+				# Negotiate client extension offers and yield accepted response headers.
+				# @parameter headers [Array(String)] The `Sec-WebSocket-Extensions` request header values.
+				# @yields {|header| ...} Each accepted extension header to include in the response.
+				# 	@parameter header [Array(String)] The negotiated extension header tokens.
+				# @returns [Array] The accepted extensions as `[klass, options]` pairs.
 				def accept(headers)
 					extensions = []
 
@@ -124,6 +161,8 @@ def accept(headers)
 					return @accepted
 				end
 
+				# Apply all accepted extensions to the given connection as a server.
+				# @parameter connection [Connection] The WebSocket connection to configure.
 				def apply(connection)
 					@accepted.reverse_each do |(klass, options)|
 						klass.server(connection, **options)

lib/protocol/websocket/frame.rb

@@ -10,6 +10,7 @@
 
 module Protocol
 	module WebSocket
+		# Represents a single WebSocket frame as defined by RFC 6455.
 		class Frame
 			include Comparable
 
@@ -35,18 +36,28 @@ def initialize(finished = true, payload = nil, flags: 0, opcode: self.class::OPC
 				@payload = payload
 			end
 
+			# Check whether the specified RSV flag bit is set on this frame.
+			# @parameter value [Integer] The flag bitmask to test (e.g. `RSV1`).
+			# @returns [Boolean] `true` if the flag bit is set.
 			def flag?(value)
 				@flags & value != 0
 			end
 
+			# Compare this frame to another frame by their array representation.
+			# @parameter other [Frame] The frame to compare against.
+			# @returns [Integer] A comparison result (-1, 0, or 1).
 			def <=> other
 				to_ary <=> other.to_ary
 			end
 
+			# Convert this frame to an array of its fields for comparison or inspection.
+			# @returns [Array] An array of `[finished, flags, opcode, mask, length, payload]`.
 			def to_ary
 				[@finished, @flags, @opcode, @mask, @length, @payload]
 			end
 
+			# Check whether this is a control frame (opcode has bit 3 set).
+			# @returns [Boolean] `true` if this is a control frame.
 			def control?
 				@opcode & 0x8 != 0
 			end
@@ -56,10 +67,14 @@ def data?
 				false
 			end
 
+			# Check whether this is the final frame in a message.
+			# @returns [Boolean] `true` if the FIN bit is set.
 			def finished?
 				@finished == true
 			end
 
+			# Check whether this frame is a continuation fragment (FIN bit not set).
+			# @returns [Boolean] `true` if the FIN bit is not set.
 			def continued?
 				@finished == false
 			end
@@ -116,6 +131,9 @@ def continued?
 				end
 			end
 
+			# Pack the given data into this frame's payload, applying masking if configured.
+			# @parameter data [String] The payload data to pack.
+			# @returns [Frame] Returns `self`.
 			def pack(data = "")
 				length = data.bytesize
 
@@ -134,6 +152,8 @@ def pack(data = "")
 				return self
 			end
 
+			# Unpack the raw payload, removing masking if present.
+			# @returns [String] The unmasked payload data.
 			def unpack
 				if @mask and !@payload.empty?
 					return mask_xor(@payload, @mask)
@@ -142,10 +162,16 @@ def unpack
 				end
 			end
 
+			# Apply this frame to the connection by dispatching it to the appropriate handler.
+			# @parameter connection [Connection] The WebSocket connection to receive this frame.
 			def apply(connection)
 				connection.receive_frame(self)
 			end
 
+			# Parse the first byte of a frame header to extract FIN, RSV flags, and opcode.
+			# @parameter buffer [String] A 1-byte binary string.
+			# @returns [Array] A tuple of `[finished, flags, opcode]`.
+			# @raises [ProtocolError] If the opcode is a reserved non-control or control opcode.
 			def self.parse_header(buffer)
 				byte = buffer.unpack("C").first
 
@@ -162,6 +188,15 @@ def self.parse_header(buffer)
 				return finished, flags, opcode
 			end
 
+			# Read a full frame from the stream given pre-parsed header fields.
+			# @parameter finished [Boolean] Whether the FIN bit was set.
+			# @parameter flags [Integer] The RSV flag bits.
+			# @parameter opcode [Integer] The frame opcode.
+			# @parameter stream [IO] The stream to read from.
+			# @parameter maximum_frame_size [Integer] The maximum allowed payload size in bytes.
+			# @returns [Frame] The fully read and populated frame.
+			# @raises [ProtocolError] If the frame violates protocol constraints.
+			# @raises [EOFError] If the stream ends unexpectedly.
 			def self.read(finished, flags, opcode, stream, maximum_frame_size)
 				buffer = stream.read(1) or raise EOFError, "Could not read header!"
 				byte = buffer.unpack("C").first
@@ -202,6 +237,9 @@ def self.read(finished, flags, opcode, stream, maximum_frame_size)
 				return self.new(finished, payload, flags: flags, opcode: opcode, mask: mask)
 			end
 
+			# Write this frame to the given stream.
+			# @parameter stream [IO] The stream to write the serialized frame to.
+			# @raises [ProtocolError] If the frame has invalid length or mask.
 			def write(stream)
 				buffer = String.new(encoding: Encoding::BINARY)
 

lib/protocol/websocket/framer.rb

@@ -29,6 +29,9 @@ module WebSocket
 
 		# Wraps an underlying {Async::IO::Stream} for reading and writing binary data into structured frames.
 		class Framer
+			# Initialize a new framer wrapping the given stream.
+			# @parameter stream [IO] The underlying stream to read from and write to.
+			# @parameter frames [Hash] A mapping of opcodes to frame classes.
 			def initialize(stream, frames = FRAMES)
 				@stream = stream
 				@frames = frames