protostar 0.1.0.beta1

data/lib/protostar/well_known/timestamp.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Protostar
+  module WellKnown
+    # Mixed into google.protobuf.Timestamp
+    module Timestamp
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # @param value [Object]
+      # @return [Array(Integer, Integer), nil] seconds and nanos of a Time, a
+      #   DateTime or a Date; nil for anything else
+      def self.parts(value)
+        time = if value.is_a?(::Time) then value
+        elsif defined?(::Date) && value.is_a?(::Date) then value.to_time
+        else return nil
+        end
+        [time.to_i, time.nsec]
+      end
+
+      module ClassMethods
+        # @param time [Time]
+        # @return [Message] a new Timestamp at the same instant, to the nanosecond
+        def from_time(time)
+          new.from_time(time)
+        end
+
+        # What a Timestamp field makes of a value that is neither a Timestamp
+        # nor a Hash: a Time, a DateTime or a Date becomes a Timestamp
+        # @return [Message, nil]
+        # @api private
+        def __coerce(value)
+          seconds, nanos = Timestamp.parts(value)
+          new(seconds: seconds, nanos: nanos) if seconds
+        end
+      end
+
+      # @param time [Time]
+      # @return [self]
+      def from_time(time)
+        self.seconds = time.to_i
+        self.nanos = time.nsec
+        self
+      end
+
+      # @return [Time] in the local zone, as `Time.at` gives it
+      def to_time
+        ::Time.at(seconds, nanos, :nanosecond)
+      end
+
+      # @return [Integer] seconds since the epoch
+      def to_i
+        seconds
+      end
+
+      # @return [Rational] seconds since the epoch, exact; google-protobuf
+      #   returns a Rational here too
+      def to_f
+        seconds + nanos.quo(1_000_000_000)
+      end
+    end
+  end
+end

data/lib/protostar/well_known/value.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Protostar
+  module WellKnown
+    # Mixed into google.protobuf.Value
+    module Value
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # @param value [Object] nil, Numeric, String, true, false, Hash,
+        #   Array, a Struct or a ListValue
+        # @return [Message] a new Value
+        # @raise [UnexpectedStructType]
+        def from_ruby(value)
+          new.from_ruby(value)
+        end
+      end
+
+      # @param recursive [Boolean] whether to convert a Struct or ListValue to
+      #   a Hash or Array as well
+      # @return [Object]
+      # @raise [UnexpectedStructType] when no kind is set
+      def to_ruby(recursive = false)
+        case which_kind
+        when :struct_value then recursive ? struct_value.to_h : struct_value
+        when :list_value then recursive ? list_value.to_a : list_value
+        when :null_value then nil
+        when :number_value then number_value
+        when :string_value then string_value
+        when :bool_value then bool_value
+        else raise UnexpectedStructType
+        end
+      end
+
+      # Sets the kind matching a Ruby value
+      # @return [self]
+      # @raise [UnexpectedStructType]
+      def from_ruby(value)
+        fields = self.class.__by_name
+        struct_class = fields.fetch("struct_value").message_class
+        list_class = fields.fetch("list_value").message_class
+        case value
+        when NilClass then self.null_value = :NULL_VALUE
+        when Numeric then self.number_value = value.to_f
+        when String then self.string_value = value
+        when TrueClass then self.bool_value = true
+        when FalseClass then self.bool_value = false
+        when struct_class then self.struct_value = value
+        when Hash then self.struct_value = struct_class.from_hash(value)
+        when list_class then self.list_value = value
+        when Array then self.list_value = list_class.from_a(value)
+        else raise UnexpectedStructType
+        end
+        self
+      end
+    end
+  end
+end

