raptor 0.7.0 → 0.8.0

data/lib/raptor/http2.rb

@@ -6,7 +6,7 @@ require "stringio"
 require "atomic-ruby/atom"
 require "rack"
 
-require_relative "request"
+require_relative "http"
 require_relative "raptor_http2"
 
 module Raptor
@@ -27,12 +27,17 @@ module Raptor
       IDLE = :idle
 
       # @rbs @state: Atom
+      # @rbs @write_timeout: Integer
 
       # Creates a new Writer.
       #
-      # @rbs () -> void
-      def initialize
+      # @param write_timeout [Integer] per-write socket timeout passed through to {Http.socket_write}
+      # @return [void]
+      #
+      # @rbs (write_timeout: Integer) -> void
+      def initialize(write_timeout:)
         @state = Atom.new(IDLE)
+        @write_timeout = write_timeout
       end
 
       # Writes frames to the socket, coordinating with concurrent writers
@@ -69,7 +74,7 @@ module Raptor
           break if pending.empty?
 
           pending.each do |frame|
-            Request.socket_write(socket, frame) rescue nil
+            Http.socket_write(socket, frame, timeout: @write_timeout) rescue nil
           end
         end
       end
@@ -78,7 +83,7 @@ module Raptor
     # Per-connection outbound flow-control accounting.
     #
     # Tracks the peer's connection-level and per-stream receive windows so
-    # outbound DATA frames respect RFC 7540 §5.2. Threads dispatching stream
+    # outbound DATA frames respect RFC 7540 section 5.2. Threads dispatching stream
     # responses call `acquire` to reserve send capacity; threads applying
     # inbound WINDOW_UPDATE or SETTINGS frames call the mutating methods to
     # replenish it. The connection window and per-stream windows live in
@@ -146,9 +151,9 @@ module Raptor
           end
 
           if granted > 0
-            @stream_windows.swap do |s|
-              current = s[stream_id] || initial
-              s.merge(stream_id => current - granted)
+            @stream_windows.swap do |windows|
+              current = windows[stream_id] || initial
+              windows.merge(stream_id => current - granted)
             end
             return granted
           end
@@ -178,14 +183,14 @@ module Raptor
       # @rbs (Integer stream_id, Integer increment) -> void
       def add_stream_window(stream_id, increment)
         initial = @initial_stream_window.value
-        @stream_windows.swap do |s|
-          current = s[stream_id] || initial
-          s.merge(stream_id => current + increment)
+        @stream_windows.swap do |windows|
+          current = windows[stream_id] || initial
+          windows.merge(stream_id => current + increment)
         end
       end
 
       # Updates the peer's `SETTINGS_INITIAL_WINDOW_SIZE`. Shifts every
-      # existing stream window by the delta as required by RFC 7540 §6.9.2.
+      # existing stream window by the delta as required by RFC 7540 section 6.9.2.
       #
       # @param new_size [Integer] the peer's new initial window size
       # @return [void]
@@ -197,8 +202,8 @@ module Raptor
         delta = new_size - old
         return if delta.zero?
 
-        @stream_windows.swap do |s|
-          s.transform_values { |size| size + delta }
+        @stream_windows.swap do |windows|
+          windows.transform_values { |size| size + delta }
         end
       end
 
@@ -213,12 +218,12 @@ module Raptor
       def discard_stream(stream_id)
         return unless @stream_windows.value.key?(stream_id)
 
-        @stream_windows.swap do |s|
-          next s unless s.key?(stream_id)
+        @stream_windows.swap do |windows|
+          next windows unless windows.key?(stream_id)
 
-          new = s.dup
-          new.delete(stream_id)
-          new
+          pruned = windows.dup
+          pruned.delete(stream_id)
+          pruned
         end
       end
     end
@@ -244,34 +249,51 @@ module Raptor
 
     # @rbs @app: ^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped]
     # @rbs @server_port: Integer
+    # @rbs @write_timeout: Integer
+    # @rbs @access_log_io: IO?
     # @rbs @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
+    # @rbs @initial_settings_frame: String
+
+    # The initial server SETTINGS frame sent on every new HTTP/2 connection.
+    #
+    # @return [String] the encoded SETTINGS frame
+    attr_reader :initial_settings_frame
 
     # Creates a new Http2 handler.
     #
     # @param app [#call] the Rack application to dispatch requests to
     # @param server_port [Integer] port number used to populate SERVER_PORT in the Rack env
