protocol-websocket 0.7.5 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d2733227a287e2dfb58f393566e6afea44470aba32c7a8eda8bd9a8f25c2d72
-  data.tar.gz: bdd0966fcc837f1314cf2b88e55699f2de57e6d6af36ecbe3bcdf0c12350935a
+  metadata.gz: 0ca30621d2f489b08f475047f539d2fe048661dbe2b109a8d0ef441c6e95ed37
+  data.tar.gz: fe325e6b9041103c704cf912f73f3838c2e9d50af6368b2db54e280906600aa4
 SHA512:
-  metadata.gz: a3fdd8546a648fa96663aafe278499e3a19266d1dfd9d2c68cd6d330f24c8af7d31ee94fd88c632a4bddec85dd56456980bf5a27d02197548279e069eae3d515
-  data.tar.gz: 2b4faa47644b9811dab2d856831176b282c83df85863fad5db5a7b28055b123230ac89ae2e29eb3529843fec12d80ec11f26b2894ca85a2f243eef2d09bf10fb
+  metadata.gz: 35a0841efafc3a3b1fb98cbfdccff848a51262cf3e493d78cb95c4f300a1ced40779837d51e31edfd5d2cc3626b4ad22fd9f1066bcedfd4b9d8d460d44e9ddf4
+  data.tar.gz: 1528871ed4e31683e9334eb91096d7ad6cf592d60020bd151e70e93324d727067dfc2a62c8ec8471ba3f3f56e289cc95890f7a6d89e32afce62c2a5fd55506fc

checksums.yaml.gz.sig

