connectrpc 0.1.0

data/lib/connectrpc/generator/rbs_renderer.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  module Generator
+    class RBSRenderer
+      include StreamingMethods
+
+      def initialize(schema, file)
+        @schema = schema
+        @file = file
+      end
+
+      def render
+        @lines = ["# Generated by protoc-gen-connectrpc-ruby. DO NOT EDIT!", "# source: #{@file.name}", ""]
+        namespace = Names.namespace(@file)
+        namespace.each_with_index { |name, index| line(index, "module #{name}") }
+        @file.service.each { |service| render_service(service, namespace.size) }
+        namespace.size.times { |index| line(namespace.size - index - 1, "end") }
+        "#{@lines.join("\n")}\n"
+      end
+
+      private
+
+      def line(depth, text)
+        @lines << (("  " * depth) + text)
+      end
+
+      def types(method)
+        [method.input_type, method.output_type].map { |type| @schema.ruby_types.fetch(type) }
+      end
+
+      def handler(method)
+        request, reply = types(method)
+        case declaration_type(method)
+        when "ServerStreamMethod"
+          "(^(#{request}, ::ConnectRPC::ResponseWriter[#{reply}], ::ConnectRPC::StreamingContext) -> void) | " \
+          "::ConnectRPC::_ServerStreamHandler[#{request}, #{reply}]"
+        when "ClientStreamMethod"
+          "(^(::ConnectRPC::RequestReader[#{request}], ::ConnectRPC::StreamingContext) -> #{reply}) | " \
+          "::ConnectRPC::_ClientStreamHandler[#{request}, #{reply}]"
+        when "BidiStreamMethod"
+          "(^(::ConnectRPC::ServerDuplex[#{request}, #{reply}], ::ConnectRPC::StreamingContext) -> void) | " \
+          "::ConnectRPC::_BidiStreamHandler[#{request}, #{reply}]"
+        else
+          "(^(#{request}, ::ConnectRPC::Context) -> #{reply}) | ::ConnectRPC::_Handler[#{request}, #{reply}]"
+        end
+      end
+
+      def render_client_signature(method, depth)
+        request, reply = types(method)
+        options = "?metadata: ::ConnectRPC::metadata_input, ?timeout: ::Numeric?, " \
+                  "?cancellation: ::ConnectRPC::CancellationToken?"
+        name = Names.rpc(method.name)
+        case declaration_type(method)
+        when "ServerStreamMethod"
+          line(depth + 2,
+               "def #{name}: (#{request} request, #{options}) " \
+               "{ (::ConnectRPC::ResponseReader[#{reply}]) -> void } -> nil")
+        when "ClientStreamMethod"
+          line(depth + 2, "def #{name}: (#{options}) { (::ConnectRPC::RequestWriter[#{request}]) -> void } " \
+                          "-> ::ConnectRPC::Response[#{reply}]")
+        when "BidiStreamMethod"
+          line(depth + 2,
+               "def #{name}: (#{options}) { (::ConnectRPC::ClientDuplex[#{request}, #{reply}]) -> void } -> nil")
+        else
+          line(depth + 2, "def #{name}: (#{request} request, #{options}) -> ::ConnectRPC::Response[#{reply}]")
+        end
+      end
+
+      def render_service(service, depth)
+        line(depth, "module #{Names.rubify(service.name)}")
+        methods = service["method"]
+        methods.each do |method|
+          line(depth + 1,
+               "#{Names.rpc(method.name).upcase}: " \
+               "::ConnectRPC::#{declaration_type(method)}[#{types(method).join(', ')}]")
+        end
+        line(depth + 1, "SERVICE: ::ConnectRPC::Service")
+        line(depth + 1, "class Client")
+        line(depth + 2, "def initialize: (client: ::ConnectRPC::Client) -> void")
+        methods.each { |method| render_client_signature(method, depth) }
+        line(depth + 1, "end")
+        keywords = methods.map { |method| "#{Names.rpc(method.name)}: (#{handler(method)})" }.join(", ")
+        values = methods.map do |method|
+          "::ConnectRPC::#{handler_type(method)}[#{types(method).join(', ')}]"
+        end.uniq
+        line(depth + 1,
+             "def self.handlers: (#{keywords}) -> ::Hash[::String, #{values.empty? ? 'bot' : values.join(' | ')}]")
+        line(depth, "end")
+      end
+    end
+  end
+end

