protocol-websocket 0.7.3 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86e03089f165a2cf50a6b4cbd20328da1a782778c02f23a3be4e4542de0ea692
-  data.tar.gz: d4f856117d7e13373cd115871276682f08793ddf353f3106f5569cc8e38fb4ad
+  metadata.gz: 076d348e98312526d98d8fc80840b9760cf30496ac4ca83d129ac53e120c10a0
+  data.tar.gz: 142d1fa0b2c8e06a3642cfff30f76f835308b23ca3d6964e1c3ae0870204d5e1
 SHA512:
-  metadata.gz: fbd6e6cbec72148770e2c3979bc56cdea6f12726ae8270759a613814ee1e54492ee0ba24a51b5077d3dfeff93e19abb56ea5ff219e042a03445e87ff0b33c051
-  data.tar.gz: 519c30e7774eac646675e8a940e9665214bd9d9a266297038d781030e8ca9150a9aa877c85b0ece209ff0a9475203403e7879155b472b8d283bb3a066af6c4bd
+  metadata.gz: 941eda4ac12acbc31bdd359cae2b2aaffd59f78f328844fcd171f6aca517cc225831ea3726f919448eaef3c7246a630d415988528ef08f4f6a394239b5924aeb
+  data.tar.gz: 9c37cfc67173a3632c344d042682f906b9b9afc2c4cbc35263f9cc48fa0cf4e62ee7348b4ce5a1af7bed2b118d23f477721e2b575f8d91f991806fa53996da7c

data/lib/protocol/websocket/binary_frame.rb

@@ -29,6 +29,10 @@ module Protocol
 				true
 			end
 			
+			def read_message(buffer)
+				buffer
+			end
+			
 			def apply(connection)
 				connection.receive_binary(self)
 			end

data/lib/protocol/websocket/close_frame.rb

@@ -29,11 +29,41 @@ module Protocol
 			def unpack
 				data = super
 				
-				return data.unpack(FORMAT)
+				case data.length
+				when 0
+					[nil, ""]
+				when 1
+					raise ProtocolError, "invalid close frame length!"
+				else
+					code, reason = *data.unpack(FORMAT)
+					
+					case code
+					when 0 .. 999, 1005 .. 1006, 1015, 5000 .. 0xFFFF
+						raise ProtocolError, "invalid close code!"
+					when 1004, 1016 .. 2999
+						raise ProtocolError, "reserved close code!"
+					end
+					
+					reason.force_encoding(Encoding::UTF_8)
+					
+					unless reason.valid_encoding?
+						raise ProtocolError, "invalid UTF-8 in close reason!"
+					end
+					
+					[code, reason]
+				end
 			end
 			
 			def pack(code, reason)
-				super [code, reason].pack(FORMAT)
+				if code
+					unless reason.encoding == Encoding::UTF_8
+						reason = reason.encode(Encoding::UTF_8)
+					end
+					
+					super [code, reason].pack(FORMAT)
+				else
+					super String.new(encoding: Encoding::BINARY)
+				end
 			end
 			
 			def apply(connection)

data/lib/protocol/websocket/connection.rb

@@ -23,18 +23,20 @@ require 'securerandom'
 
 module Protocol
 	module WebSocket
+		# Wraps a framer and implements for implementing connection specific interactions like reading and writing text.
 		class Connection
-			# @option mask [String] 4-byte mask to be used for frames generated by this connection.
-			def initialize(framer, mask: nil)
-				if mask == true
-					mask = SecureRandom.bytes(4)
-				end
-				
+			# @parameter mask [String] 4-byte mask to be used for frames generated by this connection.
+			def initialize(framer, mask: nil, **options)
 				@framer = framer
 				@mask = mask
 				
 				@state = :open
 				@frames = []
+				
+				@reserved = Frame::RESERVED
+				
+				@reader = self
+				@writer = self
 			end
 			
 			# The framer which is used for reading and writing frames.
@@ -43,9 +45,25 @@ module Protocol
 			# The (optional) mask which is used when generating frames.
 			attr :mask
 			
+			# The allowed reserved bits:
+			attr :reserved
+			
 			# Buffered frames which form part of a complete message.
 			attr_accessor :frames
 			
