zser 0.0.0 → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fb260ef1f52f3f448b3c0d0ab9ccb928eccee9ca
-  data.tar.gz: dfd54beaadb613c40f5efc22d03b74a13e269aaa
+  metadata.gz: a4ff5c747cc1a2d7be12df6224a14c098a1a06a5
+  data.tar.gz: 331c618c62205dea46544daa16a2ebbdebd59a3e
 SHA512:
-  metadata.gz: 44a8c44a41ef521928a8d4df503d4a83b294b8fbf65af1633f2a3b3117a6b999ea08ab330d4613aad5a337d558dd2fbb82bd5e1eb0c11a78fb246b72f28bab9b
-  data.tar.gz: 434712a1819396dfe786fafd4a06f189025c01a6ef300478a66bb1a2108440676cd5903af2cc7e21954836b78096c007aa58d9c2a2feb16650501de472d0dec5
+  metadata.gz: 55f3a70cc8e4e67c19adea81d7f32172970168b0b710e182b5e95a5e1c7cdde8d53d1642508b3c6e6a649eab4597899c30e9211d8bfa7daa9c4fc4523e745e85
+  data.tar.gz: d95178c9ad6d06c2ed2de519c7a3d0749963161ee9f15b7cb30163e715e3d7d43cfcc0ef2ce77ea99dd5dc56378d229400a2d5b4496fa9958752aac4e8d1180e

data/.gitignore

@@ -7,6 +7,7 @@
 /pkg/
 /spec/reports/
 /tmp/
+/.rakeTasks
 
 # rspec failure tracking
 .rspec_status

data/.rspec

@@ -1,2 +1,4 @@
---format documentation
 --color
+--format=documentation
+--order random
+--require spec_helper

data/.rubocop.yml

@@ -5,8 +5,11 @@ AllCops:
 # Style
 #
 
-LineLength:
-  Max: 128
+Style/ModuleFunction:
+  Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes
@@ -16,16 +19,22 @@ Style/StringLiterals:
 #
 
 Metrics/AbcSize:
-  Enabled: false
-
-Metrics/CyclomaticComplexity:
-  Enabled: false
+  Max: 25
 
-Metrics/PerceivedComplexity:
+Metrics/BlockLength:
   Enabled: false
 
 Metrics/ClassLength:
   Max: 100
 
+Metrics/CyclomaticComplexity:
+  Max: 25
+
+Metrics/LineLength:
+  Max: 128
+
 Metrics/MethodLength:
   Max: 25
+
+Metrics/PerceivedComplexity:
+  Max: 25

data/.ruby-version

@@ -0,0 +1 @@
+2.4.1

data/Gemfile

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
 source "https://rubygems.org"
+ruby RUBY_VERSION
 
 gemspec
 
 group :development, :test do
+  gem "benchmark-ips"
+  gem "guard-rspec"
   gem "rake"
   gem "rspec", "~> 3.5"
-  gem "rubocop", "0.44.1"
+  gem "rubocop", "0.48.1"
+  gem "tjson", "~> 0.5"
 end

