Raptor

Raptor is a high-performance, preloading, pre-forking, multi-threaded Ruby 4+ web server implementing Rack 3.2+, using NIO for non-blocking I/O and Ractors for parallel HTTP/1.1 and HTTP/2 parsing via native C extensions, which also implement HPACK compression.

[!NOTE] Your application does not need to be Ractor-safe. Ractors handle protocol-level work only; your Rack application is invoked on a thread pool, so any thread-safe Rack app (including Rails) works as-is.

Reference documentation is published at https://joshuay03.github.io/raptor.

Installation

Install the gem and add to the application's Gemfile by executing:

bundle add raptor

If bundler is not being used to manage dependencies, install the gem by executing:

gem install raptor

Usage

# hello_world.ru

# frozen_string_literal: true

run proc { |_env| [200, { "content-type" => "text/plain" }, ["Hello, World!"]] }

> bundle exec raptor -w 10 -t 3 hello_world.ru
[Raptor 46475|Main|Main] Cluster initializing:
[Raptor 46475|Main|Main] ├─ Version: 0.19.0
[Raptor 46475|Main|Main] ├─ Ruby Version: ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +YJIT +PRISM [arm64-darwin23]
[Raptor 46475|Main|Main] ├─ Environment: development
[Raptor 46475|Main|Main] ├─ Master PID: 46475
[Raptor 46475|Main|Main] │  └─ 10 worker processes
[Raptor 46475|Main|Main] │     ├─ 1 server thread
[Raptor 46475|Main|Main] │     ├─ 1 reactor thread
[Raptor 46475|Main|Main] │     ├─ 1 HTTP/1.1 pipeline ractor
[Raptor 46475|Main|Main] │     ├─ 1 pipeline collector thread
[Raptor 46475|Main|Main] │     ├─ 3 worker threads (scaling, no limit)
[Raptor 46475|Main|Main] │     └─ 1 stats thread
[Raptor 46475|Main|Main] └─ Listening on 0.0.0.0:9292
[Raptor 46480|Main|Main] Worker 0 booted
[Raptor 46484|Main|Main] Worker 4 booted
[Raptor 46482|Main|Main] Worker 2 booted
[Raptor 46481|Main|Main] Worker 1 booted
[Raptor 46483|Main|Main] Worker 3 booted
[Raptor 46485|Main|Main] Worker 5 booted
[Raptor 46486|Main|Main] Worker 6 booted
[Raptor 46487|Main|Main] Worker 7 booted
[Raptor 46488|Main|Main] Worker 8 booted
[Raptor 46489|Main|Main] Worker 9 booted

> curl localhost:9292
Hello, World!%   

Also works with rackup and rails server:

> bundle exec rackup -s raptor hello_world.ru
> bundle exec rails server -u raptor

Configuration

Raptor accepts configuration via command-line flags, a Ruby config file, or both (CLI flags override config file values). Run bundle exec raptor --help for the full flag list.

The config file is a Ruby file that evaluates to a hash of options. By default Raptor loads raptor.rb then config/raptor.rb from the working directory; pass -c PATH to point at a specific file. Settings are nested under connection: (shared across protocols), http1: (HTTP/1.1-specific), and http2: (HTTP/2-specific).

# raptor.rb

# Every key below is set to its default value; only include the ones you want to override.
{
  binds: ["tcp://0.0.0.0:9292"],
  socket_backlog: 1024,
  drain_accept_queue: false,
  workers: 4, # `Etc.nprocessors`
  threads: 3,
  max_threads: Float::INFINITY, # set to `threads` for a fixed pool
  chdir: nil,
  environment: nil, # falls back to `RAILS_ENV`, then `RACK_ENV`, then `"development"`
  connection: {
    first_data_timeout: 30,
    chunk_data_timeout: 10,
    write_timeout: 5,
    max_body_size: nil,
    body_spool_threshold: 1024 * 1024,
  },
  http1: {
    ractors: nil,
    persistent_data_timeout: 65,
    max_keepalive_requests: 100,
  },
  http2: {
    ractors: nil,
    max_concurrent_streams: 100,
  },
  worker_boot_timeout: 60,
  worker_timeout: 60,
  worker_drain_timeout: 25,
  worker_shutdown_timeout: 30,
  refork_after: 1000, # `nil` on non-Linux
  before_fork: [],
  before_worker_boot: [],
  before_worker_shutdown: [],
  before_refork: [],
  stats_file: "tmp/raptor.json",
  pid_file: nil,
  stdout_file: nil,
  stderr_file: nil,
  access_log_file: nil,
}

