Class: Arpie::Protocol

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

Overview

A Protocol converts messages (which are arbitary objects) to a suitable on-the-wire format, and back.

Constant Summary collapse

CAN_SEPARATE_MESSAGES =

Set this to true in child classes which implement message separation within a stream.

false

Instance Method Summary collapse

Instance Method Details

#again! ⇒ Object

Call this within Protocol#from to reparse the current message.

Raises:



218
219
220
 
# File 'lib/arpie/protocol.rb', line 218

def again!
  raise ETryAgain
end

#assemble(binaries, token) ⇒ Object

Called when we’re trying to reassemble a stream of packets.

Call incomplete! when not enough data is here to reassemble this stream, and yield all results of the reassembled stream.

Raises:

  • (NotImplementedError) 


275
276
277
 
# File 'lib/arpie/protocol.rb', line 275

def assemble binaries, token
  raise NotImplementedError, "Tried to assemble! something, but no assembler defined."
end

#assemble!(binary, token = :default, meta = {}) ⇒ Object

Stow away a message in this protocols buffer for later reassembly. Optional argument: a token if you are planning to reassemble multiple interleaved/fragmented message streams.

binary is the binary packet you want to add to the assembly token is a object which can be used to re-identify multiple concurrent assemblies meta is a hash containing meta-information for this assembly

each call to assemble! will merge these hashes, and pass them
on to Protocol#assemble

Raises:



246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/arpie/protocol.rb', line 246

def assemble! binary, token = :default, meta = {}
  @stowbuffer ||= {}
  @stowbuffer[token] ||= []
  @stowbuffer[token] << binary

  @metabuffer ||= {}
  @metabuffer[token] ||= {}
  @metabuffer[token].merge(meta)

  assembled = []

  assemble @stowbuffer[token], token, meta do |a|
    assembled << a
  end  # rescue case $!
    #when EIncomplet
    #  puts "Cant reassemble, asking for moarh"
    #  raise EIncomplete
    #else
    #  raise
  #end

  assembled.size > 0 or raise "assemble! did not return any results."
  raise YieldResult, assembled
end

#bogon!(data = nil, message = nil) ⇒ Object

Call this if you think the stream has been corrupted, or non-protocol data arrived. message is the text to display. data is the optional misbehaving data for printing. This breaks out of Protocol#from.

Raises:



284
285
286
 
# File 'lib/arpie/protocol.rb', line 284

def bogon! data = nil, message = nil
  raise StreamError, "#{self.class.to_s}#{message.nil? ? " thinks the data is bogus" : ": " + message }#{data.nil? ? "" : ": " + data.inspect}."
end

#from(binary) {|binary| ... } ⇒ Object

Extract message(s) from binary.i

Yields each message found, with all protocol-specifics stripped.

Should call incomplete when no message can be read yet.

Must not block by waiting for multiple messages if a message can be yielded directly.

Must not return without calling incomplete or yielding a message.

Must return the number of bytes these message(s) occupied in the stream, for truncating of the same. Mandatory when CAN_SEPARATE_MESSAGES is true for this class, but ignored otherwise.

Yields:

  • (binary) 


211
212
213
214
 
# File 'lib/arpie/protocol.rb', line 211

def from binary, &block #:yields: message
  yield binary
  0
end

#gulp! ⇒ Object Also known as: swallow!

Swallow the complete message currently passed to Protocol#from. Not advised for the outermost protocol, which works on io buffer streams and may swallow more than intended.

Raises:



232
233
234
 
# File 'lib/arpie/protocol.rb', line 232

def gulp!
  raise ESwallow
end

#incomplete! ⇒ Object

Tell the protocol chain that the given chunk of data is not enough to construct a whole message. This breaks out of Protocol#from.

Raises:



225
226
227
 
# File 'lib/arpie/protocol.rb', line 225

def incomplete!
  raise EIncomplete
end

#to(obj) ⇒ Object

Convert obj to on-the-wire format.



192
193
194
 
# File 'lib/arpie/protocol.rb', line 192

def to obj
  obj
end