protocol-websocket 0.15.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec6ec828408c7579273d456c0a9ce582a794757b5c532e228c45eca4779acee1
-  data.tar.gz: 5abe7c8dcb8e1e5cd64e62e06cb0f7585ec0fa8646baf4cecaa6945542cf8b33
+  metadata.gz: 6c565e42a63322140910616237842446c9faf392325569500454cff2bcfe500d
+  data.tar.gz: db2129c90eb70609ef3b14f62c5a8f261cca9d4e5796be21c15ed24f545f3a19
 SHA512:
-  metadata.gz: e5daf9a48e29e811b255516dd777fafbbdf084c8ed681d81ebe2fc67eead205702186b42231abfa032060afc62d439a2e6c8c90d1696eec58be37c40cf52d2a9
-  data.tar.gz: 6dc89a62a3179b9e2d397cac57204a5d73897ada519abba42d3f85ec184c6f74c1c2f26d81b2ef5277c0fa4b17c35cf283019f99e9a01537d32fece66c76db2b
+  metadata.gz: 68c058f51adbcadb882cfd139bc88a0dbdb0d1024d3c7cc62794796e83ab730340b72289f505f5fcd1d213cda0901f4b16aaee42c899c25ffca57e3baa057078
+  data.tar.gz: 80121ca724e4f275a88479d4778aa35070b0ddc62660ad4acda47247a1ed7461137a5227e65ea8c3569120a0bf98ff0c0a24b33039d4cf67602b825c2289891a

data/lib/protocol/websocket/close_frame.rb

@@ -59,6 +59,14 @@ module Protocol
 				end
 			end
 			
+			# Generate a suitable reply.
+			# @returns [CloseFrame]
+			def reply(code = Error::NO_ERROR, reason = "")
+				frame = CloseFrame.new
+				frame.pack(code, reason)
+				return frame
+			end
+			
 			# Apply this frame to the specified connection.
 			def apply(connection)
 				connection.receive_close(self)

data/lib/protocol/websocket/connection.rb

@@ -89,13 +89,34 @@ module Protocol
 				@state == :closed
 			end
 			
-			# Immediately transition the connection to the closed state *and* close the underlying connection.
+			# Immediately transition the connection to the closed state *and* close the underlying connection. Any data not yet read will be lost.
 			def close(...)
 				close!(...)
 				
 				@framer.close
 			end
 			
+			# Close the connection gracefully, sending a close frame with the specified error code and reason. If an error occurs while sending the close frame, the connection will be closed immediately. You may continue to read data from the connection after calling this method, but you should not write any more data.
+			#
+			# @parameter error [Error | Nil] The error that occurred, if any.
+			def close_write(error = nil)
+				if error
+					send_close(Error::INTERNAL_ERROR, error.message)
+				else
+					send_close
+				end
+			end
+			
+			# Close the connection gracefully. This will send a close frame and wait for the remote end to respond with a close frame. Any data received after the close frame is sent will be ignored. If you want to process this data, use {#close_write} instead, and read the data before calling {#close}.
+			def shutdown
+				send_close unless @state == :closed
+				
+				# `read_frame` will return nil after receiving a close frame:
+				while read_frame
+					# Drain the connection.
+				end
+			end
+			
 			# Read a frame from the framer, and apply it to the connection.
 			def read_frame
 				return nil if closed?
@@ -244,16 +265,19 @@ module Protocol
 			# Write a message to the connection.
 			# @parameter message [Message] The message to send.
 			def write(message, **options)
+				case message
+				when String
 				# 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
+				when Message
+					message.send(self, **options)
+				else
+					raise ArgumentError, "Unsupported message type: #{message}"
 				end
-				
-				message.send(self, **options)
 			end
 			
 			# The default implementation for reading a message buffer. This is used by the {#reader} interface.

data/lib/protocol/websocket/error.rb

@@ -19,10 +19,24 @@ module Protocol
 			# Indicates that an endpoint is terminating the connection due to a protocol error.
 			PROTOCOL_ERROR = 1002
 			
-			# Indicates that an endpoint is terminating the connection because it has received a type of data it cannot accept.
+			# Indicates that an endpoint is terminating the connection because it has received a type of data it cannot accept. (e.g., an endpoint that understands only text data MAY send this if it receives a binary message).
 			INVALID_DATA = 1003
 			
-			# There are other status codes but most of them are "implementation specific".
+			
+			# Indicates that an endpoint is terminating the connection because it has received data within a message that was not consistent with the type of the message (e.g., non-UTF-8 data within a text message).
+			INVALID_PAYLOAD = 1007
+			
+			# Indicates that an endpoint is terminating the connection because it has received a message that violates its policy. This is a generic status code that can be returned when there is no other more suitable status code (e.g., 1003 or 1009) or if there is a need to hide specific details about the policy.
+			POLICY_VIOLATION = 1008
+			
+			# Indicates that an endpoint is terminating the connection because it has received a message that is too big for it to process.
+			MESSAGE_TOO_LARGE = 1009
+			
+			# Indicates that an endpoint (client) is terminating the connection because it has expected the server to negotiate one or more extension, but the server didn't return them in the response message of the WebSocket handshake. The list of extensions that are needed should appear in the /reason/ part of the Close frame. Note that this status code is not used by the server, because it can fail the WebSocket handshake instead.
+			MISSING_EXTENSION = 1010
+			
+			# Indicates that a server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request.
+			INTERNAL_ERROR = 1011
 		end
 		
 		# Raised by stream or connection handlers, results in GOAWAY frame which signals termination of the current connection. You *cannot* recover from this exception, or any exceptions subclassed from it.

data/lib/protocol/websocket/message.rb

@@ -56,13 +56,14 @@ module Protocol
 			def to_h(...)
 				parse(...).to_h
 			end
+			
+			def send(connection, **options)
+				connection.send_text(@buffer, **options)
+			end
 		end
 		
 		# Represents a text message that can be sent or received over a WebSocket connection.
 		class TextMessage < Message
-			def send(connection, **options)
-				connection.send_text(@buffer, **options)
-			end
 		end
 		
 		# Represents a binary message that can be sent or received over a WebSocket connection.

data/lib/protocol/websocket/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module WebSocket
-		VERSION = "0.15.0"
+		VERSION = "0.17.0"
 	end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-websocket
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -41,7 +41,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-07-03 00:00:00.000000000 Z
+date: 2024-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: protocol-http