+			attr_accessor :reader
+			attr_accessor :writer
+			
+			def reserve!(bit)
+				if (@reserved & bit).zero?
+					raise "Unable to use #{bit}!"
+				end
+				
+				@reserved  &= ~bit
+				
+				return true
+			end
+			
 			def flush
 				@framer.flush
 			end
@@ -54,8 +72,8 @@ module Protocol
 				@state == :closed
 			end
 			
-			def close
-				send_close unless closed?
+			def close(code = Error::NO_ERROR, reason = "")
+				send_close(code, reason) unless closed?
 				
 				@framer.close
 			end
@@ -65,6 +83,10 @@ module Protocol
 				
 				frame = @framer.read_frame
 				
+				unless (frame.flags & @reserved).zero?
+					raise ProtocolError, "Received frame with reserved flags set!"
+				end
+				
 				yield frame if block_given?
 				
 				frame.apply(self)
@@ -82,6 +104,8 @@ module Protocol
 			
 			def write_frame(frame)
 				@framer.write_frame(frame)
+				
+				return frame
 			end
 			
 			def receive_text(frame)
@@ -108,23 +132,31 @@ module Protocol
 				end
 			end
 			
-			def send_text(buffer)
+			def text_message(buffer, **options)
 				frame = TextFrame.new(mask: @mask)
-				frame.pack buffer
+				frame.pack(buffer)
 				
-				write_frame(frame)
+				return frame
+			end
+			
+			def send_text(buffer, **options)
+				write_frame(@writer.text_message(buffer, **options))
 			end
 			
-			def send_binary(buffer)
+			def binary_message(buffer, **options)
 				frame = BinaryFrame.new(mask: @mask)
-				frame.pack buffer
+				frame.pack(buffer)
 				
-				write_frame(frame)
+				return frame
 			end
 			
-			def send_close(code = Error::NO_ERROR, message = nil)
+			def send_binary(buffer, **options)
+				write_frame(@writer.binary_message(buffer, **options))
+			end
+			
+			def send_close(code = Error::NO_ERROR, reason = "")
 				frame = CloseFrame.new(mask: @mask)
-				frame.pack(code, message)
+				frame.pack(code, reason)
 				
 				self.write_frame(frame)
 				self.flush
@@ -135,10 +167,12 @@ module Protocol
 			def receive_close(frame)
 				@state = :closed
 				
-				code, message = frame.unpack
+				code, reason = frame.unpack
+				
+				send_close(code, reason)
 				
 				if code and code != Error::NO_ERROR
-					raise ClosedError.new message, code
+					raise ClosedError.new reason, code
 				end
 			end
 			
@@ -161,7 +195,7 @@ module Protocol
 			
 			def receive_ping(frame)
 				if @state != :closed
-					write_frame(frame.reply)
+					write_frame(frame.reply(mask: @mask))
 				else
 					raise ProtocolError, "Cannot receive ping in state #{@state}"
 				end
@@ -175,31 +209,24 @@ module Protocol
 				warn "Unhandled frame #{frame.inspect}"
 			end
 			
-			# @param buffer [String] a unicode or binary string.
-			def write(buffer)
+			def write_message(buffer, **options)
+				# Text: The "Payload data" is text data encoded as UTF-8
 				if buffer.encoding == Encoding::UTF_8
-					send_text(buffer)
+					send_text(buffer, **options)
 				else
-					send_data(buffer)
+					send_binary(buffer, **options)
 				end
 			end
 			
-			# @return [String] a unicode or binary string.
-			def read
-				@framer.flush
+			# @param buffer [String] a unicode or binary string.
+			def write(buffer, **options)
+				# https://tools.ietf.org/html/rfc6455#section-5.6
 				
-				while read_frame
-					if @frames.last&.finished?
-						buffer = @frames.map(&:unpack).join
-						@frames = []
-						
-						return buffer
-					end
-				end
+				self.write_message(buffer, **options)
 			end
 			
-			# Deprecated.
-			def next_message
+			# @return [String] a unicode or binary string.
+			def read(**options)
 				@framer.flush
 				
 				while read_frame
@@ -207,9 +234,18 @@ module Protocol
 						frames = @frames
 						@frames = []
 						
