Dry-Run (Shadow) Mode

Shadow mode lets operators roll out L402 enforcement safely. With l402_dry_run on; set on a location, the module evaluates the full pricing pipeline, synthesises a valid L402 challenge, and records structured logs and Prometheus metrics — but always passes the request through to the upstream. No client ever sees 401 or 402.

This is the recommended way to validate pricing, LN backend reachability, and traffic patterns with real production traffic before flipping a route to enforcement.

Enabling shadow mode

location /api/ {
    l402                        on;
    l402_amount_msat_default    10000;
    l402_dry_run                on;          # evaluate, log, never block
    proxy_pass                  http://upstream;
}

l402_dry_run accepts on or off (default). It can be combined with any other l402_* directive — dynamic pricing from Redis, multi-tenant LNURLs, macaroon timeouts, invoice rate limits — so the shadow-mode numbers you measure match the configuration you are about to enforce.

l402 must still be on for the module to enter the access handler. Turning l402 off disables the module entirely, including shadow mode.

What happens per request

For every request reaching a shadow-mode location, the module:

1. Reads the static and dynamic (Redis) price for the route and picks the effective amount_msat.
2. Looks up any per-tenant LNURL override.
3. Verifies the Authorization header if one is present (L402 or Cashu).
4. If no valid token is present, calls the configured LN backend and generates a real invoice + macaroon — exactly the challenge enforce mode would have returned.
5. Emits a structured JSON log line and bumps the relevant Prometheus counters.
6. Returns NGX_DECLINED, so Nginx continues to the content phase and serves the upstream response with its natural status code.

Cost note: generating a challenge contacts your LN backend on every unauthenticated request. If you have high traffic, start by enabling shadow mode on a sampled location (e.g. a canary route) before rolling it out everywhere.

Latency cap: the challenge-synthesis call is bounded by a 5-second timeout. If the LN backend does not respond within that window the request still passes through (with no X-L402-Dry-Run-Challenge header) and l402_dry_run_challenge_errors_total is incremented — shadow mode must never add latency to user-facing traffic.

Response headers

Shadow mode attaches debug headers to the upstream response so operators can inspect what would have happened without scraping logs:

Structured log events

Every shadow-mode request produces a single info-level JSON line via the Rust logger. A minimal example (formatted for readability):

{
  "event": "l402_dry_run",
  "route": "/api/resource",
  "price_msat": 10000,
  "price_source": "static",
  "backend": "LNURL",
  "client_ip": "203.0.113.42",
  "auth_state": "missing",
  "would_return": 402
}

Fields:

Pipe into jq to see a live firehose:

sudo tail -f /var/log/nginx/error.log \
  | grep '"event":"l402_dry_run"' \
  | jq -c 'select(.would_return != 200) | {route, price_msat, auth_state}'

Prometheus metrics

The l402_metrics directive turns a location into a Prometheus scrape endpoint. It serves counters in text exposition format v0.0.4.

location = /metrics {
    l402_metrics;

    # Production: restrict to your scrape network.
    allow 10.0.0.0/8;
    deny  all;
}

Scrape it with a standard Prometheus config:

scrape_configs:
  - job_name: ngx_l402
    metrics_path: /metrics
    static_configs:
      - targets: ['nginx:8000']

Exported counters

Useful PromQL

# Fraction of traffic that would be blocked if you flipped enforcement on:
rate(l402_dry_run_would_block_total[5m])
/
rate(l402_dry_run_requests_total[5m])

# Average price served by shadow mode (msat):
rate(l402_dry_run_price_msat_sum[5m])
/
rate(l402_dry_run_requests_total[5m])

# Challenge-synthesis error rate — a signal that your LN backend is flaky:
rate(l402_dry_run_challenge_errors_total[5m])

The endpoint has no built-in authentication. Restrict it at the Nginx level with allow/deny, an auth subrequest, or a firewall rule — exposing it publicly leaks traffic volume and pricing details.

Suggested rollout recipe

1. Deploy with l402 on; and l402_dry_run on; on the target location. Leave existing routes untouched.
2. Scrape /metrics for 24–48 hours. Confirm:
   • l402_dry_run_challenge_errors_total stays flat (LN backend healthy).
   • l402_dry_run_would_allow_total / l402_dry_run_requests_total matches the fraction of paying clients you expect.
   • l402_dry_run_price_msat_sum divided by request count matches your posted price.
3. Sample the JSON log for a few high-volume paths and confirm price_source is what you configured (static vs dynamic).
4. Remove l402_dry_run on; (or set it to off). Reload Nginx. The location now enforces.

If you ever need to revert, setting l402_dry_run on; again immediately disables enforcement without touching upstream code paths.