Skip to main content

Architecture overview

chukei is a wire-protocol-level HTTPS proxy in front of *.snowflakecomputing.com. It intercepts exactly one endpoint — POST /queries/v1/query-request — and passes everything else through verbatim (login, session token renewal, file transfers, chunk negotiation).

The hot path​

  Snowflake driver  (JDBC / ODBC / Python / BI tool / dbt)
      │
      │  TLS
      v
  ┌──────────────────────────────────────────────────────────┐
  │ chukei proxy           deterministic Rust / ~2ms p99     │
  │                                                          │
  │ 1. wire shim    intercept POST /queries/v1/query-request │
  │ 2. parse        gzip decode -> AST -> fingerprint        │
  │ 3. plugin bus   Veto > ServeFromCache > Route >          │
  │                 Rewrite > SetWarehouseSize > Annotate    │
  └───┬──────────────────────────────────────────────────────┘
      │
      │  the plugin bus decides one of:
      v

  cache hit       ->  serve verified cache result
  miss / forward  ->  Snowflake  (*.snowflakecomputing.com)
  fail open       ->  Snowflake, unchanged
                      (on parse error / panic / ambiguity)

  all results return to the driver unchanged

The hot path is deterministic Rust only — no LLM, no extra network calls. Measured overhead is ~2 ms p99 on commodity hardware (see benchmarks). Every other endpoint — login, token renewal, file transfers, chunk negotiation — is passed through byte-for-byte; see the wire-protocol shim.

Fail open​

Any chukei-side failure — parse error, plugin panic, cache problem — degrades to byte-identical passthrough. A query is never broken by the proxy. This is the property that makes a supervised pilot safe: the worst case is paying what you already pay.

The cache is false-positive-intolerant​

  • Only deterministic reads are cacheable (a strict determinism gate vetoes RANDOM(), CURRENT_TIMESTAMP(), writes, and anything ambiguous).
  • Writes invalidate cached entries for the affected tables.
  • Chunked (large) results are never cached — chunk downloads go directly from the driver to Snowflake's presigned cloud storage URLs.
  • Blame mode re-executes a sample of cache hits against live Snowflake and counts mismatches. The SLO is zero; a 13.5-hour soak recorded 60,000 hits and 0 mismatches.

Sessions and credentials​

Client auth passes through verbatim — password, key-pair (JWT), and programmatic access tokens are all validated end-to-end. Session tokens live in memory only and re-key automatically on Snowflake's ~4-hour token rotation. chukei never persists or logs credentials.

Plugins​

Plugins communicate only via a Decision enum merged by precedence (Veto > ServeFromCache > Route > Rewrite > SetWarehouseSize > Annotate). The five built-in plugins — cache, router, rewrite, suspend, attribute — are all independently kill-switchable via CHUKEI_PLUGINS_*_ENABLED env overrides. See the plugin bus for how the precedence ladder resolves competing decisions.

Deep dives​