+    # @param connection_options [Hash] per-connection settings shared across protocols
+    # @option connection_options [Integer] :write_timeout per-write socket timeout in seconds
+    # @param http2_options [Hash] HTTP/2-specific settings
+    # @option http2_options [Integer] :max_concurrent_streams maximum HTTP/2 concurrent streams per connection
+    # @param access_log_io [IO, nil] IO to write Common Log Format access entries to, or nil to disable
     # @param on_error [#call, nil] callback invoked with (env, exception) when the Rack app raises
     # @return [void]
     #
-    # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, Integer server_port, ?on_error: ^(Hash[String, untyped]?, Exception) -> void | nil) -> void
-    def initialize(app, server_port, on_error: nil)
+    # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, Integer server_port, ?connection_options: Hash[Symbol, untyped], ?http2_options: Hash[Symbol, untyped], ?access_log_io: IO?, ?on_error: ^(Hash[String, untyped]?, Exception) -> void | nil) -> void
+    def initialize(app, server_port, connection_options: {}, http2_options: {}, access_log_io: nil, on_error: nil)
       @app = app
       @server_port = server_port
+      @write_timeout = connection_options[:write_timeout] || Http::WRITE_TIMEOUT
+      @access_log_io = access_log_io
       @on_error = on_error
-    end
 
-    # Builds the initial server SETTINGS frame to send on connection establishment.
-    #
-    # @return [String] the encoded SETTINGS frame
-    #
-    # @rbs () -> String
-    def self.build_server_settings_frame
       parser = Http2Parser.new
       settings_payload = parser.build_settings(
-        max_concurrent_streams: 100,
+        max_concurrent_streams: http2_options[:max_concurrent_streams],
         initial_window_size: DEFAULT_WINDOW_SIZE
       )
-      parser.build_frame(:settings, 0, 0, settings_payload)
+      @initial_settings_frame = parser.build_frame(:settings, 0, 0, settings_payload).freeze
+    end
+
+    # Creates a per-connection {Writer} configured with the handler's write timeout.
+    #
+    # @return [Writer] a new per-connection frame writer
+    #
+    # @rbs () -> Writer
+    def create_writer
+      Writer.new(write_timeout: @write_timeout)
     end
 
     # Processes HTTP/2 frames from the connection buffer.
@@ -626,7 +648,8 @@ module Raptor
       env = build_rack_env(headers, body, remote_addr: remote_addr)
       status, response_headers, response_body = @app.call(env)
 
-      write_http2_response(socket, writer, flow_control, stream_id, status, response_headers, response_body)
+      response_size = write_http2_response(socket, writer, flow_control, stream_id, status, response_headers, response_body)
+      write_access_log(env, status, response_size, remote_addr) if @access_log_io
     rescue => error
       write_http2_error_response(socket, writer, stream_id)
 
@@ -652,9 +675,9 @@ module Raptor
     # @param status [Integer] HTTP status code
     # @param headers [Hash] response headers from the Rack application
     # @param body [Object] response body responding to each
-    # @return [void]
+    # @return [String] the response body size in bytes
     #
-    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> void
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> String
     def write_http2_response(socket, writer, flow_control, stream_id, status, headers, body)
       parser = Http2Parser.new
 
@@ -673,11 +696,16 @@ module Raptor
 
       encoded_headers = parser.encode_headers(header_pairs)
       body_chunks = []
-      body.each { |chunk| body_chunks << chunk unless chunk.empty? }
+      body_bytes = 0
+      body.each do |chunk|
+        next if chunk.empty?
+        body_chunks << chunk
+        body_bytes += chunk.bytesize
+      end
 
       if body_chunks.empty?
         writer.write_frames(socket, [parser.build_frame(:headers, FLAG_END_STREAM | FLAG_END_HEADERS, stream_id, encoded_headers)])
-        return
+        return "0"
       end
 
       frames = [parser.build_frame(:headers, FLAG_END_HEADERS, stream_id, encoded_headers)]
@@ -697,6 +725,7 @@ module Raptor
       end
 
       writer.write_frames(socket, frames)
+      body_bytes.to_s
     end
 
     # Writes a 500 error response as HTTP/2 frames.
@@ -717,6 +746,20 @@ module Raptor
       )
     end
 