threads sets the number of application threads each worker keeps running. By default, Raptor adds temporary threads without a fixed limit when queued work is held up by blocking operations. It does not add threads when waiting for the GVL is the bottleneck, and temporary threads leave after the queue drains. Set max_threads to cap growth, or set it to the same value as threads for a fixed pool.

Bindings

Raptor accepts multiple binds: URIs across three schemes.

• tcp://host:port for TCP. Host can be a specific IP, 0.0.0.0 / [::], or localhost (expanded to both IPv4 and IPv6 loopback addresses).
• unix:///path/to/socket for a Unix domain socket. Stale sockets left by crashed processes are cleaned up automatically.
• ssl://host:port?cert=/path/to.crt&key=/path/to.key for TLS. HTTP/1.1 and HTTP/2 are negotiated via ALPN.

Multiple binds can be combined freely.

Signals

Send to the master process.

Signal	Effect
INT	Graceful shutdown
TERM	Graceful shutdown
HUP	Reopen stdout_file, stderr_file, and access_log_file
USR1	Phased restart (rolling worker replacement)
USR2	Hot restart (re-exec master, inheriting listening sockets)

Restarts

• Phased restart (USR1) replaces workers one at a time, waiting for each new worker to boot before retiring the previous one. The master process keeps running, so existing workers continue serving until they are individually replaced. Use to pick up code changes that don't affect the master's boot path.
• Hot restart (USR2) re-execs the master process with its original command line, inheriting the listening sockets so accepted connections continue to be served across the swap. The successor master re-runs initialization from scratch. Use to pick up changes that affect master-level state (config layout, dependency upgrades, Raptor itself).

systemd

Raptor implements socket activation (LISTEN_FDS) and sd_notify, so it integrates cleanly with Type=notify units. When the socket unit is active, systemd hands the pre-bound listening file descriptors to Raptor, which serves them in place of binds:. READY=1, STOPPING=1, and RELOADING=1 lifecycle messages are emitted automatically.

# /etc/systemd/system/myapp.socket
[Socket]
ListenStream=0.0.0.0:9292

[Install]
WantedBy=sockets.target

# /etc/systemd/system/myapp.service
[Service]
Type=notify
WorkingDirectory=/srv/myapp
ExecStart=/usr/bin/bundle exec raptor
ExecReload=/bin/kill -USR2 $MAINPID
KillMode=mixed

Stats

Each worker writes per-worker stats (request count, busy and available threads, backlog, last check-in) to shared memory and to a JSON file (default tmp/raptor.json; set via stats_file).

> bundle exec raptor stats
Master PID: 91348
Worker 0 (phase 0): pid=91350, requests=1234, busy=2/3, backlog=0, booted, last_checkin=10:42:01
Worker 1 (phase 0): pid=91351, requests=1199, busy=1/3, backlog=0, booted, last_checkin=10:42:01
...

(Micro) Benchmarks

Raptor 0.19.0 vs Puma 8.0.2 vs Falcon 0.57.0 across two workload profiles. IO-bound is a GET endpoint that interleaves 5-10 short sleeps (total 2.5-15ms) with small CPU work, simulating a read path that makes several DB or cache calls. CPU-bound is a POST endpoint that accepts a small JSON body, interleaves 3-5 chunks of JSON item building (total 450-1500 items) with sub-100µs sleeps, and returns the built array, simulating a write path that does most of its work in Ruby with a few near-zero-cost cache hits.

Raptor is run in two modes: Fixed keeps 3 application threads per worker, matching Puma, while Scaling starts with 3 and may add threads without a fixed limit when queued work is blocked outside the GVL. Both modes are compared with both Puma and Falcon in the table below.

