Class: Raptor::Cluster

Inherits:
Object
  • Object
show all
Defined in:
lib/raptor/cluster.rb

Overview

Multi-process web server cluster with advanced concurrency architecture.

Cluster manages multiple worker processes, each running a complete server stack including a reactor thread, server thread, ractor pool for HTTP parsing, and thread pool for application processing. It handles process forking, signal management, graceful shutdown, and automatic worker restart when a worker process unexpectedly exits.

The architecture provides horizontal scaling through processes while maintaining efficient I/O and CPU utilization within each process through the combination of NIO reactors, ractor-based parsing, and thread pools.

Flow per worker process:

  1. Server continuously accepts connections but skips acceptance when backlog is high

  2. Reactor manages I/O multiplexing and provides backlog metrics for load control

  3. Ractor pool handles CPU-intensive HTTP parsing in parallel

  4. Thread pool processes Rack applications and handles response writing

  5. Natural load balancing occurs through backpressure-based acceptance control

Examples:

Basic usage

options = {
  threads: 8, ractors: 2, workers: 4,
  binds: ["tcp://0.0.0.0:3000"],
  rackup: "config.ru",
  client: { first_data_timeout: 30, chunk_data_timeout: 10 }
}
Cluster.run(options)

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ void

Creates a new Cluster with the specified configuration.

Initializes the cluster with thread, ractor, and worker counts, sets up network binding, loads the Rack application, and prepares for multi-process operation.

Parameters:

  • options (Hash) —

    cluster configuration options

Options Hash (options):

  • :threads (Integer) —

    number of threads per worker process

  • :ractors (Integer) —

    number of ractors per worker process

  • :workers (Integer) —

    number of worker processes

  • :binds (Array<String>) —

    array of bind URIs

  • :app (#call) —

    pre-built Rack application

  • :rackup (String) —

    path to Rack configuration file

  • :client (Hash) —

    client configuration

  • :on_error (#call) —

    callback invoked with (env, exception) when the Rack app raises

  • :stats_file (String, nil) —

    path to write per-worker stats JSON, or nil to disable

  • :pidfile (String, nil) —

    path to write the master PID to, or nil to disable



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/raptor/cluster.rb', line 93

def initialize(options)
  @thread_count = options[:threads]
  @ractor_count = options[:ractors]
  @worker_count = options[:workers]
  @client_options = options[:client]
  @on_error = options[:on_error]
  @stats_file = options[:stats_file]
  @pidfile = options[:pidfile]

  @binder = Binder.new(options[:binds])
  @server_port = @binder.server_port
  @app = options[:app] || Rack::Builder.parse_file(options[:rackup])
  log_initialization

  @shutdown = false
  @workers = {}
  @stats = Stats.new(@worker_count)
  @phased_restart_requested = false
  @phased_restarting = false
end

Class Method Details

.run(options) ⇒ void

This method returns an undefined value.

Convenience method to create and run a cluster with the given options.

Parameters:

  • options (Hash) —

    cluster configuration options



53
54
55
 
# File 'lib/raptor/cluster.rb', line 53

def self.run(options)
  new(options).run
end

Instance Method Details

#run ⇒ void

This method returns an undefined value.

Starts the multi-process cluster and manages worker processes.

Forks the configured number of worker processes and monitors them, automatically restarting any that exit unexpectedly. Handles graceful shutdown via INT or TERM signals, stats logging via USR1, and phased restart via USR2.

Each worker process includes:

  • 1 server thread (continuously accepts connections with backpressure control)

  • 1 reactor thread (I/O multiplexing, timeout handling, backlog monitoring)

  • N ractor workers (parallel HTTP parsing)

  • 1 ractor collector thread (coordinates parsing results)

  • M worker threads (Rack application processing and response writing)

  • 1 stats thread (writes per-worker metrics to shared memory every second)



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/raptor/cluster.rb', line 132

def run
  trap("INT") { shutdown }
  trap("TERM") { shutdown }
  trap("USR1") { log_stats }
  trap("USR2") { @phased_restart_requested = true }

  File.open(@pidfile, File::CREAT | File::EXCL | File::WRONLY) { |file| file.write(Process.pid.to_s) } if @pidfile

  @worker_count.times { |index| spawn_worker(index) }

  stats_file_thread = if @stats_file
    Thread.new do
      Thread.current.name = "Raptor Stats File"

      write_stats_file_loop
    end
  end

  until @shutdown
    break if reap_workers == :no_children

    perform_phased_restart if @phased_restart_requested && !@phased_restarting

    sleep 0.1
  end

  @workers.values.each { |pid| Process.kill("TERM", pid) rescue nil }
  @workers.values.each { |pid| Process.wait(pid) rescue nil }
  stats_file_thread&.join
  File.delete(@stats_file) rescue nil if @stats_file
  File.delete(@pidfile) rescue nil if @pidfile
  @stats.unmap
end

#stats ⇒ Array<Hash>

Returns stats for all worker processes.

Returns:

  • (Array<Hash>) —

    array of per-worker stat hashes, each containing :pid, :requests, :backlog, :started_at, :last_checkin, and :booted



172
173
174
 
# File 'lib/raptor/cluster.rb', line 172

def stats
  @stats.all
end