Ruby: Rails, Sinatra, any Rack app

The camada gem enforces your snapshot inside a Ruby process: your ordered custom rules, then allow, block and challenge, decided in-process, with events shipped off the request path. One gem with a Rack middleware that any Rack app mounts and a Railtie that mounts it for Rails — the sentry-ruby model.

Install

bundle add camada

Ruby 3.1 or newer. No runtime dependencies (stdlib only); it never requires rack itself. On RubyGems as camada.

Mount it

# config.ru — Sinatra, Hanami, or any Rack app
require "camada"
use Camada::Rack      # first, so camada answers before routing
run App

# Rails — nothing to add: the Railtie inserts Camada::Rack at the top of the middleware stack
gem "camada"

The middleware shares one lazy engine, built from the environment on the first request:

export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest

Set these as environment variables: export them in the shell that starts your app, or add them in your host's settings. Rack and Rails read no .env file (Rails needs the dotenv-rails gem for that).

That build starts the snapshot poll on a thread and never blocks, so the request that triggered it is answered cold: it passes (fail open), and so does anything that arrives before the first poll lands. To enforce from request 1, warm the engine at boot by waiting for the boot poll:

# config/initializers/camada.rb, or config.ru before `run`
engine = Camada.default          # builds the engine; the boot poll is already running on its thread
if engine.snap                   # nil when CAMADA_KEY is unset or CAMADA_DISABLED=1
  probe = Camada::Snapshot::MatchInput.new(ip: "0.0.0.0")
  deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 5
  while engine.snap.verdict(probe).reason == "cold" && Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
    sleep 0.01                   # bounded: an unreachable analyst leaves it cold, and the app still fails open
  end
end

An app that reads its own configuration can build the engine itself and hand it in:

# my_key, my_ingest: read from your own configuration
engine = Camada::Engine.new(env: { "CAMADA_KEY" => my_key, "CAMADA_INGEST_URL" => my_ingest }, challenge_path: "/api/__camada/challenge")
use Camada::Rack, engine

Quickstart: Rails and Rack.

The options you will use

Environment: CAMADA_KEY, CAMADA_INGEST_URL, CAMADA_SNAPSHOT_URL, CAMADA_TRUSTED_PROXY, CAMADA_SERVERLESS=1 (a per-request staleness check, no poll thread), CAMADA_CHALLENGE=0, and the kill switch CAMADA_DISABLED=1, checked per request (set at boot, no threads start at all). The docs index lists what each one means.

What it does per request

1. Keeps the snapshot fresh off the request path: a poll thread at the cadence your tenant config sets (gzip on the wire, 304 when nothing changed), asking for snapshot v5, the container that carries your ordered custom rules. CAMADA_SERVERLESS=1 checks staleness per request instead.
2. Resolves the client from the socket peer (REMOTE_ADDR), combined with X-Forwarded-For only under your trusted-proxy setting. Never request.ip: Rack::Request#ip trusts a forwarded header from anyone, which is exactly the spoof camada refuses.
3. Runs your ordered custom rules, then the allow, block and challenge lists. A blocked request gets 403 with x-block-reason (and x-block-rule when a rule decided) before your app runs. The event still ships, marked as an SDK block so it is not confused with your own 403s.
4. A challenged browser gets the proof-of-work page; an API call reaches your app, and its response carries x-camada-challenge: 1 for your frontend to act on. A request whose IP cannot be resolved is let through. See challenge.
5. Serves the beacon endpoints, then runs your app with x-rid and the _sfp session cookie on its response, and when the server closes the response body ships one batched, redacted event with its real status, latency and the matched route pattern when the framework names it (sinatra.route, Rails' route_uri_pattern). An exception in your app ships as st: 500 and propagates unchanged.

Add the beacon

Bots that never run JavaScript are the cheapest to catch. Put the tag in the <head> of the pages you render and the middleware does the rest:

# Sinatra: `env` is the Rack env; Rails: request.env
get "/" do
  "<html><head>#{Camada.script_tag(env)}</head><body>…</body></html>"
end

Camada.script_tag(env) (Rails: request.env) returns a <script src="/_cam/b.js?r=…" async> tag carrying this request's event id, so the beacon is joined to the page view it came from. The middleware serves the script at GET /_cam/b.js (cacheable for an hour) and relays POST /_cam/fp onto the event batch, stamped with the client address camada resolved — never the one the body claims. Both endpoints sit behind the verdict, so a blocked client gets 403 there too. Turn the beacon off in the project's settings and the tag becomes empty and both endpoints fall through to your app.

Report what your app knows

The wire shows a POST /login; only your handler knows whether it failed. Tell camada from the handler:

post "/login" do
  ok = sign_in(params)   # your own check
  Camada.track(env, "login_failed", user: params[:email]) unless ok   # hashed in-process; never raises
  ok ? redirect("/") : halt(401, { error: "invalid" }.to_json)
end

Camada.track(env, event, user: …) ships the outcome joined to this request's event and session. The user identifier is hashed in-process with your ingest token before it is queued — the raw value never leaves the process. It never raises and is a no-op on a request the middleware did not run for. The event name is free-form; the analyst's rules read this vocabulary:

A route you want to gate yourself can serve the challenge on demand; the answer is a Rack triple:

get "/export" do
  if (answer = Camada.serve_challenge(env))
    halt(*answer)   # the proof-of-work page (or 403 JSON) until this browser holds a valid _cch
  end
  big_file   # your response
end

What this position sees

The same position as @camada/node, in a Ruby process: the final status and latency, the session, the beacon's browser signals and your app's outcomes. The Rack env carries no wire header order, so the analyst reads no header-order signal from this tap — camada knows what this tap can see from the position itself and never scores the absence of header order as evidence against a request. No ASN, country or TLS fingerprint reaches a Ruby process, so those conditions fail open in-app and the analyst resolves ASN and country itself. matches patterns are JS regexes read by Ruby's Onigmo: named groups are native, ^ and $ become \A and \z, and a spelling Ruby still rejects never matches here (and never raises) while it does at the edge. What a rule can key on is on rules and list entries.

Deploying it

• Every worker process polls its own snapshot (about 5 MB resident, read a word at a time) and flushes its own batches; the tenant's poll_seconds keeps the cadence honest across a fleet.
• Threads do not survive a fork. Ruby has no fork hook, so the SDK compares Process.pid on every call and starts over in a forked worker: new locks, an empty queue, its poll and flush threads restarted. Puma cluster mode with preload_app!, Unicorn and Passenger need nothing added.
• Pending events drain at interpreter exit within half a second (at_exit). No signal handlers are installed — an app owns its own shutdown — so a worker killed by SIGKILL, or by SIGTERM without a handler, may drop its last batch.
• Serverless hosts: CAMADA_SERVERLESS=1. A cold invocation fails open and catches up on the next one.
• The middleware writes lower-case header names; it appends set-cookie as an Array under Rack 3 and joins cookies with "\n" under Rack 2.

It fails open

Without a key the middleware is inert: one log line, no requests, no enforcement, so an unprovisioned environment behaves exactly as if camada were not installed. Beyond that, a dead ingest (logged at most once a minute, one line, no backtrace), a corrupt snapshot or a bug in the gem costs you the telemetry, never the request — camada can never turn one of your responses into a 5xx. The whole stance is on the security page.