data/lib/protostar/well_known.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Protostar
+  # Ruby helpers for the well-known types, with the names google-protobuf's
+  # `well_known_types.rb` gives them. {Types.define} includes the matching
+  # mixin into a class whose full name is in {MIXINS}, so the helpers are
+  # there however the class came to be defined.
+  #
+  #   any = Google::Protobuf::Any.pack(person)
+  #   any.unpack(Person)              # => person
+  #   Google::Protobuf::Timestamp.from_time(Time.now).to_time
+  #   Google::Protobuf::Struct.from_hash("a" => [1, nil]).to_h
+  module WellKnown
+    # Raised by Struct, Value and ListValue for a Ruby value they cannot hold
+    class UnexpectedStructType < Protostar::Error; end
+  end
+end
+
+require_relative "well_known/any"
+require_relative "well_known/timestamp"
+require_relative "well_known/duration"
+require_relative "well_known/struct"
+require_relative "well_known/value"
+require_relative "well_known/list_value"
+
+module Protostar
+  module WellKnown
+    # Full name to the mixin {Types.define} includes into that class
+    MIXINS = {
+      "google.protobuf.Any" => Any,
+      "google.protobuf.Timestamp" => Timestamp,
+      "google.protobuf.Duration" => Duration,
+      "google.protobuf.Struct" => Struct,
+      "google.protobuf.Value" => Value,
+      "google.protobuf.ListValue" => ListValue
+    }.freeze
+  end
+end

data/lib/protostar/wire/io_source.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Wire
+    # Presents an IO::Buffer with the String methods {Reader} uses, so that
+    # a buffer is read in place: numbers with `get_value`, and only string
+    # and bytes values copied out, with `get_string`.
+    class IOSource
+      # unpack1 directives the codec uses, as IO::Buffer data types
+      TYPES = {"V" => :u32, "Q<" => :u64, "l<" => :s32, "q<" => :s64, "e" => :f32, "E" => :f64}.freeze
+
+      # @return [IO::Buffer]
+      attr_reader :buffer
+      # @return [Integer]
+      attr_reader :bytesize
+
+      # @param buffer [IO::Buffer] must not change while it is read
+      def initialize(buffer)
+        @buffer = buffer
+        @bytesize = buffer.size
+        freeze
+      end
+
+      # @return [Integer]
+      def getbyte(offset)
+        @buffer.get_value(:U8, offset)
+      end
+
+      # @return [String] a new binary String
+      def byteslice(offset, length)
+        @buffer.get_string(offset, length)
+      end
+
+      # @param format [String] one of the directives in {TYPES}
+      def unpack1(format, offset:)
+        @buffer.get_value(TYPES.fetch(format), offset)
+      end
+    end
+  end
+end

