protocol-websocket 0.20.2 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 359985418f2c1304957337e8d10ca42c7dec2225fa60e5db0e030e40ccdfbc30
-  data.tar.gz: fc29187e933f95505987ff87616c61877809fe3a0a94600b782d4d1728edef87
+  metadata.gz: 90750bdfa4f0cafe292f5b7faf67cecc3ad8dd599ef30e6be28bf6594405f424
+  data.tar.gz: 16d01a6e7e451a9444698cc852f937f1f50b9898bdb072d90cf3c93be2ce8b95
 SHA512:
-  metadata.gz: ef23fec7204ea0b9d965c3972b94fa39e615b5581470703f16564e5031d9819acd720618027274fd900b77864bf662c8adb44e895ce74b505c95c4cb3a7393ed
-  data.tar.gz: 5fb3eefc7a49e405fa7c8cd729812cf79095e8b8addf8af27a8aa35b4d3f759901de6c41a7233aceb2a76df43166dba43440e54d5bda5b765225480b21fd4057
+  metadata.gz: 49fdf1a4d58cc4a0b994a763b792cb576a1833d4c50c4abbc7596b8ded83f2df873e13ecf1b5948af392ac42dee3afb6e16210a25ed128b1ca0206e734dc08b4
+  data.tar.gz: d3ded669f47a3a58a226ee186c58a58e3234c4bf2678cc9fb1633a4a8d58caac9d11715825049a359568af896a376a33c1a42d7b60e02e08d090dc49c2e4ecd9

data/context/extensions.md

@@ -0,0 +1,91 @@
+# Extensions
+
+This guide explains how to use `protocol-websocket` for implementing a websocket client and server using extensions.
+
+## Per-message Deflate
+
+WebSockets have a mechanism for implementing extensions. At the time of writing, the only published extension is `permessage-deflate` for per-message compression. It operates on complete messages rather than individual frames.
+
+Clients and servers can negotiate a set of extensions to use. The server can accept or reject these extensions. The client can then instantiate the extensions and apply them to the connection. More specifically, clients need to define a set of extensions they want to support:
+
+~~~ ruby
+require 'protocol/websocket'
+require 'protocol/websocket/extensions'
+
+client_extensions = Protocol::WebSocket::Extensions::Client.new([
+	[Protocol::WebSocket::Extension::Compression, {}]
+])
+
+offer_headers = []
+
+client_extensions.offer do |header|
+	offer_headers << header.join(';')
+end
+
+offer_headers # => ["permessage-deflate;client_max_window_bits"]
+~~~
+
+This is transmitted to the server via the `Sec-WebSocket-Extensions` header. The server processes this and returns a subset of accepted extensions. The client receives a list of accepted extensions and instantiates them:
+
+~~~ ruby
+server_extensions = Protocol::WebSocket::Extensions::Server.new([
+	[Protocol::WebSocket::Extension::Compression, {}]
+])
+
+accepted_headers = []
+
+server_extensions.accept(offer_headers) do |header|
+	accepted_headers << header.join(';')
+end
+
+accepted_headers # => ["permessage-deflate;client_max_window_bits=15"]
+
+client_extensions.accept(accepted_headers)
+~~~
+
+We can check the extensions are accepted:
+
+~~~ ruby
+server_extensions.accepted
+# => [[Protocol::WebSocket::Extension::Compression, {:client_max_window_bits=>15}]]
+
+client_extensions.accepted
+# => [[Protocol::WebSocket::Extension::Compression, {:client_max_window_bits=>15}]]
+~~~
+
+Once the extensions are negotiated, they can be applied to the connection:
+
+~~~ ruby
+require 'protocol/websocket/connection'
+require 'socket'
+
+sockets = Socket.pair(Socket::PF_UNIX, Socket::SOCK_STREAM)
+
+client = Protocol::WebSocket::Connection.new(Protocol::WebSocket::Framer.new(sockets.first))
+server = Protocol::WebSocket::Connection.new(Protocol::WebSocket::Framer.new(sockets.last))
+
+client_extensions.apply(client)
+server_extensions.apply(server)
+
+# We can see that the appropriate wrappers have been added to the connections:
+client.reader.class # => Protocol::WebSocket::Extension::Compression::Inflate
+client.writer.class # => Protocol::WebSocket::Extension::Compression::Deflate
+server.reader.class # => Protocol::WebSocket::Extension::Compression::Inflate
+server.writer.class # => Protocol::WebSocket::Extension::Compression::Deflate
+
+client.send_text("Hello World")
+# => #<Protocol::WebSocket::TextFrame:0x000000011d555460 @finished=true, @flags=4, @length=13, @mask=nil, @opcode=1, @payload="\xF2H\xCD\xC9\xC9W\b\xCF/\xCAI\x01\x00">
+
+server.read
+# => #<Protocol::WebSocket::TextMessage:0x000000011e1e5248 @buffer="Hello World">
+~~~
+
+It's possible to disable compression on a per-message basis:
+
+~~~ ruby
+client.send_text("Hello World", compress: false)
+# => #<Protocol::WebSocket::TextFrame:0x00000001028945b0 @finished=true, @flags=0, @length=11, @mask=nil, @opcode=1, @payload="Hello World">
+
+server.read
+# => #<Protocol::WebSocket::TextMessage:0x000000011e77eb50 @buffer="Hello World">
+~~~

