arf 0.1.0

data/lib/arf/wire/error_code.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Arf
+  module Wire
+    ERROR_CODE_NO_ERROR             = 0x00
+    ERROR_CODE_PROTOCOL_ERROR       = 0x01
+    ERROR_CODE_INTERNAL_ERROR       = 0x02
+    ERROR_CODE_STREAM_CLOSED        = 0x03
+    ERROR_CODE_FRAME_SIZE_ERROR     = 0x04
+    ERROR_CODE_REFUSED_STREAM       = 0x05
+    ERROR_CODE_CANCEL               = 0x06
+    ERROR_CODE_COMPRESSION_ERROR    = 0x07
+    ERROR_CODE_ENHANCE_YOUR_CALM    = 0x08
+    ERROR_CODE_INADEQUATE_SECURITY  = 0x09
+
+    ERROR_TO_STRING = {
+      ERROR_CODE_NO_ERROR => "No error",
+      ERROR_CODE_PROTOCOL_ERROR => "Protocol Error",
+      ERROR_CODE_INTERNAL_ERROR => "Internal Error",
+      ERROR_CODE_STREAM_CLOSED => "Stream Closed",
+      ERROR_CODE_FRAME_SIZE_ERROR => "Frame Size Error",
+      ERROR_CODE_REFUSED_STREAM => "Refused Stream",
+      ERROR_CODE_CANCEL => "Cancel",
+      ERROR_CODE_COMPRESSION_ERROR => "Compression Error",
+      ERROR_CODE_ENHANCE_YOUR_CALM => "Enhance Your Calm",
+      ERROR_CODE_INADEQUATE_SECURITY => "Inadequate Security"
+    }.freeze
+
+    def self.error_code_to_string(code)
+      return ERROR_TO_STRING[code] if ERROR_TO_STRING.key? code
+
+      "Unknown error 0x#{code.to_s(16)}"
+    end
+  end
+end

data/lib/arf/wire/errors.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Arf
+  module Wire
+    class WireError < Arf::Error; end
+
+    class FrameMismatchError < WireError
+      attr_reader :expected, :received
+
+      def initialize(expected, received)
+        @expected = expected
+        @received = received
+        super("Frame type mismatch: Expected #{expected}, got #{received}")
+      end
+    end
+
+    class UnexpectedUnassociatedFrameError < WireError
+      attr_reader :kind
+
+      def initialize(kind)
+        @kind = kind
+        super("Frame #{kind} must be associated to a stream")
+      end
+    end
+
+    class UnexpectedAssociatedFrameError < WireError
+      attr_reader :kind
+
+      def initialize(kind)
+        @kind = kind
+        super("Frame #{kind} must not be associated to a stream")
+      end
+    end
+
+    class InvalidFrameLengthError < WireError; end
+
+    class InvalidFrameError < WireError; end
+
+    class StreamResetError < WireError
+      attr_reader :reason
+
+      def initialize(reason)
+        @reason = reason
+        super("Stream reset: #{Wire.error_code_to_string(reason)}")
+      end
+    end
+
+    class StreamCanceledError < WireError
+      attr_reader :reason
+
+      def initialize(reason)
+        @reason = reason
+        super("Stream canceled: #{Wire.error_code_to_string(reason)}")
+      end
+    end
+
+    class ConnectionResetError < WireError
+      attr_reader :reason, :details
+
+      def initialize(reason, details = nil)
+        @reason = reason
+        @details = details
+        super(if details
+                "Connection reset: #{Wire.error_code_to_string(reason)} #{details}"
+              else
+                "Connection reset: #{Wire.error_code_to_string(reason)}"
+              end)
+      end
+    end
+
+    class UnknownFrameKindError < WireError
+      attr_reader :received_kind
+
+      def initialize(kind)
+        @received_kind = kind
+        if kind.is_a? Symbol
+          super("Unknown frame kind 0x#{received_kind}")
+        else
+          super("Unknown frame kind 0x#{received_kind.to_s(16)}")
+        end
+      end
+    end
+
+    class MagicNumberMismatchError < WireError; end
+
+    class ClosedStreamError < WireError; end
+  end
+end