+    # Instance-level wrapper around {Http.write_access_log} that routes to
+    # the configured `@access_log_io`.
+    #
+    # @param env [Hash] the Rack environment
+    # @param status [Integer] the response status code
+    # @param size [String] the response body size in bytes, or `-` if unknown
+    # @param remote_addr [String] the client IP address
+    # @return [void]
+    #
+    # @rbs (Hash[String, untyped] env, Integer status, String size, String remote_addr) -> void
+    def write_access_log(env, status, size, remote_addr)
+      Http.write_access_log(@access_log_io, env, status, size, remote_addr)
+    end
+
     # Builds a Rack environment hash from HTTP/2 headers and body.
     #
     # Translates HTTP/2 pseudo-headers into Rack-compatible environment keys
@@ -743,9 +786,9 @@ module Raptor
           when ":authority" then env[Rack::HTTP_HOST] = value
           end
         elsif name == "content-type"
-          env["CONTENT_TYPE"] = value
+          env[Http::CONTENT_TYPE] = value
         elsif name == "content-length"
-          env["CONTENT_LENGTH"] = value
+          env[Http::CONTENT_LENGTH] = value
         else
           rack_key = "HTTP_#{name.upcase.tr("-", "_")}"
           env[rack_key] = value
@@ -763,11 +806,13 @@ module Raptor
       env[Rack::PATH_INFO] = "" unless env.key?(Rack::PATH_INFO)
       env[Rack::QUERY_STRING] = "" unless env.key?(Rack::QUERY_STRING)
 
-      if body.bytesize.positive? && !env.key?("CONTENT_LENGTH")
-        env["CONTENT_LENGTH"] = body.bytesize.to_s
+      if body.bytesize.positive? && !env.key?(Http::CONTENT_LENGTH)
+        env[Http::CONTENT_LENGTH] = body.bytesize.to_s
       end
 
-      env["REMOTE_ADDR"] = remote_addr
+      env[Http::REMOTE_ADDR] = remote_addr
+      env[Http::SERVER_SOFTWARE] = Http::SERVER_SOFTWARE_VALUE
+      env[Http::HTTP_VERSION] = SERVER_PROTOCOL
 
       populate_server_name_and_port(env)
 

data/lib/raptor/reactor.rb

@@ -14,10 +14,12 @@ module Raptor
   # the server uses for backpressure control to prevent overload.
   #
   # @example
-  #   reactor = Reactor.new(ractor_pool, thread_pool, client_options: {
-  #     first_data_timeout: 30,
-  #     chunk_data_timeout: 10
-  #   })
+  #   reactor = Reactor.new(
+  #     ractor_pool,
+  #     thread_pool,
+  #     connection_options: { first_data_timeout: 30, chunk_data_timeout: 10 },
+  #     http1_options: { persistent_data_timeout: 65 }
+  #   )
   #   reactor.run
   #   reactor.add(id: client.object_id, socket: client)
   #   # ... later
@@ -68,7 +70,9 @@ module Raptor
 
     # @rbs @thread_pool: untyped
     # @rbs @ractor_pool: untyped
-    # @rbs @client_options: Hash[Symbol, Integer]
+    # @rbs @first_data_timeout: Integer
+    # @rbs @chunk_data_timeout: Integer
+    # @rbs @persistent_data_timeout: Integer
     # @rbs @selector: NIO::Selector
     # @rbs @queue: Queue[TCPSocket]
     # @rbs @timeouts: RedBlackTree[TimeoutClient]
@@ -82,17 +86,20 @@ module Raptor
     #
     # @param ractor_pool [RactorPool] ractor pool for HTTP parsing
     # @param thread_pool [AtomicThreadPool] thread pool for application processing
-    # @param client_options [Hash] timeout configuration options
-    # @option client_options [Integer] :first_data_timeout timeout for initial data
-    # @option client_options [Integer] :chunk_data_timeout timeout for subsequent chunks
-    # @option client_options [Integer] :persistent_data_timeout timeout for keep-alive connections
+    # @param connection_options [Hash] per-connection timeout configuration
+    # @option connection_options [Integer] :first_data_timeout timeout for initial data
+    # @option connection_options [Integer] :chunk_data_timeout timeout for subsequent chunks
+    # @param http1_options [Hash] HTTP/1.1-specific configuration
+    # @option http1_options [Integer] :persistent_data_timeout timeout for keep-alive idle connections
     # @return [void]
     #
