connectrpc-falcon 0.1.0

data/lib/connectrpc/falcon/rack_guard.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "English"
+
+module ConnectRPC
+  module Falcon
+    class RackGuard
+      class Unsupported < StandardError; end
+      private_constant :Unsupported
+
+      class Request < SimpleDelegator
+        def initialize(request, reject)
+          super(request)
+          @reject = reject
+        end
+
+        def hijack? = false
+        def hijack! = @reject.call
+      end
+      private_constant :Request
+
+      def initialize(app)
+        raise ArgumentError, "rack_app must be callable" unless app.respond_to?(:call)
+
+        @app = app
+      end
+
+      def call(env)
+        attempted = false
+        reject = lambda do
+          attempted = true
+          raise Unsupported, "Socket ownership transfer is unsupported"
+        end
+        env["rack.hijack?"] = false
+        env["rack.hijack"] = reject
+        env["protocol.http.request"] = Request.new(env["protocol.http.request"], reject)
+        response = @app.call(env)
+        status, headers, body = response
+        original = guarded_body(body)
+        if attempted || status == 101 || headers.keys.any? do |key|
+             %w[rack.hijack rack.protocol upgrade].include?(key.downcase)
+           end
+          return rejected
+        end
+
+        response = [status, headers, completing_body(env, status, headers, original)]
+        handed_off = true
+        response
+      rescue Unsupported
+        rejected
+      ensure
+        original&.close($ERROR_INFO) unless handed_off
+      end
+
+      private
+
+      def guarded_body(body)
+        if body.is_a?(::Protocol::HTTP::Body::Readable)
+          CloseOnce.new(body)
+        elsif body
+          RackBody.new(body)
+        end
+      end
+
+      def completing_body(env, status, headers, original)
+        # Original-body ownership is needed even without callbacks: upstream
+        # array conversion retains only the array's contents.
+        callbacks = env["rack.response_finished"] || []
+        callback = ::Protocol::Rack::Body.completion_callback(callbacks, env, status, headers)
+        env["rack.response_finished"] = []
+        CompletionBody.new(callback, original) do
+          ::Protocol::Rack::Body.wrap(env, status, headers.dup, original, env["protocol.http.request"].body)
+        end
+      end
+
+      def rejected
+        [501, { "content-type" => "text/plain" }, ["Socket ownership transfer is unsupported"]]
+      end
+    end
+    private_constant :RackGuard
+
+    class RackBody < SimpleDelegator
+      def close(*)
+        return if @closed
+
+        @closed = true
+        __getobj__.close if __getobj__.respond_to?(:close)
+      end
+    end
+    private_constant :RackBody
+
+    class CompletionBody < ::Protocol::HTTP::Body::Wrapper
+      def initialize(callback, original)
+        super(::Protocol::HTTP::Body::Buffered.wrap([]))
+        @callback = callback
+        @original = original
+        begin
+          @body = yield || @body
+          converted = true
+        ensure
+          close($ERROR_INFO) unless converted
+        end
+      end
+
+      def rewindable? = false
+      def rewind = false
+
+      # The Rack adapter closes a rejected tuple without passing its exception.
+      def close(error = $ERROR_INFO)
+        return if @closed
+
+        @closed = true
+        begin
+          @callback.call(error)
+        ensure
+          begin
+            super
+          ensure
+            @original&.close(error)
+          end
+        end
+      end
+    end
+    private_constant :CompletionBody
+
+    class ListenerApplication
+      def initialize(application, scheme)
+        @application = application
+        @scheme = scheme
+      end
+
+      def publication?(request) = @application.send(:publication?, request)
+      def http1_streaming_route?(request) = @application.send(:http1_streaming_route?, request)
+      private :publication?, :http1_streaming_route?
+      def admission_response(request) = @application.admission_response(request)
+
+      def call(request, lifecycle: nil, publication: nil, resource: nil)
+        request.scheme ||= @scheme
+        if request.method == "CONNECT" || request.protocol || request.headers["upgrade"]
+          lifecycle&.host_rejected!
+          return ::Protocol::HTTP::Response[501, {}, nil]
+        end
+
+        response = if publication
+                     publication.on_publish { |head| head.body = CloseOnce.new(head.body) if head&.body }
+                     @application.call_with_publication(request, lifecycle: lifecycle, publication: publication,
+                                                                 resource: resource)
+                   else
+                     @application.call(request, lifecycle: lifecycle)
+                   end
+        return if publication && response.nil?
+
+        if response.nil? || response.status == 101 || response.protocol
+          response&.close
+          return ::Protocol::HTTP::Response[501, {}, nil]
+        end
+        response.body = CloseOnce.new(response.body) if response.body
+        response
+      end
+    end
+    private_constant :ListenerApplication
+
+    # Upstream write ensure and cancellation can both close a body. Mark before
+    # entering callbacks so a blocked rack.response_finished cannot reenter.
+    class CloseOnce < ::Protocol::HTTP::Body::Wrapper
+      def close(error = nil)
+        return if @closed
+
+        @closed = true
+        super
+      end
+    end
+    private_constant :CloseOnce
+  end
+end

