gritz-native 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1acc3257753cf7f6cb65db29e2c77692136a2050044b225b2cc73880fe67e9d3
+  data.tar.gz: 665dcaae2cc563da543b1305337cce4634d6094bfd39863ed09762765bae35c3
+SHA512:
+  metadata.gz: 0ee1d520c991ea1b015215651b60a94071e73ccdf130b3e1bbf2982b4b72be90c448d3a2d89db82b37132f170bd6428455428f54d20be68c11f57a8b329be368
+  data.tar.gz: b1f58698b7e9cd52e1c94bf170ecdee3bf2ebec81a0a9ed2e954b81d7369f1dd880104306c2067e3b9fccf8d96b4c7ad48a4e45b1e1429bdafef861c465b5c45

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,37 @@
+# Gritz Native
+
+The native gRPC transport adapter for Gritz, using the official `grpc` gem (C-core) and a thread pool. It supports unary, server streaming, client streaming and bidirectional streaming, and provides the real-socket testing helper.
+
+Requires CRuby 3.3 or later and grpc 1.83 or later. Linux and macOS are tested.
+
+```ruby
+require "gritz/native"
+```
+
+The entry point loads `gritz-core` and registers `Gritz::Transport::Native`. The configuration value is `transport :native`. Use [gritz](https://github.com/gritzrpc/gritz) for the default combination and executable. The Fiber adapter `gritz-async` is planned separately.
+
+```ruby
+Gritz::Testing::Server.start(controllers: [GreeterController]) do |server|
+  stub = Helloworld::Greeter::Stub.new(server.address, :this_channel_is_insecure)
+  stub.say_hello(Helloworld::HelloRequest.new(name: "Ruby"))
+end
+```
+
+The helper opens an ephemeral port and stops the server when the block exits. The server currently supports a single process and insecure sockets; use a trusted network or a TLS-terminating proxy. See the [framework documentation](https://github.com/gritzrpc/gritz) for configuration and limitations.
+
+## Development
+
+```sh
+git clone https://github.com/gritzrpc/gritz-native.git
+cd gritz-native
+bundle install
+COVERAGE=1 bundle exec rake
+bundle exec rubocop
+bundle exec rake build
+```
+
+Integration tests contain their own protobuf fixtures and exercise all four RPC forms over real sockets. The [Linux devcontainer](.devcontainer/devcontainer.json) includes grpcurl and ghz. For local core changes, use the Bundler override in [CONTRIBUTING.md](CONTRIBUTING.md). See [SECURITY.md](SECURITY.md) and the [release guide](docs/guides/releasing.md).
+
+## License
+
+[MIT](LICENSE.txt).

data/lib/gritz/native/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Gritz
+  module Native
+    VERSION = "0.1.0"
+  end
+end

data/lib/gritz/native.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "gritz/core"
+require "grpc"
+require "google/rpc/status_pb"
+require "google/protobuf/any_pb"
+require "google/protobuf/well_known_types"
+require_relative "native/version"
+require_relative "transport/native"
+require_relative "transport/native/call"
+require_relative "transport/native/bridge"
+require_relative "transport/native/server"
+require_relative "testing/server"

data/lib/gritz/testing/server.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Gritz
+  module Testing
+    # Starts a single-process server for integration tests.
+    # @api public
+    class Server
+      attr_reader :port, :address, :transport
+
+      def self.start(config = nil, controllers: nil, middleware: nil, logger: Logger.new(File::NULL))
+        config ||= Configuration.new.tap do |settings|
+          settings.workers = 0
+          settings.bind = "127.0.0.1:0"
+        end
+        config.controllers = controllers if controllers
+        config.middleware = middleware if middleware
+        server = new(config, logger:).start
+        return server unless block_given?
+
+        begin
+          yield server
+        ensure
+          server.stop
+        end
+      end
+
+      def initialize(config, logger:)
+        @config = config
+        @logger = logger
+        config.validate_single_process!
+      end
+
+      def start
+        raise ArgumentError, "Testing::Server is already started or stopped" if @started || @stopped
+
+        @started = true
+        begin
+          @config.preload! if @config.preload_app?
+          router = Router.new(controllers: @config.controllers, strict: @config.strict_routes, logger: @logger)
+          dispatcher = Dispatcher.new(router:, middleware: @config.middleware, logger: @logger)
+          @transport = Transport::Native.new(config: @config, dispatcher:, logger: @logger)
+          @lifecycle_started = true
+          @config.run_hooks(:on_worker_boot, 0)
+          @port = transport.bind
+          @address = @config.bind.sub(/:\d+\z/, ":#{port}")
+          transport.start
+          self
+        rescue StandardError
+          stop
+          raise
+        end
+      end
+
+      def stop
+        return if @stopped
+
+        @stopped = true
+        begin
+          transport&.stop(deadline: Time.now + @config.shutdown_timeout)
+        ensure
+          @config.run_hooks(:on_worker_shutdown, 0) if @lifecycle_started
+        end
+      end
+    end
+  end
+end

data/lib/gritz/transport/native/bridge.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Gritz
+  module Transport
+    class Native
+      # Installs handlers with the arities checked by GRPC::RpcDesc.
+      # @api private
+      module Bridge
+        def self.build(service_class, descriptors, adapter)
+          Class.new(service_class) do
+            self.service_name = service_class.service_name
+            descriptors.each do |descriptor|
+              case descriptor.kind
+              when :client_streaming
+                define_method(descriptor.action) do |view|
+                  adapter.dispatch(Call.new(method_descriptor: descriptor, view:, messages: view.each_remote_read))
+                end
+              when :unary
+                define_method(descriptor.action) do |request, view|
+                  adapter.dispatch(Call.new(method_descriptor: descriptor, view:, messages: [request]))
+                end
+              else
+                define_method(descriptor.action) do |request, view|
+                  messages = descriptor.client_streaming? ? request : [request]
+                  Enumerator.new do |writer|
+                    adapter.dispatch(Call.new(method_descriptor: descriptor, view:, messages:, writer:))
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gritz/transport/native/call.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Gritz
+  module Transport
+    class Native
+      # Translates the public grpc views into the Call contract.
+      # @api private
+      class Call
+        include Gritz::Call
+
+        attr_reader :method_descriptor
+
+        def initialize(method_descriptor:, view:, messages:, writer: nil)
+          @method_descriptor = method_descriptor
+          @view = view
+          @messages = messages.to_enum
+          @writer = writer
+        end
+
+        # SingleReqView and MultiReqView both expose these methods in grpc 1.83.
+        # Client streams add each_remote_read; bidi passes a separate request enum.
+        def metadata = @view.metadata
+        # C-core represents an unset deadline as a Time at epoch - 1, not nil.
+        def deadline = @view.deadline.to_r == -1 ? nil : @view.deadline
+        def peer = @view.peer
+        def peer_identity = @view.peer_cert
+        def cancelled? = @view.cancelled?
+        def trailing_metadata = @view.output_metadata
+        def send_initial_metadata(metadata = {}) = @view.send_initial_metadata(metadata)
+        def merge_initial_metadata(metadata = {}) = @view.merge_metadata_to_send(metadata)
+
+        def read
+          @messages.next
+        rescue StopIteration
+          nil
+        end
+
+        def each_message
+          return enum_for(:each_message) unless block_given?
+
+          loop do
+            message = read
+            break unless message
+
+            yield message
+          end
+        end
+
+        def write(message)
+          raise Gritz::Errors::Internal, "RPC does not have a response stream" unless @writer
+
+          @view.send_initial_metadata
+          @writer << message
+        end
+      end
+    end
+  end
+end

data/lib/gritz/transport/native/server.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Gritz
+  module Transport
+    class Native
+      # Adapts RpcServer's lifecycle and rejection callbacks.
+      # @api private
+      class Server < GRPC::RpcServer
+        def initialize(on_rejected:, **)
+          @on_rejected = on_rejected
+          super(**)
+        end
+
+        def available?(rpc)
+          result = super
+          @on_rejected.call unless result
+          result
+        end
+
+        def stop(deadline:)
+          # grpc 1.83's stop takes no deadline and reads @poll_period instead.
+          # Set its relative grace from the caller's absolute shutdown deadline.
+          @poll_period = [deadline - Time.now, 0].max
+          super()
+        end
+
+        def close_unstarted
+          return unless running_state == :not_started
+
+          @pool.stop
+          # C-core requires shutdown even when a bound listener was never started.
+          @server.shutdown_and_notify(Time.now)
+          @server.close
+        end
+      end
+    end
+  end
+end

data/lib/gritz/transport/native.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "set" # rubocop:disable Lint/RedundantRequireStatement -- required by Ruby 3.3
+require "securerandom"
+
+module Gritz
+  module Transport
+    # Runs generated services through Gritz's transport-independent dispatcher.
+    # @api public
+    class Native
+      def self.capabilities = Set[:unary, :client_streaming, :server_streaming, :bidi, :reuseport].freeze
+
+      def initialize(config:, dispatcher:, logger:)
+        @config = config
+        @dispatcher = dispatcher
+        @logger = logger
+        @lock = Mutex.new
+        @inflight = {}.compare_by_identity
+        @requests_total = @rejected_total = 0
+      end
+
+      # Creates C-core resources only when binding, so construction is safe before fork.
+      # @return [Integer] the port selected by C-core
+      def bind(listener_spec = @config.bind)
+        raise ArgumentError, "transport is already bound" if @server
+        raise ArgumentError, "TLS is not available in this version" unless @config.tls.empty?
+        raise ArgumentError, "at least one controller must be registered" if @dispatcher.router.routes.empty?
+
+        created_server = @server = Server.new(
+          pool_size: @config.threads,
+          # grpc 1.83 accepts but ignores this value: busy pools reject immediately.
+          max_waiting_requests: @config.max_waiting_requests,
+          poll_period: @config.shutdown_timeout,
+          pool_keep_alive: 0,
+          server_args: @config.server_args,
+          on_rejected: -> { @lock.synchronize { @rejected_total += 1 } }
+        )
+        @dispatcher.router.routes.values.group_by(&:service_class).each do |service_class, descriptors|
+          @server.handle(Bridge.build(service_class, descriptors, self))
+        end
+        @port = @server.add_http2_port(listener_spec, :this_port_is_insecure)
+        raise ArgumentError, "could not bind #{listener_spec}" unless @port.positive?
+
+        @port
+      rescue StandardError
+        created_server&.close_unstarted
+        @server = nil if created_server
+        raise
+      end
+
+      def start
+        raise ArgumentError, "bind must be called before start" unless @server
+        raise ArgumentError, "transport is already started" if @thread
+
+        @thread = Thread.new { @server.run }
+        return self if @server.wait_till_running(5)
+
+        @thread.value unless @thread.alive?
+        kill
+        raise "gRPC server did not start within 5 seconds"
+      rescue StandardError
+        @server&.close_unstarted
+        raise
+      end
+
+      def wait = @thread&.value
+      def running? = @thread&.alive? && @server.running?
+
+      def stop(deadline:)
+        unless @thread
+          @server&.close_unstarted
+          @server = nil
+          return
+        end
+
+        @server.stop(deadline:)
+        wait
+      end
+
+      def kill = stop(deadline: Time.now)
+
+      def stats
+        @lock.synchronize do
+          oldest = @inflight.values.min
+          {
+            inflight: @inflight.size, busy: @inflight.size, capacity: @config.threads,
+            rejected_total: @rejected_total, requests_total: @requests_total,
+            oldest_inflight_age: oldest ? Process.clock_gettime(Process::CLOCK_MONOTONIC) - oldest : 0
+          }
+        end
+      end
+
+      # @api private
+      def dispatch(call)
+        @lock.synchronize do
+          @inflight[call] = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @requests_total += 1
+        end
+        @dispatcher.call(call)
+      rescue Gritz::Error => e
+        raise status_exception(call, e)
+      ensure
+        @lock.synchronize { @inflight.delete(call) }
+      end
+
+      private
+
+      def status_exception(call, error)
+        metadata = call.trailing_metadata.merge(error.metadata)
+        unless error.details.empty?
+          details = error.details.map do |detail|
+            detail.is_a?(Google::Protobuf::Any) ? detail : Google::Protobuf::Any.pack(detail)
+          end
+          status = Google::Rpc::Status.new(code: error.grpc_code, message: error.message, details:)
+          metadata["grpc-status-details-bin"] = Google::Rpc::Status.encode(status)
+        end
+        GRPC::BadStatus.new_status_exception(error.grpc_code, error.message, metadata)
+      rescue StandardError => e
+        error_id = SecureRandom.uuid
+        @logger.error("#{error_id}: #{e.full_message}")
+        GRPC::Internal.new("internal error (#{error_id})", { "error-id" => error_id })
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: gritz-native
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: googleapis-common-protos-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.20'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.20'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: gritz-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: grpc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.83'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.83'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: The native gRPC adapter for Gritz, using the official grpc gem and a
+  thread pool.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/gritz/native.rb
+- lib/gritz/native/version.rb
+- lib/gritz/testing/server.rb
+- lib/gritz/transport/native.rb
+- lib/gritz/transport/native/bridge.rb
+- lib/gritz/transport/native/call.rb
+- lib/gritz/transport/native/server.rb
+homepage: https://github.com/gritzrpc/gritz-native
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/gritzrpc/gritz-native
+  changelog_uri: https://github.com/gritzrpc/gritz-native/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: gRPC C-core transport for Gritz
+test_files: []