data/lib/arf/wire/frame.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Arf
+  module Wire
+    class Frame
+      MAGIC = "arf"
+      MAGIC_SIZE = 3
+      STREAM_ID_SIZE = 4
+      FRAME_KIND_SIZE = 1
+      FLAGS_SIZE = 1
+      LENGTH_SIZE = 2
+      FRAME_SIZE = MAGIC_SIZE + STREAM_ID_SIZE + FRAME_KIND_SIZE + FLAGS_SIZE + LENGTH_SIZE
+
+      attr_accessor :stream_id, :frame_kind, :flags, :length
+      attr_reader :payload
+
+      def empty? = length ? length.zero? : true
+
+      def self.read_exactly(io, into, n)
+        into.truncate(0)
+        into.write(io.read(n - into.length)) until into.length == n
+        into.rewind
+        into
+      end
+
+      def self.from_io(io)
+        buf = StringIO.new
+        read_exactly(io, buf, FRAME_SIZE)
+        raise MagicNumberMismatchError if buf.read(3) != Frame::MAGIC
+
+        stream_id = Wire.decode_uint32(buf)
+        raw_kind = buf.readbyte
+        frame_kind = Wire::FRAME_TO_SYMBOL[raw_kind]
+        raise UnknownFrameKindError, raw_kind unless frame_kind
+
+        flags = buf.readbyte
+        length = Wire.decode_uint16(buf)
+        payload = nil
+        if length.positive?
+          payload = StringIO.new
+          read_exactly(io, payload, length)
+        end
+
+        new.tap do |f|
+          f.stream_id = stream_id
+          f.frame_kind = frame_kind
+          f.flags = flags
+          f.payload = payload
+          f.length = length
+        end
+      end
+
+      def bytes(compressor)
+        @payload = IO::COMPRESSOR[compressor].compress(@payload)
+        @length = @payload&.length || 0
+
+        IO::Buffer.new
+          .write_raw(MAGIC)
+          .write_raw(Wire.encode_uint32(@stream_id || 0))
+          .write_raw([SYMBOL_TO_FRAME[@frame_kind]].pack("C*"))
+          .write_raw(@flags || 0)
+          .write_raw(Wire.encode_uint16(@length))
+          .write_raw(@payload&.string || "")
+          .string
+      end
+
+      def validate_kind(expected, associated)
+        raise FrameMismatchError.new(expected, @frame_kind) if @frame_kind != expected
+
+        if associated && (@stream_id.nil? || @stream_id.zero?)
+          raise UnexpectedUnassociatedFrameError, @frame_kind
+        elsif !associated && (!@stream_id.nil? && @stream_id != 0)
+          raise UnexpectedAssociatedFrameError, @frame_kind
+        end
+      end
+
+      def validate_size(size)
+        return unless @length != size
+
+        raise InvalidFrameLengthError, "invalid length for frame #{@frame_kind} " \
+                                       "#{size} bytes are required, received #{@length}"
+      end
+
+      def decompress(compressor)
+        @payload = IO::COMPRESSOR[compressor].decompress(@payload)
+        @length = @payload&.length || 0
+      end
+
+      def payload=(value)
+        if value.nil?
+          @payload = nil
+          return
+        end
+
+        @payload = if value.is_a? StringIO
+                     value
+                   else
+                     StringIO.new(value)
+                   end
+      end
+
+      def specialize(compressor)
+        cls = BaseFrame.frame_by_kind(@frame_kind)
+        raise UnknownFrameKindError, @frame_kind if cls.nil?
+
+        decompress(compressor)
+        cls.new(self)
+      end
+    end
+  end
+end

data/lib/arf/wire/frame_kind.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Arf
+  module Wire
+    FRAME_KIND_CONFIGURATION  = 0x0
+    FRAME_KIND_PING           = 0x1
+    FRAME_KIND_GO_AWAY        = 0x2
+    FRAME_KIND_MAKE_STREAM    = 0x3
+    FRAME_KIND_RESET_STREAM   = 0x4
+    FRAME_KIND_DATA           = 0x5
+
+    FRAME_TO_SYMBOL = {
+      FRAME_KIND_CONFIGURATION => :configuration,
+      FRAME_KIND_PING => :ping,
+      FRAME_KIND_GO_AWAY => :go_away,
+      FRAME_KIND_MAKE_STREAM => :make_stream,
+      FRAME_KIND_RESET_STREAM => :reset_stream,
+      FRAME_KIND_DATA => :data
+    }.freeze
+
+    SYMBOL_TO_FRAME = FRAME_TO_SYMBOL.to_a.to_h(&:reverse)
+  end
+end