data/context/getting-started.md

@@ -0,0 +1,73 @@
+# Getting Started
+
+This guide explains how to use `protocol-websocket` for implementing a websocket client and server.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add protocol-websocket
+~~~
+
+## Core Concepts
+
+`protocol-websocket` has several core concepts:
+
+- A {ruby Protocol::WebSocket::Frame} is the base class which is used to represent protocol-specific structured frames.
+- A {ruby Protocol::WebSocket::Framer} wraps an underlying {ruby Async::IO::Stream} for reading and writing binary data into structured frames.
+- A {ruby Protocol::WebSocket::Connection} wraps a framer and implements for implementing connection specific interactions like reading and writing text.
+- A {ruby Protocol::WebSocket::Message} is a higher-level abstraction for reading and writing messages.
+
+## Bi-directional Communication
+
+We can create a small bi-directional WebSocket client server:
+
+~~~ ruby
+require 'protocol/websocket'
+require 'protocol/websocket/connection'
+require 'socket'
+
+sockets = Socket.pair(Socket::PF_UNIX, Socket::SOCK_STREAM)
+
+client = Protocol::WebSocket::Connection.new(Protocol::WebSocket::Framer.new(sockets.first))
+server = Protocol::WebSocket::Connection.new(Protocol::WebSocket::Framer.new(sockets.last))
+
+client.send_text("Hello World")
+server.read
+# #<Protocol::WebSocket::TextMessage:0x000000011d2338e0 @buffer="Hello World">
+
+client.send_binary("Hello World")
+server.read
+#<Protocol::WebSocket::BinaryMessage:0x000000011d371db0 @buffer="Hello World">
+~~~
+
+## Messages
+
+We can also use the {ruby Protocol::WebSocket::Message} class to read and write messages:
+
+~~~ ruby
+require 'protocol/websocket'
+require 'protocol/websocket/connection'
+require 'socket'
+
+sockets = Socket.pair(Socket::PF_UNIX, Socket::SOCK_STREAM)
+
+client = Protocol::WebSocket::Connection.new(Protocol::WebSocket::Framer.new(sockets.first))
+server = Protocol::WebSocket::Connection.new(Protocol::WebSocket::Framer.new(sockets.last))
+
+# Encode a value using JSON:
+message = Protocol::WebSocket::TextMessage.generate({hello: "world"})
+
+client.write(message)
+server.read.to_h
+# {:hello=>"world"}
+~~~
+
+### Text Messages
+
+Text messages contain UTF-8 encoded text. Invalid UTF-8 sequences will result in errors. Text messages are useful for sending structured data like JSON.
+
+### Binary Messages
+
+Binary messages contain arbitrary binary data. They can be used to send any kind of data. Binary messages are useful for sending files or other binary data, like images or video.