-						return frames
+						buffer = @reader.read_message(frames, **options)
+						return frames.first.read_message(buffer)
 					end
 				end
+			rescue ProtocolError => error
+				send_close(error.code, error.message)
+				
+				raise
+			end
+			
+			def read_message(frames, **options)
+				frames.map(&:unpack).join("")
 			end
 		end
 	end

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

@@ -0,0 +1,93 @@
+# Copyright, 2021, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'zlib'
+
+module Protocol
+	module WebSocket
+		module Extension
+			module Compression
+				class Deflate
+					def self.client(parent, client_window_bits: 15, client_no_context_takeover: false, **options)
+						self.new(parent,
+							window_bits: client_window_bits,
+							context_takeover: !client_no_context_takeover,
+							**options
+						)
+					end
+					
+					def self.server(parent, server_window_bits: 15, server_no_context_takeover: false, **options)
+						self.new(parent,
+							window_bits: server_window_bits,
+							context_takeover: !server_no_context_takeover,
+							**options
+						)
+					end
+					
+					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
+						
+						@deflate = nil
+						
+						@compression_level = level
+						@memory_level = memory_level
+						@strategy = strategy
+						
+						@window_bits = window_bits
+						@context_takeover = context_takeover
+					end
+					
+					def text_message(buffer, compress: true, **options)
+						buffer = self.deflate(buffer)
+						
+						frame = @parent.text_message(buffer, **options)
+						
+						frame.flags |= Frame::RSV1
+						
+						return frame
+					end
+					
+					def binary_message(buffer, compress: false, **options)
+						message = self.deflate(buffer)
+						
+						frame = parent.binary_message(buffer, **options)
+						
+						frame.flags |= Frame::RSV1
+						
+						return frame
+					end
+					
+					private
+					
+					def deflate(buffer)
+						Console.logger.info(self, "Deflating #{buffer.size} bytes")
+						deflate = @deflate || Zlib::Deflate.new(@level, -@window_bits, @memory_level, @strategy)
+						
+						if @context_takeover
+							@deflate = deflate
+						end
+						
+						return @deflate.deflate(buffer, Zlib::SYNC_FLUSH)[0...-4]
+					end
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,85 @@
+# Copyright, 2021, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'zlib'
+
+module Protocol
+	module WebSocket
+		module Extension
+			module Compression
+				class Inflate
+					def self.client(parent, client_window_bits: 15, client_no_context_takeover: false, **options)
+						self.new(parent,
+							window_bits: client_window_bits,
+							context_takeover: !client_no_context_takeover,
+							**options
+						)
+					end
+					
+					def self.server(parent, server_window_bits: 15, server_no_context_takeover: false, **options)
+						self.new(parent,
+							window_bits: server_window_bits,
+							context_takeover: !server_no_context_takeover,
+							**options
+						)
+					end
+					
+					TRAILER = [0x00, 0x00, 0xff, 0xff].pack('C*')
+					
+					def initialize(parent, context_takeover: true, window_bits: 15)
+						@parent = parent
+						
+						@inflate = nil
+						
+						@window_bits = window_bits
+						@context_takeover = context_takeover
+					end
+					
+					def read_message(frames, **options)
+						buffer = @parent.read_message(frames, **options)
+						
+						frame = frames.first
+						
+						if frame.flags & Frame::RSV1
+							buffer = self.inflate(buffer)
+						end
+						
+						frame.flags &= ~Frame::RSV1
+						
+						return buffer
+					end
+					
+					private
+					
+					def inflate(buffer)
+						Console.logger.info(self, "Inflating #{buffer.bytesize} bytes")
+						inflate = @inflate || Zlib::Inflate.new(-@window_bits)
+						
+						if @context_takeover
+							@inflate = inflate
+						end
+						
+						return inflate.inflate(buffer + TRAILER)
+					end
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,131 @@
+# Copyright, 2021, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'zlib'
+require_relative 'compression/inflate'
+require_relative 'compression/deflate'
+
+module Protocol
+	module WebSocket
+		module Extension
+			module Compression
+				NAME = 'permessage-deflate'
+				
+				# Client offer to server, construct a list of requested compression parameters suitable for the `Sec-WebSocket-Extensions` header.
+				# @returns [Array(String)] a list of compression parameters suitable to send to the server.
+				def self.offer(client_window_bits: true, server_window_bits: true, client_no_context_takeover: false, server_no_context_takeover: false)
+					
+					header = [NAME]
+					
+					case client_window_bits
+					when 8..15
+						header << "client_max_window_bits=#{client_window_bits}"
+					when true
+						header << 'client_max_window_bits'
+					else
+						raise ArgumentError, "Invalid local maximum window bits!"
+					end
+					
+					if client_no_context_takeover
+						header << 'client_no_context_takeover'
+					end
+					
+					case server_window_bits
+					when 8..15
+						header << "server_max_window_bits=#{server_window_bits}"
+					when true
+						# Default (unspecified) to the server maximum window bits.
+					else
+						raise ArgumentError, "Invalid remote maximum window bits!"
+					end
+					
+					if server_no_context_takeover
+						header << 'server_no_context_takeover'
+					end
+					
+					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.
+				def self.negotiate(arguments, **options)
+					header = [NAME]
+					
+					arguments.each do |key, value|
+						case key
+						when "server_no_context_takeover"
+							options[:server_no_context_takeover] = false
+							header << key
+						when "client_no_context_takeover"
+							options[:client_no_context_takeover] = false
+							header << key
+						when "server_max_window_bits"
+							options[:server_max_window_bits] = Integer(value || 15)
+						when "client_max_window_bits"
+							options[:client_max_window_bits] = Integer(value || 15)
+						else
+							raise ArgumentError, "Unknown option #{key}!"
+						end
+					end
+					
+					# The header which represents the final accepted/negotiated configuration.
+					return header
+				end
+				
+				# @parameter options [Hash] a hash of options which are accepted by the server.
+				def self.server(connection, **options)
+					connection.reserve!(Frame::RSV1)
+					
+					connection.reader = Inflate.server(connection.reader, **options)
+					connection.writer = Deflate.server(connection.writer, **options)
+				end
+				
+				# Accept on the client, the negotiated server response.
+				# @parameter options [Hash] a hash of options which are accepted by the client.
+				# @parameter arguments [Array(String)] a list of compression parameters as accepted/negotiated by the server.
+				def self.accept(arguments, **options)
+					arguments.each do |key, value|
+						case key
+						when "server_no_context_takeover"
+							options[:server_no_context_takeover] = false
+						when "client_no_context_takeover"
+							options[:client_no_context_takeover] = false
+						when "server_max_window_bits"
+							options[:server_max_window_bits] = Integer(value || 15)
+						when "client_max_window_bits"
+							options[:client_max_window_bits] = Integer(value || 15)
+						else
+							raise ArgumentError, "Unknown option #{key}!"
+						end
+					end
+				end
+				
+				# @parameter options [Hash] a hash of options which are accepted by the client.
+				def self.client(connection, **options)
+					connection.reserve!(Frame::RSV1)
+					
+					connection.reader = Inflate.client(connection.reader, **options)
+					connection.writer = Deflate.client(connection.writer, **options)
+				end
+			end
+		end
+	end
+end

