grpc-dc 0.37.1

data/lib/grpcdc/endpoint.rb

@@ -0,0 +1,397 @@
+# @generated by grpc-dc codegen. DO NOT EDIT.
+# SPDX-License-Identifier: Apache-2.0
+# Endpoint: multiplexes grpc-dc streams over one Transport.
+
+require_relative "codec"
+require_relative "wire_gen"
+
+module Grpcdc
+  EVENT_HEADERS = "headers"
+  EVENT_DATA = "data"
+  EVENT_HALF_CLOSE = "half-close"
+  EVENT_TRAILERS = "trailers"
+  EVENT_RST = "rst"
+
+  # Carries whole DataChannel messages (boundaries preserved).
+  #
+  # recv returns one message, or raises EOFError when the
+  # transport is closed.
+  class Transport
+    def send(_data)
+      raise NotImplementedError
+    end
+
+    def recv
+      raise NotImplementedError
+    end
+  end
+
+  class StreamEvent
+    attr_reader :kind, :headers, :payload, :status
+
+    def initialize(kind, headers: nil, payload: nil, status: nil)
+      @kind = kind
+      @headers = headers
+      @payload = payload
+      @status = status
+    end
+  end
+
+  # Receiving queue of one stream; closed after a terminal event.
+  class StreamInput
+    CLOSED = Object.new
+
+    def initialize
+      @events = Queue.new
+    end
+
+    def put(event)
+      @events << event
+    end
+
+    def close
+      @events << CLOSED
+    end
+
+    TIMEOUT = Object.new
+
+    # Next event, or nil once the stream is closed. With a
+    # timeout (seconds), returns TIMEOUT when the wait expires.
+    def get(timeout = nil)
+      return get_blocking if timeout.nil?
+
+      # Portable timed wait: Queue#pop(timeout:) only exists on
+      # Ruby >= 3.2 (3.1 raises immediately), so poll non-blocking.
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      loop do
+        begin
+          event = @events.pop(true)
+          return event.equal?(CLOSED) ? nil : event
+        rescue ThreadError
+          return TIMEOUT if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+          sleep(0.001)
+        end
+      end
+    end
+
+    private
+
+    def get_blocking
+      event = @events.pop
+      event.equal?(CLOSED) ? nil : event
+    end
+
+    public
+  end
+
+  class ResponseSink
+    # Wired to the CallContext maps by the endpoint.
+    attr_accessor :resp_headers, :resp_trailers
+
+    def initialize(endpoint, stream_id)
+      @endpoint = endpoint
+      @id = stream_id
+      @resp_headers = {}
+      @resp_trailers = {}
+      @headers_sent = false
+    end
+
+    def send_data(payload)
+      # A stream the endpoint has forgotten was RST by the peer
+      # (or the channel went away): fail the send so a producing
+      # handler stops instead of streaming into the void.
+      if @endpoint.stream(@id).nil?
+        raise StatusError.new(CODE_CANCELLED, "call cancelled")
+      end
+
+      flush_headers
+      @endpoint.send_frame(Codec.encode_frame(FRAME_DATA, @id, payload))
+    end
+
+    def flush_headers
+      return if @headers_sent
+
+      @headers_sent = true
+      send_headers(@resp_headers)
+    end
+
+    def send_headers(metadata = nil)
+      if @endpoint.stream(@id).nil?
+        raise StatusError.new(CODE_CANCELLED, "call cancelled")
+      end
+
+      @headers_sent = true
+      @endpoint.send_frame(Codec.headers_frame(@id, nil, metadata || @resp_headers))
+    end
+
+    def send_trailers(status)
+      if @resp_trailers && !@resp_trailers.empty?
+        merged = @resp_trailers.merge(status.trailers || {})
+        status = StatusError.new(status.code, status.message)
+        status.trailers = merged
+      end
+      @endpoint.send_frame(Codec.status_frame(FRAME_TRAILERS, @id, status))
+    end
+
+    # Server sink interface used by Server.
+    def send(payload)
+      send_data(payload)
+    end
+  end
+
+  # Per-call context: metadata sent in HEADERS, plus deadline.
+  class CallContext
+    attr_reader :metadata, :deadline, :response_headers, :response_trailers
+
+    # Record response initial metadata (sent lazily, before
+    # the first response message).
+    def set_headers(md)
+      @response_headers.merge!(md)
+    end
+
+    # Record response trailing metadata (rides the terminal
+    # status frame).
+    def set_trailers(md)
+      @response_trailers.merge!(md)
+    end
+
+    def initialize(metadata = nil, timeout: nil)
+      @metadata = metadata || {}
+      @response_headers = {}
+      @response_trailers = {}
+      remaining = Codec.parse_timeout(@metadata["grpc-timeout"])
+      @deadline = remaining.nil? ? nil : Process.clock_gettime(Process::CLOCK_MONOTONIC) + remaining
+    end
+
+    # Seconds left before the deadline, or nil when unbounded.
+    def time_remaining
+      return nil if @deadline.nil?
+
+      [@deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0.0].max
+    end
+
+    def deadline_exceeded?
+      time_remaining == 0.0
+    end
+  end
+
+  # Multiplexes streams over one Transport.
+  #
+  # The side that created the channel allocates odd stream ids,
+  # the answerer even.
+  class Endpoint
+    attr_reader :transport
+    attr_accessor :dispatcher
+
+    def initialize(transport, creator:)
+      @transport = transport
+      @dispatcher = nil
+      @next_id = creator ? 1 : 2
+      @send_lock = Mutex.new
+      @streams = {}
+      @streams_lock = Mutex.new
+      @closed = false
+      @started = false
+    end
+
+    # Start the read loop (idempotent). Called after any
+    # dispatcher is installed, so an early HEADERS can never race
+    # dispatcher setup.
+    def start
+      return if @started
+
+      @started = true
+      Thread.new { read_loop }
+    end
+
+    def set_dispatcher(dispatcher)
+      @dispatcher = dispatcher
+    end
+
+    def send_frame(frame)
+      @send_lock.synchronize { @transport.send(frame) }
+    end
+
+    def open_stream
+      stream_id = @send_lock.synchronize do
+        id = @next_id
+        @next_id += 2
+        id
+      end
+      stream_input = StreamInput.new
+      @streams_lock.synchronize { @streams[stream_id] = stream_input }
+      [stream_id, stream_input]
+    end
+
+    def close_stream(stream_id)
+      @streams_lock.synchronize { @streams.delete(stream_id) }
+    end
+
+    # Abort one stream: RST towards the peer; any thread blocked
+    # in recv wakes with the cancellation status (the local input
+    # is closed with a synthetic RST event).
+    def cancel_stream(stream_id)
+      status = StatusError.new(CODE_CANCELLED, "call cancelled")
+      input = @streams_lock.synchronize { @streams.delete(stream_id) }
+      unless input.nil?
+        input.put(StreamEvent.new(EVENT_RST, status: status))
+        input.close
+      end
+      begin
+        send_frame(Codec.status_frame(FRAME_RST, stream_id, status))
+      rescue StandardError
+        nil
+      end
+    end
+
+    def stream(stream_id)
+      @streams_lock.synchronize { @streams[stream_id] }
+    end
+
+    def close
+      return if @closed
+
+      @closed = true
+      begin
+        @transport.close if @transport.respond_to?(:close)
+      rescue StandardError
+        nil
+      end
+      fail_all
+    end
+
+    private
+
+    def fail_all
+      pending = @streams_lock.synchronize do
+        items = @streams.to_a
+        @streams.clear
+        items
+      end
+      pending.each do |_stream_id, stream_input|
+        stream_input.put(StreamEvent.new(
+                           EVENT_RST,
+                           status: StatusError.new(CODE_UNAVAILABLE, "data channel closed")
+                         ))
+        stream_input.close
+      end
+    end
+
+    def read_loop
+      loop do
+        begin
+          data = @transport.recv
+        rescue StandardError
+          fail_all
+          return
+        end
+        return if @closed
+
+        on_bytes(data)
+      end
+    end
+
+    def on_bytes(data)
+      begin
+        frame_type, stream_id, payload = Codec.decode_frame(data)
+      rescue StatusError
+        return # malformed frame: drop, keep the channel up
+      end
+      case frame_type
+      when 1 then on_headers(stream_id, payload)
+      when 2 then push_event(stream_id, StreamEvent.new(EVENT_DATA, payload: payload))
+      when 3 then on_terminal(stream_id, payload, EVENT_TRAILERS)
+      when 4 then push_event(stream_id, StreamEvent.new(EVENT_HALF_CLOSE))
+      when 5 then on_terminal(stream_id, payload, EVENT_RST)
+      end
+
+    end
+
+    def on_terminal(stream_id, payload, kind)
+      stream_input = stream(stream_id)
+      return unless stream_input
+
+      stream_input.put(StreamEvent.new(kind, status: Codec.parse_status(payload)))
+      stream_input.close
+      close_stream(stream_id)
+    end
+
+    def push_event(stream_id, event)
+      stream_input = stream(stream_id)
+      stream_input&.put(event)
+    end
+
+    def on_headers(stream_id, payload)
+      begin
+        headers = Codec.parse_headers(payload)
+      rescue StatusError => e
+        begin
+          send_frame(Codec.status_frame(FRAME_RST, stream_id, Grpcdc.to_status(e)))
+        rescue StandardError
+          nil
+        end
+        return
+      end
+      if headers.path.nil?
+        # Server response headers for one of our outbound streams.
+        stream_input = stream(stream_id)
+        stream_input&.put(StreamEvent.new(EVENT_HEADERS, headers: headers))
+        return
+      end
+      if stream(stream_id)
+        begin
+          send_frame(Codec.status_frame(
+                       FRAME_RST, stream_id,
+                       StatusError.new(CODE_INTERNAL, "HEADERS for stream already in use")
+                     ))
+        rescue StandardError
+          nil
+        end
+        return
+      end
+      if @dispatcher.nil?
+        begin
+          send_frame(Codec.status_frame(
+                       FRAME_TRAILERS, stream_id,
+                       StatusError.new(CODE_UNIMPLEMENTED, "unknown method #{headers.path}")
+                     ))
+        rescue StandardError
+          nil
+        end
+        return
+      end
+      stream_input = StreamInput.new
+      @streams_lock.synchronize { @streams[stream_id] = stream_input }
+      sink = ResponseSink.new(self, stream_id)
+      dispatcher = @dispatcher
+      Thread.new do
+        begin
+          # No eager HEADERS: initial metadata flushes lazily
+          # via the sink (first DATA, or below on a DATA-less
+          # success) so handlers can set_headers first. Errors
+          # end trailers-only, as gRPC allows.
+          ctx = CallContext.new(headers.metadata)
+          sink.resp_headers = ctx.response_headers
+          sink.resp_trailers = ctx.response_trailers
+          status = dispatcher.call(ctx, headers, stream_input, sink)
+          if status.nil?
+            status = StatusError.new(CODE_OK, "")
+            begin
+              sink.flush_headers
+            rescue StandardError
+              nil
+            end
+          end
+          begin
+            sink.send_trailers(status)
+          rescue StandardError
+            nil
+          end
+        ensure
+          close_stream(stream_id)
+        end
+      end
+    end
+  end
+end