data/lib/connectrpc/falcon/server.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  module Falcon
+    class Server < ::Falcon::Server
+      def initialize(server:, endpoint:, rack_app: nil, cache: false, tls: nil, tls_provider: nil,
+                     utilization_registry: nil, max_connections: 128, max_requests: 128,
+                     handshake_timeout: 10, idle_timeout: 60, refresh_interval: 60,
+                     refresh_jitter: 0.1, refresh_timeout: 10, on_tls_error: nil)
+        raise ArgumentError, "cache must be true or false" unless [true, false].include?(cache)
+
+        configured = if endpoint.is_a?(::IO::Endpoint::BoundEndpoint)
+                       endpoint.endpoint
+                     else
+                       endpoint
+                     end
+        unless configured.is_a?(Endpoint) && (configured.scheme == "https") == (!tls.nil? || !tls_provider.nil?)
+          raise ArgumentError, "Listener scheme and TLS configuration must agree"
+        end
+
+        fallback = ::Falcon::Server.rack_middleware(RackGuard.new(rack_app), cache: cache) unless rack_app.nil?
+        application = ::ConnectRPC::Async::Application.new(server: server, fallback: fallback)
+        listener_application = ListenerApplication.new(application, configured.scheme)
+        @listener_application = listener_application
+        utilization_registry ||= ::Async::Utilization::Registry.new
+        @connection_total = utilization_registry.metric(:connections_total)
+        @connection_active = utilization_registry.metric(:connections_active)
+        @request_total = utilization_registry.metric(:requests_total)
+        @request_active = utilization_registry.metric(:requests_active)
+        @session = ::ConnectRPC::Async::ServerSession.new(
+          application: self, lifecycle_factory: application.method(:start_call),
+          tls: tls, tls_provider: tls_provider,
+          max_connections: max_connections, max_requests: max_requests,
+          handshake_timeout: handshake_timeout, idle_timeout: idle_timeout,
+          refresh_interval: refresh_interval, refresh_jitter: refresh_jitter,
+          refresh_timeout: refresh_timeout, on_tls_error: on_tls_error,
+          alpn_protocols: %w[h2 http/1.1], http1: HTTP1Resource.method(:new),
+          stop_accepting: method(:stop_accepting), on_request_rejected: -> { @request_total.increment }
+        )
+        # Preserve parent-bound descriptors while installing a worker-local
+        # accept wrapper through IO::Endpoint's supported wrapper option.
+        @accept_wrapper = AcceptWrapper.new(@session, on_reject: -> { @connection_total.increment })
+        endpoint = @owned_bound = endpoint.bound unless endpoint.is_a?(::IO::Endpoint::BoundEndpoint)
+        wrapped = endpoint.with(wrapper: @accept_wrapper)
+        super(listener_application, wrapped, protocol: configured.protocol, scheme: configured.scheme,
+                                             utilization_registry: utilization_registry)
+      rescue StandardError
+        @session&.abort
+        raise
+      end
+
+      def run
+        @session.start
+        @run_task = super
+      end
+
+      def accept(peer, _address, **)
+        @connection_total.increment
+        @session.schedule { @connection_active.track { peer.wait_closed } }
+        peer.serve
+      end
+
+      def close(grace: 5)
+        @session.close(grace: grace)
+      end
+
+      def abort = @session.abort
+
+      def publication?(request) = @listener_application.send(:publication?, request)
+      def http1_streaming_route?(request) = @listener_application.send(:http1_streaming_route?, request)
+      private :publication?, :http1_streaming_route?
+      def admission_response(request) = @listener_application.admission_response(request)
+
+      def call_with_publication(request, publication:, lifecycle: nil, resource: nil)
+        publication.on_publish do |response|
+          response.body = ::Falcon::Body::RequestFinished.new(response.body, @request_active) if response&.body
+        end
+        call_native(request, lifecycle: lifecycle, publication: publication, resource: resource)
+      end
+
+      def call(request, lifecycle: nil)
+        call_native(request, lifecycle: lifecycle)
+      end
+
+      def call_native(request, lifecycle: nil, publication: nil, resource: nil)
+        @request_total.increment
+        @request_active.increment
+        response = @listener_application.call(request, lifecycle: lifecycle, publication: publication,
+                                                       resource: resource)
+        if response&.body && !publication
+          # Empty bodies can still own completion callbacks. Preserve their
+          # wire length while retaining the metric until close finishes.
+          response.body = ::Falcon::Body::RequestFinished.new(response.body, @request_active)
+          wrapped = true
+        end
+        response
+      ensure
+        retained = publication && (publication.published? || response&.body)
+        @request_active.decrement unless wrapped || retained
+      end
+
+      private :call_native
+
+      def reload_tls(**) = @session.reload_tls(**)
+      def refresh_tls = @session.refresh_tls
+      def drain_tls(**) = @session.drain_tls(**)
+      def tls_generation = @session.tls_generation
+      def tls_status = @session.tls_status
+      def peer_certificate = @session.peer_certificate
+
+      private
+
+      def stop_accepting
+        # Stop this worker's accept tasks after session validation. Accepted
+        # peers have an independent lifetime; parent-bound listeners stay open.
+        @accept_wrapper&.stop
+        @owned_bound&.close
+      end
+    end
+  end
+end

