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(code = Error::NO_ERROR, reason = "") ⇒ Object 



62
63
64
65
66
 
# File 'lib/protocol/websocket/connection.rb', line 62

def close(code = Error::NO_ERROR, reason = "")
	send_close(code, reason) unless closed?
	
	@framer.close
end

#close! ⇒ Object 



151
152
153
154
155
 
# File 'lib/protocol/websocket/connection.rb', line 151

def close!
	@state = :closed
	
	return self
end

#closed? ⇒ Boolean

Returns:

  • (Boolean) 


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

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 



145
146
147
148
149
 
# File 'lib/protocol/websocket/connection.rb', line 145

def open!
	@state = :open
	
	return self
end

#pack_binary_frame(buffer, **options) ⇒ Object 



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

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

#pack_text_frame(buffer, **options) ⇒ Object 



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

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.



227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/protocol/websocket/connection.rb', line 227

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
	send_close(error.code, error.message)
	
	raise
end

#read_frame ⇒ Object 



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/protocol/websocket/connection.rb', line 68

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

#receive_binary(frame) ⇒ Object 



106
107
108
109
110
111
112
 
# File 'lib/protocol/websocket/connection.rb', line 106

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

#receive_close(frame) ⇒ Object 



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

def receive_close(frame)
	@state = :closed
	
	code, reason = frame.unpack
	
	send_close(code, reason)
	
	if code and code != Error::NO_ERROR
		raise ClosedError.new reason, code
	end
end

#receive_continuation(frame) ⇒ Object 



114
115
116
117
118
119
120
 
# File 'lib/protocol/websocket/connection.rb', line 114

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

#receive_frame(frame) ⇒ Object

Raises:



169
170
171
 
# File 'lib/protocol/websocket/connection.rb', line 169

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

#receive_ping(frame) ⇒ Object 



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

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 



165
166
167
 
# File 'lib/protocol/websocket/connection.rb', line 165

def receive_pong(frame)
	# Ignore.
end

#receive_text(frame) ⇒ Object 



98
99
100
101
102
103
104
 
# File 'lib/protocol/websocket/connection.rb', line 98

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 



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

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

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



195
196
197
198
199
200
201
202
203
 
# File 'lib/protocol/websocket/connection.rb', line 195

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

#send_ping(data = "") ⇒ Object 



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

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 



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

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.



221
222
223
 
# File 'lib/protocol/websocket/connection.rb', line 221

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

#write(message, **options) ⇒ Object

Write a message to the connection.



207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/protocol/websocket/connection.rb', line 207

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 



92
93
94
95
96
 
# File 'lib/protocol/websocket/connection.rb', line 92

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