data/context/index.yaml

@@ -0,0 +1,16 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: A low level implementation of the WebSocket protocol.
+metadata:
+  documentation_uri: https://socketry.github.io/protocol-websocket/
+  source_code_uri: https://github.com/socketry/protocol-websocket.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `protocol-websocket` for implementing
+    a websocket client and server.
+- path: extensions.md
+  title: Extensions
+  description: This guide explains how to use `protocol-websocket` for implementing
+    a websocket client and server using extensions.

data/lib/protocol/websocket/coder/json.rb

@@ -10,6 +10,8 @@ module Protocol
 		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

data/lib/protocol/websocket/coder.rb

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

data/lib/protocol/websocket/connection.rb

@@ -281,7 +281,11 @@ module Protocol
 			
 			# The default implementation for reading a message buffer. This is used by the {#reader} interface.
 			def unpack_frames(frames)
-				frames.map(&:unpack).join("")
+				if frames.size == 1
+					frames[0].unpack
+				else
+					frames.map(&:unpack).join("")
+				end
 			end
 			
 			# Read a message from the connection. If an error occurs while reading the message, the connection will be closed.

data/lib/protocol/websocket/error.rb

@@ -41,6 +41,9 @@ module Protocol
 		
 		# 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)
 				

data/lib/protocol/websocket/extension/compression/constants.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2026, by Samuel Williams.
 
 require "zlib"
 
@@ -10,7 +10,7 @@ module Protocol
 		module Extension
 			module Compression
 				NAME = "permessage-deflate"
-								
+				
 				# Zlib is not capable of handling < 9 window bits.
 				MINIMUM_WINDOW_BITS = 9
 			end

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2026, by Samuel Williams.
 
 require_relative "constants"
 
@@ -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 @@ module Protocol
 						)
 					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
 						
@@ -36,7 +44,7 @@ module Protocol
 						@level = level
 						@memory_level = memory_level
 						@strategy = strategy
-
+						
 						# This is handled during negotiation:
 						# if window_bits < MINIMUM_WINDOW_BITS
 						# 	window_bits = MINIMUM_WINDOW_BITS
@@ -46,13 +54,20 @@ module Protocol
 						@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 @@ module Protocol
 						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)

data/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 @@ module Protocol
 					
 					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 @@ module Protocol
 						@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)
 						

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2026, by Samuel Williams.
 
 require_relative "compression/constants"
 require_relative "compression/inflate"
@@ -9,6 +9,7 @@ require_relative "compression/deflate"
 
 module Protocol
 	module WebSocket
+		# @namespace
 		module Extension
 			# Provides support for the permessage-deflate extension.
 			module Compression
@@ -46,7 +47,7 @@ module Protocol
 					
 					return header
 				end
-
+				
 				# Negotiate on the server a response to client based on the incoming client offer.
 				# @parameter options [Hash] a hash of options which are accepted by the server.
 				# @returns [Array(String)] a list of compression parameters suitable to send back to the client.

data/lib/protocol/websocket/extensions.rb

@@ -8,7 +8,13 @@ require_relative "headers"
 
 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 @@ module Protocol
 				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 @@ module Protocol
 					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,6 +90,8 @@ module Protocol
 					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)
@@ -76,27 +99,41 @@ module Protocol
 				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 @@ module Protocol
 					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)

data/lib/protocol/websocket/frame.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2025, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 # Copyright, 2019, by Soumya.
 # Copyright, 2021, by Aurora Nockert.
 # Copyright, 2025, by Taleh Zaliyev.
@@ -10,6 +10,7 @@ require_relative "error"
 
 module Protocol
 	module WebSocket
