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

Immediately transition the connection to the closed state and close the underlying connection.



84
85
86
87
88
 
# File 'lib/protocol/websocket/connection.rb', line 84

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

#close! ⇒ Object

If not already closed, transition the connection to the closed state and send a close frame.



65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/protocol/websocket/connection.rb', line 65

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

#closed? ⇒ Boolean

Returns:

  • (Boolean) 


79
80
81
 
# File 'lib/protocol/websocket/connection.rb', line 79

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 



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

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

#pack_text_frame(buffer, **options) ⇒ Object 



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

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.



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

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 



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 90

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

#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
 
# File 'lib/protocol/websocket/connection.rb', line 142

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

#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:



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

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

#receive_ping(frame) ⇒ Object 



164
165
166
167
168
169
170
 
# File 'lib/protocol/websocket/connection.rb', line 164

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 



172
173
174
 
# File 'lib/protocol/websocket/connection.rb', line 172

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 



198
199
200
 
# File 'lib/protocol/websocket/connection.rb', line 198

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

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

Send a control frame with data containing a specified control sequence to begin the closing handshake. Does not close the connection, until the remote end responds with a close frame.



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

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 



153
154
155
156
157
158
159
160
161
162
 
# File 'lib/protocol/websocket/connection.rb', line 153

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 



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

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.



227
228
229
 
# File 'lib/protocol/websocket/connection.rb', line 227

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

#write(message, **options) ⇒ Object

Write a message to the connection.



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

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