mfp 0.1.0

data/lib/mfp/ping_handler.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Mfp
+  class PingHandler
+    def initialize(idle_timeout:, ping_timeout:)
+      @timer_notify = Async::Queue.new
+      @notifications = Async::Queue.new
+
+      @idle_timer = ResettableTimer.new(idle_timeout, @timer_notify, tag: :idle)
+      @response_timer = ResettableTimer.new(ping_timeout, @timer_notify, tag: :response)
+
+      @waiting_response = false
+      @waiting_cookie = nil
+    end
+
+    def recv = @notifications.dequeue
+
+    def start(task)
+      task.async { @idle_timer.start(task) }
+      task.async { @response_timer.start(task) }
+      task.async do
+        loop do
+          ev, tag = @timer_notify.dequeue
+          if ev.nil? && tag.nil?
+            break
+          elsif tag == :response && ev == :timeout
+            @notifications.enqueue({ kind: :timeout })
+            stop
+            break
+          elsif tag == :idle && ev == :timeout
+            next if @waiting_response
+
+            @waiting_response = true
+            @waiting_cookie = SecureRandom.bytes(8).unpack1("Q>")
+            @notifications.enqueue({
+              kind: :request,
+              cookie: @waiting_cookie,
+            })
+            @response_timer.reset
+          else
+            raise "Unexpected ev/tag pair: #{ev}, #{tag}"
+          end
+        end
+      end
+    end
+
+    def notify_received
+      return if @waiting_response
+
+      @idle_timer.reset
+      @response_timer.reset
+    end
+
+    def notify_pong(cookie)
+      return if !@waiting_response || cookie != @waiting_cookie
+
+      @waiting_response = false
+      @waiting_cookie = nil
+      @idle_timer.reset
+      @response_timer.reset
+    end
+
+    def stop
+      @idle_timer.stop
+      @response_timer.stop
+      @timer_notify.close
+      @notifications.close
+    end
+  end
+end

data/lib/mfp/proto/error.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Mfp
+  module Proto
+    # Error is the payload of a MessageKindError frame. It signals a problem on
+    # either a stream or the connection. The enclosing frame's StreamID
+    # disambiguate the scope: zero for connection-level errors, non-zero for
+    # stream-level errors.
+    class Error
+      attr_accessor :code, :terminal, :debug
+
+      def initialize(code, terminal: false, debug: nil)
+        @code = code
+        @terminal = terminal
+        @debug = debug
+      end
+
+      def encode(stream_id)
+        buf = Writer.new
+        buf.write_u8(@code)
+        if (size = @debug&.bytesize || 0).positive?
+          buf.write_u32(size)
+          buf.write(@debug)
+        else
+          buf.write_u32(0)
+        end
+
+        Frame.new(
+          call_sign: nil,
+          stream_id:,
+          kind: MessageKind::ERROR,
+          flags: @terminal ? 1 : 0,
+          length: buf.length,
+          payload: buf.string,
+        )
+      end
+
+      def self.read(fr)
+        raise ParserError.new(ErrorKind::FRAME_SIZE_ERROR) if fr.length < 5
+
+        reader = Reader.from_bytes(fr.payload)
+        terminal = fr.flags.allbits?(0x01)
+        code = reader.read_byte
+        debug_len = reader.read_u32
+        debug = nil
+        debug = reader.read_n(debug_len) if debug_len.positive?
+
+        new(code, terminal:, debug:)
+      end
+    end
+  end
+end

