class Connection

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

attribute　Framer

The framer which is used for reading and writing frames.

attribute　String | Boolean | Nil

The optional mask which is used when generating frames.

attribute　Integer

The allowed reserved bits.

attribute　Array(Frame)

Buffered frames which form part of a complete message.

attribute　Object

The reader which is used to unpack frames into messages.

attribute　Object

The writer which is used to pack messages into frames.

parameter　bit　Integer

The bit to reserve, see RESERVED = RSV1 | RSV2 | RSV3 for more details.

def reserve!(bit)
	if (@reserved & bit).zero?
		raise ArgumentError, "Unable to use #{bit}!"
	end
	
	@reserved &= ~bit
	
	return true
end

def flush
	@framer.flush
end

def open!
	@state = :open
	
	return self
end

def close!(...)
	unless @state == :closed
		@state = :closed
		
		begin
			send_close(...)
		rescue
			# Ignore errors.
		end
	end
	
	return self
end

returns　Boolean

if the connection is in the closed state.

def closed?
	@state == :closed
end

def close(...)
	close!(...)
	
	@framer.close
end

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

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

def read_frame
	return nil if closed?
	
	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)
	
	return frame
rescue ProtocolError => error
	close(error.code, error.message)
	raise
rescue => error
	close(Error::PROTOCOL_ERROR, error.message)
	raise
end

def write_frame(frame)
	@framer.write_frame(frame)
	
	return frame
end

def receive_text(frame)
	if @frames.empty?
		@frames << frame
	else
		raise ProtocolError, "Received text, but expecting continuation!"
	end
end

def receive_binary(frame)
	if @frames.empty?
		@frames << frame
	else
		raise ProtocolError, "Received binary, but expecting continuation!"
	end
end

def receive_continuation(frame)
	if @frames.any?
		@frames << frame
	else
		raise ProtocolError, "Received unexpected continuation!"
	end
end

def receive_close(frame)
	code, reason = frame.unpack
	
	# On receiving a close frame, we must enter the closed state:
	close!(code, reason)
	
	if code and code != Error::NO_ERROR
		raise ClosedError.new reason, code
	end
end

parameter　data　String

The data to send in the ping frame.

def send_ping(data = "")
	if @state != :closed
		frame = PingFrame.new(mask: @mask)
		frame.pack(data)
		
		write_frame(frame)
	else
		raise ProtocolError, "Cannot send ping in state #{@state}"
	end
end

def receive_ping(frame)
	if @state != :closed
		write_frame(frame.reply(mask: @mask))
	else
		raise ProtocolError, "Cannot receive ping in state #{@state}"
	end
end

def receive_pong(frame)
	# Ignore.
end

def receive_frame(frame)
	raise ProtocolError, "Unhandled frame: #{frame}"
end

parameter　buffer　String

The text to pack into the frame.

returns　TextFrame

The packed frame.

def pack_text_frame(buffer, **options)
	frame = TextFrame.new(mask: @mask)
	frame.pack(buffer)
	
	return frame
end

parameter　buffer　String

The text to send.

def send_text(buffer, **options)
	write_frame(@writer.pack_text_frame(buffer, **options))
end

parameter　buffer　String

The binary data to pack into the frame.

returns　BinaryFrame

The packed frame.

def pack_binary_frame(buffer, **options)
	frame = BinaryFrame.new(mask: @mask)
	frame.pack(buffer)
	
	return frame
end

parameter　buffer　String

The binary data to send.

def send_binary(buffer, **options)
	write_frame(@writer.pack_binary_frame(buffer, **options))
end

parameter　code　Integer

The close code to send.

parameter　reason　String

The reason for closing the connection.

def send_close(code = Error::NO_ERROR, reason = "")
	frame = CloseFrame.new(mask: @mask)
	frame.pack(code, reason)
	
	self.write_frame(frame)
	self.flush
end

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.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
end

def unpack_frames(frames)
	frames.map(&:unpack).join("")
end

def read(**options)
	@framer.flush
	
	while read_frame
		if @frames.last&.finished?
			frames = @frames
			@frames = []
			
			buffer = @reader.unpack_frames(frames, **options)
			return frames.first.read_message(buffer)
		end
	end
rescue ProtocolError => error
	close(error.code, error.message)
	raise
end