@@ -0,0 +1,3 @@
+[�uy�jZ�L!=�5C���14���r��{���i���ij��1��I��|�żKU��(���][�H����q\��yB�C�3J�3�*���Lf�rEc��oa�$qVY;PWcG^M'^*c��(�
4�Fy�����G��q1�o��Ǵ��Z���i�b��S
+�&{�\S�s^C��1�<S
�GRbxD�
+3OEI}��"�ͿՓ�}w�Ɖ0�s#�-f��Q�Y���$~ʲa����/I��˩&s���t���&��E�,#�kzD�*<�

data/lib/protocol/websocket/binary_frame.rb

@@ -19,6 +19,7 @@
 # THE SOFTWARE.
 
 require_relative 'frame'
+require_relative 'message'
 
 module Protocol
 	module WebSocket
@@ -29,6 +30,10 @@ module Protocol
 				true
 			end
 			
+			def read_message(buffer)
+				return BinaryMessage.new(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,14 +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
 			# @parameter mask [String] 4-byte mask to be used for frames generated by this connection.
-			def initialize(framer, mask: nil)
+			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.
@@ -39,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
@@ -50,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
@@ -61,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)
@@ -105,38 +131,16 @@ module Protocol
 					raise ProtocolError, "Received unexpected continuation!"
 				end
 			end
-			
-			def send_text(buffer)
-				frame = TextFrame.new(mask: @mask)
-				frame.pack buffer
-				
-				write_frame(frame)
-			end
-			
-			def send_binary(buffer)
-				frame = BinaryFrame.new(mask: @mask)
-				frame.pack buffer
-				
-				write_frame(frame)
-			end
-			
-			def send_close(code = Error::NO_ERROR, message = nil)
-				frame = CloseFrame.new(mask: @mask)
-				frame.pack(code, message)
-				
-				self.write_frame(frame)
-				self.flush
-				
-				@state = :closed
-			end
-			
+					
 			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
 			
@@ -173,34 +177,61 @@ module Protocol
 				warn "Unhandled frame #{frame.inspect}"
 			end
 			
-			# @param buffer [String] a unicode or binary string.
-			def write(buffer)
-				# https://tools.ietf.org/html/rfc6455#section-5.6
+			def pack_text_frame(buffer, **options)
+				frame = TextFrame.new(mask: @mask)
+				frame.pack(buffer)
+				
+				return frame
+			end
+			
+			def send_text(buffer, **options)
+				write_frame(@writer.pack_text_frame(buffer, **options))
+			end
+			
+			def pack_binary_frame(buffer, **options)
+				frame = BinaryFrame.new(mask: @mask)
+				frame.pack(buffer)
 				
-				# Text: The "Payload data" is text data encoded as UTF-8
-				if buffer.encoding == Encoding::UTF_8
-					send_text(buffer)
-				else
-					send_binary(buffer)
-				end
+				return frame
 			end
 			
-			# @return [String] a unicode or binary string.
-			def read
-				@framer.flush
+			def send_binary(buffer, **options)
+				write_frame(@writer.pack_binary_frame(buffer, **options))
+			end
+			
+			def send_close(code = Error::NO_ERROR, reason = "")
+				frame = CloseFrame.new(mask: @mask)
+				frame.pack(code, reason)
 				
-				while read_frame
-					if @frames.last&.finished?
-						buffer = @frames.map(&:unpack).join
-						@frames = []
-						
-						return buffer
+				self.write_frame(frame)
+				self.flush
+				
+				@state = :closed
+			end
+			
+			# Write a message to the connection.
+			# @parameter message [Message] The message to send.
+			def write(message, **options)
+				# This is a compatibility shim for the previous implementation. We may want to eventually deprecate this use case... or maybe it's convenient enough to leave it around.
+				if message.is_a?(String)
+					if message.encoding == Encoding::UTF_8
+						return send_text(message, **options)
+					else
+						return send_binary(message, **options)
 					end
 				end
+				
+				message.send(self, **options)
+			end
+			
+			# The default implementation for reading a message buffer.
+			def unpack_frames(frames)
+				frames.map(&:unpack).join("")
 			end
 			
-			# Deprecated.
-			def next_message
+			# Read a message from the connection.
+			# @returns message [Message] The received message.
+			def read(**options)
 				@framer.flush
 				
 				while read_frame
@@ -208,9 +239,14 @@ module Protocol
 						frames = @frames
 						@frames = []
 						
-						return frames
+						buffer = @reader.unpack_frames(frames, **options)
+						return frames.first.read_message(buffer)
 					end
 				end
+			rescue ProtocolError => error
+				send_close(error.code, error.message)
+				
+				raise
 			end
 		end
 	end

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

@@ -0,0 +1,34 @@
+# 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
+				NAME = 'permessage-deflate'
+								
+				# Zlib is not capable of handling < 9 window bits.
+				MINIMUM_WINDOW_BITS = 9
+			end
+		end
+	end
+end

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

@@ -0,0 +1,105 @@
+# 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 'constants'
+
+module Protocol
+	module WebSocket
+		module Extension
+			module Compression
+				class Deflate
+					# Client writing to server.
+					def self.client(parent, client_max_window_bits: 15, client_no_context_takeover: false, **options)
+						self.new(parent,
+							window_bits: client_max_window_bits,
+							context_takeover: !client_no_context_takeover,
+							**options
+						)
+					end
+					
+					# Server writing to client.
+					def self.server(parent, server_max_window_bits: 15, server_no_context_takeover: false, **options)
+						self.new(parent,
+							window_bits: server_max_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
+						
+						@level = level
+						@memory_level = memory_level
+						@strategy = strategy
+						
+						if window_bits < MINIMUM_WINDOW_BITS
+							window_bits = MINIMUM_WINDOW_BITS
+						end
+						
+						@window_bits = window_bits
+						@context_takeover = context_takeover
+					end
+					
+					def inspect
+						"#<#{self.class} window_bits=#{@window_bits} context_takeover=#{@context_takeover}>"
+					end
+					
+					attr :window_bits
+					attr :context_takeover
+					
+					def pack_text_frame(buffer, compress: true, **options)
+						buffer = self.deflate(buffer)
+						
+						frame = @parent.pack_text_frame(buffer, **options)
+						
+						frame.flags |= Frame::RSV1
+						
+						return frame
+					end
+					
+					def pack_binary_frame(buffer, compress: false, **options)
+						buffer = self.deflate(buffer)
+						
+						frame = @parent.pack_binary_frame(buffer, **options)
+						
+						frame.flags |= Frame::RSV1
+						
+						return frame
+					end
+					
+					private
+					
+					def deflate(buffer)
+						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,91 @@
+# 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 'constants'
+
+module Protocol
+	module WebSocket
+		module Extension
+			module Compression
+				class Inflate
+					# Client reading from server.
+					def self.client(parent, server_max_window_bits: 15, server_no_context_takeover: false, **options)
+						self.new(parent,
+							window_bits: server_max_window_bits,
+							context_takeover: !server_no_context_takeover,
+						)
+					end
+					
+					# Server reading from client.
+					def self.server(parent, client_max_window_bits: 15, client_no_context_takeover: false, **options)
+						self.new(parent,
+							window_bits: client_max_window_bits,
+							context_takeover: !client_no_context_takeover,
+						)
+					end
+					
+					TRAILER = [0x00, 0x00, 0xff, 0xff].pack('C*')
+					
+					def initialize(parent, context_takeover: true, window_bits: 15)
+						@parent = parent
+						
+						@inflate = nil
+						
+						if window_bits < MINIMUM_WINDOW_BITS
+							window_bits = MINIMUM_WINDOW_BITS
+						end
+						
+						@window_bits = window_bits
+						@context_takeover = context_takeover
+					end
+					
+					attr :window_bits
+					attr :context_takeover
+					
+					def unpack_frames(frames, **options)
+						buffer = @parent.unpack_frames(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)
+						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,137 @@
+# 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 'compression/constants'
+require_relative 'compression/inflate'
+require_relative 'compression/deflate'
+
+module Protocol
+	module WebSocket
+		module Extension
+			module Compression
+				# 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_max_window_bits: true, server_max_window_bits: true, client_no_context_takeover: false, server_no_context_takeover: false)
+					
+					header = [NAME]
+					
+					case client_max_window_bits
+					when 8..15
+						header << "client_max_window_bits=#{client_max_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_max_window_bits
+					when 8..15
+						header << "server_max_window_bits=#{server_max_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] = true
+							header << key
+						when "client_no_context_takeover"
+							options[:client_no_context_takeover] = true
+							header << key
+						when "server_max_window_bits"
+							value = Integer(value || 15)
+							value = MINIMUM_WINDOW_BITS if value < MINIMUM_WINDOW_BITS
+							options[:server_max_window_bits] = value
+							header << "server_max_window_bits=#{value}"
+						when "client_max_window_bits"
+							value = Integer(value || 15)
+							value = MINIMUM_WINDOW_BITS if value < MINIMUM_WINDOW_BITS
+							options[:client_max_window_bits] = value
+							header << "client_max_window_bits=#{value}"
+						else
+							raise ArgumentError, "Unknown option #{key}!"
+						end
+					end
+					
+					# The header which represents the final accepted/negotiated configuration.
+					return header, options
+				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] = true
+						when "client_no_context_takeover"
+							options[:client_no_context_takeover] = true
+						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
+					
+					return options
+				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,148 @@
+# 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
+							
+							options = klass.accept(arguments, **options)
+							
+							@accepted << [klass, options]
+						end
+					end
+				end
+				
+				def apply(connection)
+					@accepted.each do |(klass, options)|
+						klass.client(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 result = klass.negotiate(arguments, **options)
+								header, options = result
+								
+								# 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,16 +25,22 @@ module Protocol
 		class Frame
 			include Comparable
 			
-			OPCODE = 0
+			RSV1 = 0b0100
+			RSV2 = 0b0010
+			RSV3 = 0b0001
+			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, opcode: self.class::OPCODE, mask: false)
+			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
@@ -46,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?
@@ -87,6 +93,7 @@ module Protocol
 			# +---------------------------------------------------------------+
 			
 			attr_accessor :finished
+			attr_accessor :flags
 			attr_accessor :opcode
 			attr_accessor :mask
 			attr_accessor :length
@@ -98,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))
@@ -111,11 +118,13 @@ module Protocol
 					@payload = data
 					@length = length
 				end
+				
+				return self
 			end
 			
 			def unpack
 				if @mask and !@payload.empty?
-					data = String.new.b
+					data = String.new(encoding: Encoding::BINARY)
 					
 					for i in 0...@payload.bytesize do
 						data << (@payload.getbyte(i) ^ @mask.getbyte(i % 4))
@@ -135,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
@@ -170,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}!"
@@ -193,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/json_message.rb