-    # @rbs (untyped ractor_pool, untyped thread_pool, client_options: Hash[Symbol, Integer]) -> void
-    def initialize(ractor_pool, thread_pool, client_options:)
+    # @rbs (untyped ractor_pool, untyped thread_pool, connection_options: Hash[Symbol, untyped], http1_options: Hash[Symbol, untyped]) -> void
+    def initialize(ractor_pool, thread_pool, connection_options:, http1_options:)
       @ractor_pool = ractor_pool
       @thread_pool = thread_pool
-      @client_options = client_options
+      @first_data_timeout = connection_options[:first_data_timeout]
+      @chunk_data_timeout = connection_options[:chunk_data_timeout]
+      @persistent_data_timeout = http1_options[:persistent_data_timeout]
 
       @selector = NIO::Selector.new
       @queue = Queue.new
@@ -354,11 +361,11 @@ module Raptor
       state = @socket_to_state[socket]
       client = TimeoutClient.new(state)
       timeout = if state[:persisted]
-        @client_options[:persistent_data_timeout]
+        @persistent_data_timeout
       elsif first_data_received?(state)
-        @client_options[:chunk_data_timeout]
+        @chunk_data_timeout
       else
-        @client_options[:first_data_timeout]
+        @first_data_timeout
       end
       client.timeout_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
       @timeouts << client

data/lib/raptor/server.rb

@@ -19,9 +19,10 @@ module Raptor
   #
   # @example
   #   binder = Binder.new(["tcp://0.0.0.0:3000"])
-  #   reactor = Reactor.new(ractor_pool, thread_pool, client_options: {})
-  #   request = Request.new(app, 3000)
-  #   server = Server.new(binder, reactor, thread_pool, request, client_options: { first_data_timeout: 30 })
+  #   reactor = Reactor.new(ractor_pool, thread_pool, connection_options: {}, http1_options: {})
+  #   http1 = Http1.new(app, 3000)
+  #   http2 = Http2.new(app, 3000)
+  #   server = Server.new(binder, reactor, thread_pool, http1, http2, connection_options: { first_data_timeout: 30 })
   #   server.run
   #   # ... later
   #   server.shutdown
@@ -40,8 +41,10 @@ module Raptor
     # @rbs @binder: Binder
     # @rbs @reactor: Reactor
     # @rbs @thread_pool: AtomicThreadPool
-    # @rbs @request: Request
-    # @rbs @client_options: Hash[Symbol, untyped]
+    # @rbs @http1: Http1
+    # @rbs @http2: Http2
+    # @rbs @first_data_timeout: Integer
+    # @rbs @drain_accept_queue: bool
     # @rbs @running: AtomicBoolean
 
     # Creates a new Server instance.
@@ -49,17 +52,21 @@ module Raptor
     # @param binder [Binder] the binder managing listening sockets
     # @param reactor [Reactor] the reactor for handling client connections
     # @param thread_pool [AtomicThreadPool] thread pool for application processing
-    # @param request [Request] the HTTP/1.1 request handler
-    # @param client_options [Hash] client timeout configuration, used to bound TLS handshakes
+    # @param http1 [Http1] the HTTP/1.1 handler
+    # @param http2 [Http2] the HTTP/2 handler (provides the initial SETTINGS frame)
+    # @param connection_options [Hash] per-connection timeout configuration, used to bound TLS handshakes
+    # @param drain_accept_queue [Boolean] whether to drain the kernel accept queue on shutdown
     # @return [void]
     #
-    # @rbs (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Request request, client_options: Hash[Symbol, untyped]) -> void
-    def initialize(binder, reactor, thread_pool, request, client_options:)
+    # @rbs (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Http1 http1, Http2 http2, connection_options: Hash[Symbol, untyped], ?drain_accept_queue: bool) -> void
+    def initialize(binder, reactor, thread_pool, http1, http2, connection_options:, drain_accept_queue: false)
       @binder = binder
       @reactor = reactor
       @thread_pool = thread_pool
-      @request = request
-      @client_options = client_options
+      @http1 = http1
+      @http2 = http2
+      @first_data_timeout = connection_options[:first_data_timeout]
+      @drain_accept_queue = drain_accept_queue
       @running = AtomicBoolean.new(true)
     end
 
@@ -74,12 +81,12 @@ module Raptor
     #
     # @rbs () -> Thread
     def run