data/lib/connectrpc/falcon/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ConnectRPC
+  module Falcon
+    VERSION = "0.1.0" # x-release-please-version
+  end
+end

data/lib/connectrpc/falcon.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "connectrpc/async"
+require_relative "falcon/version"
+require "falcon/server"
+require "falcon/environment/server"
+require "async/http/endpoint"
+require "io/endpoint/wrapper"
+require "delegate"
+
+module ConnectRPC
+  # Explicit optional listener. Falcon owns process supervision and accepts.
+  module Falcon
+  end
+end
+
+require_relative "falcon/endpoint"
+require_relative "falcon/rack_guard"
+require_relative "falcon/http1"
+require_relative "falcon/server"
+require_relative "falcon/environment"

data/rbs/async_service_0_25/service.rbs

@@ -0,0 +1,29 @@
+# Explicit opt-in for Falcon 0.57.0 / async-service 0.25.0 service configuration.
+# These are the documented ConnectRPC DSL forms, not general method_missing.
+module Async
+  module Service
+    class Loader
+      def service: (?String?) { () [self: Environment::Builder] -> void } -> void
+    end
+    class Environment
+      class Builder < BasicObject
+        def include: (Module) -> void
+        def url: (String) -> void
+               | () { () [self: ConnectRPC::Falcon::Environment] -> String } -> void
+        def count: (Integer) -> void
+                 | () { () [self: ConnectRPC::Falcon::Environment] -> Integer } -> void
+        def prepare!: () { (Object) [self: ConnectRPC::Falcon::Environment] -> void } -> void
+        def connectrpc_server: (ConnectRPC::Server) -> void
+                            | () { () [self: ConnectRPC::Falcon::Environment] -> ConnectRPC::Server } -> void
+        def rack_app: ((ConnectRPC::Falcon::_RackFallback | ^(Hash[String, Object]) -> ConnectRPC::Falcon::rack_response)?) -> void
+                    | () { () [self: ConnectRPC::Falcon::Environment] -> (ConnectRPC::Falcon::_RackFallback | ^(Hash[String, Object]) -> ConnectRPC::Falcon::rack_response)? } -> void
+        def tls: (ConnectRPC::Async::tls?) -> void
+               | () { () [self: ConnectRPC::Falcon::Environment] -> ConnectRPC::Async::tls? } -> void
+        def tls_provider: ((ConnectRPC::Async::_TLSProvider | ^() -> ConnectRPC::Async::tls_snapshot)?) -> void
+                        | () { () [self: ConnectRPC::Falcon::Environment] -> (ConnectRPC::Async::_TLSProvider | ^() -> ConnectRPC::Async::tls_snapshot)? } -> void
+        def server_options: (ConnectRPC::Falcon::server_options) -> void
+                          | () { () [self: ConnectRPC::Falcon::Environment] -> ConnectRPC::Falcon::server_options } -> void
+      end
+    end
+  end
+end

data/sig/connectrpc-falcon.rbs