data/lib/protostar/wire/reader.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Wire
+    # Reads wire-format values from a String without copying it or allocating
+    # per byte. The String is never mutated, and its encoding does not matter:
+    # every read works on bytes. An IO::Buffer is read in place through an
+    # {IOSource}, and so is any source answering `getbyte`, `byteslice`,
+    # `unpack1(format, offset:)` and `bytesize` the way String does.
+    #
+    # A reader has a position and a limit. Reads never go past the limit, so a
+    # nested message is read by narrowing the limit to its end and restoring it
+    # afterwards ({#push_limit}, {#pop_limit}).
+    #
+    #   r = Protostar::Wire::Reader.new(bytes)
+    #   until r.eof?
+    #     number, wire_type = r.read_tag
+    #     ...
+    #   end
+    class Reader
+      # What a source other than a String must answer
+      SOURCE_METHODS = %i[getbyte byteslice unpack1 bytesize].freeze
+
+      # @return [String, IOSource, Object] the underlying bytes
+      attr_reader :buffer
+      # @return [Integer] the current byte offset
+      attr_accessor :pos
+      # @return [Integer] the offset reads must not pass
+      attr_reader :limit
+
+      # @param buffer [String, IO::Buffer, #getbyte] an IO::Buffer is wrapped in an {IOSource}, not copied
+      # @param pos [Integer] where to start
+      # @param limit [Integer, nil] where to stop, the end of the buffer by default
+      def initialize(buffer, pos = 0, limit = nil)
+        buffer = IOSource.new(buffer) if defined?(IO::Buffer) && buffer.is_a?(IO::Buffer)
+        unless buffer.is_a?(String) || SOURCE_METHODS.all? { |m| buffer.respond_to?(m) }
+          raise ::TypeError, "expected a String, an IO::Buffer or a source answering #{SOURCE_METHODS.join(", ")}, got #{buffer.class}"
+        end
+        @buffer = buffer
+        @pos = pos
+        @limit = limit || buffer.bytesize
+        raise ArgumentError, "limit #{@limit} is past the end of the buffer" if @limit > buffer.bytesize
+      end
+
+      # @return [Boolean] whether the position has reached the limit
+      def eof?
+        @pos >= @limit
+      end
+
+      # Narrows the limit to `length` bytes from the current position
+      # @return [Integer] the previous limit, to hand to {#pop_limit}
+      # @raise [DecodeError] when that runs past the current limit
+      def push_limit(length)
+        new_limit = @pos + length
+        raise DecodeError.new("length #{length} runs past the end of the input", offset: @pos) if new_limit > @limit
+        old = @limit
+        @limit = new_limit
+        old
+      end
+
+      # Restores a limit returned by {#push_limit}
+      def pop_limit(old_limit)
+        @limit = old_limit
+      end
+
+      # @return [Integer] an unsigned varint of up to 64 bits. Longer encodings
+      #   are truncated to 64 bits, as protoc does.
+      # @raise [DecodeError] when truncated or longer than ten bytes
+      def read_varint
+        pos = @pos
+        raise DecodeError.new("truncated varint", offset: pos) if pos >= @limit
+        byte = @buffer.getbyte(pos)
+        if byte < 0x80
+          @pos = pos + 1
+          return byte
+        end
+        read_varint_slow(pos)
+      end
+
+      # @return [Integer] a tag's varint, unchecked
+      # @raise [DecodeError] when truncated or longer than five bytes, which
+      #   protoc refuses even when the value would fit
+      def read_tag_varint
+        at = @pos
+        tag = read_varint
+        raise DecodeError.new("tag longer than 5 bytes", offset: at) if @pos - at > 5
+        tag
+      end
+
+      # @return [Array(Integer, Integer)] field number and wire type
+      # @raise [DecodeError] for field number 0, an out of range tag or an invalid wire type
+      def read_tag
+        at = @pos
+        tag = read_tag_varint
+        Reader.check_tag(tag, at)
+        [tag >> 3, tag & 7]
+      end
+
+      # @return [Integer] a signed 32-bit integer from a varint (int32 and enum)
+      def read_int32
+        v = read_varint & MASK32
+        (v >= 0x8000_0000) ? v - 0x1_0000_0000 : v
+      end
+
+      # @return [Integer] a signed 64-bit integer from a varint
+      def read_int64
+        v = read_varint
+        (v >= 0x8000_0000_0000_0000) ? v - 0x1_0000_0000_0000_0000 : v
+      end
+
+      # @return [Integer] an unsigned 32-bit integer from a varint
+      def read_uint32
+        read_varint & MASK32
+      end
+
+      # @return [Integer] a zigzag-decoded signed 32-bit integer (sint32)
+      def read_sint32
+        v = read_varint & MASK32
+        (v >> 1) ^ -(v & 1)
+      end
+
+      # @return [Integer] a zigzag-decoded signed 64-bit integer (sint64)
+      def read_sint64
+        v = read_varint
+        (v >> 1) ^ -(v & 1)
+      end
+
+      # @return [Integer] an unsigned 32-bit little-endian integer
+      def read_fixed32
+        read_fixed(4, "V")
+      end
+
+      # @return [Integer] an unsigned 64-bit little-endian integer
+      def read_fixed64
+        read_fixed(8, "Q<")
+      end
+
+      # @return [Integer]
+      def read_sfixed32
+        read_fixed(4, "l<")
+      end
+
+      # @return [Integer]
+      def read_sfixed64
+        read_fixed(8, "q<")
+      end
+
+      # @return [Float]
+      def read_float
+        read_fixed(4, "e")
+      end
+
+      # @return [Float]
+      def read_double
+        read_fixed(8, "E")
+      end
+
+      # Reads a varint length and that many bytes
+      # @return [String] a new binary String
+      def read_bytes
+        len = read_varint
+        read_raw(len)
+      end
+
+      # @return [String] the next `length` bytes as a new binary String
+      def read_raw(length)
+        pos = @pos
+        raise DecodeError.new("length #{length} runs past the end of the input", offset: pos) if pos + length > @limit
+        @pos = pos + length
+        s = @buffer.byteslice(pos, length)
+        s.force_encoding(BINARY)
+      end
+
+      # Skips the value of a field whose tag was just read
+      # @param number [Integer] the field number, needed to match the end of a group
+      # @param wire_type [Integer]
+      # @param depth [Integer] groups left before {DecodeError} for nesting too deep
+      def skip_field(number, wire_type, depth = 100)
+        case wire_type
+        when VARINT then read_varint
+        when FIXED64 then skip(8)
+        when LENGTH_DELIMITED then skip(read_varint)
+        when FIXED32 then skip(4)
+        when START_GROUP then skip_group(number, depth)
+        when END_GROUP then raise DecodeError.new("unmatched end of group #{number}", offset: @pos)
+        else raise DecodeError.new("invalid wire type #{wire_type}", offset: @pos)
+        end
+        nil
+      end
+
+      # @raise [DecodeError] unless `length` bytes remain before the limit
+      def skip(length)
+        raise DecodeError.new("length #{length} runs past the end of the input", offset: @pos) if @pos + length > @limit
+        @pos += length
+      end
+
+      # Skips the contents of a group up to and including its end tag
+      def skip_group(number, depth = 100)
+        raise DecodeError.new("groups nested too deep", offset: @pos) if depth <= 0
+        loop do
+          raise DecodeError.new("missing end of group #{number}", offset: @pos) if @pos >= @limit
+          at = @pos
+          tag = read_tag_varint
+          Reader.check_tag(tag, at)
+          n = tag >> 3
+          wt = tag & 7
+          if wt == END_GROUP
+            return if n == number
+            raise DecodeError.new("end of group #{n} does not match group #{number}", offset: at)
+          end
+          skip_field(n, wt, depth - 1)
+        end
+      end
+
+      # @api private
+      def self.check_tag(tag, at)
+        raise DecodeError.new("tag out of range", offset: at) if tag > MASK32
+        raise DecodeError.new("field number 0", offset: at) if tag < 8
+        wt = tag & 7
+        raise DecodeError.new("invalid wire type #{wt}", offset: at) if wt > 5
+      end
+
+      private
+
+      def read_fixed(size, format)
+        pos = @pos
+        raise DecodeError.new("truncated #{size * 8}-bit value", offset: pos) if pos + size > @limit
+        @pos = pos + size
+        @buffer.unpack1(format, offset: pos)
+      end
+
+      def read_varint_slow(start)
+        buf = @buffer
+        limit = @limit
+        pos = start
+        result = 0
+        shift = 0
+        while shift < 70
+          raise DecodeError.new("truncated varint", offset: start) if pos >= limit
+          byte = buf.getbyte(pos)
+          pos += 1
+          result |= (byte & 0x7F) << shift
+          if byte < 0x80
+            @pos = pos
+            # masking with a Bignum allocates, and only a tenth byte can overflow 64 bits
+            return (shift == 63) ? result & MASK64 : result
+          end
+          shift += 7
+        end
+        raise DecodeError.new("varint longer than 10 bytes", offset: start)
+      end
+    end
+  end
+end

