protocol-websocket 0.16.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65d2f2f5247451bba72a1b622fff8caf46fb03d8843531eb107c0a46f4cc5ff1
-  data.tar.gz: 555d8a9a9a9cd09d678d5d04961af2134a06adf1bf32ba42d0ecb608e35528bb
+  metadata.gz: ef7b32c9de28a9b7486a004d8ae53739fbe34de345e32b7a5e4ff056df5c755c
+  data.tar.gz: 2b8d07f45527f32e5a4b2cf0bb5d22707083a6fea94bedb1e93413aece140ee1
 SHA512:
-  metadata.gz: dd72ffc0701049551abe38408ae500f05dd2d32186cab990f49091e6600357b5c887903fd1e48b23b957b80f8d0deb4d9ddfcd8ac1b2b4c68eb5bbae63cbaf92
-  data.tar.gz: 647ec40540b3f991b79d96b13022f16c1b4fb7960d53b09cbf773a45b5d5726fbbe328a8129ff22e56c9805cd407d2e1bb998f9bc6dc29d1489d66a7b4dfc2b9
+  metadata.gz: dfef8b28cadd857f4d7430cb35e668f14789ce9d70fed4fa2c24c945ff9848ef9d35000e143b0344489c8120b4d940168a07e717a8da22738d1972f1f373bb8d
+  data.tar.gz: b3df54c2b5fa01963ffa5f26f15ddd16f3d983b20aeac9d1ee39fb60d052bfb720ee7963c2588708aebb6a9d649c29af81518f3af2bd1dc67c147b9fc6983673

data/lib/protocol/websocket/binary_frame.rb

@@ -4,8 +4,8 @@
 # Copyright, 2019-2024, by Samuel Williams.
 # Copyright, 2021, by Aurora Nockert.
 
-require_relative 'frame'
-require_relative 'message'
+require_relative "frame"
+require_relative "message"
 
 module Protocol
 	module WebSocket

data/lib/protocol/websocket/close_frame.rb

@@ -4,7 +4,7 @@
 # Copyright, 2019-2024, by Samuel Williams.
 # Copyright, 2021, by Aurora Nockert.
 
-require_relative 'frame'
+require_relative "frame"
 
 module Protocol
 	module WebSocket
@@ -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/coder/json.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2024, by Samuel Williams.
 
-require 'json'
+require "json"
 
 module Protocol
 	module WebSocket

data/lib/protocol/websocket/coder.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2024, by Samuel Williams.
 
-require_relative 'coder/json'
+require_relative "coder/json"
 
 module Protocol
 	module WebSocket

data/lib/protocol/websocket/connection.rb

@@ -5,8 +5,7 @@
 # Copyright, 2019, by William T. Nelson.
 # Copyright, 2021, by Aurora Nockert.
 
-require_relative 'framer'
-require 'securerandom'
+require_relative "framer"
 
 module Protocol
 	module WebSocket
@@ -89,13 +88,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?
@@ -246,7 +266,7 @@ module Protocol
 			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.
+					# 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.encoding == Encoding::UTF_8
 						return send_text(message, **options)
 					else

data/lib/protocol/websocket/continuation_frame.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2019-2024, by Samuel Williams.
 
-require_relative 'frame'
+require_relative "frame"
 
 module Protocol
 	module WebSocket

data/lib/protocol/websocket/error.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2019-2024, by Samuel Williams.
 
-require 'protocol/http/error'
+require "protocol/http/error"
 
 module Protocol
 	module WebSocket
@@ -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/extension/compression/constants.rb

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

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

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2023, by Samuel Williams.
+# Copyright, 2022-2024, by Samuel Williams.
 
-require_relative 'constants'
+require_relative "constants"
 
 module Protocol
 	module WebSocket

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

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2023, by Samuel Williams.
+# Copyright, 2022-2024, by Samuel Williams.
 
-require_relative 'constants'
+require_relative "constants"
 
 module Protocol
 	module WebSocket
@@ -26,7 +26,7 @@ module Protocol
 						)
 					end
 					