data/lib/protocol/websocket/extensions.md

@@ -0,0 +1,13 @@
+# Extensions
+
+WebSockets have a mechanism for implementing extensions. The only published extension is for per-message compression. It operates on complete messages rather than individual frames.
+
+## Setup
+
+Clients need to define a set of extensions they want to support. The server then receives this via the `Sec-WebSocket-Extensions` header which includes a list of:
+
+	Name, Options
+
+The server processes this and returns a subset of accepted `(Name, Options)`. It also instantiates the extensions and applies them to the server connection object.
+
+The client receives a list of accepted `(Name, Options)` and instantiates the extensions and applies them to the client connection object.

data/lib/protocol/websocket/extensions.rb

@@ -0,0 +1,146 @@
+# Copyright, 2021, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'extension/compression'
+require_relative 'headers'
+
+module Protocol
+	module WebSocket
+		module Extensions
+			def self.parse(headers)
+				return to_enum(:parse, headers) unless block_given?
+				
+				headers.each do |header|
+					name, *arguments = header.split(/\s*;\s*/)
+					
+					arguments = arguments.map do |argument|
+						argument.split('=', 2)
+					end
+					
+					yield name, arguments
+				end
+			end
+			
+			class Client
+				def self.default
+					self.new([
+						[Extension::Compression, {}]
+					])
+				end
+				
+				def initialize(extensions = [])
+					@extensions = extensions
+					@accepted = []
+				end
+				
+				attr :extensions
+				attr :accepted
+				
+				def named
+					@extensions.map do |extension|
+						[extension.first::NAME, extension]
+					end.to_h
+				end
+				
+				def offer
+					@extensions.each do |extension, options|
+						if header = extension.offer(**options)
+							yield header
+						end
+					end
+				end
+				
+				def accept(headers)
+					named = self.named
+					
+					# Each response header should map to at least one extension.
+					Extensions.parse(headers) do |name, arguments|
+						if extension = named.delete(name)
+							klass, options = extension
+							
+							klass.accept(arguments, **options)
+							
+							@accepted << [klass, options]
+						end
+					end
+				end
+				
+				def apply(connection)
+					@accepted.each do |(klass, options)|
+						klass.server(connection, **options)
+					end
+				end
+			end
+			
+			class Server
+				def self.default
+					self.new([
+						[Extension::Compression, {}]
+					])
+				end
+				
+				def initialize(extensions)
+					@extensions = extensions
+					@accepted = []
+				end
+				
+				attr :extensions
+				attr :accepted
+				
+				def named
+					@extensions.map do |extension|
+						[extension.first::NAME, extension]
+					end.to_h
+				end
+				
+				def accept(headers)
+					extensions = []
+					
+					named = self.named
+					response = []
+					
+					# Each response header should map to at least one extension.
+					Extensions.parse(headers) do |name, arguments|
+						if extension = named[name]
+							klass, options = extension
+							
+							if header = klass.negotiate(arguments, **options)
+								# The extension is accepted and no further offers will be considered:
+								named.delete(name)
+								
+								yield header
+								
+								@accepted << [klass, options]
+							end
+						end
+					end
+					
+					return headers
+				end
+				
+				def apply(connection)
+					@accepted.reverse_each do |(klass, options)|
+						klass.server(connection, **options)
+					end
+				end
+			end
+		end
+	end
+end

