grpc-dc 0.37.1

data/lib/grpcdc/codec.rb

@@ -0,0 +1,262 @@
+# @generated by grpc-dc codegen. DO NOT EDIT.
+# SPDX-License-Identifier: Apache-2.0
+# Codec + status types for gRPC over WebRTC DataChannels.
+#
+# Wire protocol in ../SPEC.md. Frame, status, channel and server
+# semantics mirror the Rust, JavaScript, Go and Python runtimes;
+# the tables in wire_gen.rb are generated by grpc-dc codegen.
+
+require "json"
+require_relative "wire_gen"
+
+module Grpcdc
+  HEADER_LEN = 9
+  MAX_DATA_PAYLOAD = 16 * 1024 * 1024
+
+  # Canonical status name ("CODE_N" for unknown codes).
+  def self.status_name(code)
+    STATUS_NAMES.fetch(code, "CODE_#{code}")
+  end
+
+  # A gRPC status (code + message) carried as an exception.
+  # (message is an attribute, like the Python runtime; note
+  # Exception#message normally delegates to to_s, so to_s must
+  # build from the attribute, never from itself.)
+  class StatusError < StandardError
+    attr_reader :code, :message
+
+    # Trailing metadata carried by a status frame (never nil).
+    attr_accessor :trailers
+
+    def initialize(code, message = "")
+      super(message)
+      @code = code
+      @message = message
+      @trailers = {}
+    end
+
+    def to_s
+      "#{Grpcdc.status_name(@code)}: #{@message}"
+    end
+  end
+
+  # The call completed OK (client-side stream end).
+  class CallClosed < EOFError; end
+
+  # --- Homegrown tracing (W3C traceparent propagation) ----------
+  # Dormant until Grpcdc.set_tracer registers an observer with
+  # on_start(kind, method, trace_id, span_id, parent_span_id) and
+  # on_end(kind, method, trace_id, span_id, status_name).
+  # Generated code stays dependency-free: sampling and export are
+  # the application's problem.
+  @tracer = nil
+
+  def self.set_tracer(tracer)
+    @tracer = tracer
+  end
+
+  def self.tracer
+    @tracer
+  end
+
+  @trace_filter = []
+
+  # Restrict traced methods: ';'-separated paths, a trailing
+  # '*' means prefix match ('/echo.Echo/*'). Empty = trace all.
+  def self.set_trace_filter(patterns)
+    @trace_filter = patterns.split(";").reject(&:empty?)
+  end
+
+  def self.trace_allowed?(method)
+    return true if @trace_filter.empty?
+
+    @trace_filter.any? do |p|
+      p.end_with?("*") ? method.start_with?(p[0...-1]) : method == p
+    end
+  end
+
+  def self.format_traceparent(trace_id, span_id)
+    "00-#{trace_id}-#{span_id}-01"
+  end
+
+  # Parse a traceparent header -> [trace_id, span_id] or nil.
+  def self.parse_traceparent(value)
+    return nil unless value.is_a?(String)
+
+    parts = value.split("-")
+    return nil unless parts.length == 4
+
+    trace_id, span_id = parts[1], parts[2]
+    return nil unless trace_id.length == 32 && span_id.length == 16
+    return nil unless trace_id.match?(/\A[0-9a-f]+\z/) && span_id.match?(/\A[0-9a-f]+\z/)
+
+    [trace_id, span_id]
+  end
+
+  def self.trace_start(kind, method, parent)
+    return nil if @tracer.nil? || !trace_allowed?(method)
+
+    require "securerandom"
+    trace_id, parent_span_id = parent || [SecureRandom.hex(16), ""]
+    ctx = {
+      "trace_id" => trace_id,
+      "span_id" => SecureRandom.hex(8),
+      "parent_span_id" => parent_span_id
+    }
+    begin
+      @tracer.on_start(kind, method, ctx["trace_id"], ctx["span_id"], parent_span_id)
+    rescue StandardError
+      # observers must never break the call
+    end
+    ctx
+  end
+
+  def self.trace_end(kind, method, ctx, status)
+    return if ctx.nil? || @tracer.nil?
+
+    begin
+      @tracer.on_end(kind, method, ctx["trace_id"], ctx["span_id"], status)
+    rescue StandardError
+      # observers must never break the call
+    end
+  end
+
+  # Convert an exception to StatusError (OK for nil).
+  def self.to_status(err)
+    return StatusError.new(CODE_OK, "") if err.nil?
+    return err if err.is_a?(StatusError)
+
+    StatusError.new(CODE_INTERNAL, err.message)
+  end
+
+  # A parsed HEADERS payload: path=nil marks response headers.
+  class Headers
+    attr_reader :path, :metadata
+
+    def initialize(path = nil, metadata = nil, timeout: nil)
+      @path = path
+      @metadata = metadata || {}
+    end
+
+    def inspect
+      "Headers(path=#{@path.inspect}, metadata=#{@metadata.inspect})"
+    end
+  end
+
+  module Codec
+    module_function
+
+    # Build one DataChannel message: header + payload.
+    def encode_frame(frame_type, stream_id, payload)
+      unless FRAME_NAMES.value?(frame_type)
+        raise StatusError.new(CODE_INVALID_ARGUMENT, "unknown frame type #{frame_type}")
+      end
+      payload = payload.b
+      if frame_type == FRAME_DATA && payload.bytesize > MAX_DATA_PAYLOAD
+        raise StatusError.new(CODE_RESOURCE_EXHAUSTED, "DATA payload exceeds 16 MiB")
+      end
+
+      [frame_type, stream_id, payload.bytesize].pack("CNN") + payload
+    end
+
+    # Parse one DataChannel message -> [frame_type, stream_id, payload].
+    def decode_frame(data)
+      if data.bytesize < HEADER_LEN
+        raise StatusError.new(
+          CODE_INVALID_ARGUMENT,
+          "frame shorter than 9-byte header: #{data.bytesize} bytes"
+        )
+      end
+      frame_type, stream_id, length = data.byteslice(0, HEADER_LEN).unpack("CNN")
+      if length != data.bytesize - HEADER_LEN
+        raise StatusError.new(
+          CODE_INVALID_ARGUMENT,
+          "payload length #{length} does not match message size #{data.bytesize}"
+        )
+      end
+
+      [frame_type, stream_id, data.byteslice(HEADER_LEN..-1) || "".b]
+    end
+
+    def headers_frame(stream_id, path, metadata)
+      body = {}
+      body["path"] = path unless path.nil?
+      body["metadata"] = metadata if metadata && !metadata.empty?
+      encode_frame(FRAME_HEADERS, stream_id, JSON.generate(body).b)
+    end
+
+    def parse_headers(payload)
+      begin
+        body = JSON.parse(payload.dup.force_encoding(Encoding::UTF_8))
+      rescue JSON::ParserError, EncodingError => e
+        raise StatusError.new(CODE_INVALID_ARGUMENT, "bad HEADERS payload: #{e.message}")
+      end
+      unless body.is_a?(Hash)
+        raise StatusError.new(CODE_INVALID_ARGUMENT, "HEADERS payload is not an object")
+      end
+      metadata = body["metadata"] || {}
+      unless metadata.is_a?(Hash)
+        raise StatusError.new(CODE_INVALID_ARGUMENT, "HEADERS metadata is not an object")
+      end
+
+      Headers.new(body["path"], metadata)
+    end
+
+        # gRPC timeout grammar (grpc-timeout metadata): <digits><unit>,
+    # units H/M/S/m/u/n (at most 8 digits). Encoding uses
+    # milliseconds (seconds past the digit limit), rounded up.
+    def encode_timeout(seconds)
+      ms = (seconds * 1000.0).ceil
+      return "#{ms}m" if ms <= 99999999
+
+      "#{seconds.ceil}S"
+    end
+
+    # Decoded grpc-timeout in seconds, or nil when malformed.
+    def parse_timeout(text)
+      return nil unless text.is_a?(String) && text.length >= 2 && text.length <= 9
+
+      digits = text[0...-1]
+      return nil unless digits.match?(/\A\d+\z/)
+
+      n = digits.to_i.to_f
+      case text[-1]
+      when "H" then n * 3600.0
+      when "M" then n * 60.0
+      when "S" then n
+      when "m" then n / 1000.0
+      when "u" then n / 1000000.0
+      when "n" then n / 1000000000.0
+      end
+    end
+
+def status_frame(frame_type, stream_id, status)
+      body = { "code" => status.code, "message" => status.message }
+      body["metadata"] = status.trailers if status.trailers && !status.trailers.empty?
+      encode_frame(frame_type, stream_id, JSON.generate(body).b)
+    end
+
+    def parse_status(payload)
+      body = JSON.parse(payload.dup.force_encoding(Encoding::UTF_8))
+      status = StatusError.new(Integer(body.fetch("code")), String(body["message"] || ""))
+      md = body["metadata"]
+      if md.is_a?(Hash)
+        status.trailers = md.each_with_object({}) do |(k, v), out|
+          out[k.to_s] = v.to_s
+        end
+      end
+      status
+    rescue JSON::ParserError, EncodingError, KeyError, TypeError, ArgumentError
+      StatusError.new(CODE_UNKNOWN, "malformed trailers")
+    end
+  end
+
+  # Convenience delegates (the Python runtime's flat surface).
+  def self.encode_frame(frame_type, stream_id, payload)
+    Codec.encode_frame(frame_type, stream_id, payload)
+  end
+
+  def self.decode_frame(data)
+    Codec.decode_frame(data)
+  end
+end