data/lib/grpcdc/eventbus.rb

@@ -0,0 +1,250 @@
+# @generated by grpc-dc codegen. DO NOT EDIT.
+# SPDX-License-Identifier: Apache-2.0
+# Event bus (grpcdc.events.v1.EventBus): in-memory broker,
+# client helpers, and tag matching. Wire messages and stubs
+# are generated from proto/events.proto (events_pb,
+# events_grpc_dc); the broker policy comes from the shared
+# event-bus spec.
+#
+# Delivery is at-most-once: each subscriber has a bounded
+# queue (SUBSCRIBER_QUEUE_CAPACITY) and drops its oldest
+# events when it falls behind; stats reports the drops.
+
+require "thread"
+
+require_relative "events_pb"
+require_relative "events_grpc_dc"
+
+module Grpcdc
+  module Eventbus
+    SUBSCRIBER_QUEUE_CAPACITY = 128
+
+    # Canonical identity of one tag value. The oneof kind is
+    # part of the identity (int 5 != "5" != enum 5). Kinds are
+    # told apart by value, so an all-default TagValue reads as
+    # the empty string value; numbers compare bit-exact, never
+    # via decimal text.
+    def self.value_key(tv)
+      return "s:#{tv.string_value}" unless tv.string_value.empty?
+      return "i:#{tv.int_value}" unless tv.int_value.zero?
+      return "d:#{[tv.double_value].pack("G").unpack1("H*")}" unless tv.double_value.zero?
+      return "b:true" if tv.bool_value
+      return "e:#{tv.enum_value}" unless tv.enum_value.zero?
+
+      "s:"
+    end
+
+    # Stable key for one TagValue, e.g. "1|s:orders".
+    def self.tag_value_key(tv)
+      "#{tv.tag}|#{value_key(tv)}"
+    end
+
+    # Containment match: the event is delivered when its tag
+    # list contains every (tag, value) pair of the filter. An
+    # empty filter matches everything.
+    def self.tags_match(event_tags, filter_tags)
+      return true if filter_tags.nil? || filter_tags.empty?
+
+      have = {}
+      (event_tags || []).each { |tv| have[tag_value_key(tv)] = true }
+      filter_tags.all? { |f| have.key?(tag_value_key(f)) }
+    end
+
+    def self.tag_string(tag, value)
+      EventsPb::TagValue.new(tag: tag, string_value: value.to_s)
+    end
+
+    def self.tag_int(tag, value)
+      EventsPb::TagValue.new(tag: tag, int_value: Integer(value))
+    end
+
+    def self.tag_double(tag, value)
+      EventsPb::TagValue.new(tag: tag, double_value: Float(value))
+    end
+
+    def self.tag_bool(tag, value)
+      EventsPb::TagValue.new(tag: tag, bool_value: value ? true : false)
+    end
+
+    def self.tag_enum(tag, value)
+      EventsPb::TagValue.new(tag: tag, enum_value: Integer(value))
+    end
+
+    class Subscriber
+      attr_reader :filter, :dropped
+
+      def initialize(filter_tags, capacity)
+        @filter = filter_tags || []
+        @capacity = capacity
+        @queue = []
+        @mutex = Mutex.new
+        @cond = ConditionVariable.new
+        @dropped = 0
+      end
+
+      def push(event)
+        @mutex.synchronize do
+          dropped = false
+          if @queue.length >= @capacity
+            @queue.shift
+            @dropped += 1
+            dropped = true
+          end
+          @queue << event
+          @cond.broadcast
+          dropped
+        end
+      end
+
+      # Next queued event, or nil when the wait times out. The
+      # broker re-checks every tick; a cancelled call is reaped
+      # when its next matching send fails (the runtime surfaces
+      # cancellation only at send time).
+      def take(timeout)
+        @mutex.synchronize do
+          @cond.wait(@mutex, timeout) if @queue.empty?
+          @queue.empty? ? nil : @queue.shift
+        end
+      end
+    end
+
+    # In-memory grpcdc.events.v1.EventBus broker. Any peer can
+    # host it: register() it on a Grpcdc::Server next to your
+    # own services, or call publish_event directly in-process.
+    class EventBusBroker
+      def initialize(queue_capacity: SUBSCRIBER_QUEUE_CAPACITY)
+        @queue_capacity = queue_capacity
+        @mutex = Mutex.new
+        @subscribers = []
+        @seq = 0
+        @published = 0
+        @dropped = 0
+      end
+
+      # Accept an event: assign its sequence number and
+      # timestamp and fan it out to matching subscribers.
+      # Returns the stamped EventsPb::Event.
+      def publish_event(tags, payload, publisher_id = "")
+        event = nil
+        subscribers = nil
+        @mutex.synchronize do
+          @seq += 1
+          event = EventsPb::Event.new(
+            tags: tags || [],
+            payload: (payload || "".b).to_s.b,
+            seq: @seq,
+            publisher_id: publisher_id || "",
+            timestamp_unix_ms: (Time.now.to_f * 1000).to_i
+          )
+          @published += 1
+          subscribers = @subscribers.dup
+        end
+        subscribers.each do |sub|
+          next unless Eventbus.tags_match(event.tags, sub.filter)
+
+          if sub.push(event)
+            @mutex.synchronize { @dropped += 1 }
+          end
+        end
+        event
+      end
+
+      def stats
+        @mutex.synchronize do
+          { "published" => @published, "subscribers" => @subscribers.length, "dropped" => @dropped }
+        end
+      end
+
+      # grpcdc.events.v1.EventBus service implementation
+      # (register calls these).
+      def Publish(_ctx, req)
+        event = publish_event(req.tags, req.payload, req.publisher_id)
+        EventsPb::PublishReply.new(seq: event.seq)
+      end
+
+      def Subscribe(req, stream)
+        sub = Subscriber.new(req.filter, @queue_capacity)
+        @mutex.synchronize { @subscribers << sub }
+        begin
+          loop do
+            event = sub.take(0.1)
+            stream.send(event) unless event.nil?
+          end
+        ensure
+          @mutex.synchronize { @subscribers.delete(sub) }
+        end
+      end
+
+      # In-process subscription: events fan out to it exactly
+      # like an RPC subscriber, without a call. Useful embedded
+      # and for tests; close() unregisters.
+      def subscribe_local(filter_tags)
+        sub = Subscriber.new(filter_tags, @queue_capacity)
+        @mutex.synchronize { @subscribers << sub }
+        LocalSubscription.new(self, sub)
+      end
+
+      def remove_subscriber(sub)
+        @mutex.synchronize { @subscribers.delete(sub) }
+      end
+
+      def register(server)
+        EventsGrpcDc.register_event_bus_server(server, self)
+        self
+      end
+    end
+
+    # Handle for EventBusBroker#subscribe_local: pull events
+    # in-process. take returns the next event (waiting up to
+    # the timeout, in seconds), or nil; dropped counts this
+    # subscription's drop-oldest losses.
+    class LocalSubscription
+      def initialize(broker, sub)
+        @broker = broker
+        @sub = sub
+      end
+
+      def dropped
+        @sub.dropped
+      end
+
+      def take(timeout = 1.0)
+        deadline = Time.now + timeout
+        loop do
+          remaining = deadline - Time.now
+          return @sub.take(0) if remaining <= 0
+
+          event = @sub.take([remaining, 0.1].min)
+          return event unless event.nil?
+          return nil if Time.now >= deadline
+        end
+      end
+
+      def close
+        @broker.remove_subscriber(@sub)
+      end
+    end
+
+    # Publish through a generated EventBusClient; returns the
+    # broker-assigned sequence number.
+    def self.publish_event(client, tags, payload, publisher_id = "")
+      reply = client.Publish(EventsPb::PublishRequest.new(
+                               tags: tags || [],
+                               payload: (payload || "".b).to_s.b,
+                               publisher_id: publisher_id || ""
+                             ))
+      reply.seq
+    end
+
+    # Subscribe through a generated EventBusClient; returns the
+    # receiving stream (enumerate it, or close() it to
+    # unsubscribe).
+    def self.subscribe_events(client, filter_tags)
+      client.Subscribe(EventsPb::SubscribeRequest.new(filter: filter_tags || []))
+    end
+
+    # Re-exported so users can build a client without requiring
+    # the stub module directly.
+    EventBusClient = EventsGrpcDc::EventBusClient
+  end
+end