-      Thread.new(@binder.listeners, @reactor, @running) do |server_sockets, reactor, running|
+      Thread.new do
         Thread.current.name = "Server"
 
-        while running.true?
+        while @running.true?
           begin
-            ready_servers, _, _ = IO.select(server_sockets, nil, nil, 1)
+            ready_servers, _, _ = IO.select(@binder.listeners, nil, nil, 1)
           rescue IOError, Errno::EBADF
             break
           end
@@ -87,28 +94,42 @@ module Raptor
           next unless ready_servers
           next if @reactor.backlog >= [(@thread_pool.size * 1.2).ceil, MIN_BACKPRESSURE_THRESHOLD].max
 
-          ready_servers.each do |listener|
-            accept_connection(listener, reactor)
-          end
+          ready_servers.each { |listener| accept_connection(listener) }
         end
       end
     end
 
     # Gracefully shuts down the server.
     #
-    # Stops accepting new connections and closes all listening sockets.
-    # The server thread will exit after handling any in-flight accept operations.
+    # Stops accepting new connections and closes all listening sockets. When
+    # `drain_accept_queue` is enabled, dispatches every connection already in
+    # the kernel accept queue before closing the listeners.
     #
     # @return [void]
     #
     # @rbs () -> void
     def shutdown
       @running.make_false
+      drain_accept_queue if @drain_accept_queue
       @binder.close
     end
 
     private
 
+    # Dispatches every connection already in the kernel accept queue for each
+    # listener until all are drained.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def drain_accept_queue
+      loop do
+        accepted = false
+        @binder.listeners.each { |listener| accepted = true if accept_connection(listener) }
+        break unless accepted
+      end
+    end
+
     # Accepts a connection from the given listener and dispatches it.
     #
     # For SSL listeners the TLS handshake is offloaded to the thread pool so
@@ -118,15 +139,14 @@ module Raptor
     # follow the HTTP/1.1 path.
     #
     # @param listener [TCPServer, UNIXServer, Binder::SslListener] the ready listener
-    # @param reactor [Reactor] the reactor to dispatch connections to
-    # @return [void]
+    # @return [Boolean] true if a connection was accepted, false if the listener had nothing to dispatch
     #
-    # @rbs (TCPServer | UNIXServer | Binder::SslListener listener, Reactor reactor) -> void
-    def accept_connection(listener, reactor)
+    # @rbs (TCPServer | UNIXServer | Binder::SslListener listener) -> bool
+    def accept_connection(listener)
       tcp_client = begin
         listener.is_a?(Binder::SslListener) ? listener.tcp_server.accept_nonblock : listener.accept_nonblock
       rescue IO::WaitReadable
-        return
+        return false
       end
 
       if tcp_client.is_a?(TCPSocket)
@@ -138,19 +158,20 @@ module Raptor
 
       if listener.is_a?(Binder::SslListener)
         @thread_pool << proc do
-          dispatch_ssl_connection(listener, tcp_client, remote_addr, reactor)
+          dispatch_ssl_connection(listener, tcp_client, remote_addr)
         end
-        return
+        return true
       end
 