-					TRAILER = [0x00, 0x00, 0xff, 0xff].pack('C*')
+					TRAILER = [0x00, 0x00, 0xff, 0xff].pack("C*")
 					
 					def initialize(parent, context_takeover: true, window_bits: 15)
 						@parent = parent

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

@@ -3,9 +3,9 @@
 # Released under the MIT License.
 # Copyright, 2022-2024, by Samuel Williams.
 
-require_relative 'compression/constants'
-require_relative 'compression/inflate'
-require_relative 'compression/deflate'
+require_relative "compression/constants"
+require_relative "compression/inflate"
+require_relative "compression/deflate"
 
 module Protocol
 	module WebSocket
@@ -22,13 +22,13 @@ module Protocol
 					when 8..15
 						header << "client_max_window_bits=#{client_max_window_bits}"
 					when true
-						header << 'client_max_window_bits'
+						header << "client_max_window_bits"
 					else
 						raise ArgumentError, "Invalid local maximum window bits!"
 					end
 					
 					if client_no_context_takeover
-						header << 'client_no_context_takeover'
+						header << "client_no_context_takeover"
 					end
 					
 					case server_max_window_bits
@@ -41,7 +41,7 @@ module Protocol
 					end
 					
 					if server_no_context_takeover
-						header << 'server_no_context_takeover'
+						header << "server_no_context_takeover"
 					end
 					
 					return header

data/lib/protocol/websocket/extensions.rb

@@ -3,8 +3,8 @@
 # Released under the MIT License.
 # Copyright, 2022-2024, by Samuel Williams.
 
-require_relative 'extension/compression'
-require_relative 'headers'
+require_relative "extension/compression"
+require_relative "headers"
 
 module Protocol
 	module WebSocket
@@ -16,7 +16,7 @@ module Protocol
 					name, *arguments = header.split(/\s*;\s*/)
 					
 					arguments = arguments.map do |argument|
-						argument.split('=', 2)
+						argument.split("=", 2)
 					end
 					
 					yield name, arguments

data/lib/protocol/websocket/frame.rb

@@ -5,7 +5,7 @@
 # Copyright, 2019, by Soumya.
 # Copyright, 2021, by Aurora Nockert.
 
-require_relative 'error'
+require_relative "error"
 
 module Protocol
 	module WebSocket
@@ -178,10 +178,10 @@ module Protocol
 				
 				if length == 126
 					buffer = stream.read(2) or raise EOFError, "Could not read length!"
-					length = buffer.unpack('n').first
+					length = buffer.unpack("n").first
 				elsif length == 127
 					buffer = stream.read(8) or raise EOFError, "Could not read length!"
-					length = buffer.unpack('Q>').first
+					length = buffer.unpack("Q>").first
 				end
 				
 				if length > maximum_frame_size
@@ -223,12 +223,12 @@ module Protocol
 				buffer << [
 					(@finished ? 0b1000_0000 : 0) | (@flags << 4) | @opcode,
 					(@mask ? 0b1000_0000 : 0) | short_length,
-				].pack('CC')
+				].pack("CC")
 				
 				if short_length == 126
-					buffer << [@length].pack('n')
+					buffer << [@length].pack("n")
 				elsif short_length == 127
-					buffer << [@length].pack('Q>')
+					buffer << [@length].pack("Q>")
 				end
 				
 				buffer << @mask if @mask

data/lib/protocol/websocket/framer.rb

@@ -3,14 +3,14 @@
 # Released under the MIT License.
 # Copyright, 2019-2024, by Samuel Williams.
 
-require_relative 'frame'
+require_relative "frame"
 
-require_relative 'continuation_frame'
-require_relative 'text_frame'
-require_relative 'binary_frame'
-require_relative 'close_frame'
-require_relative 'ping_frame'
-require_relative 'pong_frame'
+require_relative "continuation_frame"
+require_relative "text_frame"
+require_relative "binary_frame"
+require_relative "close_frame"
+require_relative "ping_frame"
+require_relative "pong_frame"
 
 module Protocol
 	module WebSocket

data/lib/protocol/websocket/headers.rb

@@ -1,27 +1,27 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
-require 'digest/sha1'
-require 'securerandom'
+require "digest/sha1"
+require "securerandom"
 
 module Protocol
 	module WebSocket
 		module Headers
 			# The protocol string used for the `upgrade:` header (HTTP/1) and `:protocol` pseudo-header (HTTP/2).