+		# Represents a single WebSocket frame as defined by RFC 6455.
 		class Frame
 			include Comparable
 			
@@ -19,8 +20,7 @@ module Protocol
 			RESERVED = RSV1 | RSV2 | RSV3
 			
 			OPCODE = 0
-						
-			# @parameter length [Integer] The length of the payload, or nil if the header has not been read yet.
+			
 			# @parameter mask [Boolean | String] An optional 4-byte string which is used to mask the payload.
 			def initialize(finished = true, payload = nil, flags: 0, opcode: self.class::OPCODE, mask: false)
 				if mask == true
@@ -31,22 +31,31 @@ module Protocol
 				@flags = flags
 				@opcode = opcode
 				@mask = mask
-				@length = payload&.bytesize
 				@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, payload]`.
 			def to_ary
-				[@finished, @flags, @opcode, @mask, @length, @payload]
+				[@finished, @flags, @opcode, @mask, @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 +65,14 @@ module Protocol
 				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
@@ -89,9 +102,14 @@ module Protocol
 			attr_accessor :flags
 			attr_accessor :opcode
 			attr_accessor :mask
-			attr_accessor :length
 			attr_accessor :payload
 			
+			# The byte length of the payload.
+			# @returns [Integer | nil]
+			def length
+				@payload&.bytesize
+			end
+			
 			if IO.const_defined?(:Buffer) && IO::Buffer.respond_to?(:for) && IO::Buffer.method_defined?(:xor!)
 				private def mask_xor(data, mask)
 					buffer = data.dup
@@ -107,7 +125,7 @@ module Protocol
 				warn "IO::Buffer not available, falling back to slow implementation of mask_xor!"
 				private def mask_xor(data, mask)
 					result = String.new(encoding: Encoding::BINARY)
-						
+					
 					for i in 0...data.bytesize do
 						result << (data.getbyte(i) ^ mask.getbyte(i % 4))
 					end
@@ -116,24 +134,25 @@ module Protocol
 				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
-				
-				if length.bit_length > 63
-					raise ProtocolError, "Frame length #{@length} bigger than allowed maximum!"
+				if data.bytesize.bit_length > 63
+					raise ProtocolError, "Frame length #{data.bytesize} bigger than allowed maximum!"
 				end
 				
 				if @mask
-					@payload = mask_xor(data, mask)
-					@length = length
+					@payload = mask_xor(data, @mask)
 				else
 					@payload = data
-					@length = length
 				end
 				
 				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,101 +161,11 @@ module Protocol
 				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
-			
-			def self.parse_header(buffer)
-				byte = buffer.unpack("C").first
-				
-				finished = (byte & 0b1000_0000 != 0)
-				flags = (byte & 0b0111_0000) >> 4
-				opcode = byte & 0b0000_1111
-				
-				if (0x3 .. 0x7).include?(opcode)
-					raise ProtocolError, "Non-control opcode = #{opcode} is reserved!"
-				elsif (0xB .. 0xF).include?(opcode)
-					raise ProtocolError, "Control opcode = #{opcode} is reserved!"
-				end
-				
-				return finished, flags, opcode
-			end
-			
-			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
-				
-				mask = (byte & 0b1000_0000 != 0)
-				length = byte & 0b0111_1111
-				
-				if opcode & 0x8 != 0
-					if length > 125
-						raise ProtocolError, "Invalid control frame payload length: #{length} > 125!"
-					elsif !finished
-						raise ProtocolError, "Fragmented control frame!"
-					end
-				end
-				
-				if length == 126
-					buffer = stream.read(2) or raise EOFError, "Could not read length!"
-					length = buffer.unpack("n").first
-				elsif length == 127
-					buffer = stream.read(8) or raise EOFError, "Could not read length!"
-					length = buffer.unpack("Q>").first
-				end
-				
-				if length > maximum_frame_size
-					raise ProtocolError, "Invalid payload length: #{length} > #{maximum_frame_size}!"
-				end
-				
-				if mask
-					mask = stream.read(4) or raise EOFError, "Could not read mask!"
-				end
-				
-				payload = stream.read(length) or raise EOFError, "Could not read payload!"
-				
-				if payload.bytesize != length
-					raise EOFError, "Incorrect payload length: #{length} != #{payload.bytesize}!"
-				end
-				
-				return self.new(finished, payload, flags: flags, opcode: opcode, mask: mask)
-			end
-			
-			def write(stream)
-				buffer = String.new(encoding: Encoding::BINARY)
-				
-				if @payload&.bytesize != @length
-					raise ProtocolError, "Invalid payload length: #{@length} != #{@payload.bytesize} for #{self}!"
-				end
-				
-				if @mask and @mask.bytesize != 4
-					raise ProtocolError, "Invalid mask length!"
-				end
-				
-				if length <= 125
-					short_length = length
-				elsif length.bit_length <= 16
-					short_length = 126
-				else
-					short_length = 127
-				end
-				
-				buffer << [
-					(@finished ? 0b1000_0000 : 0) | (@flags << 4) | @opcode,
-					(@mask ? 0b1000_0000 : 0) | short_length,
-				].pack("CC")
-				
-				if short_length == 126
-					buffer << [@length].pack("n")
-				elsif short_length == 127
-					buffer << [@length].pack("Q>")
-				end
-				
-				buffer << @mask if @mask
-				
-				stream.write(buffer)
-				stream.write(@payload)
-			end
 		end
 	end
 end

data/lib/protocol/websocket/framer.rb

@@ -29,6 +29,9 @@ module Protocol
 		
 		# 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
@@ -47,28 +50,105 @@ module Protocol
 			# Read a frame from the underlying stream.
 			# @returns [Frame] the frame read from the stream.
 			def read_frame(maximum_frame_size = MAXIMUM_ALLOWED_FRAME_SIZE)
-				# Read the header:
-				finished, flags, opcode = read_header
+				buffer = @stream.read(2)
 				
-				# Read the frame:
-				klass = @frames[opcode] || Frame
-				frame = klass.read(finished, flags, opcode, @stream, maximum_frame_size)
+				unless buffer and buffer.bytesize == 2
+					raise EOFError, "Could not read frame header!"
+				end
+				
+				first_byte = buffer.getbyte(0)
+				second_byte = buffer.getbyte(1)
+				
+				finished = (first_byte & 0b1000_0000 != 0)
+				flags = (first_byte & 0b0111_0000) >> 4
+				opcode = first_byte & 0b0000_1111
+				
+				if opcode >= 0x3 && opcode <= 0x7
+					raise ProtocolError, "Non-control opcode = #{opcode} is reserved!"
+				elsif opcode >= 0xB
+					raise ProtocolError, "Control opcode = #{opcode} is reserved!"
+				end
+				
+				mask = (second_byte & 0b1000_0000 != 0)
+				length = second_byte & 0b0111_1111
+				
+				if opcode & 0x8 != 0
+					if length > 125
+						raise ProtocolError, "Invalid control frame payload length: #{length} > 125!"
+					elsif !finished
+						raise ProtocolError, "Fragmented control frame!"
+					end
+				end
+				
+				if length == 126
+					if mask
+						buffer = @stream.read(6) or raise EOFError, "Could not read length and mask!"
+						length = buffer.unpack1("n")
+						mask = buffer.byteslice(2, 4)
+					else
+						buffer = @stream.read(2) or raise EOFError, "Could not read length!"
+						length = buffer.unpack1("n")
+					end
+				elsif length == 127
+					if mask
+						buffer = @stream.read(12) or raise EOFError, "Could not read length and mask!"
+						length = buffer.unpack1("Q>")
+						mask = buffer.byteslice(8, 4)
+					else
+						buffer = @stream.read(8) or raise EOFError, "Could not read length!"
+						length = buffer.unpack1("Q>")
+					end
+				elsif mask
+					mask = @stream.read(4) or raise EOFError, "Could not read mask!"
+				end
+				
+				if length > maximum_frame_size
+					raise ProtocolError, "Invalid payload length: #{length} > #{maximum_frame_size}!"
+				end
 				
-				return frame
+				payload = @stream.read(length) or raise EOFError, "Could not read payload!"
+				
+				if payload.bytesize != length
+					raise EOFError, "Incorrect payload length: #{length} != #{payload.bytesize}!"
+				end
+				
+				klass = @frames[opcode] || Frame
+				return klass.new(finished, payload, flags: flags, opcode: opcode, mask: mask)
 			end
 			
 			# Write a frame to the underlying stream.
+			# @parameter frame [Frame] The frame to serialize and write.
+			# @raises [ProtocolError] If the frame has an invalid mask.
 			def write_frame(frame)
-				frame.write(@stream)
-			end
-			
-			# Read the header of the frame.
-			def read_header
-				if buffer = @stream.read(1) and buffer.bytesize == 1
-					return Frame.parse_header(buffer)
+				if frame.mask and frame.mask.bytesize != 4
+					raise ProtocolError, "Invalid mask length!"
 				end
 				
-				raise EOFError, "Could not read frame header!"
+				length = frame.length
+				
+				if length <= 125
+					short_length = length
+				elsif length.bit_length <= 16
+					short_length = 126
+				else
+					short_length = 127
+				end
+				
+				buffer = [
+					(frame.finished ? 0b1000_0000 : 0) | (frame.flags << 4) | frame.opcode,
+					(frame.mask ? 0b1000_0000 : 0) | short_length,
+				].pack("CC")
+				
+				if short_length == 126
+					buffer << [length].pack("n")
+				elsif short_length == 127
+					buffer << [length].pack("Q>")
+				end
+				
+				buffer << frame.mask if frame.mask
+				
+				@stream.write(buffer)
+				@stream.write(frame.payload)
 			end
 		end
 	end

data/lib/protocol/websocket/headers.rb

@@ -8,6 +8,7 @@ require "securerandom"
 
 module Protocol
 	module WebSocket
+		# @namespace
 		module Headers
 			# The protocol string used for the `upgrade:` header (HTTP/1) and `:protocol` pseudo-header (HTTP/2).
 			PROTOCOL = "websocket"
@@ -23,6 +24,7 @@ module Protocol
 			
 			SEC_WEBSOCKET_EXTENSIONS = "sec-websocket-extensions"
 			
+			# Provides utilities for generating and verifying the WebSocket handshake nonce.
 			module Nounce
 				GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
 				

data/lib/protocol/websocket/message.rb

@@ -57,6 +57,8 @@ module Protocol
 				parse(...).to_h
 			end
 			
+			# Send this message as a text frame over the given connection.
+			# @parameter connection [Connection] The WebSocket connection to send through.
 			def send(connection, **options)
 				connection.send_text(@buffer, **options)
 			end
@@ -68,6 +70,8 @@ module Protocol
 		
 		# Represents a binary message that can be sent or received over a WebSocket connection.
 		class BinaryMessage < Message
+			# Send this message as a binary frame over the given connection.
+			# @parameter connection [Connection] The WebSocket connection to send through.
 			def send(connection, **options)
 				connection.send_binary(@buffer, **options)
 			end
@@ -75,6 +79,8 @@ module Protocol
 		
 		# Represents a ping message that can be sent over a WebSocket connection.
 		class PingMessage < Message
+			# Send this message as a ping frame over the given connection.
+			# @parameter connection [Connection] The WebSocket connection to send through.
 			def send(connection)
 				connection.send_ping(@buffer)
 			end

data/lib/protocol/websocket/version.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
+# @namespace
 module Protocol
+	# @namespace
 	module WebSocket
-		VERSION = "0.20.2"
+		VERSION = "0.21.0"
 	end
 end

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2019-2025, by Samuel Williams.  
+Copyright, 2019-2026, by Samuel Williams.  
 Copyright, 2019, by Soumya.  
 Copyright, 2019, by William T. Nelson.  
 Copyright, 2020, by Olle Jonsson.  

data/readme.md

@@ -12,6 +12,52 @@ Please see the [project documentation](https://socketry.github.io/protocol-webso
 
   - [Extensions](https://socketry.github.io/protocol-websocket/guides/extensions/index) - This guide explains how to use `protocol-websocket` for implementing a websocket client and server using extensions.
 
+## Releases
+
+Please see the [project releases](https://socketry.github.io/protocol-websocket/releases/index) for all releases.
+
+### v0.21.0
+
+  - All frame reading and writing logic has been consolidated into `Framer` to improve performance.
+
+### v0.20.2
+
+  - Fix error messages for `Frame` to be more descriptive.
+
+### v0.20.1
+
+  - Revert masking enforcement option introduced in v0.20.0 due to compatibility issues.
+
+### v0.20.0
+
+  - Introduce option `requires_masking` to `Framer` for enforcing masking on received frames.
+
+### v0.19.1
+
+  - Ensure ping reply payload is packed correctly.
+
+### v0.19.0
+
+  - Default to empty string for message buffer when no data is provided.
+
+### v0.18.0
+
+  - Add `PingMessage` alongside `TextMessage` and `BinaryMessage` for a consistent message interface.
+  - Remove `JSONMessage` (use application-level encoding instead).
+
+### v0.17.0
+
+  - Introduce `#close_write` and `#shutdown` methods on `Connection` for more precise connection lifecycle control.
+
+### v0.16.0
+
+  - Move `#send` logic into `Message` for better encapsulation.
+  - Improve error handling when a `nil` message is passed.
+
+### v0.15.0
+
+  - Require `Message` class by default.
+
 ## Contributing
 
 We welcome contributions to this project.
