connectrpc 0.1.0

data/lib/connectrpc/client.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module ConnectRPC
+  class Client # rubocop:disable Metrics/ClassLength
+    # Configuration validates each independent public bound eagerly.
+    # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+    def initialize(base_url:, binding:, transport: nil, codec: :proto, request_limit: Protocol::DEFAULT_LIMIT,
+                   response_limit: Protocol::DEFAULT_LIMIT, request_wire_limit: request_limit,
+                   response_wire_limit: response_limit, accept_encoding: nil, use_get: false, get_url_limit: 8192,
+                   protocol: :connect, mode: :unary, encoding: :identity, instrumentation: nil,
+                   terminal_wire_limit: 65_536, terminal_limit: 65_536, status_codec: nil,
+                   grpc_status_wire_limit: 65_536, grpc_status_limit: 65_536)
+      Protocol.profile!(protocol, mode, encoding)
+      @protocol = protocol
+      @grpc_status_wire_limit = Protocol.limit!(grpc_status_wire_limit)
+      @grpc_status_limit = Protocol.limit!(grpc_status_limit)
+      @status_codec = GRPCProtocol.status_codec!(binding, status_codec) if protocol == :grpc
+      raise ArgumentError, "gRPC requires protobuf POST" if protocol == :grpc && (codec != :proto || use_get)
+      raise ArgumentError, "use_get must be true or false" unless [true, false].include?(use_get)
+
+      @terminal_wire_limit = Protocol.limit!(terminal_wire_limit)
+      @terminal_limit = Protocol.limit!(terminal_limit)
+      @use_get = use_get
+      @get_url_limit = Protocol.limit!(get_url_limit)
+      @base_url = parse_base_url(base_url)
+      @instrumentation = instrumentation
+      @binding = binding
+      @transport = transport || default_transport
+      @codec = Protocol.codec!(codec)
+      @encoding = encoding
+      @accept_encoding = Protocol.accept_encoding!(accept_encoding, encoding)
+      @request_wire_limit = Protocol.limit!(request_wire_limit)
+      @response_wire_limit = Protocol.limit!(response_wire_limit)
+      @request_limit = Protocol.limit!(request_limit)
+      @response_limit = Protocol.limit!(response_limit)
+    end
+
+    # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+
+    def call(method, request, metadata: {}, timeout: 30, cancellation: nil)
+      raise ArgumentError, "call requires a unary Method" unless method.is_a?(Method)
+
+      unless cancellation.nil? || cancellation.is_a?(CancellationToken)
+        raise ArgumentError, "cancellation must be a CancellationToken or nil"
+      end
+
+      if @protocol == :grpc
+        raise ArgumentError, "Transport does not support unary gRPC" unless stream_capability?(method)
+
+        return stream_call(method, request, metadata, timeout, cancellation) { |_| nil }
+      end
+      return instrumented_call(method, request, metadata, timeout, cancellation) if @instrumentation
+
+      process_call(method, request, metadata, timeout, cancellation)
+    end
+
+    private
+
+    # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def process_call(method, request, metadata, timeout, cancellation, lifecycle: nil, injection: nil)
+      # @type var state: CallCancellation?
+      state = nil
+      deadline = Deadline.new(timeout) unless timeout.nil?
+      active = state = CallCancellation.new(deadline: deadline, cancellation: cancellation)
+      active.check!
+      metadata = Metadata.new(metadata)
+      if lifecycle
+        metadata = injected_metadata(metadata, injection)
+        lifecycle.request_metadata = Instrumentation.carrier(metadata)
+      end
+      outgoing = build_request(method, request, metadata, active, lifecycle)
+      outgoing.deadline = deadline
+      outgoing.cancellation = state
+      outgoing.headers["connect-timeout-ms"] = [deadline.timeout_ms] if deadline
+      outgoing.lifecycle = lifecycle if lifecycle
+      active.check!
+      lifecycle.request_bytes = outgoing.body.bytesize if lifecycle && outgoing.http_method != "GET"
+      transport = @transport #: _Transport
+      response = transport.call(outgoing)
+      yield response if block_given?
+      active.check!
+      Protocol.check_size!(response.body, @response_wire_limit)
+      result = read_response(response, method, active, lifecycle)
+      active.commit!
+      result
+    rescue StandardError => e
+      lifecycle&.record_failure(e)
+      state&.commit!
+      raise
+    ensure
+      state&.close
+    end
+
+    def instrumented_call(method, request, metadata, timeout, cancellation)
+      # @type var injection: Hash[String, String | Array[String]]
+      injection = {}
+      instrumentation = @instrumentation #: Instrumentation
+      lifecycle = instrumentation.start(owner: self, role: :client, method: method.is_a?(Method) ? method : nil,
+                                        carrier: injection, server_address: @base_url.hostname.freeze,
+                                        server_port: @base_url.port)
+      lifecycle.begin_processing(self)
+      # @type var response: TransportResponse?
+      response = nil
+      # @type var error: Exception?
+      error = nil
+      completed = false
+      begin
+        result = lifecycle.activate do
+          process_call(method, request, metadata, timeout, cancellation, lifecycle: lifecycle,
+                                                                         injection: injection) do |received|
+            response = received
+          end
+        end
+        completed = true
+        result
+      rescue Exception => e # rubocop:disable Lint/RescueException -- observe the actual escape and preserve it
+        error = e
+        raise
+      ensure
+        lifecycle.processing_finished(code: error.is_a?(Error) ? error.code : ("OK" if completed),
+                                      error: error, normalized_error: error, http_status: response&.status,
+                                      response_bytes: response&.body&.bytesize,
+                                      response_metadata: response ? Instrumentation.carrier(response.headers) : {})
+        lifecycle.finish(delivery: :unobserved)
+      end
+    end
+
+    # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    def injected_metadata(metadata, injection)
+      instrumentation = @instrumentation #: Instrumentation
+      carrier = injection #: metadata_input
+      instrumentation.safely do
+        validated = Metadata.new(carrier)
+        return Metadata.new(metadata.to_h.merge(validated.to_h))
+      end
+      metadata
+    end
+
+    def parse_base_url(base_url)
+      uri = URI(base_url)
+      unless %w[http https].include?(uri.scheme) && uri.host && !uri.userinfo && !uri.query && !uri.fragment
+        raise ArgumentError, "Base URL must be an HTTP(S) URL without credentials, query or fragment"
+      end
+
+      uri
+    end
+
+    def default_transport
+      require_relative "transports/net_http"
+      Transports::NetHTTP.new
+    end
+
+    def encode_request(method, request, deadline, lifecycle = nil)
+      deadline&.check!
+      body = @binding.encode(request, type: method.request_type, codec: @codec)
+      deadline&.check!
+      Protocol.check_size!(body, @request_limit)
+      body
+    rescue CodecError => e
+      lifecycle&.record_failure(e)
+      raise Error.new(:invalid_argument, "Cannot encode request")
+    end
+
+    def build_request(method, request, metadata, deadline, lifecycle = nil) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity
+      body = encode_request(method, request, deadline, lifecycle)
+      body = compress_request(body, deadline, lifecycle) if @encoding == :gzip
+      Protocol.check_size!(body, @request_wire_limit)
+      url = @base_url.dup
+      base_path = @base_url.path #: String
+      url.path = base_path.delete_suffix("/") + method.path
+      get = @use_get && method.idempotency == :no_side_effects
+      lifecycle.request_bytes = body.bytesize if lifecycle && get
+      GetQuery.build(url, body, codec: @codec, encoding: @encoding, limit: @get_url_limit, deadline: deadline) if get
+      TransportRequest.new(url: url, http_method: get ? "GET" : "POST",
+                           headers: request_headers(metadata, nil, get: get), body: get ? "" : body,
+                           response_limit: @response_wire_limit, deadline: nil)
+    end
+
+    def request_headers(metadata, deadline, get: false)
+      headers = metadata.to_h.merge("content-type" => [Protocol::CONTENT_TYPES.fetch(@codec)],
+                                    "accept-encoding" => [@accept_encoding.join(", ")],
+                                    "connect-protocol-version" => ["1"])
+      headers["content-encoding"] = ["gzip"] if @encoding == :gzip
+      %w[content-type content-encoding connect-protocol-version].each { |key| headers.delete(key) } if get
+      headers["connect-timeout-ms"] = [deadline.timeout_ms] if deadline
+      headers
+    end
+
+    def compress_request(body, deadline, lifecycle = nil)
+      Compression.encode(body, limit: @request_wire_limit, deadline: deadline,
+                               on_error: ->(error) { lifecycle&.record_failure(error) })
+    rescue Zlib::Error => e
+      lifecycle&.record_failure(e)
+      raise Error.new(:internal, "Cannot compress request")
+    end
+
+    def response_body(response, headers, deadline, lifecycle = nil)
+      encoding = response_encoding!(headers)
+
+      body = response.body
+      body = inflate_response(body, response.status, deadline, lifecycle) if encoding == :gzip && !body.empty?
+      Protocol.check_size!(body, @response_limit)
+      deadline&.check!
+      body
+    end
+
+    def inflate_response(body, status, deadline, lifecycle = nil)
+      Compression.decode(body, limit: @response_limit, deadline: deadline,
+                               on_error: ->(error) { lifecycle&.record_failure(error) })
+    rescue Compression::Malformed => e
+      lifecycle&.record_failure(e)
+      raise Error.new(:internal, "Cannot decompress response") if status == 200
+
+      # Malformed error Bare-Messages use HTTP fallback, preserving metadata.
+      ""
+    rescue Zlib::Error => e
+      lifecycle&.record_failure(e)
+      raise Error.new(:internal, "Cannot decompress response")
+    end
+
+    def response_encoding!(headers)
+      encoding = Protocol.content_encoding(headers)
+      return encoding if encoding && @accept_encoding.include?(encoding)
+
+      raise Error.new(:internal, "Unsupported response content encoding")
+    end
+
+    def validate_response!(status, headers, body)
+      raise Protocol.parse_error(status, headers, body) unless status == 200
+
+      content_type = Protocol.single(headers, "content-type")
+      return if Protocol.content_codec(content_type) == @codec
+
+      code = content_type&.downcase&.start_with?("application/") ? :internal : :unknown
+      raise Error.new(code, "Unexpected response content type")
+    end
+
+    def read_response(response, method, deadline, lifecycle = nil)
+      headers = Protocol.headers(response.headers)
+      body = response_body(response, headers, deadline, lifecycle)
+      validate_response!(response.status, headers, body)
+      message = decode_response(body, method, lifecycle)
+      Response.new(message: message, metadata: Protocol.metadata(headers),
+                   trailers: Protocol.metadata(headers, trailers: true))
+    rescue ArgumentError => e
+      lifecycle&.record_failure(e)
+      raise Error.new(:internal, "Malformed response metadata")
+    end
+
+    def decode_response(bytes, method, lifecycle = nil)
+      @binding.decode(bytes, type: method.response_type, codec: @codec)
+    rescue CodecError => e
+      lifecycle&.record_failure(e)
+      raise Error.new(:internal, "Cannot decode response")
+    end
+  end
+end