data/lib/mfp/proto/frame.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Mfp
+  module Proto
+    # Frame is the fundamental unit of the MFP wire protocol. Every message
+    # exchanged between endpoints is wrapped in a Frame.
+    class Frame
+      attr_accessor :call_sign, :stream_id, :kind, :flags, :length, :payload
+
+      def initialize(stream_id:, kind:, flags:, length:, payload:, call_sign: "")
+        @call_sign = call_sign
+        @stream_id = stream_id
+        @kind = kind
+        @flags = flags
+        @length = length
+        @payload = payload
+      end
+
+      def encode
+        w = Writer.new
+        w.write(@call_sign)
+        w.write_u32(@stream_id || 0)
+        w.write_u8(@kind)
+        w.write_u8(@flags || 0)
+        w.write_u32(@length || 0)
+        w.write(@payload || "")
+        w.string
+      end
+
+      def self.read(io, max_len, call_sign)
+        r = Reader.new(io)
+        cs = r.read_n(4)
+        if cs.nil?
+          # This is a clean disconnect before reading the callsign.
+          # Raise ConnectionClosedError instead of an spurious
+          # InvalidCallSignError
+          raise ConnectionClosedError
+        end
+        raise InvalidCallSignError, cs.inspect if cs != call_sign
+
+        stream_id = r.read_u32
+        kind = r.read_byte
+        kind = MessageKind::UNKNOWN if kind > MessageKind.max
+        flags = r.read_byte
+        length = r.read_u32
+        raise PayloadTooLargeError if max_len.positive? && length > max_len
+
+        payload = length.positive? ? r.read_n(length) : ""
+        new(call_sign:, stream_id:, kind:, flags:, length:, payload:)
+      end
+    end
+  end
+end

data/lib/mfp/proto/hello.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Mfp
+  module Proto
+    # Hello is the payload of a MessageKindHello frame. It must be the first
+    # frame sent by the client on every connection. The server responds with
+    # either a HelloResponse or an Error.
+    class Hello
+      attr_accessor :version_major, :version_minor, :capabilities, :application, :host
+
+      def initialize(version_major:, version_minor:, capabilities: 0, application: "", host: "")
+        @version_major = version_major
+        @version_minor = version_minor
+        @capabilities = capabilities
+        @application = application
+        @host = host
+      end
+
+      def encode(stream_id)
+        buf = Writer.new
+        buf.write_u8(@version_major)
+        buf.write_u8(@version_minor)
+        buf.write_u16(@capabilities)
+        buf.write_u16_string(@application)
+        buf.write_u16_string(@host)
+
+        Frame.new(
+          stream_id:,
+          kind: MessageKind::HELLO,
+          flags: 0,
+          length: buf.length,
+          payload: buf.string,
+        )
+      end
+
+      def self.read(fr)
+        raise ParserError.new(ErrorKind::FRAME_SIZE_ERROR) if fr.length < 8
+
+        r = Reader.new(StringIO.new(fr.payload))
+        version_major = r.read_byte
+        version_minor = r.read_byte
+        capabilities = r.read_u16
+        application = r.read_u16_string
+        host = r.read_u16_string
+        new(version_major:, version_minor:, capabilities:, application:, host:)
+      end
+    end
+  end
+end

data/lib/mfp/proto/hello_response.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Mfp
+  module Proto
+    # HelloResponse is the payload of a MessageKindHelloResponse frame, sent by
+    # the server upon successfully accepting a Hello. It confirms the negotiated
+    # capabilities and advertises connection limits.
+    class HelloResponse
+      attr_accessor :capabilities, :max_streams, :max_payload
+
+      def initialize(capabilities:, max_streams:, max_payload:)
+        @capabilities = capabilities
+        @max_streams = max_streams
+        @max_payload = max_payload
+      end
+
+      def encode(stream_id)
+        buf = Writer.new
+        buf.write_u16(@capabilities)
+        buf.write_u32(@max_streams)
+        buf.write_u32(@max_payload)
+        Frame.new(
+          stream_id:,
+          kind: MessageKind::HELLO_RESPONSE,
+          flags: 0,
+          length: buf.length,
+          payload: buf.string,
+        )
+      end
+
+      def self.read(fr)
+        raise ParserError.new(ErrorKind::FRAME_SIZE_ERROR) if fr.length != 10
+
+        r = Reader.new(StringIO.new(fr.payload))
+        capabilities = r.read_u16
+        max_streams = r.read_u32
+        max_payload = r.read_u32
+
+        new(capabilities:, max_streams:, max_payload:)
+      end
+    end
+  end
+end