@@ -22,6 +68,22 @@ We welcome contributions to this project.
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
 
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
 ### Developer Certificate of Origin
 
 In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.

data/releases.md

@@ -0,0 +1,43 @@
+# Releases
+
+## v0.21.0
+
+  - All frame reading and writing logic has been consolidated into `Framer` to improve performance.
+
+## v0.20.2
+
+  - Fix error messages for `Frame` to be more descriptive.
+
+## v0.20.1
+
+  - Revert masking enforcement option introduced in v0.20.0 due to compatibility issues.
+
+## v0.20.0
+
+  - Introduce option `requires_masking` to `Framer` for enforcing masking on received frames.
+
+## v0.19.1
+
+  - Ensure ping reply payload is packed correctly.
+
+## v0.19.0
+
+  - Default to empty string for message buffer when no data is provided.
+
+## v0.18.0
+
+  - Add `PingMessage` alongside `TextMessage` and `BinaryMessage` for a consistent message interface.
+  - Remove `JSONMessage` (use application-level encoding instead).
+
+## v0.17.0
+
+  - Introduce `#close_write` and `#shutdown` methods on `Connection` for more precise connection lifecycle control.
+
+## v0.16.0
+
+  - Move `#send` logic into `Message` for better encapsulation.
+  - Improve error handling when a `nil` message is passed.
+
+## v0.15.0
+
+  - Require `Message` class by default.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-websocket
 version: !ruby/object:Gem::Version
-  version: 0.20.2
+  version: 0.21.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -41,7 +41,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-04-12 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: protocol-http
@@ -61,6 +61,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/extensions.md
+- context/getting-started.md
+- context/index.yaml
 - lib/protocol/websocket.rb
 - lib/protocol/websocket/binary_frame.rb
 - lib/protocol/websocket/close_frame.rb
@@ -84,6 +87,7 @@ files:
 - lib/protocol/websocket/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/protocol-websocket
 licenses:
 - MIT
@@ -97,14 +101,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.6
 specification_version: 4
 summary: A low level implementation of the WebSocket protocol.
 test_files: []