Class: Protocol::WebSocket::Connection

Inherits:
Object
  • Object
show all
Defined in:
lib/protocol/websocket/connection.rb

Overview

Wraps a framer and implements for implementing connection specific interactions like reading and writing text.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(framer, mask: nil, **options) ⇒ Connection

Returns a new instance of Connection.



16
17
18
19
20
21
22
23
24
25
26
27
 
# File 'lib/protocol/websocket/connection.rb', line 16

def initialize(framer, mask: nil, **options)
	@framer = framer
	@mask = mask
	
	@state = :open
	@frames = []
	
	@reserved = Frame::RESERVED
	
	@reader = self
	@writer = self
end

Instance Attribute Details

#framer ⇒ Object (readonly)

The framer which is used for reading and writing frames.



30
31
32
 
# File 'lib/protocol/websocket/connection.rb', line 30

def framer
  @framer
end

#frames ⇒ Object

Buffered frames which form part of a complete message.



39
40
41
 
# File 'lib/protocol/websocket/connection.rb', line 39

def frames
  @frames
end

#mask ⇒ Object (readonly)

The (optional) mask which is used when generating frames.



33
34
35
 
# File 'lib/protocol/websocket/connection.rb', line 33

def mask
  @mask
end

#reader ⇒ Object

Returns the value of attribute reader.



41
42
43
 
# File 'lib/protocol/websocket/connection.rb', line 41

def reader
  @reader
end

#reserved ⇒ Object (readonly)

The allowed reserved bits:



36
37
38
 
# File 'lib/protocol/websocket/connection.rb', line 36

def reserved
  @reserved
end

#writer ⇒ Object

Returns the value of attribute writer.



42
43
44
 
# File 'lib/protocol/websocket/connection.rb', line 42

def writer
  @writer
end

Instance Method Details

#close ⇒ Object 



74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/protocol/websocket/connection.rb', line 74

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

#close! ⇒ Object 



64
65
66
67
68
 
# File 'lib/protocol/websocket/connection.rb', line 64

def close!(...)
	@state = :closed
	
	return self
end

#closed? ⇒ Boolean

Returns:

  • (Boolean) 


70
71
72
 
# File 'lib/protocol/websocket/connection.rb', line 70

def closed?
	@state == :closed
end

#flush ⇒ Object 



54
55
56
 
# File 'lib/protocol/websocket/connection.rb', line 54

def flush
	@framer.flush
end

#open! ⇒ Object 



58
59
60
61
62
 
# File 'lib/protocol/websocket/connection.rb', line 58

def open!
	@state = :open
	
	return self
end

#pack_binary_frame(buffer, **options) ⇒ Object 



194
195
196
197
198
199
 
# File 'lib/protocol/websocket/connection.rb', line 194

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

#pack_text_frame(buffer, **options) ⇒ Object 



183
184
185
186
187
188
 
# File 'lib/protocol/websocket/connection.rb', line 183

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

#read(**options) ⇒ Object

Read a message from the connection.



235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
 
# File 'lib/protocol/websocket/connection.rb', line 235

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

#read_frame ⇒ Object 



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/protocol/websocket/connection.rb', line 88

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
	close(Error::PROTOCOL_ERROR, $!.message)
	
	raise
end

#receive_binary(frame) ⇒ Object 



126
127
128
129
130
131
132
 
# File 'lib/protocol/websocket/connection.rb', line 126

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

#receive_close(frame) ⇒ Object 



142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/protocol/websocket/connection.rb', line 142

def receive_close(frame)
	code, reason = frame.unpack
	
	# If we're already closed, then we don't need to send a close frame. Otherwise, according to the RFC, we should echo the close frame. However, it's possible it will fail to send if the connection is already closed.
	unless @state == :closed
		close!
		send_close(code, reason)
	end
	
	if code and code != Error::NO_ERROR
		raise ClosedError.new reason, code
	end
end

#receive_continuation(frame) ⇒ Object 



134
135
136
137
138
139
140
 
# File 'lib/protocol/websocket/connection.rb', line 134

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

#receive_frame(frame) ⇒ Object

Raises:



179
180
181
 
# File 'lib/protocol/websocket/connection.rb', line 179

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

#receive_ping(frame) ⇒ Object 



167
168
169
170
171
172
173
 
# File 'lib/protocol/websocket/connection.rb', line 167

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

#receive_pong(frame) ⇒ Object 



175
176
177
 
# File 'lib/protocol/websocket/connection.rb', line 175

def receive_pong(frame)
	# Ignore.
end

#receive_text(frame) ⇒ Object 



118
119
120
121
122
123
124
 
# File 'lib/protocol/websocket/connection.rb', line 118

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

#reserve!(bit) ⇒ Object 



44
45
46
47
48
49
50
51
52
 
# File 'lib/protocol/websocket/connection.rb', line 44

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

#send_binary(buffer, **options) ⇒ Object 



201
202
203
 
# File 'lib/protocol/websocket/connection.rb', line 201

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

#send_close(code = Error::NO_ERROR, reason = "") ⇒ Object 



205
206
207
208
209
210
211
 
# File 'lib/protocol/websocket/connection.rb', line 205

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

#send_ping(data = "") ⇒ Object 



156
157
158
159
160
161
162
163
164
165
 
# File 'lib/protocol/websocket/connection.rb', line 156

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

#send_text(buffer, **options) ⇒ Object 



190
191
192
 
# File 'lib/protocol/websocket/connection.rb', line 190

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

#unpack_frames(frames) ⇒ Object

The default implementation for reading a message buffer.



229
230
231
 
# File 'lib/protocol/websocket/connection.rb', line 229

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

#write(message, **options) ⇒ Object

Write a message to the connection.



215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/protocol/websocket/connection.rb', line 215

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

#write_frame(frame) ⇒ Object 



112
113
114
115
116
 
# File 'lib/protocol/websocket/connection.rb', line 112

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