data/lib/mfp/proto/ping.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Mfp
+  module Proto
+    class Ping
+      attr_accessor :ack, :payload
+
+      def initialize(ack:, payload:)
+        @ack = ack
+        @payload = payload
+      end
+
+      def encode(*)
+        buf = Writer.new
+        buf.write_u64(@payload)
+        Frame.new(
+          stream_id: 0,
+          kind: MessageKind::PING,
+          flags: @ack ? 0x01 : 0x00,
+          length: 8,
+          payload: buf.string,
+        )
+      end
+
+      def self.read(fr)
+        new(
+          ack: fr.flags.allbits?(0x01),
+          payload: fr.payload.unpack1("Q>"),
+        )
+      end
+    end
+  end
+end

data/lib/mfp/proto/protocol.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Mfp
+  module Proto
+    # Message Kind -------------------------------------------------------------
+
+    class MessageKind < Enum
+      # UNKNOWN is the zero value and represents an unrecognised or
+      # uninitialised frame kind. Frames with this kind MUST be rejected as a
+      # protocol violation.
+      define :UNKNOWN, 0
+
+      # HELLO is sent by the client as the first frame of every
+      # connection. No other frame may be sent before the handshake is complete
+      define :HELLO, 1
+
+      # HELLO_RESPONSE is sent by the server in response to a Hello
+      # frame, confirming negotiated capabilities and connection limits
+      define :HELLO_RESPONSE, 2
+
+      # PING may be sent by either endpoint to verify that the
+      # connection is still alive. The receiving endpoint must echo the payload
+      # with the ACK flag set.
+      define :PING, 3
+
+      # ERROR signals a problem on a stream or the connection itself.
+      # The frame's StreamID disambiguates scope: zero for connection-level
+      # errors, non-zero for stream-level errors.
+      define :ERROR, 4
+
+      # STREAM carries an opaque payload for a given stream. The
+      # frame's StreamID must be non-zero. Payload semantics are defined by
+      # the upper-layer protocol.
+      define :STREAM, 5
+
+      # CONTROL carries an opaque, out-of-band signal scoped to
+      # either a stream (non-zero StreamID) or the connection (zero StreamID).
+      # Control frames are exempt from compression. Payload semantics are
+      # defined by the upper-layer protocol.
+      define :CONTROL, 6
+    end
+
+    # Capabilities -------------------------------------------------------------
+
+    class Capability < Enum
+      # COMPRESSION_GZIP indicates support for gzip payload
+      # compression on STREAM frames.
+      define :COMPRESSION_GZIP, 1 << 0
+      # COMPRESSION_BROTLI indicates support for Brotli payload
+      # compression on STREAM frames.
+      define :COMPRESSION_BROTLI, 1 << 1
+    end
+
+    # Error Kinds --------------------------------------------------------------
+
+    class ErrorKind < Enum
+      # PROTOCOL_ERROR signals that an invalid frame was received at this point
+      # in the stream's or connection's lifetime. Applicable to both streams
+      # and connections.
+      define :PROTOCOL_ERROR, 0x01
+
+      # INTERNAL_ERROR signals that an unexpected internal error occurred.
+      # Applicable to both streams and connections.
+      define :INTERNAL_ERROR, 0x02
+
+      # STREAM_CLOSED_ERROR signals that the targeted stream has been terminated
+      # or was never established. Applicable to streams only.
+      define :STREAM_CLOSED_ERROR, 0x03
+
+      # REFUSED_STREAM_ERROR signals that the server refused to open the stream.
+      # Applicable to streams only.
+      define :REFUSED_STREAM_ERROR, 0x04
+
+      # FRAME_SIZE_ERROR signals that a frame exceeded the negotiated Max. Payload
+      # or had an otherwise invalid size (e.g. a PING whose Length ≠ 8).
+      # Applicable to both streams and connections.
+      define :FRAME_SIZE_ERROR, 0x05
+
+      # COMPRESSION_ERROR signals that a payload could not be decompressed.
+      # Applicable to connections only.
+      define :COMPRESSION_ERROR, 0x06
+
+      # ENHANCE_YOUR_CALM_ERROR signals that the peer is generating excessive load.
+      # Applicable to connections only.
+      define :ENHANCE_YOUR_CALM_ERROR, 0x07
+
+      # INADEQUATE_SECURITY_ERROR signals that the underlying transport does not
+      # meet minimum security requirements. Applicable to connections only.
+      define :INADEQUATE_SECURITY_ERROR, 0x08
+
+      # INSUFFICIENT_CAPACITY_ERROR signals that the server lacks capacity to
+      # handle the request. Applicable to connections only.
+      define :INSUFFICIENT_CAPACITY_ERROR, 0x09
+    end
+  end
+end