data/lib/arf/wire/frame_reader.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Arf
+  module Wire
+    class FrameReader
+      STATES = %i[
+        magic
+        stream_id
+        kind
+        flags
+        length
+        payload
+      ].freeze
+
+      def initialize
+        @data = IO::Buffer.new
+        @fr = Frame.new
+        @state = :magic
+        @c = 0
+        @data.reset
+      end
+
+      def feed_all(data)
+        c = 0
+        data.each_byte do |b|
+          v = feed b
+          c += 1
+          if v && c < data.length
+            raise "Short read: Read #{c} bytes of #{data.length}"
+          elsif v
+            return v
+          end
+        end
+        nil
+      end
+
+      def feed(b)
+        case @state
+        when :magic
+          @data.write(b)
+          return nil if @data.length < 3
+
+          if @data.string != Frame::MAGIC
+            @data.reset
+            raise MagicNumberMismatchError
+          end
+          @data.reset
+          @state = :stream_id
+
+        when :stream_id
+          @data.write(b)
+          return nil if @data.length < 4
+
+          @data.rewind
+          @fr.stream_id = Wire.decode_uint32(@data)
+          @data.reset
+          @state = :kind
+
+        when :kind
+          raw_frame_kind = b
+          frame_kind = Wire::FRAME_TO_SYMBOL[raw_frame_kind]
+          raise UnknownFrameKindError, raw_frame_kind unless frame_kind
+
+          @fr.frame_kind = frame_kind
+          @state = :flags
+
+        when :flags
+          @fr.flags = b
+          @state = :length
+
+        when :length
+          @data.write(b)
+          return nil if @data.length < 2
+
+          @data.rewind
+          @fr.length = Wire.decode_uint16(@data)
+          @data.reset
+          @state = :payload
+          if @fr.empty?
+            @state = :magic
+            frame = @fr
+            @fr = Frame.new
+            return frame
+          end
+
+        when :payload
+          @data.write(b)
+          return nil if @data.length < @fr.length
+
+          @fr.payload = @data.extract
+          @fr.payload.rewind
+          @data = IO::Buffer.new
+          @state = :magic
+          @data.reset
+          frame = @fr
+          @fr = Frame.new
+          return frame
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/arf/wire/frames/base_frame.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Arf
+  module Wire
+    class BaseFrame
+      def self.register_frame(kind, cls)
+        @frames ||= {}
+        @frames[kind] = cls
+      end
+
+      def self.frame_by_kind(kind) = @frames[kind]
+
+      def self.frame_kind(name = nil)
+        BaseFrame.register_frame(name, self) if name
+        @frame_kind ||= name
+      end
+
+      def self.value_size(size = nil)
+        @value_size ||= size
+      end
+
+      def self.wants_stream_id!
+        attr_accessor :stream_id
+
+        @wants_stream_id = true
+      end
+
+      def self.wants_stream_id?
+        @wants_stream_id || false
+      end
+
+      def self.define_flag(name, offset)
+        @flags ||= {}
+        @flags[name] = offset
+        define_method("#{name}!") do
+          instance_variable_set("@#{name}", true)
+        end
+
+        define_method("#{name}?") do
+          instance_variable_get("@#{name}") || false
+        end
+      end
+
+      def self.flags
+        @flags || {}
+      end
+
+      def initialize(frame = nil)
+        if frame
+          frame.validate_kind(frame_kind, wants_stream_id?)
+          frame.validate_size(value_size) unless value_size.nil?
+          @stream_id = frame.stream_id if wants_stream_id?
+          decode_flags(frame)
+          from_frame(frame)
+        end
+        yield self if block_given?
+      end
+
+      def frame_kind = self.class.frame_kind
+      def wants_stream_id? = self.class.wants_stream_id?
+      def value_size = self.class.value_size
+      def from_frame(_frame) = nil
+      def encode_payload = nil
+      def flags = self.class.flags
+
+      # :nocov:
+
+      def inspect_flags
+        flags.keys.to_h do |k|
+          [k, instance_variable_get("@#{k}")]
+        end
+      end
+
+      # :nocov:
+
+      def encode_uint16(*) = Wire.encode_uint16(*)
+      def encode_uint32(*) = Wire.encode_uint32(*)
+      def decode_uint16(*) = Wire.decode_uint16(*)
+      def decode_uint32(*) = Wire.decode_uint32(*)
+
+      def encode_flags
+        value = 0x00
+        flags.each_pair do |name, offset|
+          value |= (0x01 << offset) if send("#{name}?")
+        end
+        value
+      end
+
+      def decode_flags(frame)
+        flags.each_pair do |name, offset|
+          send("#{name}!") if frame.flags.anybits?((0x01 << offset))
+        end
+      end
+
+      def to_frame
+        Frame.new.tap do |f|
+          f.stream_id = stream_id if wants_stream_id?
+          f.frame_kind = frame_kind
+          f.flags = encode_flags
+          payload = encode_payload
+          payload = StringIO.new(payload) if payload && !payload.is_a?(StringIO)
+          f.length = (payload || "").length
+          f.payload = payload
+        end
+      end
+    end
+  end
+end