data/lib/connectrpc/compression.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module ConnectRPC
+  # Retains bounded output from native gzip streams. Each native output callback
+  # yields at most 16 KiB on the supported default Zlib versions.
+  class Compression
+    class Malformed < StandardError; end
+
+    CHUNK_SIZE = 16_384
+
+    def self.encode(bytes, limit:, deadline: nil, on_error: nil)
+      new(limit, deadline, on_error: on_error).encode(bytes)
+    end
+
+    def self.decode(bytes, limit:, deadline: nil, on_error: nil)
+      new(limit, deadline, on_error: on_error).decode(bytes)
+    end
+
+    def initialize(limit, deadline, on_error: nil)
+      @limit = limit
+      @deadline = deadline
+      @on_error = on_error
+      @output = +"".b
+    end
+
+    def encode(bytes)
+      stream = Zlib::Deflate.new(Zlib::DEFAULT_COMPRESSION, Zlib::MAX_WBITS + 16)
+      chunks(bytes) { |chunk| step { stream.deflate(chunk) { |output| append(output) } } }
+      step { stream.finish { |output| append(output) } }
+      @output
+    ensure
+      # @type var stream: Zlib::Deflate?
+      stream&.close
+    end
+
+    def decode(bytes)
+      cursor = 0
+      while cursor < bytes.bytesize
+        @deadline&.check!
+        cursor = member(bytes, cursor)
+      end
+      @deadline&.check!
+      @output
+    rescue Zlib::DataError, Zlib::BufError
+      raise Malformed, "Malformed gzip content"
+    end
+
+    private
+
+    def chunks(bytes)
+      cursor = 0
+      while cursor < bytes.bytesize
+        chunk = bytes.byteslice(cursor, CHUNK_SIZE) #: String
+        yield chunk
+        cursor += chunk.bytesize
+      end
+    end
+
+    def member(bytes, cursor)
+      stream = Zlib::Inflate.new(Zlib::MAX_WBITS + 16)
+      until stream.finished?
+        raise Malformed, "Malformed gzip content" if cursor == bytes.bytesize
+
+        chunk = bytes.byteslice(cursor, CHUNK_SIZE) #: String
+        cursor += inflate_chunk(stream, chunk)
+      end
+      # finish may return raw trailing input. Only inflate's validated block
+      # output belongs in the payload; the cursor starts the next gzip member.
+      cursor
+    ensure
+      # @type var stream: Zlib::Inflate?
+      stream&.close
+    end
+
+    def inflate_chunk(stream, chunk)
+      before = stream.total_in
+      step { stream.inflate(chunk) { |output| append(output) } }
+      consumed = stream.total_in - before
+      raise Malformed, "Malformed gzip content" unless consumed.positive?
+
+      consumed
+    end
+
+    def step
+      @deadline&.check!
+      result = begin
+        yield
+      rescue StandardError => e
+        check_after_failure(e)
+        raise
+      end
+      @deadline&.check!
+      result
+    end
+
+    def check_after_failure(error)
+      @deadline&.check!
+    rescue StandardError
+      # Ordinary gzip normalization belongs to the owner unless this check wins.
+      record_failure(error)
+      raise
+    end
+
+    def record_failure(error)
+      @on_error&.call(error)
+    rescue StandardError
+      nil
+    end
+
+    def append(chunk)
+      @deadline&.check!
+      raise Error.new(:resource_exhausted, "Message exceeds byte limit") if @output.bytesize + chunk.bytesize > @limit
+
+      @output << chunk
+      @deadline&.check!
+    end
+  end
+end

