sanford-protocol 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in sanford-protocol.gemspec
+gemspec
+
+gem 'bson_ext', '~>1.7'
+gem 'rake',     '~>0.9.2'

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 jcredding
+
+MIT License
+
+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/README.md

@@ -0,0 +1,145 @@
+# Sanford Protocol
+
+Ruby implementation of the Sanford communication protocol.
+
+## The Protocol
+
+**Version**: `1`
+
+Sanford communicates using binary encoded messages.  Sanford messages are two headers and a body:
+
+```
+|------ 1B -------|------ 4B -------|---- (Body Size)B ----|
+| (packed header) | (packed header) | (BSON binary string) |
+|     Version     |    Body Size    |         Body         |
+|-----------------|-----------------|----------------------|
+```
+
+### Version
+
+The first header represents the protocol version in use.  It is a 1 byte unsigned integer and exists to ensure both the client and the server are talking the same protocol.
+
+### Body Size
+
+The second header represents the size of the message's body.  It is a 4 byte unsigned integer and tells the receiver how many bytes to read to receive the body.
+
+### Body
+
+The Body is the content of the message.  It is a [BSON](http://bsonspec.org/) encoded binary string that decodes to a ruby hash.  Since the size of the body is encoded as a 4 byte (32 bit) unsigned integer, there is a size limit for body data (`(2 ** 32) - 1` or `4,294,967,295` or `~4GB`).
+
+## Request
+
+A request is made up of 3 required parts: the version, the name, and the params.
+
+* **version** - (string) version of the requested API.
+* **name**    - (string) name of the requested API service.
+* **params**  - (object) data for the service call - can be any BSON serializable object.
+
+Requests are encoded as BSON hashes when transmitted in messages.
+
+```ruby
+{ 'version': 'v1',
+  'name':    'some_service',
+  'params':  'something'
+}
+```
+
+## Response
+
+A response is made up of 2 parts: the status and the result.
+
+* **status** - (tuple, required) A code and message describing the result of the service call.
+* **result** - (object, optional) Result of calling the service. This can be any BSON serializable object.  Typically won't be set if the request is not successful.
+
+Responses are encoded as BSON hashes when transmitted in messages.
+
+```ruby
+{ 'status': [ 200, 'The request was successful.' ]
+  'result': true
+}
+```
+
+### Status Codes
+
+This is the list of defined status codes.
+
+* `200` - `ok` - The request was successful.
+* `400` - `bad_request` - The request couldn't be read. This is usually because it was not formed correctly.
+* `404` - `not_found` - The server couldn't find something requested.
+* `500` - `error` - The server errored responding to the request.
+
+In addition to these, a service can return custom status codes, but they should use a number greater than or equal to `600` to avoid collisions with Sanford's defined status codes.
+
+## Usage
+
+The `Sanford::Protocol` module defines helper methods for encoding and decoding messages.
+
+```ruby
+# encode a message
+data = { 'something' => true }
+msg_body = Sanford::Protocol.msg_body.encode(data)
+msg_size = Sanford::Protocol.msg_size.encode(msg_body.bytesize)
+msg = [Sanford::Protocol.msg_version, msg_size, msg_body].join
+```
+
+### Connection
+
+If you are sending and receiving messages using a tcp socket, use `Sanford::Protocol::Connection`.
+
+```ruby
+connection = Sanford::Protocol::Connection.new(tcp_socket)
+incoming_data = connection.read
+connection.write(outgoing_data)
+```
+
+For incoming messages, it reads them off the socket, validate them, and return the decoded body data.  For outgoing messages, it encodes the message body from given data, adds the appropiate message headers, and writes the message to the socket.
+
+### Requests And Responses
+
+Request and response objects have helpers for sending and receiving data using a connection.
+
+```ruby
+# For a server...
+# use Request#parse to build an incoming request
+data_hash = server_connection.read
+incoming_request = Sanford::Protocol::Request.parse(data_hash)
+# use Response#to_hash to send a response
+outgoing_response = Sanford::Protocol::Response.new(status, result)
+server_connection.write(outgoing_response.to_hash)
+
+# For a client...
+# use Request#to_hash to send a request
+outgoing_request = Sanford::Protocol::Request.new(name, version, params)
+client_connection.write(outgoing_request.to_hash)
+# use Response#parse to build an incoming response
+data_hash = client_connection.read
+incoming_response = Sanford::Protocol::Response.parse(data_hash)
+```
+
+## Test Helpers
+
+A `FakeSocket` helper class and an associated `Test::Helpers` module are provided to help test receiving and sending Sanford::Protocol messages without using real sockets.
+
+```ruby
+# fake a socket with some incoming binary
+socket = FakeSocket.new(msg_binary_string)
+connection = Sanford::Protocol::Connection.new(socket)
+msg_data = connection.read
+
+# write some binary to that fake socket and verify it
+connection.write(msg_data)
+puts socket.out # => msg binary string
+
+# create a socket with an incoming request and verify the request
+socket   = FakeSocket.with_request(*request_params)
+msg_data = Sanford::Protocol::Connection.new(socket).read
+request  = Sanford::Protocol::Request.parse(msg_data)
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,4 @@
+require "bundler/gem_tasks"
+
+require "assert/rake_tasks"
+Assert::RakeTasks.install

data/lib/sanford-protocol/connection.rb

@@ -0,0 +1,54 @@
+require 'sanford-protocol/msg_data'
+
+module Sanford::Protocol
+
+  # Sanford Protocol's connection class wraps a socket and provides a `read` and
+  # `write` method for using Sanford's message protocol.  Mixes in the protocol
+  # to get the `msg_version`, `msg_size`, and `msg_body` handler methods.
+
+  class Connection
+    include Sanford::Protocol
+
+    def initialize(tcp_socket)
+      @socket = Socket.new(tcp_socket)
+    end
+
+    # Message format (see sanford-protocal.rb):
+    # |------ 1B -------|------ 4B -------|-- (msg body size)B --|
+    # | (packed header) | (packed header) | (BSON binary string) |
+    # |   msg version   |  msg body size  |       msg body       |
+    # |-----------------|-----------------|----------------------|
+
+    def read
+      MsgVersion.new{ @socket.read msg_version.bytesize }.validate!
+      size = MsgSize.new{ @socket.decode msg_size, msg_size.bytes }.validate!.value
+      return MsgBody.new{ @socket.decode msg_body, size           }.validate!.value
+    end
+
+    def write(data)
+      body = @socket.encode msg_body, data
+      size = @socket.encode msg_size, body.bytesize
+
+      @socket.write(msg_version, size, body)
+    end
+
+    class Socket < Struct.new(:tcp_socket)
+      def decode(handler, num_bytes)
+        handler.decode(read(num_bytes))
+      end
+
+      def encode(handler, data)
+        handler.encode data
+      end
+
+      def read(number_of_bytes)
+        tcp_socket.recvfrom(number_of_bytes).first
+      end
+
+      def write(*binary_strings)
+        tcp_socket.send(binary_strings.join, 0)
+      end
+    end
+
+  end
+end

data/lib/sanford-protocol/msg_data.rb

@@ -0,0 +1,61 @@
+module Sanford::Protocol
+
+  class BadMessageError < RuntimeError
+    def initialize(message, bt=nil)
+      super(message)
+      set_backtrace(bt || caller)
+    end
+  end
+
+  class MsgData
+    attr_reader :value
+
+    def initialize(called_from=nil, &get_value)
+      @called_from = called_from || caller
+
+      # By default, any exceptions from getting the value are "hidden" behind a
+      # more general `BadMessageError`. In non-debug scenarios this is ideal and
+      # allows you to rescue from a common exception and respond in a standard way.
+      # In debug scenarios, however, go ahead and raise the real exception.
+
+      begin
+        @value = get_value.call
+      rescue Exception => err
+        ENV['SANFORD_PROTOCOL_DEBUG'] ? raise(err) : self.error!(self.get_value_error)
+      end
+    end
+
+    def get_value_error; "Error reading the message"; end
+    def validate!; self; end
+
+    def error!(message)
+      raise BadMessageError.new(message, @called_from)
+    end
+
+  end
+
+  class MsgSize < MsgData
+    def get_value_error; "Error reading message body size."; end
+    def validate!
+      error!("Empty message size") if self.value.nil?
+      super
+    end
+  end
+
+  class MsgVersion < MsgData
+    def get_value_error; "Error reading message protocol version"; end
+    def validate!
+      error!("Protocol version mismatch") if version_mismatch?
+      super
+    end
+
+    def version_mismatch?
+      self.value != Sanford::Protocol.msg_version
+    end
+  end
+
+  class MsgBody < MsgData
+    def get_value_error; "Error reading message body."; end
+  end
+
+end

data/lib/sanford-protocol/request.rb

@@ -0,0 +1,48 @@
+# The Request class models a specific type of Sanford message body and provides
+# a defined structure for it. A request requires a message body to contain a
+# version, name and params. It provides methods for working with message bodies
+# (hashes) with `parse` and `to_hash`. In addition to this, a request has a
+# `valid?` method, that returns whether it is valid and if it isn't why.
+
+module Sanford::Protocol
+
+  class Request
+
+    def self.parse(body)
+      self.new(body['version'], body['name'], body['params'])
+    end
+
+    attr_reader :version, :name, :params
+
+    def initialize(version, name, params)
+      @version, @name, @params = version, name, params
+    end
+
+    def to_hash
+      { 'version' => @version,
+        'name'    => @name,
+        'params'  => @params
+      }
+    end
+
+    def valid?
+      if !@version
+        [ false, "The request doesn't contain a version." ]
+      elsif !@name
+        [ false, "The request doesn't contain a name." ]
+      else
+        [ true ]
+      end
+    end
+
+    def inspect
+      reference = '0x0%x' % (self.object_id << 1)
+      "#<#{self.class}:#{reference}"\
+      " @version=#{@version.inspect}"\
+      " @name=#{@name.inspect}"\
+      " @params=#{@params.inspect}>"
+    end
+
+  end
+
+end

data/lib/sanford-protocol/response.rb

@@ -0,0 +1,45 @@
+require 'sanford-protocol/response_status'
+
+# The Response class models a specific type of Sanford message body and provides
+# a defined structure for it. A response requires a message body to contain a
+# status (which is a code and optional message) and a result. It provides
+# methods for working with message bodies (hashes) with `parse` and `to_hash`.
+
+module Sanford::Protocol
+
+  class Response
+
+    def self.parse(hash)
+      self.new(hash['status'], hash['result'])
+    end
+
+    attr_reader :status, :result
+
+    def initialize(status, result = nil)
+      @status, @result = build_status(status), result
+    end
+
+    def to_hash
+      { 'status'  => [ @status.code, @status.message ],
+        'result'  => @result
+      }
+    end
+
+    def inspect
+      reference = '0x0%x' % (self.object_id << 1)
+      "#<#{self.class}:#{reference}"\
+      " @status=#{@status.inspect}"\
+      " @result=#{@result.inspect}>"
+    end
+
+    private
+
+    def build_status(status)
+      return status if status.kind_of?(ResponseStatus)
+
+      ResponseStatus.new(*status)
+    end
+
+  end
+
+end

data/lib/sanford-protocol/response_status.rb

@@ -0,0 +1,44 @@
+# The Response Status class models a code and optional message. This makes up
+# part of a response and provides methods for building and displaying statuses.
+
+module Sanford::Protocol
+  class ResponseStatus < Struct.new(:code_obj, :message)
+
+    def initialize(code, message = nil)
+      super(Code.new(code), message)
+    end
+
+    def code; code_obj.number; end
+    def name; code_obj.name;   end
+    def to_s; code_obj.to_s;   end
+
+    def inspect
+      reference = '0x0%x' % (self.object_id << 1)
+      "#<#{self.class}:#{reference}"\
+      " @code=#{code_obj}"\
+      " @message=#{message.inspect}>"
+    end
+
+    class Code < Struct.new(:number, :name)
+      NUMBERS = {
+        'ok'          => 200,
+        'bad_request' => 400,
+        'not_found'   => 404,
+        'error'       => 500
+      }.freeze
+
+      def initialize(key)
+        num  = NUMBERS[key.to_s]  || key.to_i
+        name = NUMBERS.index(num) || NoName
+        super(num, name.upcase)
+      end
+
+      def to_s; "[#{[number, name].compact.join(', ')}]"; end
+
+      class NoName
+        def self.upcase; nil; end
+      end
+    end
+
+  end
+end

data/lib/sanford-protocol/test/fake_socket.rb

@@ -0,0 +1,51 @@
+# The FakeSocket class can be used to work with Sanford Protocol in a test
+# environment. Instead of passing a real socket, pass an instance of this class.
+# It mimics the socket API that sanford is concerned with.
+
+require 'sanford-protocol'
+require 'sanford-protocol/request'
+
+module Sanford::Protocol::Test
+  class FakeSocket
+
+    def self.with_request(*request_params)
+      request = Sanford::Protocol::Request.new(*request_params)
+      self.with_msg_body(request.to_hash)
+    end
+
+    def self.with_msg_body(body, size=nil, encoded_version=nil)
+      encoded_body = Sanford::Protocol.msg_body.encode(body)
+      self.with_encoded_msg_body(encoded_body, size, encoded_version)
+    end
+
+    def self.with_encoded_msg_body(encoded_body, size=nil, encoded_version=nil)
+      encoded_size    =   Sanford::Protocol.msg_size.encode(size || encoded_body.bytesize)
+      encoded_version ||= Sanford::Protocol.msg_version
+      self.new(encoded_version, encoded_size, encoded_body)
+    end
+
+    def initialize(*bytes)
+      @out = StringIO.new
+      @in  = StringIO.new
+      reset(*bytes)
+    end
+
+    def reset(*new_bytes)
+      @in << new_bytes.join; @in.rewind;
+    end
+
+    def in;  @in.string;  end
+    def out; @out.string; end
+
+    # Socket methods -- requied by Sanford::Protocol
+
+    def recvfrom(number_of_bytes)
+      [ @in.read(number_of_bytes.to_i) ]
+    end
+
+    def send(bytes, flag)
+      @out << bytes
+    end
+
+  end
+end

data/lib/sanford-protocol/test/helpers.rb

@@ -0,0 +1,36 @@
+require 'sanford-protocol/test/fake_socket'
+require 'sanford-protocol/response'
+
+module Sanford::Protocol::Test
+
+  module Helpers
+    extend self
+
+    def fake_socket_with_request(*args)
+      FakeSocket.with_request(*args)
+    end
+
+    def fake_socket_with_msg_body(*args)
+      FakeSocket.with_msg_body(*args)
+    end
+
+    def fake_socket_with_encoded_msg_body(*args)
+      FakeSocket.with_encoded_msg_body(*args)
+    end
+
+    def fake_socket_with(*args)
+      FakeSocket.new(*args)
+    end
+
+    def read_response_from_fake_socket(from_fake_socket)
+      data = Sanford::Protocol::Connection.new(from_fake_socket).read
+      Sanford::Protocol::Response.parse(data)
+    end
+
+    def read_written_response_from_fake_socket(from_fake_socket)
+      read_response_from_fake_socket(FakeSocket.new(from_fake_socket.out))
+    end
+
+  end
+
+end

data/lib/sanford-protocol/version.rb

@@ -0,0 +1,5 @@
+module Sanford
+  module Protocol
+    GEM_VERSION = "0.1.0"
+  end
+end

data/lib/sanford-protocol.rb

@@ -0,0 +1,52 @@
+require 'sanford-protocol/connection'
+require 'sanford-protocol/request'
+require 'sanford-protocol/response'
+
+module Sanford
+  module Protocol
+
+    extend self
+
+    # If anything changes in this file, the VERSION number should be
+    # incremented. This is used by clients and servers to ensure they are
+    # working under the same assumptions. In addition to incrementing this, the
+    # README needs to be updated to display the current version and needs to
+    # describe everything in this file.
+
+    VERSION = 1
+
+    # The message version is the 1B encoding of the `VERSION` above. It is
+    # encoded using Array#pack 'C' (8-bit unsigned integer).   The max value it
+    # can encode is 255 (`(2 ** 8) - 1`).
+
+    def msg_version; @msg_version ||= PackedHeader.new(1, 'C').encode(VERSION); end
+
+    # The message size is encoded using Array#pack 'N'. This encoding represents
+    # a 32-bit (4 byte) unsigned integer. The max value that can be encoded in
+    # 4 bytes is 4,294,967,295 (`(2 ** 32) - 1`) or a size of ~4GB.
+
+    def msg_size; @msg_size ||= PackedHeader.new(4, 'N'); end
+
+    # THe message body is encoded using BSON.
+
+    def msg_body; @msg_body ||= BsonBody.new; end
+
+    class PackedHeader < Struct.new(:bytes, :directive)
+      def encode(data);   [*data].pack(directive);             end
+      def decode(binary); binary.to_s.unpack(directive).first; end
+    end
+
+    class BsonBody
+      require 'bson'
+
+      # BSON returns a byte buffer when serializing.  This doesn't always behave
+      # like a string, so convert it to one.
+      def encode(data); ::BSON.serialize(data).to_s; end
+
+      # BSON returns an ordered hash when deserializing. This should be
+      # functionally equivalent to a regular hash.
+      def decode(binary); ::BSON.deserialize(binary); end
+    end
+
+  end
+end

data/sanford-protocol.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'sanford-protocol/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "sanford-protocol"
+  gem.version       = Sanford::Protocol::GEM_VERSION
+  gem.authors       = ["Collin Redding", "Kelly Redding"]
+  gem.email         = ["collin.redding@me.com", "kelly@kellyredding.com"]
+  gem.description   = "Ruby implementation of Sanford's communication protocol."
+  gem.summary       = "Ruby implementation of Sanford's communication protocol."
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency("bson",        ["~>1.7"])
+
+  gem.add_development_dependency("assert",        ["~> 0.8"])
+  gem.add_development_dependency("assert-mocha",  ["~> 0.1"])
+end

data/test/helper.rb

@@ -0,0 +1,32 @@
+ROOT = File.expand_path('../..', __FILE__)
+
+ENV['SANFORD_PROTOCOL_DEBUG'] = 'yes'
+
+require 'sanford-protocol/test/fake_socket'
+FakeSocket = Sanford::Protocol::Test::FakeSocket
+
+require 'assert-mocha' if defined?(Assert)
+
+class Assert::Context
+
+  def setup_some_msg_data(data=nil)
+    @data = data || { 'something' => true }
+    @encoded_body    = Sanford::Protocol.msg_body.encode(@data)
+    @encoded_size    = Sanford::Protocol.msg_size.encode(@encoded_body.bytesize)
+    @encoded_version = Sanford::Protocol.msg_version
+    @msg = [@encoded_version, @encoded_size, @encoded_body].join
+  end
+
+  def setup_some_request_data
+    @request_params = ['1', 'a_service', {:some => 'data'}]
+    @request = Sanford::Protocol::Request.new(*@request_params)
+    setup_some_msg_data(@request.to_hash)
+  end
+
+  def setup_some_response_data
+    @response_params = [200, 'in testing all is well']
+    @response = Sanford::Protocol::Response.new(*@response_params)
+    setup_some_msg_data(@response.to_hash)
+  end
+
+end

data/test/unit/connection_tests.rb

@@ -0,0 +1,27 @@
+require 'assert'
+require 'sanford-protocol/connection'
+
+class Sanford::Protocol::Connection
+
+  class BaseTests < Assert::Context
+    desc "Sanford::Protocol::Connection"
+    setup do
+      setup_some_msg_data
+      @socket     = FakeSocket.new(@msg)
+      @connection = Sanford::Protocol::Connection.new(@socket)
+    end
+    subject{ @connection }
+
+    should have_instance_methods :read, :write
+
+    should "read messages off the socket with #read" do
+      assert_equal @data, subject.read
+    end
+
+    should "write messages to the socket with #write" do
+      subject.write(@data)
+      assert_equal @msg, @socket.out
+    end
+  end
+
+end

data/test/unit/fake_socket_tests.rb

@@ -0,0 +1,85 @@
+require 'assert'
+require 'sanford-protocol/test/fake_socket'
+require 'sanford-protocol/request'
+
+class Sanford::Protocol::Test::FakeSocket
+
+  class BaseTests < Assert::Context
+    desc "a FakeSocket"
+    setup do
+      @fs = FakeSocket.new
+    end
+    subject { @fs }
+
+    should have_cmeths :with_request, :with_msg_body, :with_encoded_msg_body
+    should have_imeths :in, :out, :reset
+    should have_imeths :recvfrom, :send
+
+    should "have no `in` or `out` data by default" do
+      assert_empty subject.in
+      assert_empty subject.out
+    end
+
+    should "push `out` data using #send" do
+      subject.send('some out data', 0)
+      assert_equal 'some out data', subject.out
+    end
+
+  end
+
+  class WithInDataTests < BaseTests
+    desc "created given some data"
+    setup do
+      @in_data = 'some in data'
+      @fs = FakeSocket.new(@in_data)
+    end
+
+    should "add the data as `in` data" do
+      assert_equal @in_data, subject.in
+    end
+
+    should "pull `in` data using #recvfrom" do
+      recvfrom_data = subject.recvfrom(@in_data.bytesize)
+
+      assert_kind_of ::Array, recvfrom_data
+      assert_equal @in_data, recvfrom_data.first
+    end
+
+    should "reset its `in` data using #reset" do
+      subject.reset('some different in data')
+      assert_equal 'some different in data', subject.in
+    end
+
+  end
+
+  class EncodedMessageTests < BaseTests
+    desc "with encoded msg data"
+    setup do
+      setup_some_msg_data
+    end
+
+    should "build with the msg as `in` data given the encoded msg body" do
+      s = FakeSocket.with_encoded_msg_body(@encoded_body)
+      assert_equal @msg, s.in
+    end
+
+    should "build with the msg as `in` data given the unencoded msg body" do
+      s = FakeSocket.with_msg_body(@data)
+      assert_equal @msg, s.in
+    end
+
+  end
+
+  class RequestTests < BaseTests
+    desc "that is a request"
+    setup do
+      setup_some_request_data
+    end
+
+    should "build with the request msg as `in` data given the request" do
+      s = FakeSocket.with_request(*@request_params)
+      assert_equal @msg, s.in
+    end
+  end
+
+end

data/test/unit/msg_data_tests.rb

@@ -0,0 +1,121 @@
+require 'assert'
+require 'sanford-protocol/msg_data'
+require 'sanford-protocol'
+
+class Sanford::Protocol::MsgData
+
+  class BadMessageTests < Assert::Context
+    desc "reading data on a bad message"
+    setup do
+      @debug = ENV['SANFORD_PROTOCOL_DEBUG']
+      ENV.delete('SANFORD_PROTOCOL_DEBUG')
+
+      @connection = Sanford::Protocol::Connection.new(FakeSocket.new)
+      @socket     = @connection.instance_variable_get "@socket"
+    end
+    teardown do
+      ENV['SANFORD_PROTOCOL_DEBUG'] = @debug
+    end
+    subject{ @connection }
+
+    def assert_bad_message(expected_msg)
+      exception = begin; subject.read; rescue Exception => err; err; end
+      assert_instance_of Sanford::Protocol::BadMessageError, exception
+      assert_equal expected_msg, exception.message
+    end
+
+  end
+
+  class BadSizeTests < BadMessageTests
+    desc "that errors when reading the version part"
+    setup do
+      @socket.stubs(:read).  # when reading the version, fail
+        with(Sanford::Protocol.msg_version.bytesize).
+        raises("simulated socket read error!")
+    end
+    teardown do
+      @socket.unstub(:read)
+    end
+
+    should "raise a BadMessageError with a relevant message" do
+      assert_bad_message "Error reading message protocol version"
+    end
+  end
+
+  class BadVersionTests < BadMessageTests
+    desc "that errors when reading the size part"
+    setup do
+      @socket.stubs(:read).  # when reading the version, succeed
+        with(Sanford::Protocol.msg_version.bytesize).
+        returns(Sanford::Protocol.msg_version)
+      @socket.stubs(:read).  # when reading the size, fail
+        with(Sanford::Protocol.msg_size.bytes).
+        raises("simulated socket read error!")
+    end
+    teardown do
+      @socket.unstub(:read)
+    end
+
+    should "raise a BadMessageError with a relevant message" do
+      assert_bad_message "Error reading message body size."
+    end
+  end
+
+  class BadBodyTests < BadMessageTests
+    desc "that errors when reading the body part"
+    setup do
+      @socket.stubs(:read).  # when reading the version, succeed
+        with(Sanford::Protocol.msg_version.bytesize).
+        returns(Sanford::Protocol.msg_version)
+      @socket.stubs(:read).  # when reading the size, succeed
+        with(Sanford::Protocol.msg_size.bytes).
+        returns(Sanford::Protocol.msg_size.encode(50))
+      @socket.stubs(:read).  # when reading the body, fail
+        with(50).
+        raises("simulated socket read error!")
+    end
+    teardown do
+      Sanford::Protocol.unstub(:read)
+    end
+
+    should "raise a BadMessageError with a relevant message" do
+      assert_bad_message "Error reading message body."
+    end
+  end
+
+  class NilSizeTests < BadMessageTests
+    desc 'that reads a nil size'
+    setup do
+      @socket.stubs(:read).  # when reading the version, succeed
+        with(Sanford::Protocol.msg_version.bytesize).
+        returns(Sanford::Protocol.msg_version)
+      @socket.stubs(:read).  # when reading the size, return nil
+        with(Sanford::Protocol.msg_size.bytes).
+        returns(nil)
+    end
+    teardown do
+      @socket.unstub(:read)
+    end
+
+    should "raise a BadMessageError with a relevant message" do
+      assert_bad_message "Empty message size"
+    end
+  end
+
+  class VersionMismatchTests < BadMessageTests
+    desc "with a mismatched protocol version"
+    setup do
+      @socket.stubs(:read).  # when reading the version, encode wrong number
+        with(Sanford::Protocol.msg_version.bytesize).
+        returns(Sanford::Protocol::PackedHeader.new(1, 'C').encode(0))
+    end
+    teardown do
+      @socket.unstub(:read)
+    end
+
+    should "raise a BadMessageError with a relevant message" do
+      assert_bad_message "Protocol version mismatch"
+    end
+  end
+
+end

data/test/unit/protocol_tests.rb

@@ -0,0 +1,51 @@
+# These tests are intended to be brittle and make sure the protocol conforms to
+# an expected spec. If any of these tests fail, you probably need to modify the
+# protocol's version constant.
+
+require 'assert'
+require 'sanford-protocol'
+
+module Sanford::Protocol
+  class BaseTests < Assert::Context
+    desc "Sanford::Protocol"
+    subject{ Sanford::Protocol }
+
+    should have_instance_methods :msg_version, :msg_size, :msg_body
+
+    should "define the protocol version" do
+      assert_equal 1, subject::VERSION
+    end
+
+    should "encode the protocol version to a 1B binary string" do
+      assert_equal 1, subject.msg_version.bytesize
+
+      expected = [ subject::VERSION ].pack('C')
+      assert_equal expected, subject.msg_version
+    end
+
+    should "encode/decode the size to/from a 4B binary string" do
+      assert_equal 4, subject.msg_size.bytes
+
+      size   = (2 ** 32) - 1 # the max number it supports
+      binary = [ size ].pack('N')
+      assert_equal binary, subject.msg_size.encode(size)
+      assert_equal size,   subject.msg_size.decode(binary)
+    end
+
+    should "encode the body to BSON" do
+      data = {
+        'string'  => 'test',
+        'int'     => 1,
+        'float'   => 2.1,
+        'boolean' => true,
+        'array'   => [ 1, 2, 3 ],
+        'hash'    => { 'something' => 'else' }
+      }
+      binary = ::BSON.serialize(data).to_s
+
+      assert_equal binary, subject.msg_body.encode(data)
+      assert_equal data,   subject.msg_body.decode(binary)
+    end
+
+  end
+end

data/test/unit/request_tests.rb

@@ -0,0 +1,71 @@
+require 'assert'
+require 'sanford-protocol/request'
+
+class Sanford::Protocol::Request
+
+  class BaseTests < Assert::Context
+    desc "Sanford::Protocol::Request"
+    setup do
+      @request = Sanford::Protocol::Request.new('v1', 'some_service', [ true ])
+    end
+    subject{ @request }
+
+    should have_instance_methods :name, :version, :params, :to_hash, :valid?
+    should have_class_methods :parse
+
+    should "return an instance of a Sanford::Protocol::Request given a hash using #parse" do
+      # using BSON messages are hashes
+      hash = {
+        'name'    => 'service_name',
+        'version' => 'service_version',
+        'params'  => 'service_params'
+      }
+      request = Sanford::Protocol::Request.parse(hash)
+
+      assert_instance_of Sanford::Protocol::Request, request
+      assert_equal hash['name'],     request.name
+      assert_equal hash['version'],  request.version
+      assert_equal hash['params'],   request.params
+    end
+
+    should "return the request as a hash with #to_hash" do
+      # using BSON messages are hashes
+      expected = {
+        'version' => 'v1',
+        'name'    => 'some_service',
+        'params'  => [ true ]
+      }
+
+      assert_equal expected, subject.to_hash
+    end
+  end
+
+  class ValidTests < BaseTests
+    desc "valid?"
+
+    should "return true and no message with a valid request" do
+      request = Sanford::Protocol::Request.new('name', 'v1', {})
+      is_valid, message = request.valid?
+
+      assert_equal true, is_valid
+      assert_equal nil, message
+    end
+
+    should "return false and a message when there isn't a name" do
+      request = Sanford::Protocol::Request.new('v1', nil, {})
+      is_valid, message = request.valid?
+
+      assert_equal false, is_valid
+      assert_equal "The request doesn't contain a name.", message
+    end
+
+    should "return false and a message when there isn't a version" do
+      request = Sanford::Protocol::Request.new(nil, 'name', {})
+      is_valid, message = request.valid?
+
+      assert_equal false, is_valid
+      assert_equal "The request doesn't contain a version.", message
+    end
+  end
+
+end

data/test/unit/response_status_tests.rb

@@ -0,0 +1,44 @@
+require 'assert'
+require 'sanford-protocol/response_status'
+
+class Sanford::Protocol::ResponseStatus
+
+  class BaseTests < Assert::Context
+    desc "Sanford::Protocol::ResponseStatus"
+    setup do
+      @status = Sanford::Protocol::ResponseStatus.new(200, "OK")
+    end
+    subject{ @status }
+
+    should have_readers :code_obj, :message
+    should have_instance_methods :code, :name
+
+    should "know it's code name" do
+      named  = Sanford::Protocol::ResponseStatus.new(200)
+      unamed = Sanford::Protocol::ResponseStatus.new(999)
+
+      assert_equal "OK", named.name
+      assert_equal nil,  unamed.name
+    end
+
+    should "know it's code numbers" do
+      Code::NUMBERS.each do |name, value|
+        status = Sanford::Protocol::ResponseStatus.new(name)
+        assert_equal value, status.code
+      end
+
+      unamed = Sanford::Protocol::ResponseStatus.new('unamed')
+      assert_equal 0, unamed.code
+    end
+
+    should "return it's code number and code name with #to_s" do
+      named  = Sanford::Protocol::ResponseStatus.new(200)
+      unamed = Sanford::Protocol::ResponseStatus.new(999)
+
+      assert_equal "[#{named.code}, #{named.name}]", named.to_s
+      assert_equal "[#{unamed.code}]", unamed.to_s
+    end
+
+  end
+
+end

data/test/unit/response_tests.rb

@@ -0,0 +1,74 @@
+require 'assert'
+require 'sanford-protocol/response'
+
+class Sanford::Protocol::Response
+
+  class BaseTests < Assert::Context
+    desc "Sanford::Protocol::Response"
+    setup do
+      @response = Sanford::Protocol::Response.new([ 672, 'YAR!' ], { 'something' => true })
+    end
+    subject{ @response }
+
+    should have_instance_methods :status, :result, :to_hash
+    should have_class_methods :parse
+
+    should "return an instance of a Sanford::Protocol::Response given a hash using #parse" do
+      # using BSON messages are hashes
+      hash = {
+        'status'  => [ 200, 'OK' ],
+        'result'  => 'yes'
+      }
+      request = Sanford::Protocol::Response.parse(hash)
+
+      assert_instance_of Sanford::Protocol::Response, request
+      assert_equal hash['status'].first,   request.status.code
+      assert_equal hash['status'].last,    request.status.message
+      assert_equal hash['result'],         request.result
+    end
+
+    should "return the request as a hash with #to_hash" do
+      # using BSON messages are hashes
+      expected = {
+        'status'  => [ 672, 'YAR!' ],
+        'result'  => { 'something' => true }
+      }
+
+      assert_equal expected, subject.to_hash
+    end
+  end
+
+  # Somewhat of a system test, want to make sure if Response is passed some
+  # "fuzzy" args that it will build it's status object as expected
+  class StatusBuildingTests < BaseTests
+
+    should "build a status with it's code set, given an integer" do
+      response = Sanford::Protocol::Response.new(574)
+
+      assert_equal 574, response.status.code
+      assert_equal nil, response.status.message
+    end
+
+    should "build a status with it's code set, given a name" do
+      response = Sanford::Protocol::Response.new('ok')
+
+      assert_equal 200, response.status.code
+      assert_equal nil, response.status.message
+    end
+
+    should "use a status object, if given one" do
+      status = Sanford::Protocol::ResponseStatus.new(200, "OK")
+      response = Sanford::Protocol::Response.new(status)
+
+      assert_same status, response.status
+    end
+
+    should "build a status with a code and message set, when given both" do
+      response = Sanford::Protocol::Response.new([ 348, "my message" ])
+
+      assert_equal 348,           response.status.code
+      assert_equal "my message",  response.status.message
+    end
+  end
+
+end

data/test/unit/test_helpers_tests.rb

@@ -0,0 +1,35 @@
+require 'assert'
+require 'sanford-protocol/test/helpers'
+
+module Sanford::Protocol::Test::Helpers
+
+  class BaseTests < Assert::Context
+    desc "the test helpers"
+    subject { Sanford::Protocol::Test::Helpers }
+
+    should have_imeths :fake_socket_with_request, :fake_socket_with_msg_body
+    should have_imeths :fake_socket_with_encoded_msg_body, :fake_socket_with
+    should have_imeths :read_response_from_fake_socket
+    should have_imeths :read_written_response_from_fake_socket
+
+    should "be able to read responses given a fake socket" do
+      setup_some_response_data
+      fs = FakeSocket.new(@msg)
+      response = subject.read_response_from_fake_socket(fs)
+
+      assert_kind_of Sanford::Protocol::Response, response
+      assert_equal @data, response.to_hash
+    end
+
+    should "be able to read responses written to a fake socket" do
+      setup_some_response_data
+      fs = FakeSocket.new; fs.send(@msg, 0)
+      response = subject.read_written_response_from_fake_socket(fs)
+
+      assert_kind_of Sanford::Protocol::Response, response
+      assert_equal @data, response.to_hash
+    end
+
+  end
+
+end

metadata

@@ -0,0 +1,143 @@
+--- !ruby/object:Gem::Specification 
+name: sanford-protocol
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Collin Redding
+- Kelly Redding
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-11-14 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bson
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 1
+        segments: 
+        - 1
+        - 7
+        version: "1.7"
+  type: :runtime
+  requirement: *id001
+  prerelease: false
+- !ruby/object:Gem::Dependency 
+  name: assert
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 0
+        - 8
+        version: "0.8"
+  type: :development
+  requirement: *id002
+  prerelease: false
+- !ruby/object:Gem::Dependency 
+  name: assert-mocha
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 9
+        segments: 
+        - 0
+        - 1
+        version: "0.1"
+  type: :development
+  requirement: *id003
+  prerelease: false
+description: Ruby implementation of Sanford's communication protocol.
+email: 
+- collin.redding@me.com
+- kelly@kellyredding.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/sanford-protocol.rb
+- lib/sanford-protocol/connection.rb
+- lib/sanford-protocol/msg_data.rb
+- lib/sanford-protocol/request.rb
+- lib/sanford-protocol/response.rb
+- lib/sanford-protocol/response_status.rb
+- lib/sanford-protocol/test/fake_socket.rb
+- lib/sanford-protocol/test/helpers.rb
+- lib/sanford-protocol/version.rb
+- sanford-protocol.gemspec
+- test/helper.rb
+- test/unit/connection_tests.rb
+- test/unit/fake_socket_tests.rb
+- test/unit/msg_data_tests.rb
+- test/unit/protocol_tests.rb
+- test/unit/request_tests.rb
+- test/unit/response_status_tests.rb
+- test/unit/response_tests.rb
+- test/unit/test_helpers_tests.rb
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Ruby implementation of Sanford's communication protocol.
+test_files: 
+- test/helper.rb
+- test/unit/connection_tests.rb
+- test/unit/fake_socket_tests.rb
+- test/unit/msg_data_tests.rb
+- test/unit/protocol_tests.rb
+- test/unit/request_tests.rb
+- test/unit/response_status_tests.rb
+- test/unit/response_tests.rb
+- test/unit/test_helpers_tests.rb