Each cell reports the median throughput and median p95 latency independently across 3 runs, so the two numbers in a row may come from different runs. Every run starts a fresh server process so the samples are independent of each other; state accumulated in a previous run cannot bias the next. Across the whole table, the widest spread ((max - min) / 2 / median) between runs of a single cell was ±26.6% for throughput and ±45.2% for p95.

Protocol	Workload	Raptor mode	Raptor req/s	Raptor p95	Puma req/s	Puma p95	vs Puma req/s	vs Puma p95	Falcon req/s	Falcon p95	vs Falcon req/s	vs Falcon p95
HTTP/1.1	IO	Fixed	3.11k req/s	60.50 ms	1.51k req/s	123.80 ms	106.1% higher	51.1% lower	12.20k req/s	14.20 ms	74.5% lower	326.1% higher
HTTP/1.1	IO	Scaling	8.63k req/s	21.60 ms	1.51k req/s	123.80 ms	471.4% higher	82.6% lower	12.20k req/s	14.20 ms	29.3% lower	52.1% higher
HTTP/1.1	CPU	Fixed	8.22k req/s	25.40 ms	8.65k req/s	20.90 ms	5.0% lower	21.5% higher	6.52k req/s	27.40 ms	26.0% higher	7.3% lower
HTTP/1.1	CPU	Scaling	8.22k req/s	25.10 ms	8.65k req/s	20.90 ms	4.9% lower	20.1% higher	6.52k req/s	27.40 ms	26.1% higher	8.4% lower
HTTP/1.1 (keep-alive)	IO	Fixed	3.21k req/s	45.90 ms	1.46k req/s	105.50 ms	119.5% higher	56.5% lower	6.23k req/s	28.20 ms	48.6% lower	62.8% higher
HTTP/1.1 (keep-alive)	IO	Scaling	9.43k req/s	21.60 ms	1.46k req/s	105.50 ms	545.8% higher	79.5% lower	6.23k req/s	28.20 ms	51.3% higher	23.4% lower
HTTP/1.1 (keep-alive)	CPU	Fixed	8.49k req/s	21.80 ms	8.54k req/s	22.20 ms	0.7% lower	1.8% lower	6.86k req/s	32.70 ms	23.8% higher	33.3% lower
HTTP/1.1 (keep-alive)	CPU	Scaling	8.49k req/s	22.20 ms	8.54k req/s	22.20 ms	0.6% lower	0.0% higher	6.86k req/s	32.70 ms	23.8% higher	32.1% lower
HTTP/2	IO	Fixed	1.14k req/s	150.03 ms	N/A	N/A	-	-	6.40k req/s	28.07 ms	82.1% lower	434.4% higher
HTTP/2	IO	Scaling	4.46k req/s	39.65 ms	N/A	N/A	-	-	6.40k req/s	28.07 ms	30.3% lower	41.2% higher
HTTP/2	CPU	Fixed	5.35k req/s	35.99 ms	N/A	N/A	-	-	7.32k req/s	41.05 ms	26.9% lower	12.3% lower
HTTP/2	CPU	Scaling	6.28k req/s	32.32 ms	N/A	N/A	-	-	7.32k req/s	41.05 ms	14.2% lower	21.3% lower

ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +YJIT +PRISM [aarch64-linux] 10 worker processes; fixed Raptor and Puma run 3 threads per worker; scaling Raptor starts at 3 with no fixed limit; Falcon runs unbounded fibers per worker; 120 concurrent HTTP/1.1 client connections; 40 concurrent HTTP/2 client connections × 3 streams each

See bin/benchmark for more details.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bundle exec rake to compile native extensions and run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

On macOS (or any non-Linux host), bin/dev builds and drops you into a Docker image with Ruby and the required Linux toolchain preinstalled, mounting the repo at /workspace. Run bin/dev for an interactive shell, or bin/dev <command> for one-off commands like bin/dev bundle exec rake or bin/dev bin/benchmark.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/joshuay03/raptor. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Raptor project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.