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​

driver ──TLS──▶ chukei ──TLS──▶ account.snowflakecomputing.com
                  │
                  ├─ gzip decode (official drivers gzip every POST body)
                  ├─ parse (sqlparser, Snowflake dialect) → fingerprint
                  ├─ plugin bus: Veto > ServeFromCache > Route > Rewrite
                  │              > SetWarehouseSize > Annotate
                  └─ forward / serve from cache

The hot path is deterministic Rust only — no LLM, no extra network calls. Measured overhead is ~2ms p99 on commodity hardware.

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.