data/lib/mfp/proto/reader.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mfp
+  module Proto
+    class Reader
+      def self.from_bytes(value) = new(StringIO.new(value))
+
+      def initialize(io)
+        @io = io
+      end
+
+      def read_n(n) = @io.read(n)
+      def read_u16 = @io.read(2).unpack1("S>")
+      def read_u32 = @io.read(4).unpack1("L>")
+      def read_u64 = @io.read(8).unpack1("Q>")
+      def read_byte = @io.read(1).unpack1("C")
+
+      def read_u16_string
+        size = read_u16
+        return "" if size.zero?
+
+        read_n(size).encode("utf-8")
+      end
+    end
+  end
+end

data/lib/mfp/proto/writer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Mfp
+  module Proto
+    class Writer
+      def initialize
+        @buf = StringIO.new
+      end
+
+      def write(value) = @buf.write(value)
+      def write_u8(value) = write([value].pack("C"))
+      def write_u16(value) = write([value].pack("S>"))
+      def write_u32(value) = write([value].pack("L>"))
+      def write_u64(value) = write([value].pack("Q>"))
+
+      def write_u16_string(value)
+        l = value&.bytesize || 0
+        write_u16(l)
+        return if l.zero?
+
+        write(value.encode("utf-8"))
+      end
+
+      def string = @buf.string
+      def length = @buf.length
+    end
+  end
+end

data/lib/mfp/proto.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "proto/protocol"
+require_relative "proto/writer"
+require_relative "proto/reader"
+require_relative "proto/frame"
+require_relative "proto/error"
+require_relative "proto/hello"
+require_relative "proto/hello_response"
+require_relative "proto/ping"

data/lib/mfp/resettable_timer.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Mfp
+  class ResettableTimer
+    def initialize(timeout, notify_queue, tag: nil)
+      @timeout = timeout
+      @reset_condition = Async::Condition.new
+      @running = true
+      @notify_queue = notify_queue
+      @tag = tag
+      @itask = nil
+    end
+
+    def start(task)
+      @itask = task.async do |task|
+        while @running
+          result = Async::Queue.new
+
+          sleeper = task.async do |s|
+            s.sleep(@timeout)
+            result.enqueue(:timeout)
+          end
+
+          waiter = task.async do
+            @reset_condition.wait
+            result.enqueue(:reset)
+          end
+
+          msg = result.dequeue
+          sleeper.stop unless sleeper.stopped?
+          waiter.stop unless waiter.stopped?
+          next if msg == :reset
+
+          @notify_queue.enqueue [msg, @tag]
+        end
+      end
+    end
+
+    def reset = @reset_condition.signal
+
+    def stop
+      @itask&.stop
+      @running = false
+      @reset_condition.signal
+    end
+  end
+end