data/lib/protostar/wire/writer.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Wire
+    # Writes wire-format values into a binary String, or through a small
+    # buffer into a sink: an IO, or anything that takes bytes.
+    #
+    #   w = Protostar::Wire::Writer.new
+    #   w.write_tag(1, Protostar::Wire::VARINT).write_varint(150)
+    #   w.string # => "\x08\x96\x01"
+    #
+    #   Protostar::Wire::Writer.new(io).write_bytes("hi").flush
+    class Writer
+      # Bytes buffered before a sink is written to, by default
+      FLUSH_AT = 64 * 1024
+
+      # @return [String] the bytes written so far (for a sink, those not yet flushed)
+      attr_reader :string
+      # @return [Object, nil] the sink, or nil for a String target
+      attr_reader :io
+      # @return [Integer] bytes buffered before the sink is written to
+      attr_reader :flush_at
+
+      # @param target [String, #write, #<<, #call, nil] a String to append to
+      #   (it is switched to binary encoding), a sink, or nil for a new String.
+      #   A sink is anything answering `write` (an IO, a socket, a Rack or
+      #   ActionController::Live stream), `<<` (an Array, an Enumerator::Yielder)
+      #   or `call` (a Proc). An IO or StringIO is given the buffer itself and
+      #   anything else a copy, since a sink may keep what it is given.
+      # @param flush_at [Integer] bytes to collect before writing to the sink;
+      #   0 writes on every {#flush_if_full}
+      def initialize(target = nil, flush_at: FLUSH_AT)
+        @flush_at = flush_at
+        if target.nil?
+          @string = String.new(encoding: BINARY)
+          @io = nil
+        elsif target.is_a?(String)
+          @string = target.force_encoding(BINARY)
+          @io = nil
+        else
+          @string = String.new(capacity: (flush_at > 0) ? flush_at : 256, encoding: BINARY)
+          @io = target
+          @push = Writer.push_method(target)
+          @copy = !(target.is_a?(IO) || (defined?(::StringIO) && target.is_a?(::StringIO)))
+        end
+      end
+
+      # @return [Symbol] how bytes are handed to `sink`: :write, :<< or :call
+      # @raise [ArgumentError] when it takes none of them
+      def self.push_method(sink)
+        # Proc#<< composes, so a callable is called before anything else is tried
+        if sink.is_a?(Proc) || sink.is_a?(Method) then :call
+        elsif sink.respond_to?(:write) then :write
+        elsif sink.respond_to?(:<<) then :<<
+        elsif sink.respond_to?(:call) then :call
+        else
+          raise ArgumentError, "#{sink.class} is not a sink: it answers none of write, << and call"
+        end
+      end
+
+      # @param value [Integer] negative values are written as ten-byte two's complement
+      # @return [self]
+      def write_varint(value)
+        buf = @string
+        if value < 0x80 && value >= 0
+          buf << value
+          return self
+        end
+        value &= MASK64 if value < 0
+        while value >= 0x80
+          buf << ((value & 0x7F) | 0x80)
+          value >>= 7
+        end
+        buf << value
+        self
+      end
+
+      # @return [self]
+      def write_tag(number, wire_type)
+        write_varint((number << 3) | wire_type)
+      end
+
+      # @param value [Integer] a signed integer, written zigzag-encoded (sint32, sint64)
+      # @return [self]
+      def write_zigzag(value)
+        write_varint((value << 1) ^ (value >> 63))
+      end
+
+      # @return [self]
+      def write_fixed32(value)
+        [value].pack("V", buffer: @string)
+        self
+      end
+
+      # @return [self]
+      def write_fixed64(value)
+        [value].pack("Q<", buffer: @string)
+        self
+      end
+
+      # @return [self]
+      def write_sfixed32(value)
+        [value].pack("l<", buffer: @string)
+        self
+      end
+
+      # @return [self]
+      def write_sfixed64(value)
+        [value].pack("q<", buffer: @string)
+        self
+      end
+
+      # @return [self]
+      def write_float(value)
+        if value.is_a?(Float) && value.nan?
+          @string << Wire.float_nan(value)
+        else
+          [value].pack("e", buffer: @string)
+        end
+        self
+      end
+
+      # @return [self]
+      def write_double(value)
+        [value].pack("E", buffer: @string)
+        self
+      end
+
+      # Writes a varint length followed by the bytes of `value`, whatever its encoding
+      # @return [self]
+      def write_bytes(value)
+        write_varint(value.bytesize)
+        write_raw(value)
+      end
+
+      if String.method_defined?(:append_as_bytes)
+        # Appends the bytes of `value` as they are, whatever its encoding
+        # @return [self]
+        def write_raw(value)
+          @string.append_as_bytes(value)
+          flush_if_full
+        end
+      else
+        # Appends the bytes of `value` as they are, whatever its encoding
+        # @return [self]
+        def write_raw(value)
+          # `<<` would raise or re-tag the buffer for a non-ASCII UTF-8 value
+          [value].pack("a*", buffer: @string)
+          flush_if_full
+        end
+      end
+
+      # Writes the buffer to the sink once it holds {#flush_at} bytes
+      # @return [self]
+      def flush_if_full
+        flush if @io && @string.bytesize >= @flush_at
+        self
+      end
+
+      # Writes whatever is buffered to the sink. A no-op for a String target.
+      # @return [self]
+      def flush
+        if @io && !@string.empty?
+          deliver(@copy ? @string.dup : @string)
+          @string.clear
+        end
+        self
+      end
+
+      # Writes the buffer and then `bytes` to the sink, without copying
+      # `bytes` into the buffer first. For a String target, appends them.
+      # @return [self]
+      def write_through(bytes)
+        return write_raw(bytes) unless @io
+        if @copy
+          flush
+          deliver(bytes.b)
+        else
+          # IO#write and StringIO#write take several Strings in one call
+          deliver_all(@string, bytes)
+          @string.clear
+        end
+        self
+      end
+
+      private
+
+      def deliver_all(*chunks)
+        @io.write(*chunks)
+      end
+
+      def deliver(bytes)
+        case @push
+        when :write then @io.write(bytes)
+        when :<< then @io << bytes
+        else @io.call(bytes)
+        end
+      end
+    end
+  end
+end