data/lib/arf/wire/frames/configuration_frame.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Arf
+  module Wire
+    class ConfigurationFrame < BaseFrame
+      frame_kind :configuration
+      define_flag :compression_gzip, 0
+      define_flag :compression_brotli, 1
+      define_flag :ack, 2
+      attr_accessor :max_concurrent_streams
+
+      def from_frame(frame)
+        if !frame.empty? && frame.length != 4
+          raise InvalidFrameLengthError, "invalid length for frame CONFIGURATION " \
+                                         "expected 0 or 4 bytes, got #{frame.length}"
+        end
+
+        @max_concurrent_streams = decode_uint32(frame.payload) unless frame.empty?
+
+        return unless @max_concurrent_streams && @max_concurrent_streams != 0 && !ack?
+
+        raise InvalidFrameError, "received non-ack CONFIGURATION with " \
+                                 "non-zero max_concurrent_streams"
+      end
+
+      def encode_payload
+        return unless @max_concurrent_streams
+
+        encode_uint32(@max_concurrent_streams)
+      end
+    end
+  end
+end

data/lib/arf/wire/frames/data_frame.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Arf
+  module Wire
+    class DataFrame < BaseFrame
+      frame_kind :data
+      wants_stream_id!
+
+      define_flag :end_stream, 0
+      define_flag :end_data, 1
+
+      attr_accessor :payload
+
+      def from_frame(fr)
+        @payload = fr.payload
+      end
+
+      def encode_payload = @payload
+    end
+  end
+end

data/lib/arf/wire/frames/go_away_frame.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Arf
+  module Wire
+    class GoAwayFrame < BaseFrame
+      frame_kind :go_away
+
+      attr_accessor :last_stream_id, :error_code, :additional_data
+
+      def from_frame(fr)
+        if fr.length < 8
+          raise InvalidFrameLengthError, "Invalid length for frame GOAWAY: at" \
+                                         "least 8 bytes are required"
+        end
+        @last_stream_id = decode_uint32(fr.payload)
+        @error_code = decode_uint32(fr.payload)
+        @additional_data = fr.payload.read
+      end
+
+      def encode_payload
+        buf = IO::Buffer.new
+          .write_raw(encode_uint32(last_stream_id))
+          .write_raw(encode_uint32(error_code))
+        buf.write_raw(additional_data) if additional_data
+        buf.string
+      end
+    end
+  end
+end

data/lib/arf/wire/frames/make_stream_frame.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Arf
+  module Wire
+    class MakeStreamFrame < BaseFrame
+      frame_kind :make_stream
+      value_size 0
+      wants_stream_id!
+
+      def from_frame(fr)
+        @stream_id = fr.stream_id
+      end
+    end
+  end
+end

data/lib/arf/wire/frames/ping_frame.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Arf
+  module Wire
+    class PingFrame < BaseFrame
+      frame_kind :ping
+      value_size 8
+      define_flag :ack, 2
+      attr_accessor :payload
+
+      def from_frame(fr)
+        @payload = fr.payload
+      end
+
+      def encode_payload = @payload
+    end
+  end
+end

data/lib/arf/wire/frames/reset_stream_frame.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Arf
+  module Wire
+    class ResetStreamFrame < BaseFrame
+      frame_kind :reset_stream
+      value_size 4
+      wants_stream_id!
+      attr_accessor :error_code
+
+      def from_frame(fr)
+        @stream_id = fr.stream_id
+        @error_code = decode_uint32(fr.payload)
+      end
+
+      def encode_payload = encode_uint32(error_code)
+    end
+  end
+end

data/lib/arf/wire/frames.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "frames/base_frame"
+require_relative "frames/configuration_frame"
+require_relative "frames/ping_frame"
+require_relative "frames/go_away_frame"
+require_relative "frames/make_stream_frame"
+require_relative "frames/reset_stream_frame"
+require_relative "frames/data_frame"