data/lib/protocol/websocket/frame.rb

@@ -25,11 +25,22 @@ module Protocol
 		class Frame
 			include Comparable
 			
-			OPCODE = 0
+			RSV1 = 0b0100
+			RSV2 = 0b0010
+			RSV3 = 0b0001
+			RESERVED = RSV1 | RSV2 | RSV3
 			
-			# @param length [Integer] the length of the payload, or nil if the header has not been read yet.
-			def initialize(finished = true, payload = nil, opcode: self.class::OPCODE, mask: false)
+			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
+					mask = SecureRandom.bytes(4)
+				end
+				
 				@finished = finished
+				@flags = flags
 				@opcode = opcode
 				@mask = mask
 				@length = payload&.bytesize
@@ -41,11 +52,11 @@ module Protocol
 			end
 			
 			def to_ary
-				[@finished, @opcode, @mask, @length, @payload]
+				[@finished, @flags, @opcode, @mask, @length, @payload]
 			end
 			
 			def control?
-				@opcode & 0x8
+				@opcode & 0x8 != 0
 			end
 			
 			def data?
@@ -82,6 +93,7 @@ module Protocol
 			# +---------------------------------------------------------------+
 			
 			attr_accessor :finished
+			attr_accessor :flags
 			attr_accessor :opcode
 			attr_accessor :mask
 			attr_accessor :length
@@ -93,9 +105,9 @@ module Protocol
 				if length.bit_length > 63
 					raise ProtocolError, "Frame length #{@length} bigger than allowed maximum!"
 				end
-
+				
 				if @mask
-					@payload = String.new.b
+					@payload = String.new(encoding: Encoding::BINARY)
 					
 					for i in 0...data.bytesize do
 						@payload << (data.getbyte(i) ^ mask.getbyte(i % 4))
@@ -106,11 +118,13 @@ module Protocol
 					@payload = data
 					@length = length
 				end
+				
+				return self
 			end
 			
 			def unpack
