protocol-websocket 0.7.4 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 519265fe5ebe9530d3ddec6e9bc3836dd0a2af827e377ef4ac7f390f5791f2a9
-  data.tar.gz: 32a7ab9ab4e4b065ee6b0f738396ea575b49da9c8ac927ee38da8afa1ab595fb
+  metadata.gz: 1c466ba64c434d16b197dacfb48341ab14eca48ba5aefde4cf06df4f10be84fc
+  data.tar.gz: 3d470e57b3c94936ec31adce97e829550344e6345de423f0d3c51915d951d782
 SHA512:
-  metadata.gz: 5f5e59c42893bf46ba3581f4a44952c919b56d94db139b558fd6fafa3d4c360d52d58741da99fb456afe72fb8679c27a4f22eaf551b014b4e774dd5cb31f39ff
-  data.tar.gz: '08611be52a6cbbfb10ec656bf820bc3241afb626de9aa9fb2ce19f9efa21e3d5f38bfe6f5f1b86f7ec184355bd236505469705559d7e234c4d3a8f04d5b536fa'
+  metadata.gz: 271a7a12c932857ea8887e67d7303a008852cc700e2d3bea0cbf96a6f30c53b8cae442f62877f4ad89c215dfb5bae81c0948da6b3cd5c267304dc368d795e542
+  data.tar.gz: 826444b74fd01885c66389a1c08b8b2cb99617662c3e364453d4d1572fa0237447d70d196fc867bde6231bc11efd6b47c874619bafe1efa800bcc1304a055329

checksums.yaml.gz.sig

@@ -0,0 +1,3 @@
+��\`��W��y0!�l���i�Xu�����R|
+#��v@���]�x�i�����G0#/öV�tC��,�|K�����ˈ�Xb3B�7Dlk� b{�tV
+z!�%��BY��]	�~!�q@P�����
{oc������EsACf_�ѻ>��t�6� ?𯭴�v��ES����`��F�4�5,|q�ԃ�,[U+,

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,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)
@@ -107,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
 			
@@ -161,7 +163,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,34 +177,60 @@ 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)
 				
-				# 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_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)
 				
-				while read_frame
-					if @frames.last&.finished?
-						buffer = @frames.map(&:unpack).join
-						@frames = []
-						
-						return buffer
+				return frame
+			end
+			
+			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)
+				
+				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)
+				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
@@ -210,9 +238,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