@@ -0,0 +1,47 @@
+# Copyright, 2022, 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 'json'
+
+require_relative 'message'
+
+module Protocol
+	module WebSocket
+		class JSONMessage < TextMessage
+			def self.wrap(message)
+				if message.is_a?(TextMessage)
+					self.new(message.buffer)
+				end
+			end
+			
+			def self.generate(object)
+				self.new(JSON.generate(object))
+			end
+			
+			def parse(symbolize_names: true, **options)
+				JSON.parse(@buffer, symbolize_names: symbolize_names, **options)
+			end
+			
+			def to_h
+				parse.to_h
+			end
+		end
+	end
+end

data/lib/protocol/websocket/message.rb

@@ -0,0 +1,62 @@
+# Copyright, 2022, 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 'frame'
+
+module Protocol
+	module WebSocket
+		class Message
+			def initialize(buffer)
+				@buffer = buffer
+			end
+			
+			attr :buffer
+			
+			def size
+				@buffer.bytesize
+			end
+			
+			# This can be helpful for writing tests.
+			def == other
+				@buffer == other.to_str
+			end
+			
+			def to_str
+				@buffer
+			end
+			
+			def encoding
+				@buffer.encoding
+			end
+		end
+		
+		class TextMessage < Message
+			def send(connection, **options)
+				connection.send_text(@buffer, **options)
+			end
+		end
+		
+		class BinaryMessage < Message
+			def send(connection, **options)
+				connection.send_binary(@buffer, **options)
+			end
+		end
+	end
+end