data/lib/connectrpc/generator/renderer.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  module Generator
+    class Renderer
+      include StreamingMethods
+
+      def initialize(schema, file)
+        @schema = schema
+        @file = file
+      end
+
+      def render
+        @lines = ["# frozen_string_literal: true", "", "# Generated by protoc-gen-connectrpc-ruby. DO NOT EDIT!",
+                  "# source: #{@file.name}", "", 'require "connectrpc"']
+        required_files.each { |name| @lines << "require #{"#{Names.stem(name)}_pb".dump}" }
+        @lines << ""
+        namespace = Names.namespace(@file)
+        namespace.each_with_index { |name, index| line(index, "module #{name}") }
+        @file.service.each_with_index do |service, index|
+          line(namespace.size, "") if index.positive?
+          render_service(service, namespace.size)
+        end
+        namespace.size.times { |index| line(namespace.size - index - 1, "end") }
+        "#{@lines.join("\n")}\n"
+      end
+
+      private
+
+      def required_files
+        methods = @file.service.flat_map { |service| service["method"] }
+        types = methods.flat_map { |method| [method.input_type, method.output_type] }
+        [@file.name, *types.map { |type| @schema.types.fetch(type).first.name }.uniq.sort].uniq
+      end
+
+      def line(depth, text)
+        @lines << (text.empty? ? "" : ("  " * depth) + text)
+      end
+
+      def render_service(service, depth)
+        line(depth, "module #{Names.rubify(service.name)}")
+        depth += 1
+        methods = service["method"].map { |method| [method, Names.rpc(method.name)] }
+        constants = ["SERVICE", "Client", *methods.map { |_method, ruby| ruby.upcase }]
+        line(depth, "%w[#{constants.join(' ')}].each do |name|")
+        line(depth + 1, "next unless const_defined?(name, false)")
+        line(depth, "")
+        line(depth + 1, "raise ::ArgumentError, \"Generated service constant already defined: \#{self}::\#{name}\"")
+        line(depth, "end")
+        methods.each { |method, ruby| render_method(service, method, ruby, depth) }
+        name = [@file.package, service.name].reject(&:empty?).join(".")
+        line(depth, "")
+        line(depth, "SERVICE = ::ConnectRPC::Service.new(")
+        line(depth + 1, "name: #{name.dump}, methods: [#{methods.map { |_m, ruby| ruby.upcase }.join(', ')}]")
+        line(depth, ")")
+        render_client(methods, depth)
+        render_handlers(methods, depth)
+        line(depth - 1, "end")
+      end
+
+      def render_method(service, method, ruby, depth)
+        name = [@file.package, service.name].reject(&:empty?).join(".")
+        line(depth, "")
+        line(depth, "#{ruby.upcase} = ::ConnectRPC::#{declaration_type(method)}.new(")
+        line(depth + 1, "service: #{name.dump}, name: #{method.name.dump},")
+        render_type("request_type", method.input_type, depth + 1, comma: true)
+        idempotency = { NO_SIDE_EFFECTS: :no_side_effects, IDEMPOTENT: :idempotent }[method.options&.idempotency_level]
+        render_type("response_type", method.output_type, depth + 1, comma: !idempotency.nil?)
+        line(depth + 1, "idempotency: :#{idempotency}") if idempotency
+        line(depth, ")")
+      end
+
+      def render_type(keyword, type, depth, comma:)
+        line(depth, "#{keyword}: ::Google::Protobuf::DescriptorPool.generated_pool.lookup(")
+        line(depth + 1, type.delete_prefix(".").dump)
+        line(depth, ").msgclass#{',' if comma}")
+      end
+
+      def render_client(methods, depth)
+        line(depth, "")
+        line(depth, "class Client")
+        line(depth + 1, "def initialize(client:)")
+        line(depth + 2, "@client = client")
+        line(depth + 1, "end")
+        methods.each do |entry|
+          method, ruby = entry
+          line(depth, "")
+          if method.client_streaming || method.server_streaming
+            render_streaming_client(method, ruby, depth)
+          else
+            line(depth + 1, "def #{ruby}(request, **options)")
+            line(depth + 2, "@client.call(#{ruby.upcase}, request, **options)")
+          end
+          line(depth + 1, "end")
+        end
+        line(depth, "end")
+      end
+
+      def render_handlers(methods, depth)
+        keywords = methods.map { |_method, ruby| "#{ruby}:" }.join(", ")
+        line(depth, "")
+        line(depth, "def self.handlers#{"(#{keywords})" unless methods.empty?}")
+        methods.each do |entry|
+          ruby = entry.last
+          line(depth + 1,
+               "raise ::ArgumentError, #{"#{ruby} must respond to call".dump} unless #{ruby}.respond_to?(:call)")
+        end
+        line(depth, "") unless methods.empty?
+        entries = methods.map { |_method, ruby| "#{ruby.upcase}.path => #{ruby}" }.join(", ")
+        line(depth + 1, methods.empty? ? "{}" : "{ #{entries} }")
+        line(depth, "end")
+      end
+    end
+  end
+end

data/lib/connectrpc/generator/runtime_names.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  module Generator
+    module RuntimeNames
+      # google-protobuf 4.36.2: protobuf.rb, message_exts.rb, repeated_field.rb,
+      # internal/object_cache.rb and ext/google/protobuf_c/{defs,map,protobuf}.c.
+      # Protect helper subtrees too; package modules cannot reopen their classes.
+      PROTOBUF_RUNTIME = %w[
+        AbstractMessage Descriptor DescriptorPool EnumDescriptor Error FieldDescriptor FileDescriptor
+        FFI IMPLEMENTATION Internal Map MessageExts MethodDescriptor OneofDescriptor ParseError PREFER_FFI
+        RepeatedField ServiceDescriptor TypeError UnexpectedStructType
+      ].freeze
+      RUNTIME_PACKAGES = %w[Google Google::Protobuf Google::Protobuf::Compiler].freeze
+      # Concrete assignments in the pinned gem's official *_pb.rb files. These
+      # namespaces belong to those proto definitions, including nested types.
+      PROTOBUF_FILES = {
+        "google/protobuf/any.proto" => %w[Any],
+        "google/protobuf/api.proto" => %w[Api Method Mixin],
+        "google/protobuf/descriptor.proto" => %w[
+          FileDescriptorSet FileDescriptorProto DescriptorProto ExtensionRangeOptions FieldDescriptorProto
+          OneofDescriptorProto EnumDescriptorProto EnumValueDescriptorProto ServiceDescriptorProto MethodDescriptorProto
+          FileOptions MessageOptions FieldOptions OneofOptions EnumOptions EnumValueOptions ServiceOptions MethodOptions
+          UninterpretedOption FeatureSet FeatureSetDefaults SourceCodeInfo GeneratedCodeInfo Edition SymbolVisibility
+        ],
+        "google/protobuf/duration.proto" => %w[Duration],
+        "google/protobuf/empty.proto" => %w[Empty],
+        "google/protobuf/field_mask.proto" => %w[FieldMask],
+        "google/protobuf/compiler/plugin.proto" => %w[
+          Compiler::Version Compiler::CodeGeneratorRequest Compiler::CodeGeneratorResponse
+        ],
+        "google/protobuf/source_context.proto" => %w[SourceContext],
+        "google/protobuf/struct.proto" => %w[Struct Value ListValue NullValue],
+        "google/protobuf/timestamp.proto" => %w[Timestamp],
+        "google/protobuf/type.proto" => %w[Type Field Enum EnumValue Option Syntax],
+        "google/protobuf/wrappers.proto" => %w[
+          DoubleValue FloatValue Int64Value UInt64Value Int32Value UInt32Value BoolValue StringValue BytesValue
+        ]
+      }.freeze
+
+      def self.validate!(parts, kind, origin, file)
+        name = parts.join("::")
+        if reserved_root?(parts, kind)
+          raise InvalidDescriptor, "Reserved top-level Ruby constant #{parts.first} for #{file}: #{origin}"
+        end
+
+        protected_name = protected_runtime(parts, kind) || protected_protobuf_type(parts, kind, origin, file)
+        return unless protected_name
+
+        raise InvalidDescriptor, "Reserved runtime Ruby constant #{protected_name} at #{name} for #{file}: #{origin}"
+      end
+
+      def self.protected_runtime(parts, kind)
+        name = parts.join("::")
+        return name if RUNTIME_PACKAGES.include?(name) && kind != :package
+        return unless parts.take(2) == %w[Google Protobuf] && PROTOBUF_RUNTIME.include?(parts[2])
+
+        parts.take(3).join("::")
+      end
+
+      def self.reserved_root?(parts, kind)
+        Names::TOP_LEVEL_RESERVED.include?(parts.first) &&
+          !(parts.first == "Google" && (parts.size > 1 || kind == :package))
+      end
+
+      def self.protected_protobuf_type(parts, kind, origin, file)
+        return unless parts.take(2) == %w[Google Protobuf]
+
+        suffix = parts.drop(2).take(parts[2] == "Compiler" ? 2 : 1).join("::")
+        source, = PROTOBUF_FILES.find { |_source, names| names.include?(suffix) }
+        return unless source
+
+        return if source == file && official_type?(parts, kind, origin)
+
+        "Google::Protobuf::#{suffix}"
+      end
+
+      def self.official_type?(parts, kind, origin)
+        official = "google.protobuf.#{parts.drop(2).join('.').sub(/\ACompiler\./, 'compiler.')}"
+        %i[message enum].include?(kind) && origin == official
+      end
+    end
+  end
+end

data/lib/connectrpc/generator/schema.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  module Generator
+    class Schema
+      attr_reader :targets, :types, :ruby_types, :rbs
+
+      def initialize(request)
+        unless ["", "rbs=true"].include?(request.parameter)
+          raise InvalidDescriptor, "Invalid plugin parameters #{request.parameter.inspect}; expected rbs=true or empty"
+        end
+
+        @rbs = request.parameter == "rbs=true"
+
+        @files = unique_files(request.proto_file)
+        @targets = target_files(request.file_to_generate)
+        @types = {}
+        @ruby_types = {}
+        @symbols = {}
+        @namespaces = Hash.new { |hash, key| hash[key] = [] }
+        @files.each_value { |file| index_file(file) }
+        targets.each { |file| validate_target(file) }
+        validate_namespaces
+        validate_outputs
+      end
+
+      private
+
+      def unique_files(files)
+        files.each_with_object({}) do |file, result|
+          Names.path!(file.name)
+          raise InvalidDescriptor, "Duplicate proto file #{file.name}" if result.key?(file.name)
+
+          result[file.name] = file
+        end
+      end
+
+      def target_files(names)
+        raise InvalidDescriptor, "Duplicate generation target" unless names.uniq.size == names.size
+
+        names.map do |name|
+          @files.fetch(name) { raise InvalidDescriptor, "Missing generation target #{name.inspect}" }
+        end
+      end
+
+      def symbol!(name, description)
+        previous = @symbols[name]
+        raise InvalidDescriptor, "Duplicate proto symbol #{name}: #{previous} and #{description}" if previous
+
+        @symbols[name] = description
+      end
+
+      def node(parts, kind, origin, file)
+        parts.each { |part| Names.constant!(part, origin) }
+        @namespaces[parts] << [kind, origin, file.name]
+      end
+
+      def index_file(file)
+        unless file.package.empty? || file.package.split(".", -1).all? { |part| Names::IDENTIFIER.match?(part) }
+          raise InvalidDescriptor, "Invalid package #{file.package.inspect} in #{file.name}"
+        end
+
+        namespace = Names.namespace(file)
+        namespace.each_index do |index|
+          # Repeated declarations of the same package are legitimate.
+          node(namespace.take(index + 1), :package, "package #{namespace.take(index + 1).join('::')}", file)
+        end
+        file.dependency.each do |name|
+          raise InvalidDescriptor, "Missing dependency #{name} in #{file.name}" unless @files.key?(name)
+        end
+        index_types(file.message_type, file.enum_type, file.package, namespace, file)
+        file.service.each do |service|
+          Names.identifier!(service.name, file.name)
+          full = qualified(file.package, service.name)
+          symbol!(full, file.name)
+          service["method"].each do |method|
+            Names.identifier!(method.name, full)
+            symbol!(qualified(full, method.name), file.name)
+          end
+        end
+      end
+
+      def index_types(messages, enums, prefix, namespace, file)
+        messages.each do |message|
+          Names.identifier!(message.name, file.name)
+          full = qualified(prefix, message.name)
+          symbol!(full, file.name)
+          @types[".#{full}"] = [file, message]
+          next if message.options&.map_entry
+
+          parts = namespace + [Names.rubify(message.name)]
+          @ruby_types[".#{full}"] = "::#{parts.join('::')}"
+          node(parts, :message, full, file)
+          index_types(message.nested_type, message.enum_type, full, parts, file)
+        end
+        enums.each do |enum|
+          Names.identifier!(enum.name, file.name)
+          full = qualified(prefix, enum.name)
+          symbol!(full, file.name)
+          node(namespace + [Names.rubify(enum.name)], :enum, full, file)
+        end
+      end
+
+      def validate_target(file)
+        unless ["", "proto2", "proto3"].include?(file.syntax) && !file.has_edition?
+          raise InvalidDescriptor, "Unsupported syntax/editions in #{file.name}; use proto2 or proto3"
+        end
+
+        file.service.each do |service|
+          origin = "#{file.name}: #{qualified(file.package, service.name)}"
+          parts = Names.namespace(file) + [Names.rubify(service.name)]
+          node(parts, :service, origin, file)
+          node(parts + ["SERVICE"], :generated, "#{origin} SERVICE", file)
+          node(parts + ["Client"], :generated, "#{origin} Client", file)
+          methods = {}
+          service["method"].each do |method|
+            validate_method(method, origin)
+            ruby = Names.rpc!(method.name, origin)
+            if methods.key?(ruby)
+              raise InvalidDescriptor, "Ruby RPC collision in #{origin}: #{methods[ruby]} and #{method.name} (#{ruby})"
+            end
+
+            methods[ruby] = method.name
+            node(parts + [ruby.upcase], :generated, "#{origin}.#{method.name}", file)
+          end
+        end
+      end
+
+      def validate_method(method, origin)
+        unless [nil, :IDEMPOTENCY_UNKNOWN, :NO_SIDE_EFFECTS, :IDEMPOTENT].include?(method.options&.idempotency_level)
+          raise InvalidDescriptor, "Invalid idempotency level for #{origin}.#{method.name}"
+        end
+
+        [method.input_type, method.output_type].each do |name|
+          entry = types[name]
+          unless entry && !entry.last.options&.map_entry
+            raise InvalidDescriptor, "Unresolved or non-message type #{name.inspect} for #{origin}.#{method.name}"
+          end
+        end
+      end
+
+      def validate_namespaces
+        loaded = loaded_files
+        loaded_names = loaded.map(&:name)
+        relevant = loaded.flat_map do |file|
+          namespace = Names.namespace(file)
+          if namespace.empty?
+            [*file.message_type, *file.enum_type, *file.service].map { |type| [Names.rubify(type.name)] }
+          else
+            [namespace]
+          end
+        end
+        @namespaces.each do |parts, declarations|
+          next unless relevant.any? { |prefix| parts.take(prefix.size) == prefix || prefix.take(parts.size) == parts }
+
+          declarations.each do |kind, origin, file|
+            RuntimeNames.validate!(parts, kind, origin, file) if loaded_names.include?(file)
+          end
+          unique = declarations.map { |kind, origin, _file| [kind, origin] }.uniq
+          next if unique.size == 1
+          next if unique.all? { |kind, _origin| kind == :package }
+
+          raise InvalidDescriptor,
+                "Ruby namespace collision at #{parts.join('::')}: #{unique.map(&:last).join(' and ')}"
+        end
+      end
+
+      # Official target _pb files require their imports, including public imports.
+      # Include explicitly resolved type files too for defensive indirect requests.
+      def loaded_files
+        required = targets.dup
+        targets.each do |file|
+          file.service.each do |service|
+            service["method"].each do |method|
+              [method.input_type, method.output_type].each { |type| required << types.fetch(type).first }
+            end
+          end
+        end
+        loaded = {}
+        until required.empty?
+          file = required.pop
+          next if loaded.key?(file.name)
+
+          loaded[file.name] = file
+          file.dependency.each { |name| required << @files.fetch(name) }
+        end
+        loaded.values
+      end
+
+      def validate_outputs
+        outputs = {}
+        @files.each_value do |file|
+          output = "#{Names.stem(file.name)}_pb.rb"
+          if outputs[output]
+            raise InvalidDescriptor,
+                  "Output collision: #{outputs[output]} and #{file.name} -> #{output}"
+          end
+
+          outputs[output] = file.name
+        end
+        targets.reject { |file| file.service.empty? }.each do |file|
+          extensions = rbs ? %w[rb rbs] : %w[rb]
+          extensions.each do |extension|
+            output = "#{Names.stem(file.name)}_connect.#{extension}"
+            if outputs[output]
+              raise InvalidDescriptor,
+                    "Output collision: #{outputs[output]} and #{file.name} -> #{output}"
+            end
+
+            outputs[output] = file.name
+          end
+        end
+      end
+
+      def qualified(prefix, name) = [prefix, name].reject(&:empty?).join(".")
+    end
+  end
+end

data/lib/connectrpc/generator/streaming_methods.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  module Generator
+    module StreamingMethods
+      private
+
+      def declaration_type(method)
+        return method.server_streaming ? "BidiStreamMethod" : "ClientStreamMethod" if method.client_streaming
+
+        method.server_streaming ? "ServerStreamMethod" : "Method"
+      end
+
+      def handler_type(method)
+        name = declaration_type(method)
+        name == "Method" ? "_Handler" : "_#{name.delete_suffix('Method')}Handler"
+      end
+
+      def render_streaming_client(method, ruby, depth)
+        operation = { "BidiStreamMethod" => "bidi_stream", "ClientStreamMethod" => "client_stream",
+                      "ServerStreamMethod" => "server_stream" }.fetch(declaration_type(method))
+        request = method.client_streaming ? "" : "request, "
+        line(depth + 1, "def #{ruby}(#{request}**options, &)")
+        line(depth + 2, "@client.#{operation}(#{ruby.upcase}, #{request}**options, &)")
+      end
+    end
+    private_constant :StreamingMethods
+  end
+end

data/lib/connectrpc/generator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+begin
+  gem "google-protobuf", ">= 4.36.2", "< 5"
+  require "google/protobuf/plugin_pb"
+rescue LoadError => e
+  raise LoadError, "ConnectRPC generator requires google-protobuf >= 4.36.2, < 5: #{e.message}"
+end
+
+require_relative "generator/names"
+require_relative "generator/runtime_names"
+require_relative "generator/schema"
+require_relative "generator/streaming_methods"
+require_relative "generator/renderer"
+require_relative "generator/rbs_renderer"
+
+module ConnectRPC
+  module Generator
+    class InvalidDescriptor < StandardError; end
+
+    # Pure request -> response. Expected descriptor errors use the protoc error
+    # field; unexpected implementation failures must remain visible to callers.
+    def self.generate(request)
+      schema = Schema.new(request)
+      files = schema.targets.reject { |file| file.service.empty? }.flat_map { |file| render_files(schema, file) }
+      Google::Protobuf::Compiler::CodeGeneratorResponse.new(supported_features: 1, file: files)
+    rescue InvalidDescriptor => e
+      Google::Protobuf::Compiler::CodeGeneratorResponse.new(error: e.message)
+    end
+
+    def self.render_files(schema, file)
+      renderers = [[Renderer, "rb"]]
+      renderers << [RBSRenderer, "rbs"] if schema.rbs
+      renderers.map do |renderer, extension|
+        Google::Protobuf::Compiler::CodeGeneratorResponse::File.new(
+          name: "#{Names.stem(file.name)}_connect.#{extension}", content: renderer.new(schema, file).render
+        )
+      end
+    end
+    private_class_method :render_files
+  end
+end