-      @request.eager_accept(
+      @http1.eager_accept(
         tcp_client,
         tcp_client.object_id,
-        reactor,
+        @reactor,
         @thread_pool,
         remote_addr,
         HTTP_SCHEME
       )
+      true
     end
 
     # Performs the TLS handshake for an accepted SSL connection and dispatches
@@ -160,35 +181,34 @@ module Raptor
     # @param listener [Binder::SslListener] the SSL listener that accepted the connection
     # @param tcp_client [TCPSocket] the accepted TCP socket
     # @param remote_addr [String] the client's IP address
-    # @param reactor [Reactor] the reactor to dispatch the connection to
     # @return [void]
     #
-    # @rbs (Binder::SslListener listener, TCPSocket tcp_client, String remote_addr, Reactor reactor) -> void
-    def dispatch_ssl_connection(listener, tcp_client, remote_addr, reactor)
+    # @rbs (Binder::SslListener listener, TCPSocket tcp_client, String remote_addr) -> void
+    def dispatch_ssl_connection(listener, tcp_client, remote_addr)
       ssl_socket = OpenSSL::SSL::SSLSocket.new(tcp_client, listener.ssl_context)
       ssl_socket.sync_close = true
       return unless perform_ssl_handshake(ssl_socket)
 
       if ssl_socket.alpn_protocol == H2_PROTOCOL
-        ssl_socket.write(Http2.build_server_settings_frame) rescue nil
+        ssl_socket.write(@http2.initial_settings_frame) rescue nil
 
-        reactor.add(
+        @reactor.add(
           id: ssl_socket.object_id,
           socket: ssl_socket,
           remote_addr: remote_addr,
           url_scheme: HTTPS_SCHEME,
           protocol: :http2,
-          writer: Http2::Writer.new,
+          writer: @http2.create_writer,
           flow_control: Http2::FlowControl.new
         )
 
         return
       end
 
-      @request.eager_accept(
+      @http1.eager_accept(
         ssl_socket,
         ssl_socket.object_id,
-        reactor,
+        @reactor,
         @thread_pool,
         remote_addr,
         HTTPS_SCHEME
@@ -204,7 +224,7 @@ module Raptor
     #
     # @rbs (OpenSSL::SSL::SSLSocket ssl_socket) -> bool
     def perform_ssl_handshake(ssl_socket)
-      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @client_options[:first_data_timeout]
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @first_data_timeout
 
       begin
         ssl_socket.accept_nonblock

data/lib/raptor/stats.rb

@@ -60,7 +60,7 @@ module Raptor
     # @rbs (Integer index, pid: Integer, phase: Integer, requests: Integer, backlog: Integer, busy_threads: Integer, thread_capacity: Integer, started_at: Float, last_checkin: Float, booted: bool) -> void
     def write(index, pid:, phase:, requests:, backlog:, busy_threads:, thread_capacity:, started_at:, last_checkin:, booted:)
       data = [pid, index, phase, requests, backlog, busy_threads, thread_capacity, started_at, last_checkin, booted ? 1 : 0].pack(SLOT_FORMAT)
-      @mmap.semlock { @mmap[index * SLOT_SIZE, SLOT_SIZE] = data }
+      @mmap[index * SLOT_SIZE, SLOT_SIZE] = data
     end
 
     # Returns stats for all worker slots.

data/lib/raptor/systemd.rb

@@ -0,0 +1,69 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "socket"
+
+module Raptor
+  # Integration with systemd's service notification protocol and
+  # socket-activation file descriptors.
+  #
+  module Systemd
+    LISTEN_FDS_START = 3
+
+    LISTEN_FDNAMES_ENV = "LISTEN_FDNAMES"
+    LISTEN_FDS_ENV = "LISTEN_FDS"
+    LISTEN_PID_ENV = "LISTEN_PID"
+    NOTIFY_SOCKET_ENV = "NOTIFY_SOCKET"
+
+    # Sends `message` to the systemd notification socket, returning true on
+    # success and false when the socket is unset or the send fails.
+    #
+    # @param message [String] notify protocol payload, e.g. "READY=1"
+    # @return [Boolean]
+    #
+    # @rbs (String message) -> bool
+    def self.notify(message)
+      socket_path = ENV[NOTIFY_SOCKET_ENV]
+      return false if socket_path.nil? || socket_path.empty?
+
+      address = if socket_path.start_with?("@")
+        Socket.pack_sockaddr_un("\0#{socket_path[1..]}")
+      else
+        Socket.pack_sockaddr_un(socket_path)
+      end
+
+      socket = Socket.new(Socket::AF_UNIX, Socket::SOCK_DGRAM, 0)
+      socket.send(message, 0, address)
+      true
+    rescue SystemCallError, IOError
+      false
+    ensure
+      socket&.close
+    end
+
+    # Returns the file descriptors passed in via socket activation, or an
+    # empty array when systemd has not exported any.
+    #
+    # @return [Array<Integer>]
+    #
+    # @rbs () -> Array[Integer]
+    def self.listen_fds
+      return [] unless ENV[LISTEN_PID_ENV]&.to_i == Process.pid
+
+      count = ENV[LISTEN_FDS_ENV]&.to_i || 0
+      Array.new(count) { |index| LISTEN_FDS_START + index }
+    end
+
+    # Clears the socket-activation environment variables so children don't
+    # act on stale values.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def self.clear_listen_env
+      ENV.delete(LISTEN_FDNAMES_ENV)
+      ENV.delete(LISTEN_FDS_ENV)
+      ENV.delete(LISTEN_PID_ENV)
+    end
+  end
+end

data/lib/raptor/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Raptor
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end