-				if @mask
-					data = String.new.b
+				if @mask and !@payload.empty?
+					data = String.new(encoding: Encoding::BINARY)
 					
 					for i in 0...@payload.bytesize do
 						data << (@payload.getbyte(i) ^ @mask.getbyte(i % 4))
@@ -130,19 +144,33 @@ module Protocol
 				byte = buffer.unpack("C").first
 				
 				finished = (byte & 0b1000_0000 != 0)
-				# rsv = byte & 0b0111_0000
+				flags = (byte & 0b0111_0000) >> 4
 				opcode = byte & 0b0000_1111
 				
-				return finished, opcode
+				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, opcode, stream, maximum_frame_size)
+			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
@@ -165,11 +193,11 @@ module Protocol
 					raise EOFError, "Incorrect payload length: #{@length} != #{@payload.bytesize}!"
 				end
 				
-				return self.new(finished, payload, opcode: opcode, mask: mask)
+				return self.new(finished, payload, flags: flags, opcode: opcode, mask: mask)
 			end
 			
 			def write(stream)
-				buffer = String.new.b
+				buffer = String.new(encoding: Encoding::BINARY)
 				
 				if @payload&.bytesize != @length
 					raise ProtocolError, "Invalid payload length: #{@length} != #{@payload.bytesize} for #{self}!"
@@ -188,7 +216,7 @@ module Protocol
 				end
 				
 				buffer << [
-					(@finished ? 0b1000_0000 : 0) | @opcode,
+					(@finished ? 0b1000_0000 : 0) | (@flags << 4) | @opcode,
 					(@mask ? 0b1000_0000 : 0) | short_length,
 				].pack('CC')
 				

data/lib/protocol/websocket/framer.rb

@@ -29,7 +29,7 @@ require_relative 'pong_frame'
 
 module Protocol
 	module WebSocket
-		# HTTP/2 frame type mapping as defined by the spec
+		# HTTP/2 frame type mapping as defined by the spec.
 		FRAMES = {
 			0x0 => ContinuationFrame,
 			0x1 => TextFrame,
@@ -39,8 +39,10 @@ module Protocol
 			0xA => PongFrame,
 		}.freeze
 		
+		# The maximum allowed frame size in bytes.
 		MAXIMUM_ALLOWED_FRAME_SIZE = 2**63
 		
+		# Wraps an underlying {Async::IO::Stream} for reading and writing binary data into structured frames.
 		class Framer
 			def initialize(stream, frames = FRAMES)
 				@stream = stream
@@ -55,13 +57,15 @@ module Protocol
 				@stream.flush
 			end
 			
+			# Read a frame from the underlying stream.
+			# @returns [Frame] 
 			def read_frame(maximum_frame_size = MAXIMUM_ALLOWED_FRAME_SIZE)
 				# Read the header:
-				finished, opcode = read_header
+				finished, flags, opcode = read_header
 				
 				# Read the frame:
 				klass = @frames[opcode] || Frame
-				frame = klass.read(finished, opcode, @stream, maximum_frame_size)
+				frame = klass.read(finished, flags, opcode, @stream, maximum_frame_size)
 				
 				return frame
 			end

data/lib/protocol/websocket/headers.rb

@@ -27,13 +27,17 @@ module Protocol
 			# The protocol string used for the `upgrade:` header (HTTP/1) and `:protocol` pseudo-header (HTTP/2).
 			PROTOCOL = "websocket".freeze
 			
-			# These general headers are used to negotiate the connection.
+			# The WebSocket protocol header, used for application level protocol negotiation.
 			SEC_WEBSOCKET_PROTOCOL = 'sec-websocket-protocol'.freeze
+			
+			# The WebSocket version header. Used for negotiating binary protocol version.
 			SEC_WEBSOCKET_VERSION = 'sec-websocket-version'.freeze
 			
 			SEC_WEBSOCKET_KEY = 'sec-websocket-key'.freeze
 			SEC_WEBSOCKET_ACCEPT = 'sec-websocket-accept'.freeze
 			
+			SEC_WEBSOCKET_EXTENSIONS = 'sec-websocket-extensions'.freeze
+			
 			module Nounce
 				GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
 				

data/lib/protocol/websocket/ping_frame.rb

