The planner ranks likely artifacts before rustc asks for exact keys. It is optional: local caching, exact remote lookup, sync, and client-side fallback planning work without it.

API and state

The service in crates/kache-service exposes:

• POST /v1/prefetch-plan
• POST /v2/prefetch-plan
• GET /healthz
• GET /readyz

Both plan versions use the same handler. When no useful candidates exist, the service returns a fallback disposition and the client uses its normal planner.

Planner state is stored in embedded SurrealDB. kache save-manifest writes manifests to the configured remote; it does not post them directly to this service. Current deployments seed or ingest that data separately.

Run locally

cargo run -p kache-service

The default bind address is 0.0.0.0:8080 and the default database path is /var/lib/kache/planner.db. Override them with --bind / KACHE_PLANNER_BIND and --db-path / KACHE_PLANNER_DB_PATH.

Set --token or KACHE_PLANNER_TOKEN to require bearer authentication.

Helm

helm upgrade --install kache-service ./charts/kache-service

The chart supplies a Deployment, Service, probes, optional persistent volume, optional existing-secret authentication, and optional Lease-based leader election. It does not create ingress.

Point clients at it:

export KACHE_PLANNER_ENDPOINT=http://kache-service.namespace.svc.cluster.local:8080
export KACHE_PLANNER_TOKEN=secret-if-required

The equivalent TOML is under [cache.planner].

Persistence and HA

The chart defaults to ephemeral emptyDir planner storage. Choose pvc when state must survive pod replacement:

planner:
  persistence:
    enabled: true
    type: pvc
    size: 10Gi

Enable leader election for multiple replicas:

replicaCount: 2
ha:
  enabled: true
  leaseName: kache-service

Followers remain live but not ready. If replicas share one embedded database, the volume must support their mount pattern; otherwise keep one replica.