-			PROTOCOL = "websocket".freeze
+			PROTOCOL = "websocket"
 			
 			# The WebSocket protocol header, used for application level protocol negotiation.
-			SEC_WEBSOCKET_PROTOCOL = 'sec-websocket-protocol'.freeze
+			SEC_WEBSOCKET_PROTOCOL = "sec-websocket-protocol"
 			
 			# The WebSocket version header. Used for negotiating binary protocol version.
-			SEC_WEBSOCKET_VERSION = 'sec-websocket-version'.freeze
+			SEC_WEBSOCKET_VERSION = "sec-websocket-version"
 			
-			SEC_WEBSOCKET_KEY = 'sec-websocket-key'.freeze
-			SEC_WEBSOCKET_ACCEPT = 'sec-websocket-accept'.freeze
+			SEC_WEBSOCKET_KEY = "sec-websocket-key"
+			SEC_WEBSOCKET_ACCEPT = "sec-websocket-accept"
 			
-			SEC_WEBSOCKET_EXTENSIONS = 'sec-websocket-extensions'.freeze
+			SEC_WEBSOCKET_EXTENSIONS = "sec-websocket-extensions"
 			
 			module Nounce
 				GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"

data/lib/protocol/websocket/message.rb

@@ -3,8 +3,8 @@
 # Released under the MIT License.
 # Copyright, 2022-2024, by Samuel Williams.
 
-require_relative 'frame'
-require_relative 'coder'
+require_relative "frame"
+require_relative "coder"
 
 module Protocol
 	module WebSocket
@@ -72,5 +72,12 @@ module Protocol
 				connection.send_binary(@buffer, **options)
 			end
 		end
+		
+		# Represents a ping message that can be sent over a WebSocket connection.
+		class PingMessage < Message
+			def send(connection)
+				connection.send_ping(@buffer)
+			end
+		end
 	end
 end

data/lib/protocol/websocket/ping_frame.rb

@@ -3,8 +3,8 @@
 # Released under the MIT License.
 # Copyright, 2019-2024, by Samuel Williams.
 
-require_relative 'frame'
-require_relative 'pong_frame'
+require_relative "frame"
+require_relative "pong_frame"
 
 module Protocol
 	module WebSocket

data/lib/protocol/websocket/pong_frame.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2019-2024, by Samuel Williams.
 
-require_relative 'frame'
+require_relative "frame"
 
 module Protocol
 	module WebSocket

data/lib/protocol/websocket/text_frame.rb

@@ -4,8 +4,8 @@
 # Copyright, 2019-2024, by Samuel Williams.
 # Copyright, 2021, by Aurora Nockert.
 
-require_relative 'frame'
-require_relative 'message'
+require_relative "frame"
+require_relative "message"
 
 module Protocol
 	module WebSocket

data/lib/protocol/websocket/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module WebSocket
-		VERSION = "0.16.0"
+		VERSION = "0.18.0"
 	end
 end

data/lib/protocol/websocket.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2019-2024, by Samuel Williams.
 
-require_relative 'websocket/version'
-require_relative 'websocket/framer'
-require_relative 'websocket/connection'
-require_relative 'websocket/message'
+require_relative "websocket/version"
+require_relative "websocket/framer"
+require_relative "websocket/connection"
+require_relative "websocket/message"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-websocket
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.18.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -41,7 +41,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-09-03 00:00:00.000000000 Z
+date: 2024-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: protocol-http
@@ -79,7 +79,6 @@ files:
 - 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

data/lib/protocol/websocket/json_message.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
-
-require_relative 'message'
-
-warn "Protocol::WebSocket::JSONMessage is deprecated. Use Protocol::WebSocket::TextMessage instead."
-
-module Protocol
-	module WebSocket
-		# @deprecated Use {TextMessage} instead.
-		class JSONMessage < TextMessage
-			def self.wrap(message)
-				message
-			end
-			
-			def self.generate(object)
-				self.new(JSON.generate(object))
-			end
-		end
-	end
-end