@@ -26,10 +26,13 @@ module Protocol
 		class PingFrame < Frame
 			OPCODE = 0x9
 			
-			def reply
-				PongFrame.new(true, @payload, mask: @mask)
+			# Generate a suitable reply.
+			# @returns [PongFrame]
+			def reply(**options)
+				PongFrame.new(true, self.unpack, **options)
 			end
 			
+			# Apply this frame to the specified connection.
 			def apply(connection)
 				connection.receive_ping(self)
 			end

data/lib/protocol/websocket/pong_frame.rb

@@ -25,6 +25,7 @@ module Protocol
 		class PongFrame < Frame
 			OPCODE = 0xA
 			
+			# Apply this frame to the specified connection.
 			def apply(connection)
 				connection.receive_pong(self)
 			end

data/lib/protocol/websocket/text_frame.rb

@@ -22,6 +22,7 @@ require_relative 'frame'
 
 module Protocol
 	module WebSocket
+		# Implements the text frame for sending and receiving text.
 		class TextFrame < Frame
 			OPCODE = 0x1
 			
@@ -29,14 +30,19 @@ module Protocol
 				true
 			end
 			
-			def unpack
-				super.force_encoding(Encoding::UTF_8)
-			end
-			
-			def pack(data)
-				super(data.b)
+			# Decode the binary buffer into a suitable text message.
+			# @parameter buffer [String] The binary data to unpack.
+			def read_message(buffer)
+				buffer.force_encoding(Encoding::UTF_8)
+				
+				unless buffer.valid_encoding?
+					raise ProtocolError, "invalid UTF-8 in text frame!"
+				end
+				
+				buffer
 			end
 			
+			# Apply this frame to the specified connection.
 			def apply(connection)
 				connection.receive_text(self)
 			end

data/lib/protocol/websocket/version.rb

@@ -20,6 +20,6 @@
 
 module Protocol
 	module WebSocket
-		VERSION = "0.7.3"
+		VERSION = "0.8.0"
 	end
 end

data/lib/protocol/websocket.rb

@@ -20,3 +20,4 @@
 
 require_relative 'websocket/version'
 require_relative 'websocket/framer'
+require_relative 'websocket/connection'

data.tar.gz.sig