data/Guardfile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec, cmd: "GUARD_RSPEC=1 bundle exec rspec --no-profile" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper)  { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/README.md

@@ -1,15 +1,46 @@
-# Zser
+# zser.rb [![Latest Version][gem-shield]][gem-link] [![Build Status][build-image]][build-link] [![MIT licensed][license-image]][license-link]
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/zser`. To experiment with that code, run `bin/console` for an interactive prompt.
+[gem-shield]: https://badge.fury.io/rb/zser.svg
+[gem-link]: https://rubygems.org/gems/zser
+[build-image]: https://secure.travis-ci.org/zcred/zser.svg?branch=master
+[build-link]: http://travis-ci.org/zcred/zser
+[license-image]: https://img.shields.io/badge/license-MIT-blue.svg
+[license-link]: https://github.com/zcred/zser/blob/master/LICENSE.txt
 
-TODO: Delete this and the text above, and describe your gem
+Ruby implementation of **zser**: a security-oriented serialization format
+with novel authentication properties based on "Merkleized" data structures.
+
+For more information, see the [toplevel README.md].
+
+[toplevel README.md]: https://github.com/zcred/zser/blob/master/README.md
+
+## Help and Discussion
+
+Have questions? Want to suggest a feature or change?
+
+* [Gitter]: web-based chat about zcred projects including **zser**
+* [Google Group]: join via web or email ([zcred+subscribe@googlegroups.com])
+
+[Gitter]: https://gitter.im/zcred/Lobby
+[Google Group]: https://groups.google.com/forum/#!forum/zcred
+[zcred+subscribe@googlegroups.com]: mailto:zcred+subscribe@googlegroups.com
+
+## Requirements
+
+This library is tested against the following MRI versions:
+
+- 2.2
+- 2.3
+- 2.4
+
+Other Ruby versions may work, but are not officially supported.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'zser'
+gem "zser"
 ```
 
 And then execute:
@@ -20,17 +51,25 @@ Or install it yourself as:
 
     $ gem install zser
 
-## Usage
+## API
 
-TODO: Write usage instructions here
+### Zser.parse
 
-## Development
+To parse a **zser** message, use the `Zser.parse` method:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```ruby
+>> Zser.parse("\x15\x07\x02\x03\x55".b)
+=> {1=>{24=>42}}
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/tarcieri/zser.
+Bug reports and pull requests are welcome on GitHub at https://github.com/zcred/zser
+
+## Copyright
+
+Copyright (c) 2017 [The Zcred Developers][AUTHORS].
+See [LICENSE.txt] for further details.
 
+[AUTHORS]: https://github.com/zcred/zcred/blob/master/AUTHORS.md
+[LICENSE.txt]: https://github.com/zcred/zser/blob/master/LICENSE.txt

data/Rakefile

@@ -8,4 +8,18 @@ RSpec::Core::RakeTask.new
 require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
-task default: %w(spec rubocop)
+task default: %w[spec rubocop]
+
+task :bench do
+  require "benchmark/ips"
+  require "zser"
+
+  Benchmark.ips do |b|
+    input = "\xE9\xF4\x81\x80\x80\x80@".dup.force_encoding("BINARY").freeze
+
+    b.report("zsint encode") { Zser::Varint.encode(281_474_976_741_993) }
+    b.report("zsint decode") { Zser::Varint.decode(input) }
+
+    b.compare!
+  end
+end

data/lib/zser.rb

@@ -1,5 +1,23 @@
+# frozen_string_literal: true
+
 require "zser/version"
+require "zser/exceptions"
+
+require "zser/decoder"
+require "zser/object"
+require "zser/parser"
+require "zser/varint"
 
 # zcred serialization format
 module Zser
+  # Parse the given self-describing zser message
+  #
+  # @param message [String] binary encoded zser message
+  #
+  # @return [Zser::Object] Hash-like object representing message
+  def self.parse(message)
+    parser = Zser::Parser.new(Zser::Decoder.new)
+    parser.parse(message)
+    parser.finish
+  end
 end

data/lib/zser/decoder.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Zser
+  # Build Zser::Objects from zser's self-describing form
+  class Decoder
+    # Create a new decoder object which will construct a Zser::Object tree
+    def initialize
+      @stack = [Zser::Object.new]
+    end
+
+    # Add a uint64 to the current object
+    def uint64(id, value)
+      raise TypeError, "expected Integer, got #{value.class}" unless value.is_a?(Integer)
+      @stack.last[id] = value
+    end
+
+    # Add binary data to the current object
+    def binary(id, value)
+      raise TypeError, "expected String, got #{value.class}" unless value.is_a?(String)
+      raise EncodingError, "expected BINARY encoding, got #{value.encoding}" unless value.encoding == Encoding::BINARY
+      @stack.last[id] = value
+    end
+
+    # Push down the internal stack, constructing a new Zser::Object
+    def begin_nested
+      @stack << Zser::Object.new
+    end
+
+    # Complete the pushdown, adding the newly constructed object to the next one in the stack
+    def end_nested(id)
+      value = @stack.pop
+      raise StateError, "not inside a nested message" if @stack.empty?
+      @stack.last[id] = value
+    end
+
+    # Finish decoding, returning the parent Zser::Object
+    def finish
+      result = @stack.pop
+      raise StateError, "objects remaining in stack" unless @stack.empty?
+      result
+    end
+  end
+end

data/lib/zser/exceptions.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Zser
+  # Base class of all Zser errors
+  Error = Class.new(StandardError)
+
+  # Generic parse error
+  ParseError = Class.new(Error)
+
+  # Data is not in the correct character encoding
+  EncodingError = Class.new(ParseError)
+
+  # Unexpected end of input
+  EOFError = Class.new(ParseError)
+
+  # Message is larger than our maximum configured size
+  OversizeMessageError = Class.new(ParseError)
+
+  # Nested message structure is too deep
+  DepthError = Class.new(ParseError)
+
+  # Parser is in the wrong state to perform the given task
+  StateError = Class.new(ParseError)
+
+  # Field repeated in message
+  DuplicateFieldError = Class.new(ParseError)
+end

data/lib/zser/object.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Zser
+  # Key/value pairs ala JSON objects or Protobuf messages
+  class Object
+    # Create a new Zser::Object
+    #
+    # @return [Zser::Object]
+    def initialize
+      @fields = {}
+    end
+
+    # Retrieve the value associated with a field identifier in a Zser::Object
+    #
+    # @param key [Integer] field identifier
+    #
+    # @return [Object] value associated with this key
+    def [](key)
+      @fields[key]
+    end
+
+    # Sets the value associated with a field identifier
+    #
+    # @param key [Integer] field identifier
+    # @param value [Object] value associated with the given key
+    #
+    # @raise [TypeError] non-Integer key given
+    # @raise [Zser::DuplicateFieldError] attempt to set field that's already been set
+    #
+    # @return [Object] newly set value
+    def []=(key, value)
+      raise TypeError, "key must be an integer: #{key.inspect}" unless key.is_a?(Integer)
+      raise RangeError, "key must be positive: #{key.inspect}" if key < 0
+      raise DuplicateFieldError, "duplicate field ID: #{key}" if @fields.key?(key)
+
+      @fields[key] = value
+    end
+
+    # Return a hash representation of this object (and its children).
+    # This is akin to an `#as_json` method as seen in e.g. Rails.
+    #
+    # @return [Hash] a hash representation of this object
+    def to_h
+      result = {}
+
+      @fields.each do |k, v|
+        result[k.to_s] = v.is_a?(self.class) ? v.to_h : v
+      end
+
+      result
+    end
+  end
+end

data/lib/zser/parser.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Zser
+  # Parses encoded zser messages, invoking callbacks in the given handler
+  # (i.e. this is a "push parser" which supports different backends)
+  class Parser
+    # Default maximum length of a zser message. This is a conservative choice
+    # as zser's main intended use is a credential format.
+    MAX_LENGTH = 1024
+
+    # Default maximum depth (i.e. number of levels of child objects)
+    MAX_DEPTH = 8
+
+    # Create a new message parser with the given parse event handler
+    def initialize(handler, max_length = MAX_LENGTH, max_depth = MAX_DEPTH)
+      @handler = handler
+      @max_length = max_length
+      @max_depth = max_depth
+      @remaining = []
+    end
+
+    # Parse the given zser message, invoking callbacks as necessary
+    def parse(msg)
+      raise OversizeMessageError, "length #{msg.length} exceeds max of #{@max_length}" if msg.length > @max_length
+      raise EncodingError, "expected BINARY encoding, got #{msg.encoding}" unless msg.encoding == Encoding::BINARY
+      @remaining << msg
+
+      raise DepthError, "exceeded max depth of #{@max_depth}" if @remaining.size > @max_depth
+
+      until @remaining.last.empty?
+        id, wiretype = parse_field_prefix
+
+        case wiretype
+        when 0 then parse_uint64(id)
+        when 2 then parse_message(id)
+        when 3 then parse_binary(id)
+        else raise ParseError, "unknown wiretype: #{wiretype.inspect}"
+        end
+      end
+
+      @remaining.pop
+
+      true
+    end
+
+    # Finish parsing, returning the resulting object produced by the builder
+    def finish
+      @handler.finish
+    end
+
+    private
+
+    # Parse a varint which also stores a wiretype
+    def parse_field_prefix
+      result, remaining = Zser::Varint.decode(@remaining.pop)
+      @remaining << remaining
+      wiretype = result & 0x7
+      [result >> 3, wiretype]
+    end
+
+    # Parse an unsigned 64-bit integer
+    def parse_uint64(id)
+      value, remaining = Zser::Varint.decode(@remaining.pop)
+      @remaining << remaining
+      @handler.uint64(id, value)
+    end
+
+    # Parse a data type stored with a length prefix
+    def parse_length_prefixed_data
+      length, remaining = Zser::Varint.decode(@remaining.pop)
+      raise EOFError, "not enough bytes remaining in input" if remaining.bytesize < length
+      data = remaining.byteslice(0, length)
+      @remaining << remaining.byteslice(length, remaining.bytesize - length)
+      data
+    end
+
+    # Parse a nested message
+    def parse_message(id)
+      @handler.begin_nested
+      parse(parse_length_prefixed_data)
+      @handler.end_nested(id)
+    end
+
+    # Parse length-prefixed binary data
+    def parse_binary(id)
+      @handler.binary(id, parse_length_prefixed_data)
+    end
+  end
+end

data/lib/zser/varint.rb

@@ -0,0 +1,99 @@
+# encoding: binary
+# frozen_string_literal: true
+
+module Zser
+  # zsint: Little Endian 64-bit Unsigned Prefix Varints
+  module Varint
+    # Maximum value we can encode as a zsuint64
+    MAX = (2**64) - 1
+
+    # :nodoc: Lookup table for the number of trailing zeroes in a byte
+    CTZ_TABLE = [8, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+                 4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+                 5, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+                 4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+                 6, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+                 4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+                 5, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+                 4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+                 7, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+                 4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+                 5, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+                 4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+                 6, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+                 4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+                 5, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+                 4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0].freeze
+
+    # Encode the given integer value as a zsuint64
+    #
+    # @param value [Integer] unsigned integer value to encode as a zsuint64
+    #
+    # @raise [TypeError] non-integer value given
+    # @raise [ArgumentError] value outside the unsigned 64-bit integer range
+    #
+    # @return [String] serialized zsuint64 value
+    def self.encode(value)
+      raise TypeError, "value must be an Integer" unless value.is_a?(Integer)
+      raise ArgumentError, "value must be zero or greater" if value < 0
+      raise ArgumentError, "value must be in the 64-bit unsigned range" if value > MAX
+
+      length = 1
+      result = (value << 1) | 1
+      max = 1 << 7
+
+      while value >= max
+        # 9-byte special case
+        return [0, value].pack("CQ<") if max == 1 << 63
+
+        result <<= 1
+        max <<= 7
+        length += 1
+      end
+
+      [result].pack("Q<")[0, length].force_encoding(Encoding::BINARY)
+    end
+
+    # Decode a zsuint64-serialized value into an integer
+    #
+    # @param input [String] serialized zsuint64 to decode
+    #
+    # @raise [TypeError] non-String input given
+    # @raise [ArgumentError] empty input given
+    #
+    # @return [Array<Integer, String>] decoded integer and remaining data
+    def self.decode(input)
+      raise TypeError, "input must be a String" unless input.is_a?(String)
+      raise ArgumentError, "input cannot be empty" if input.empty?
+
+      prefix = input.getbyte(0)
+      input_len = input.bytesize
+
+      # 9-byte special case
+      if prefix.zero?
+        raise EOFError, "not enough bytes to decode varint" if input_len < 9
+        [decode_le64(input[1, 8]), input.byteslice(9, input_len - 9)]
+      else
+        # Count trailing zeroes
+        length = CTZ_TABLE[prefix] + 1
+        raise EOFError, "not enough bytes to decode varint" if input_len < length
+        [decode_le64(input[0, length]) >> length, input.byteslice(length, input_len - length)]
+      end
+    end
+
+    class << self
+      private
+
+      # Decode a little endian integer (without allocating memory, unlike pack)
+      def decode_le64(bytes)
+        result = 0
+
+        (bytes.bytesize - 1).downto(0) do |i|
+          result = (result << 8) | bytes.getbyte(i)
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/zser/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Zser
-  VERSION = "0.0.0".freeze
+  VERSION = "0.0.1"
 end

data/zser.gemspec

@@ -1,4 +1,6 @@
-# coding: utf-8
+# encoding: utf-8
+# frozen_string_literal: true
+
 lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "zser/version"
@@ -16,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = ">= 2.0"
+  spec.required_ruby_version = ">= 2.2.2"
 
   spec.add_development_dependency "bundler", "~> 1.14"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zser
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.1
 platform: ruby
 authors:
 - Tony Arcieri
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-03-23 00:00:00.000000000 Z
+date: 2017-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -35,13 +35,17 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
-- ".travis.yml"
+- ".ruby-version"
 - Gemfile
+- Guardfile
 - README.md
 - Rakefile
-- bin/console
-- bin/setup
 - lib/zser.rb
+- lib/zser/decoder.rb
+- lib/zser/exceptions.rb
+- lib/zser/object.rb
+- lib/zser/parser.rb
+- lib/zser/varint.rb
 - lib/zser/version.rb
 - zser.gemspec
 homepage: https://github.com/zcred/zser/tree/master/ruby/
@@ -55,7 +59,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.0'
+      version: 2.2.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -63,7 +67,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.10
+rubygems_version: 2.6.11
 signing_key: 
 specification_version: 4
 summary: zcred serialization format

data/.travis.yml

@@ -1,5 +0,0 @@
-sudo: false
-language: ruby
-rvm:
-  - 2.4.0
-before_install: gem install bundler -v 1.14.5

data/bin/console

@@ -1,14 +0,0 @@
-#!/usr/bin/env ruby
-
-require "bundler/setup"
-require "zser"
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start(__FILE__)

data/bin/setup

@@ -1,8 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
-
-bundle install
-
-# Do any other automated setup that you need to do here