@@ -0,0 +1,66 @@
+module ConnectRPC
+  module Falcon
+    VERSION: String
+    # Endpoint and task/socket objects expose only their consumed capabilities.
+    interface _BoundEndpoint
+      def endpoint: () -> Endpoint
+      def close: () -> void
+    end
+    class Endpoint
+      def self.parse: (String, ?Object?, **Object) -> Endpoint
+      def initialize: (URI::Generic, ?Object?, **Object) -> void
+      def scheme: () -> String
+      def bound: () -> _BoundEndpoint
+      def with: (**Object) -> Endpoint
+    end
+    # Keep this small Rack capability local: Falcon does not depend on the
+    # connectrpc-rack gem. Its structural shapes also accept Rack::_App values.
+    type rack_headers = Hash[String, String | Array[String]]
+    type rack_response = [Integer, rack_headers, _RackBody | _RackCallableBody]
+    type server_options = { ?cache: bool, ?max_connections: Integer, ?max_requests: Integer, ?handshake_timeout: Numeric, ?idle_timeout: Numeric?, ?refresh_interval: Numeric, ?refresh_jitter: Numeric, ?refresh_timeout: Numeric, ?on_tls_error: (Async::_TLSErrorHandler | ^(Async::tls_event) -> void)? }
+    interface _RackBody
+      def each: () { (String) -> void } -> void
+    end
+    interface _RackStream
+      def read: (?nil, ?String?) -> String
+              | (Integer?, ?String?) -> String?
+      def write: (String) -> Integer
+      # Protocol::HTTP returns a byte count; ordinary IO returns itself.
+      def <<: (String) -> (Integer | self)
+      def flush: () -> void
+      def close: () -> void
+      def close_read: () -> void
+      def close_write: () -> void
+      def closed?: () -> bool
+    end
+    interface _RackCallableBody
+      def call: (_RackStream) -> void
+    end
+    interface _RackFallback
+      def call: (Hash[String, Object]) -> rack_response
+    end
+    class Server
+      def initialize: (server: ConnectRPC::Server, endpoint: Endpoint | _BoundEndpoint, ?rack_app: (_RackFallback | ^(Hash[String, Object]) -> rack_response)?, ?cache: bool, ?tls: Async::tls?, ?tls_provider: (Async::_TLSProvider | ^() -> Async::tls_snapshot)?, ?utilization_registry: Object?, ?max_connections: Integer, ?max_requests: Integer, ?handshake_timeout: Numeric, ?idle_timeout: Numeric?, ?refresh_interval: Numeric, ?refresh_jitter: Numeric, ?refresh_timeout: Numeric, ?on_tls_error: (Async::_TLSErrorHandler | ^(Async::tls_event) -> void)?) -> void
+      def run: () -> Async::_Task
+      def call: (Async::_Request, ?lifecycle: Instrumentation::Handle?) -> Async::_Response?
+      def close: (?grace: Numeric) -> bool?
+      def abort: () -> Async::ServerSession
+      def reload_tls: (certificate_chain: Array[String], private_key: String, client_ca: Array[String]?) -> Integer
+      def refresh_tls: () -> Integer
+      def drain_tls: (?grace: Numeric) -> bool
+      def tls_generation: () -> Integer?
+      def tls_status: () -> Async::tls_status
+      def peer_certificate: () -> OpenSSL::X509::Certificate?
+    end
+    module Environment
+      def service_class: () -> Class
+      def endpoint: () -> Endpoint
+      def rack_app: () -> (_RackFallback | ^(Hash[String, Object]) -> rack_response)?
+      def tls: () -> Async::tls?
+      def tls_provider: () -> (Async::_TLSProvider | ^() -> Async::tls_snapshot)?
+      def server_options: () -> server_options
+      def connectrpc_server: () -> ConnectRPC::Server
+      def make_server: (Endpoint | _BoundEndpoint) -> Server
+    end
+  end
+end

data/sig/manifest.yaml

@@ -0,0 +1,2 @@
+dependencies:
+  - name: connectrpc-async

metadata

@@ -0,0 +1,151 @@
+--- !ruby/object:Gem::Specification
+name: connectrpc-falcon
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- jimeh
+bindir: bin
+cert_chain: []
+date: 2026-11-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: connectrpc-async
+  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: falcon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.57.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.57.0
+- !ruby/object:Gem::Dependency
+  name: protocol-rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.23.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.23.0
+- !ruby/object:Gem::Dependency
+  name: async-service
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.25.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.25.0
+- !ruby/object:Gem::Dependency
+  name: async-container
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.38.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.38.0
+- !ruby/object:Gem::Dependency
+  name: async-utilization
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+- !ruby/object:Gem::Dependency
+  name: protocol-http1
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.41.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.41.1
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- examples/falcon.rb
+- lib/connectrpc/falcon.rb
+- lib/connectrpc/falcon/completion_join.rb
+- lib/connectrpc/falcon/endpoint.rb
+- lib/connectrpc/falcon/environment.rb
+- lib/connectrpc/falcon/http1.rb
+- lib/connectrpc/falcon/rack_guard.rb
+- lib/connectrpc/falcon/server.rb
+- lib/connectrpc/falcon/version.rb
+- rbs/async_service_0_25/service.rbs
+- sig/connectrpc-falcon.rbs
+- sig/manifest.yaml
+homepage: https://github.com/jimeh/connectrpc-ruby
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Optional Falcon worker hosting for ConnectRPC unary
+test_files: []