data/lib/connectrpc/deadline.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  class Deadline
+    # Bound native time conversions without shortening the logical deadline.
+    MAX_NATIVE_WAIT = 9_999_999.999
+
+    def initialize(timeout, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      unless timeout.is_a?(Numeric) && timeout.real? && timeout.finite? && timeout.positive?
+        raise ArgumentError, "Timeout must be finite positive seconds"
+      end
+
+      @clock = clock
+      @expires_at = @clock.call + timeout
+    end
+
+    def self.expired
+      deadline = allocate
+      deadline.instance_variable_set(:@clock, -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      deadline.instance_variable_set(:@expires_at, Process.clock_gettime(Process::CLOCK_MONOTONIC))
+      deadline
+    end
+    private_class_method :expired
+
+    def remaining
+      [@expires_at - @clock.call, 0.0].max
+    end
+
+    def expired?
+      remaining.zero?
+    end
+
+    def native_timeout
+      [remaining, MAX_NATIVE_WAIT].min
+    end
+
+    def check!
+      raise Error.new(:deadline_exceeded, "Deadline exceeded"), cause: nil if expired?
+    end
+
+    def timeout_ms
+      check!
+      [remaining * 1000, 9_999_999_999].min.ceil.clamp(1, 9_999_999_999).to_s
+    end
+  end
+
+  class Context
+    attr_reader :request_metadata, :response_metadata, :response_trailers, :deadline
+
+    def initialize(request_metadata: {}, deadline: nil, lifecycle: nil, cancellation: nil)
+      @cancellation = CallCancellation.new(deadline: deadline, cancellation: cancellation)
+      @request_metadata = Metadata.new(request_metadata)
+      @response_metadata = Metadata.new
+      @response_trailers = Metadata.new
+      @deadline = deadline
+      @lifecycle = lifecycle
+    rescue StandardError
+      @cancellation&.close
+      raise
+    end
+
+    # Framework invokers record escaping application failures before normalizing them.
+    def record_failure(error)
+      @lifecycle&.record_failure(error)
+      nil
+    end
+
+    def cancelled?
+      @cancellation.cancelled?
+    end
+
+    def check!
+      @cancellation.check!
+    end
+
+    def cancellation_reason = @cancellation.reason
+
+    def commit! = @cancellation.commit!
+    def close = @cancellation.close
+  end
+end

data/lib/connectrpc/error.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  class CodecError < StandardError; end
+
+  class ErrorDetail
+    attr_reader :type, :value
+
+    def initialize(type:, value:)
+      raise ArgumentError, "Invalid detail type" unless type.is_a?(String) && Method::QUALIFIED_NAME.match?(type)
+      raise ArgumentError, "Detail value must be binary bytes" unless value.is_a?(String)
+
+      @type = type.dup.freeze
+      @value = value.b.freeze
+      freeze
+    end
+
+    def decode(binding:, type:)
+      binding.decode(value, type: type, codec: :proto)
+    end
+
+    def to_h
+      { "type" => type, "value" => Metadata.encode_binary(value) }
+    end
+  end
+
+  class Error < StandardError
+    HTTP_STATUS = {
+      "canceled" => 499, "unknown" => 500, "invalid_argument" => 400, "deadline_exceeded" => 504,
+      "not_found" => 404, "already_exists" => 409, "permission_denied" => 403, "resource_exhausted" => 429,
+      "failed_precondition" => 400, "aborted" => 409, "out_of_range" => 400, "unimplemented" => 501,
+      "internal" => 500, "unavailable" => 503, "data_loss" => 500, "unauthenticated" => 401
+    }.freeze
+    HTTP_FALLBACK = {
+      400 => "internal", 401 => "unauthenticated", 403 => "permission_denied", 404 => "unimplemented",
+      429 => "unavailable", 502 => "unavailable", 503 => "unavailable", 504 => "unavailable"
+    }.freeze
+
+    attr_reader :code, :details, :metadata, :trailers
+
+    def initialize(code, message = "", details: [], metadata: {}, trailers: {})
+      code = code.to_s
+      raise ArgumentError, "Unknown Connect error code" unless HTTP_STATUS.key?(code)
+      unless details.is_a?(Array) && details.all?(ErrorDetail)
+        raise ArgumentError, "Details must be ErrorDetail objects"
+      end
+
+      super(safe_message(message))
+      @code = code.dup.freeze
+      @details = details.dup.freeze
+      @metadata = Metadata.new(metadata)
+      @trailers = Metadata.new(trailers)
+    end
+
+    def safe_message(message)
+      raise ArgumentError, "Error message must be UTF-8 text" unless message.is_a?(String) && message.valid_encoding?
+
+      message.encode(Encoding::UTF_8)
+    rescue EncodingError
+      raise ArgumentError, "Error message must be UTF-8 text"
+    end
+    private :safe_message
+
+    def http_status
+      HTTP_STATUS.fetch(code)
+    end
+
+    def to_h
+      { "code" => code, "message" => message, "details" => details.map(&:to_h) }
+    end
+  end
+end

data/lib/connectrpc/generator/names.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  module Generator
+    module Names
+      IDENTIFIER = /\A[A-Za-z_][A-Za-z_0-9]*\z/
+      CONSTANT = /\A[A-Z][A-Za-z_0-9]*\z/
+      KEYWORDS = %w[
+        BEGIN END alias and begin break case class def defined do else elsif end ensure false for if in module
+        next nil not or redo rescue retry return self super then true undef unless until when while yield
+        __FILE__ __LINE__ __ENCODING__
+      ].freeze
+      CLIENT_RESERVED = %w[
+        initialize handlers raise class clone define_singleton_method display dup enum_for
+        extend freeze
+        initialize_copy initialize_dup initialize_clone method_missing respond_to_missing
+        singleton_method_added singleton_method_removed singleton_method_undefined
+        to_str to_ary to_hash to_proc to_io to_path to_int to_sym to_regexp
+        to_yaml to_json pretty_print_inspect pretty_print_cycle pretty_print
+        pretty_print_instance_variables pretty_inspect
+        hash inspect instance_eval instance_exec instance_variable_get
+        instance_variable_set instance_variables itself method methods nil object_id private_methods
+        protected_methods public_method public_methods public_send remove_instance_variable send
+        singleton_class singleton_method singleton_methods tap then to_enum to_s yield_self __id__ __send__
+      ].freeze
+      TOP_LEVEL_RESERVED = %w[
+        ARGF ARGV ArgumentError Array BasicObject Binding CROSS_COMPILING Class ClosedQueueError Comparable Complex
+        ConditionVariable ConnectRPC Data DidYouMean Dir ENV EOFError Encoding EncodingError Enumerable Enumerator
+        Errno ErrorHighlight Exception FalseClass Fiber FiberError File FileTest Float FloatDomainError FrozenError
+        GC Gem Google Hash IO IOError IndexError Integer Interrupt JSON Kernel KeyError LoadError LocalJumpError
+        Marshal MatchData Math Method Module Monitor MonitorMixin Mutex NameError NilClass NoMatchingPatternError
+        NoMatchingPatternKeyError NoMemoryError NoMethodError NotImplementedError Numeric Object ObjectSpace Pathname
+        Proc Process Queue RUBYGEMS_ACTIVATION_MONITOR RUBY_COPYRIGHT RUBY_DESCRIPTION RUBY_ENGINE RUBY_ENGINE_VERSION
+        RUBY_PATCHLEVEL RUBY_PLATFORM RUBY_RELEASE_DATE RUBY_REVISION RUBY_VERSION Rack Ractor Random Range RangeError
+        Rational RbConfig Refinement Regexp RegexpError Ruby RubyVM RuntimeError STDERR STDIN STDOUT ScriptError
+        SecurityError Set Signal SignalException SizedQueue StandardError StopIteration String Struct Symbol SyntaxError
+        SyntaxSuggest SystemCallError SystemExit SystemStackError TOPLEVEL_BINDING Thread ThreadError ThreadGroup Time
+        TracePoint TrueClass TypeError UnboundMethod UncaughtThrowError UnicodeNormalize Warning ZeroDivisionError
+      ].freeze
+
+      def self.identifier!(name, description)
+        return if IDENTIFIER.match?(name)
+
+        raise InvalidDescriptor, "Invalid protobuf name #{name.inspect} in #{description}"
+      end
+
+      def self.constant!(name, description)
+        return if CONSTANT.match?(name) && !%w[BEGIN END].include?(name)
+
+        raise InvalidDescriptor, "Invalid Ruby constant #{name.inspect} for #{description}"
+      end
+
+      # Match protoc v36.2 RubifyConstant and PackageToModule, rather than
+      # camelizing message/service names (which preserves their underscores).
+      def self.rubify(name)
+        name.sub(/\A[a-z]/, &:upcase).sub(/\A(?=[^A-Za-z])/, "PB_")
+      end
+
+      def self.namespace(file)
+        option = file.options
+        package = option&.has_ruby_package? ? option.ruby_package : file.package
+        return [] if package.empty?
+
+        parts = if package.include?("::")
+                  package.split("::", -1)
+                else
+                  package.split(".", -1).map { |part| package_component(part) }
+                end
+        parts.each { |part| constant!(part, "namespace of #{file.name}") }
+        parts
+      end
+
+      def self.package_component(part)
+        part.split("_", -1).map { |word| word.sub(/\A[a-z]/, &:upcase) }.join
+      end
+
+      # gRPC Ruby's established underscore algorithm.
+      def self.rpc(name)
+        name.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').gsub(/([a-z\d])([A-Z])/, '\1_\2').tr("-", "_").downcase
+      end
+
+      def self.rpc!(name, description)
+        identifier!(name, description)
+        ruby = rpc(name)
+        if name.start_with?("_") || KEYWORDS.include?(ruby) || CLIENT_RESERVED.include?(ruby) ||
+           %w[BEGIN END SERVICE CLIENT].include?(ruby.upcase)
+          raise InvalidDescriptor, "Reserved or unsupported Ruby RPC name #{name.inspect} (#{ruby}) in #{description}"
+        end
+
+        constant!(ruby.upcase, description)
+        ruby
+      end
+
+      def self.path!(name)
+        parts = name.split("/", -1)
+        return if %r{\A[A-Za-z0-9_./-]+\.(?:proto|protodevel)\z}.match?(name) &&
+                  parts.none? { |part| part.empty? || %w[. ..].include?(part) }
+
+        raise InvalidDescriptor, "Unsafe relative proto path #{name.inspect}"
+      end
+
+      def self.stem(name) = name.sub(/\.(?:proto|protodevel)\z/, "")
+    end
+  end
+end