# Query Gateway — Local Development Runbook

This runbook explains how to work on the Rust Query Gateway implementation locally, run the
contract-aligned test suite, and start the `sf-query-gateway` binary.

Scope:
- Rust crate: `rust/crates/query` (`search-fabric-query`)
- Binary: `rust/bins/sf-query-gateway` (`sf-query-gateway`)

## 1) Fast path: run the Query Gateway test suite

The Query Gateway crate test suite is the primary local-dev harness. It uses deterministic fake
dependencies (trait fakes + in-process tonic streaming broker) to validate the public surfaces and
stable conformance invariants.

```bash
cd rust
cargo test -p search-fabric-query
```

## 2) Start `sf-query-gateway` locally

### 2.1 Build and run

```bash
cd rust
cargo run -p sf-query-gateway
```

The binary starts a tonic gRPC server hosting:
- `searchfabric.v1.QueryGatewayService`
- `searchfabric.v1.RelationalQueryService`

Dependency channels are created lazily: the process can start even when the configured CCS / Query
Broker endpoints are not reachable, and the first RPC that needs a missing dependency will fail
closed with the canonical unavailability error class.

### 2.2 Environment variables

Query Gateway is configured via the `SF_QUERY_GATEWAY_*` env var family.

Authoritative defaults live in:
- `rust/crates/query/src/config.rs`

Commonly used variables:
- `SF_QUERY_GATEWAY_LISTEN_ADDR`
- `SF_QUERY_GATEWAY_CCS_PUBLIC_ENDPOINT`
- `SF_QUERY_GATEWAY_CCS_PRIVATE_ENDPOINT`
- `SF_QUERY_GATEWAY_QUERY_BROKER_ENDPOINT`
- `SF_QUERY_GATEWAY_REQUEST_DEADLINE_MS`
- `SF_QUERY_GATEWAY_CCS_TIMEOUT_MS`
- `SF_QUERY_GATEWAY_BROKER_TIMEOUT_MS`
- `SF_QUERY_GATEWAY_POSITIVE_DESCRIPTOR_CACHE_TTL_MS`
- `SF_QUERY_GATEWAY_NEGATIVE_DESCRIPTOR_CACHE_TTL_MS`
- `SF_QUERY_GATEWAY_ENABLE_CCS_INVALIDATION_WATCH`
- `SF_QUERY_GATEWAY_INVALIDATION_QUEUE_CAPACITY`
- `SF_QUERY_GATEWAY_WATCH_RECONNECT_BACKOFF_MS`
- `SF_QUERY_GATEWAY_QUOTA_REFILL_TARGET`
- `SF_QUERY_GATEWAY_QUOTA_REFILL_TIMEOUT_MS`
- `SF_QUERY_GATEWAY_MAX_CONCURRENT_STREAMS`
- `SF_QUERY_GATEWAY_MAX_QUERY_PAYLOAD_BYTES`
- `SF_QUERY_GATEWAY_MAX_PREDICATE_AST_NODES`
- `SF_QUERY_GATEWAY_MAX_AGGREGATION_DEPTH`
- `SF_QUERY_GATEWAY_MAX_PAGE_DEPTH`

Example (override listen address only):

```bash
export SF_QUERY_GATEWAY_LISTEN_ADDR=127.0.0.1:50557
cd rust && cargo run -p sf-query-gateway
```

## 3) Tracing / diagnostics

The binary enables lightweight structured tracing by default (JSON lines on stderr). The trace
events are designed to avoid logging raw continuation tokens, search-context tokens, or raw vector
values.

For test-only inspection, see:
- `rust/crates/query/tests/observability.rs`