@@ -0,0 +1,3 @@
+}�	*>��K��X�a��*3��j���ss�U��0p2�����SE�j9�*�{�b��v��z��	�π�hf<}�>Ɩȶ����us9�v��i�P���TB<�s^�W�AP!��*{����c�P��_�9�K*�{"(�T&%(�hy�g�M3lR4�C�sά�m�ڤ����`�4*/v
+�`�LA0�d��R�U�ޥ��������������������8<I
+x���軦�_����%uW>2��Z�*��C�"`0Ƞ[�`�M�C���F�F���7.aq��f��u˄!��������'�]�Q@�c�
+�
��(���l�33MΩ:�w�C'����~r�AfC
*���4yp���z���\JZ�%�;]c��

metadata

@@ -1,14 +1,47 @@
 --- !ruby/object:Gem::Specification
 name: protocol-websocket
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.8.0
 platform: ruby
 authors:
 - Samuel Williams
-autorequire: 
+- Aurora
+- Soumya
+- Olle Jonsson
+- William T. Nelson
+autorequire:
 bindir: bin
-cert_chain: []
-date: 2019-07-13 00:00:00.000000000 Z
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
+  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
+  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
+  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
+  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
+  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
+  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
+  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
+  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
+  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
+  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
+  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
+  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
+  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
+  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
+  cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
+  xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
+  c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
+  8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
+  JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
+  eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
+  Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
+  voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
+  -----END CERTIFICATE-----
+date: 2022-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: protocol-http
@@ -39,7 +72,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.2'
 - !ruby/object:Gem::Dependency
-  name: covered
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -53,7 +86,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: covered
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -66,20 +99,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -94,25 +113,23 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: 
+description:
 email:
-- samuel.williams@oriontransfer.co.nz
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".rspec"
-- ".travis.yml"
-- Gemfile
-- README.md
-- Rakefile
 - lib/protocol/websocket.rb
 - lib/protocol/websocket/binary_frame.rb
 - lib/protocol/websocket/close_frame.rb
 - lib/protocol/websocket/connection.rb
 - lib/protocol/websocket/continuation_frame.rb
 - lib/protocol/websocket/error.rb
+- lib/protocol/websocket/extension/compression.rb
+- lib/protocol/websocket/extension/compression/deflate.rb
+- lib/protocol/websocket/extension/compression/inflate.rb
+- lib/protocol/websocket/extensions.md
+- lib/protocol/websocket/extensions.rb
 - lib/protocol/websocket/frame.rb
 - lib/protocol/websocket/framer.rb
 - lib/protocol/websocket/headers.rb
@@ -120,12 +137,11 @@ files:
 - lib/protocol/websocket/pong_frame.rb
 - lib/protocol/websocket/text_frame.rb
 - lib/protocol/websocket/version.rb
-- protocol-websocket.gemspec
 homepage: https://github.com/socketry/protocol-websocket
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -133,15 +149,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.3.7
+signing_key:
 specification_version: 4
 summary: A low level implementation of the WebSocket protocol.
 test_files: []

data/.gitignore

@@ -1,13 +0,0 @@
-/.bundle/
-/.yardoc
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-
-# rspec failure tracking
-.rspec_status
-Gemfile.lock
-.covered.db

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---warnings
---require spec_helper

data/.travis.yml

@@ -1,19 +0,0 @@
-language: ruby
-dist: xenial
-cache: bundler
-
-matrix:
-  include:
-    - rvm: 2.4
-    - rvm: 2.5
-    - rvm: 2.6
-    - rvm: 2.6
-      env: COVERAGE=PartialSummary,Coveralls
-    - rvm: truffleruby
-    - rvm: jruby-head
-      env: JRUBY_OPTS="--debug -X+O"
-    - rvm: ruby-head
-  allow_failures:
-    - rvm: truffleruby
-    - rvm: ruby-head
-    - rvm: jruby-head

data/Gemfile

@@ -1,4 +0,0 @@
-source "https://rubygems.org"
-
-# Specify your gem's dependencies in protocol-websocket.gemspec
-gemspec

data/README.md

@@ -1,64 +0,0 @@
-# Protocol::WebSocket
-
-Provides a low-level implementation of the WebSocket protocol according to [RFC6455](https://tools.ietf.org/html/rfc6455). It only implements the latest stable version (13).
-
-[![Build Status](https://travis-ci.com/socketry/protocol-websocket.svg?branch=master)](http://travis-ci.com/socketry/protocol-websocket)
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'protocol-websocket'
-```
-
-And then execute:
-
-	$ bundle
-
-Or install it yourself as:
-
-	$ gem install protocol-websocket
-
-## Usage
-
-Here is a basic WebSocket client:
-
-```ruby
-stream = # connect to remote system
-framer = Protocol::WebSocket::Framer.new(stream)
-
-frame = framer.read_frame
-```
-
-## Contributing
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
-
-## License
-
-Released under the MIT license.
-
-Copyright, 2019, by [Samuel G. D. Williams](http://www.codeotaku.com/samuel-williams).  
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.

data/Rakefile

@@ -1,6 +0,0 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-task :default => :spec

data/protocol-websocket.gemspec

@@ -1,28 +0,0 @@
-
-require_relative "lib/protocol/websocket/version"
-
-Gem::Specification.new do |spec|
-	spec.name          = "protocol-websocket"
-	spec.version       = Protocol::WebSocket::VERSION
-	spec.authors       = ["Samuel Williams"]
-	spec.email         = ["samuel.williams@oriontransfer.co.nz"]
-	
-	spec.summary       = "A low level implementation of the WebSocket protocol."
-	spec.homepage      = "https://github.com/socketry/protocol-websocket"
-	spec.license       = "MIT"
-	
-	spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-		`git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-	end
-	
-	spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-	spec.require_paths = ["lib"]
-	
-	spec.add_dependency "protocol-http", "~> 0.2"
-	spec.add_dependency "protocol-http1", "~> 0.2"
-	
-	spec.add_development_dependency "covered"
-	spec.add_development_dependency "bundler"
-	spec.add_development_dependency "rake", "~> 10.0"
-	spec.add_development_dependency "rspec", "~> 3.0"
-end