data/lib/protocol/websocket/ping_frame.rb

@@ -26,10 +26,13 @@ module Protocol
 		class PingFrame < Frame
 			OPCODE = 0x9
 			
+			# 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

@@ -19,9 +19,11 @@
 # THE SOFTWARE.
 
 require_relative 'frame'
+require_relative 'message'
 
 module Protocol
 	module WebSocket
+		# Implements the text frame for sending and receiving text.
 		class TextFrame < Frame
 			OPCODE = 0x1
 			
@@ -29,14 +31,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
+				
+				return TextMessage.new(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.5"
+		VERSION = "0.9.1"
 	end
 end

data/lib/protocol/websocket.rb

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

metadata

@@ -1,14 +1,47 @@
 --- !ruby/object:Gem::Specification
 name: protocol-websocket
 version: !ruby/object:Gem::Version
-  version: 0.7.5
+  version: 0.9.1
 platform: ruby
 authors:
 - Samuel Williams
+- Aurora
+- Soumya
+- Olle Jonsson
+- William T. Nelson
 autorequire:
 bindir: bin
-cert_chain: []
-date: 2020-09-10 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-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: protocol-http
@@ -67,34 +100,44 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: sus
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: 0.9.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: 0.9.1
 description:
 email:
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/.DS_Store
+- lib/protocol/.DS_Store
 - 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/constants.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
+- lib/protocol/websocket/json_message.rb
+- lib/protocol/websocket/message.rb
 - lib/protocol/websocket/ping_frame.rb
 - lib/protocol/websocket/pong_frame.rb
 - lib/protocol/websocket/text_frame.rb
@@ -118,7 +161,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: A low level implementation of the WebSocket protocol.