raggi-sized_header_protocol 0.1.1

data/History.txt

@@ -0,0 +1,4 @@
+== 0.1.0 / 2008-10-01
+
+* 1 major enhancement
+  * Birthday!

data/Manifest.txt

@@ -0,0 +1,25 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+TODO.txt
+lib/sized_header_protocol.rb
+sized_header_protocol.gemspec
+spec/.bacon
+spec/helper.rb
+spec/runner
+spec/spec_sized_header_protocol.rb
+tasks/ann.rake
+tasks/autospec.rake
+tasks/bones.rake
+tasks/gem.rake
+tasks/git.rake
+tasks/manifest.rake
+tasks/notes.rake
+tasks/post_load.rake
+tasks/rdoc.rake
+tasks/rubyforge.rake
+tasks/setup.rb
+tasks/spec.rake
+tasks/svn.rake
+tasks/test.rake

data/README.txt

@@ -0,0 +1,97 @@
+sized_header_protocol
+    by James Tucker
+    http://ra66i.org
+    http://github.com/raggi/sized_header_protocol
+
+== DESCRIPTION:
+
+A simple chainable implementation of a basic sized header protocol. The 
+'protocol' does not define its transport, that is left as configurable. 
+Implementing wire protocols should call send_data to construct packets or 
+frames and receive_data to deconstruct packets or frames.
+
+== FEATURES/PROBLEMS:
+
+* Simplicity.
+* Not really suitable for streaming (this is not a problem, it's a feature).
+* Needs its documentation filling in.
+
+== SYNOPSIS:
+
+The following example does not cover common usage exactly, in that it talks to
+itself, however, it shows an example of the data flow of an application
+utilizing the protocol. 
+
+For incoming data, receive_data calls the protocol in order to unpack the
+data. The protocol will call receive_packet when a fully buffered packet has
+been deconstructed and the data may be read by the application.
+
+For outgoing data, the application calls send_packet, and that will call on 
+the protocol. The protocol will use the callback send_data specified upon 
+construction in order to send data 'over the wire' or to the next protocol in
+the chain, in this case send_data.
+
+  module BackChatExample
+    def post_init
+      @prot = SizedHeaderProtocol.new(self, :send_data, self, :receive_packet)
+    end
+
+    def receive_data(data)
+      @prot.receive_data(data)
+    end
+
+    def send_packet(data)
+      @prot.send_data(data)
+    end
+
+    def receive_packet(data)
+      puts "<< #{data}"
+    end
+
+    def send_data(data)
+      puts ">> #{data}"
+    end
+  end
+
+  conn = Class.new
+  conn.extend EmMock
+  conn.post_init
+  conn.send_data('send')
+  data = "read"
+  conn.receive_data("#{[data.size].pack('N')}#{data}")
+  
+See the specs (tests) for further details.
+
+== REQUIREMENTS:
+
+* A transport system (eventmachine / packet / rev)
+* Bacon for the test (spec) suite.
+
+== INSTALL:
+
+* sudo gem install sized_header_protocol
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 James Tucker
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,27 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+load 'tasks/setup.rb'
+
+ensure_in_path 'lib'
+require 'sized_header_protocol'
+
+task :default => 'spec:run'
+
+PROJ.name = 'sized_header_protocol'
+PROJ.summary = 'A simple chainable implementation of a basic sized header protocol'
+PROJ.authors = 'James Tucker'
+PROJ.email = 'raggi@rubyforge.org'
+PROJ.url = 'http://github.com/raggi/sized_header_protocol'
+PROJ.rubyforge.name = 'sized_header_protocol'
+PROJ.version = SizedHeaderProtocol.version
+
+PROJ.exclude = %w(tmp$ bak$ ~$ CVS \.git \.hg \.svn ^pkg ^doc \.DS_Store
+  \.cvs \.svn \.hgignore \.gitignore \.dotest \.swp$ ~$)
+
+namespace :gem do
+  task :spec do
+    open(PROJ.name + '.gemspec', 'w') { |f| f << PROJ.gem._spec.to_ruby }
+  end
+end

data/lib/sized_header_protocol.rb

@@ -0,0 +1,42 @@
+class SizedHeaderProtocol
+
+  Version = '0.1.1'
+
+  def self.version
+    Version
+  end
+
+  attr_accessor :send_obj, :send_meth, :read_obj, :read_meth
+
+  def initialize(send_obj, send_meth, read_obj, read_meth)
+    @send_obj, @send_meth = send_obj, send_meth
+    @read_obj, @read_meth = read_obj, read_meth
+    @buffer, @next_size = '', nil
+  end
+
+  def send_data(data)
+    @send_obj.send @send_meth, "#{[data.size].pack('N')}#{data}"
+  end
+
+  def receive_data(data)
+    @buffer << data
+    while more?
+      unpack
+    end
+  end
+
+  private
+  def unpack
+    @next_size ||= @buffer.slice!(0, 4).unpack('N').first
+    return unless more?
+    data = @buffer.slice!(0, @next_size)
+    @next_size = nil
+    @read_obj.send(@read_meth, data)
+  end
+
+  def more?
+    # XXX 1.9 has bytesize, too, but not bytewise slice.
+    @buffer.size >= (@next_size || 4)
+  end
+
+end

data/sized_header_protocol.gemspec

@@ -0,0 +1,31 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{sized_header_protocol}
+  s.version = "0.1.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["James Tucker"]
+  s.date = %q{2008-10-02}
+  s.description = %q{A simple chainable implementation of a basic sized header protocol. The  'protocol' does not define it's transport, that is left as configurable.  Implementing wire protocols should call send_data to construct packets or  frames and receive_data to deconstruct packets or frames.}
+  s.email = %q{raggi@rubyforge.org}
+  s.extra_rdoc_files = ["History.txt", "README.txt", "TODO.txt"]
+  s.files = ["History.txt", "Manifest.txt", "README.txt", "Rakefile", "TODO.txt", "lib/sized_header_protocol.rb", "sized_header_protocol.gemspec", "spec/.bacon", "spec/helper.rb", "spec/runner", "spec/spec_sized_header_protocol.rb", "tasks/ann.rake", "tasks/autospec.rake", "tasks/bones.rake", "tasks/gem.rake", "tasks/git.rake", "tasks/manifest.rake", "tasks/notes.rake", "tasks/post_load.rake", "tasks/rdoc.rake", "tasks/rubyforge.rake", "tasks/setup.rb", "tasks/spec.rake", "tasks/svn.rake", "tasks/test.rake"]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/raggi/sized_header_protocol}
+  s.rdoc_options = ["--main", "README.txt"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{sized_header_protocol}
+  s.rubygems_version = %q{1.3.0}
+  s.summary = %q{A simple chainable implementation of a basic sized header protocol}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/spec/helper.rb

@@ -0,0 +1,16 @@
+# Disable test/unit and rspec from running, in case loaded by broken tools.
+Test::Unit.run = false if defined?(Test::Unit)
+Spec::run = false if defined?(Spec) && Spec::respond_to?(:run=)
+
+# Setup a nice testing environment
+$TESTING=true
+$:.push File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+$:.uniq!
+
+%w[rubygems bacon].each { |r| require r }
+
+# Bacon doesn't do any automagic, so lets tell it to!
+Bacon.summary_on_exit
+
+require File.expand_path(
+  File.join(File.dirname(__FILE__), *%w[.. lib sized_header_protocol]))

data/spec/runner

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+__DIR__ = File.dirname(__FILE__)
+__APP__ = File.expand_path(__DIR__ + '/../')
+
+puts
+Dir.chdir(__APP__) do
+  files = ARGV.empty? ? Dir.glob('{test,spec}/**/{test,spec}_*.rb') : ARGV
+  files.each { |f| require f }
+end

data/spec/spec_sized_header_protocol.rb

@@ -0,0 +1,76 @@
+require File.dirname(__FILE__) + '/helper'
+
+class MockTransport
+
+  attr_accessor :sent, :recv
+
+  def initialize
+    @sent, @recv = [], []
+  end
+
+  def send_data(data)
+    @sent << data
+  end
+
+  def receive_data(data)
+    @recv << data
+  end
+
+end
+
+describe 'sized header protocol sending a frame' do
+  before do
+    @trans = MockTransport.new
+    @proto = SizedHeaderProtocol.new(@trans, :send_data, @trans, :receive_data)
+  end
+
+  should 'call the send method on the target object with a size header' do
+    data = '1234567890'
+    size = data.size
+    @proto.send_data(data)
+    @trans.sent.first[0,4].unpack('N').first.should.eql(size)
+  end
+
+  should 'send the data immediately after the header' do
+    data = '1234567890'
+    @proto.send_data(data)
+    @trans.sent.first[4,data.size].should.eql(data)
+  end
+end
+
+describe 'sized header protocol receiving a frame' do
+  before do
+    @trans = MockTransport.new
+    @proto = SizedHeaderProtocol.new(@trans, :send_data, @trans, :receive_data)
+  end
+
+  should 'call receive_data with the data when a whole frame is read' do
+    data = '1234567890'
+    size = data.size
+    packet = "#{[size].pack('N')}#{data}"
+    @proto.receive_data(packet)
+    @trans.recv.first.should.eql(data)
+  end
+
+  should 'buffer data until a whole frame is read' do
+    data = '1234567890'
+    size = data.size
+    packet = "#{[size].pack('N')}#{data}"
+    first = packet.slice 0, packet.size/2
+    second = packet.slice packet.size/2, packet.size # excessive, but meh.
+    @proto.receive_data(first)
+    @trans.recv.should.be.empty
+    @proto.receive_data(second)
+    @trans.recv.first.should.eql(data)
+  end
+
+  should 'call the receive callback for each packet read' do
+    data = '1234567890'
+    size = data.size
+    packet = "#{[size].pack('N')}#{data}"
+    @proto.receive_data(packet + packet)
+    @trans.recv.size.should.eql(2)
+    @trans.recv[0].should.eql(data)
+    @trans.recv[1].should.eql(data)
+  end
+end

data/tasks/ann.rake

@@ -0,0 +1,81 @@
+# $Id$
+
+begin
+  require 'bones/smtp_tls'
+rescue LoadError
+  require 'net/smtp'
+end
+require 'time'
+
+namespace :ann do
+
+  # A prerequisites task that all other tasks depend upon
+  task :prereqs
+
+  file PROJ.ann.file do
+    ann = PROJ.ann
+    puts "Generating #{ann.file}"
+    File.open(ann.file,'w') do |fd|
+      fd.puts("#{PROJ.name} version #{PROJ.version}")
+      fd.puts("    by #{Array(PROJ.authors).first}") if PROJ.authors
+      fd.puts("    #{PROJ.url}") if PROJ.url.valid?
+      fd.puts("    (the \"#{PROJ.release_name}\" release)") if PROJ.release_name
+      fd.puts
+      fd.puts("== DESCRIPTION")
+      fd.puts
+      fd.puts(PROJ.description)
+      fd.puts
+      fd.puts(PROJ.changes.sub(%r/^.*$/, '== CHANGES'))
+      fd.puts
+      ann.paragraphs.each do |p|
+        fd.puts "== #{p.upcase}"
+        fd.puts
+        fd.puts paragraphs_of(PROJ.readme_file, p).join("\n\n")
+        fd.puts
+      end
+      fd.puts ann.text if ann.text
+    end
+  end
+
+  desc "Create an announcement file"
+  task :announcement => ['ann:prereqs', PROJ.ann.file]
+
+  desc "Send an email announcement"
+  task :email => ['ann:prereqs', PROJ.ann.file] do
+    ann = PROJ.ann
+    from = ann.email[:from] || PROJ.email
+    to   = Array(ann.email[:to])
+
+    ### build a mail header for RFC 822
+    rfc822msg =  "From: #{from}\n"
+    rfc822msg << "To: #{to.join(',')}\n"
+    rfc822msg << "Subject: [ANN] #{PROJ.name} #{PROJ.version}"
+    rfc822msg << " (#{PROJ.release_name})" if PROJ.release_name
+    rfc822msg << "\n"
+    rfc822msg << "Date: #{Time.new.rfc822}\n"
+    rfc822msg << "Message-Id: "
+    rfc822msg << "<#{"%.8f" % Time.now.to_f}@#{ann.email[:domain]}>\n\n"
+    rfc822msg << File.read(ann.file)
+
+    params = [:server, :port, :domain, :acct, :passwd, :authtype].map do |key|
+      ann.email[key]
+    end
+
+    params[3] = PROJ.email if params[3].nil?
+
+    if params[4].nil?
+      STDOUT.write "Please enter your e-mail password (#{params[3]}): "
+      params[4] = STDIN.gets.chomp
+    end
+
+    ### send email
+    Net::SMTP.start(*params) {|smtp| smtp.sendmail(rfc822msg, from, to)}
+  end
+end  # namespace :ann
+
+desc 'Alias to ann:announcement'
+task :ann => 'ann:announcement'
+
+CLOBBER << PROJ.ann.file
+
+# EOF

data/tasks/autospec.rake

@@ -0,0 +1,33 @@
+# Poor mans autotest, for when you absolutely positively, just need an autotest.
+# N.B. Uses a runner under test/ or spec/, so you can customize the runtime.
+# Thanks to manveru for this!
+desc "Run specs every time a file changes in lib or spec"
+task :autospec do
+  rb = Gem.ruby rescue nil
+  rb ||= (require 'rbconfig'; File.join(Config::CONFIG['bindir'], Config::CONFIG['ruby_install_name']))
+  command = 'spec/runner' if test ?e, 'spec/runner'
+  command ||= 'test/runner' if test ?e, 'test/runner'
+  files = Dir.glob('{lib,spec,test}/**/*.rb')
+  mtimes = {}
+  sigtrap = proc { puts "\rDo that again, I dare you!"; trap(:INT){ exit 0 }; sleep 0.8; trap(:INT, &sigtrap) }
+  trap(:INT, &sigtrap)
+  system "#{rb} -I#{GSpec.require_path} #{command}"
+  while file = files.shift
+    begin
+      mtime = File.mtime(file)
+      mtimes[file] ||= mtime
+      if mtime > mtimes[file]
+        files = Dir.glob('{lib,spec,test}/**/*.rb') - [file] # refresh the file list.
+        puts
+        system "#{rb} -I#{GSpec.require_path} #{command} #{file}"
+        puts
+      end
+      mtimes[file] = mtime
+      files << file
+    rescue Exception
+      retry
+    end
+    # print "\rChecking: #{file.ljust((ENV['COLUMNS']||80)-11)}";$stdout.flush
+    sleep 0.2
+  end
+end