Skip to content

AGENTS.md

Latest commit

 

History

History
70 lines (52 loc) · 5.2 KB

AGENTS.md

File metadata and controls

70 lines (52 loc) · 5.2 KB
Raw

AGENTS.md

Guidance for Claude Code when working in this repo.

Purpose

Instill AI's API gateway, built on KrakenD. This repo maintains the composed krakend.json configuration plus a set of custom KrakenD plugins. It fronts Instill backend services (pipeline, model, mgmt, artifact, agent, etc.) and handles routing, auth, and streaming.

Tech stack

  • KrakenD CE (version pinned via KRAKEND_CE_VERSION in .env) — the gateway binary.
  • Go (version pinned via GOLANG_VERSION in .env; plugins currently on go 1.25.6) — for plugins compiled as .so via -buildmode=plugin.
  • Alpine-based Docker image; multi-stage build with optional aarch64-linux-musl-cross toolchain for cross-compiling amd64 -> arm64.
  • flexible-config (FC) KrakenD templating to compose krakend.json from config/base.json, config/share/partials, config/share/templates, and config/settings (generated by config/envsubst.sh).
  • jwx CLI (lestrrat-go/jwx v2.0.12) built into the image for JWKS handling; scripts/generate_jwks.sh invokes it.

Repo layout

  • krakend.json — the composed, committed gateway config consumed at runtime.
  • config/ — source of truth for config composition.
    • base.json — FC entrypoint.
    • share/partials, share/templates — FC fragments.
    • settings-env/ — templated settings expanded by envsubst.sh into config/settings/.
    • envsubst.sh — substitutes env vars into settings.
  • plugins/ — one Go module per plugin, each built into a .so:
    • grpc-proxy — HTTP <-> gRPC bridging for backend services.
    • simple-auth — auth middleware.
    • registry — registry proxying.
    • blob — blob/object handling.
    • pipeline-sse-streaming, model-sse-streaming — SSE streaming for pipeline/model trigger endpoints.
  • scripts/generate_jwks.sh — generates JWKS using jwx.
  • Dockerfile (prod), Dockerfile.dev (dev).
  • release-please/ — release automation config.

Verified commands (from Makefile)

Requires a .env file at the repo root (the Makefile includes it and exports variables such as SERVICE_NAME, SERVICE_PORT, STATES_PORT, METRICS_PORT, GOLANG_VERSION, KRAKEND_CE_VERSION).

  • make help — list targets.
  • make build-dev — build instill/${SERVICE_NAME}:dev from Dockerfile.dev.
  • make build-latest — build instill/${SERVICE_NAME}:latest from Dockerfile.
  • make dev — run the dev container (auto-joins instill-network if present, else bridge).
  • make logs — tail container logs.
  • make stop — stop the container.
  • make rm — remove the container.
  • make top — show container processes.
  • make plugin — compile all six plugins to /usr/local/lib/krakend/plugins/*.so (run inside the dev container where that path and toolchain exist).
  • make config — regenerate krakend.json: runs config/envsubst.sh, scripts/generate_jwks.sh, then krakend check with FC env vars, and pretty-prints via jq. Requires krakend and jq on PATH.
  • make run — krakend run -c krakend.json.

No Go test target is defined at the repo root. Plugin modules are independent; use go commands inside each plugins/<name>/ directory if needed.

Conventions

  • Do not hand-edit krakend.json for logic changes — edit config/base.json, the partials/templates, or settings-env/, then run make config to regenerate.
  • Each plugin is its own Go module (plugins/<name>/go.mod); changes are local to that module.
  • Plugins must be built with the exact Go toolchain version used by the KrakenD binary — mismatches break -buildmode=plugin loading. Prefer building through the Docker images.
  • Cross-compiling to arm64 from amd64 uses the aarch64-linux-musl-cross toolchain pulled in the Dockerfile; replicate those env vars (CC, CGO_ENABLED=1, GOARCH) if building outside Docker.
  • Releases go through release-please; see that directory for config.

Invariants

BLOB-INV-RANGE — blob plugin transparently forwards partial/conditional headers

The plugins/blob handler is a transparent HTTP byte-proxy to MinIO; every code path through proxyToMinIO MUST:

  1. Forward Range, If-Range, If-None-Match, and If-Modified-Since verbatim onto the upstream MinIO request. Dropping these headers silently is not a perf optimisation — it coerces MinIO into 200 OK with the full object body on every request, which breaks <video>.fastSeek() and HTTP cache revalidation for every downstream consumer (multi-hundred-MB citation videos become unplayable). Per-endpoint header allow-lists in settings-env/input_headers.json do not apply to plugin/http-server handlers, so this responsibility lives entirely in the plugin code.
  2. Scope the 24 h Cache-Control: public, max-age=86400 to 200 OK responses only — 206 Partial Content bodies must never inherit the full-object cache directive (a CDN/browser would reuse them as if they were the whole object), and 304 Not Modified already carries the validator's own cache semantics.

Guarded by plugins/blob/main_test.go (unit, table-driven). Downstream consumers SHOULD pin an end-to-end k6 scenario in their own integration suite that exercises this protocol against a live gateway via derivedResourceUri.