rackattack

Quick start

Mon, 01 Jan 0001 00:00:00 +0000

Quick start — generate a datacenter, then ask an agent#

From an empty checkout to a browser-viewable gallery of live diagrams and an agent answering plain-language questions over MCP. About five minutes.

0. Prerequisites#

Go 1.25, Docker (for the CockroachDB dev node), and just.
Graphviz — the one non-obvious dependency. The blast-radius frame shells out to dot; without it that hero frame fails (the other four screens are pure Go).

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Architecture#

rackattack is one service core behind four interfaces. gRPC is the primary product contract; REST comes essentially for free via grpc-gateway over the same proto; GraphQL (gqlgen) is a third HTTP transport; and MCP is a thin secondary adapter (built last) that maps the same core to agent tools. All four speak to a single core that does validation, complex filtering, aggregation, and bulk operations, then walks the infra graph and renders the result.

Data model & schema

Mon, 01 Jan 0001 00:00:00 +0000

Data model & schema#

The infra graph is 16 CockroachDB tables across these concerns: a spatial hierarchy, devices with their ports and pluggable optical transceivers, a power chain with A/B redundancy, physical cabling, cooling, and logical fabric links. A 17th table — audit_log — is operational rather than part of the graph (it records change-data-capture events; see Audit & CDC). The diagram below reflects the migrations in internal/schema/migrations exactly.

Entity/relationship diagram of the 17-table schema

Spatial hierarchy#

sites → floors → rack_rows → racks → rack_units → devices → ports. Each level references its parent; racks also carry a cooling_budget_watts, and devices carry watts and heat_watts so power and thermal rollups have real numbers.

Rendering

Mon, 01 Jan 0001 00:00:00 +0000

Rendering — the differentiator#

A GUI is a persistent app you navigate; rackattack cuts it. A visualization is just an artifact the service renders on demand and hands back. The agent is the input, a generated artifact is the output: you ask a question in plain language and rackattack renders exactly the picture that answers it — blast radius with only the affected racks lit red, survivors green, everything else dimmed. The diagram is an answer, not a map.

MCP (agent interface)

Mon, 01 Jan 0001 00:00:00 +0000

MCP (agent interface)#

MCP is rackattack’s front door for an LLM agent. The Model Context Protocol adapter is a thin secondary transport — alongside gRPC, REST, and GraphQL — that maps the same service core to agent tools. It runs over JSON-RPC on stdio, so an agent launches rackattack mcp as a subprocess and calls tools directly; no network port, no auth handshake.

Every screen-generating tool returns structured data and a rendered diagram in one reply (the diagram comes back base64-encoded under render.image), so an agent gets both the facts and the picture from a single call.

CLI reference

Mon, 01 Jan 0001 00:00:00 +0000

CLI reference#

The rackattack binary is a single CLI with six subcommands. Runtime behaviour is configured through environment variables (see Configuration); the flags below control per-invocation inputs.

rackattack [command]

 serve Run the gRPC service and the REST (grpc-gateway) endpoint
 mcp Run the MCP adapter over stdio
 migrate Apply database migrations
 fleet Generate a synthetic datacenter fleet
 example Generate a sample fleet and a guided-tour gallery
 query Run a single query and print a summary

 -h, --help help for rackattack
 -v, --version version for rackattack

Every subcommand reads DATABASE_URL (default postgres://root@localhost:26257/rackattack?sslmode=disable). All commands that need a schema (serve, fleet, example) auto-migrate first, so a separate migrate run is optional.

API surface

Mon, 01 Jan 0001 00:00:00 +0000

API surface#

rackattack is one service core behind four interfaces. gRPC is the primary product contract. REST is generated from the same proto via grpc-gateway and served in-process. GraphQL (gqlgen, schema-first) is a third HTTP transport over the same core. MCP is a thin secondary adapter mapping the core to agent tools.

All four resolve through the single service core, so authorization, caching, and audit apply uniformly no matter which door a request comes in.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration#

Every runtime setting is an environment variable. The binary reads them at startup; there is no config file. Defaults are tuned for a one-command local evaluation (single-node CockroachDB, auth off) — review the production-relevant rows before exposing rackattack (see Security & auth, Deployment, and the production design in docs/production-deployment.md).

Booleans accept 1 / true / yes / on (and their negatives).

Server & database#

Env	Meaning	Default
`DATABASE_URL`	CockroachDB (Postgres-compatible) connection string. Used by every subcommand.	`postgres://root@localhost:26257/rackattack?sslmode=disable`
`GRPC_ADDR`	Listen address for the gRPC server (`serve`).	`:8080`
`HTTP_ADDR`	Listen address for the HTTP server (`serve`) — REST gateway, GraphQL, `/metrics`, and `/audit/*`.	`:8081`
`DB_MAX_CONNS`	Max size of the pgx connection pool — the knob to tune under concurrent load. Can also be set with a `pool_max_conns` query param on `DATABASE_URL`.	pgx default: `max(4, GOMAXPROCS)`
`DB_TLS_ROOT_CERT`	Path to the CA certificate (PEM) used to verify the CockroachDB server cert under `sslmode=verify-full`, when you’d rather not put `sslrootcert=` in `DATABASE_URL` (e.g. a mounted k8s Secret). Ignored if the URL already sets `sslrootcert`.	unset
`SHUTDOWN_GRACE_PERIOD`	On `SIGTERM`/`SIGINT`, `serve` stops accepting new work and drains in-flight gRPC RPCs and HTTP requests within this budget (Go duration) before exiting. Keep it under the pod’s `terminationGracePeriodSeconds` (30s).	`25s`
`RACKATTACK_ENV`	Set to `production` (or `prod`) to enable the production guardrail: `serve` refuses to boot with edge auth disabled, or a `DATABASE_URL` that doesn’t verify TLS (anything other than `sslmode=verify-full` or `verify-ca` — `disable`/`allow`/`prefer`/`require`/unset all fail), failing fast with a clear error. Production mode also disables the GraphQL playground and gRPC reflection. Any other value (or unset) is development mode.	unset (development)
`HTTP_MAX_BODY_BYTES`	Maximum request-body size (bytes) accepted on the HTTP app surface (GraphQL, REST, bulk upserts); oversized requests are rejected. Raise it if you bulk-import very large fleets.	`8388608` (8 MiB)

In production, DATABASE_URL should use sslmode=verify-full against a secure CockroachDB and a non-root, least-privilege SQL user — not the insecure local default. Supply the cluster CA via sslrootcert= in the URL or DB_TLS_ROOT_CERT; with RACKATTACK_ENV=production the server refuses to boot on sslmode=disable.

Security & auth

Mon, 01 Jan 0001 00:00:00 +0000

Security & authentication#

rackattack validates signed OIDC/JWT bearer tokens at every transport edge and gates the surface with role-based authorization in the shared service core — so the same rules apply whether a request arrives over gRPC, REST, or GraphQL.

How it works#

Token validation at the edge. A gRPC unary interceptor and an HTTP middleware (covering both REST and GraphQL) validate the bearer token and extract a principal.
Authorization in the core. The principal flows into a shared Authorizer that gates the surface: reads are open to any authenticated principal, while mutations and bulk operations require a writer/admin role. Because REST and GraphQL call the service in-process, authorization lives in the wrapper they all share — not only in the gRPC chain.

Both RS256/ES256 (via a JWKS endpoint) and HS256 (via a configured symmetric secret) are supported.

Caching

Mon, 01 Jan 0001 00:00:00 +0000

Read caching#

Hot read RPCs — the screens plus device/rack lookups — are memoized by a read-through cache that wraps the service core. A cache hit skips the recursive SQL and the SVG render entirely.

Backends#

The cache is a seam with two interchangeable backends:

In-process LRU (default, single replica) — CACHE_SIZE entries (default 1024), expiring after CACHE_TTL (default 30s).
Redis (multi-replica) — set REDIS_ADDR=host:6379. All replicas share one cache, so an invalidation on any replica is seen by all.

Env	Meaning	Default
`CACHE_ENABLED`	turn the read cache on/off	`true`
`CACHE_TTL`	entry time-to-live	`30s`
`CACHE_SIZE`	LRU capacity (entries)	`1024`
`REDIS_ADDR`	use Redis instead of the in-process LRU when set	—

Run Redis when you run more than one replica. The in-process LRU is per-pod, so a mutation on pod A leaves pod B’s cache stale until the TTL expires. A shared Redis gives global invalidation — set REDIS_ADDR on every replica. A single replica is fine on the LRU.

Audit & CDC

Mon, 01 Jan 0001 00:00:00 +0000

Audit logging & change data capture#

Mutations are captured to an audit_log table via CockroachDB change-data-capture (CHANGEFEED) and read back over HTTP. Tracked tables: devices, racks, crac_units, cables, and fabric_links.

Reading the history#

serve exposes the change history on the HTTP port:

curl -s 'localhost:8081/audit/history?table=racks&limit=50' | jq

Two delivery paths, one destination#

Both paths land each change in audit_log; pick one.

In-process core changefeed (default in k8s, license-free). Set AUDIT_CHANGEFEED=true and serve runs an EXPERIMENTAL CHANGEFEED over its own connection, recording each change. No inbound network needed — ideal for self-hosted/dev. Single-replica only: this feed runs inside every replica, so at more than one replica each mutation is recorded once per replica (duplicate audit_log rows). serve warns about this at startup. Run it on exactly one replica, or use the webhook sink below.

Fleet generator & guided tour

Mon, 01 Jan 0001 00:00:00 +0000

Fleet generator & guided tour#

More than a seeder: a self-driving guided tour. A scale knob produces a synthetic datacenter, then the tour mines its own interesting scenarios, writes the prompts, runs them, and emits the diagrams — so any size of fleet produces its own narrated walkthrough. Use it to evaluate rackattack against realistic sample data before you wire in your own inventory.

generate → mine → prompt → run → render

Generate a fleet (tunable, deterministic)#

rackattack fleet new --sites 8 --racks-per-row 20 --oversub 3:1 \
 --redundancy ab --seed 42

Scales from one rack → row → site → multi-site.
Plausible topology: leaf-spine switching, structured cabling through patch panels, A/B power, realistic device mixes and power/heat profiles.
Deterministic from --seed — same seed reproduces the same fleet. Benchmarks, tests, and the example preset all depend on this.
Plants guaranteed-interesting scenarios: a single-point-of-failure feed, an over-budget thermal hotspot, a congested fabric uplink.

Run the guided tour (mine → prompt → run → render)#

rackattack example run --preset example --out example-out

Mine — biggest-blast-radius feed, hottest rack, longest cable path, most-congested link.
Prompt — template natural-language questions around them (optionally LLM-phrased for variety).
Run — map each prompt to its tool call and execute.
Render — emit the diagrams into a narrated gallery. At the example preset this reproduces NARRATIVE.md exactly.

In production the prompt → tool mapping is your own LLM agent over MCP; the guided tour is a scripted stand-in that proves the pipeline without a live agent.

Performance & scale

Mon, 01 Jan 0001 00:00:00 +0000

Performance & scale#

The fleet generator exists so benchmarks are run against a real synthetic datacenter, not a toy. Full numbers, method, and reproduction steps are in BENCHMARKS.md; this page is the orientation.

Hot-query latency#

End-to-end latency of the three recursive/rollup queries, measured with hyperfine via the rackattack query <screen> CLI (a full process → connect → query round-trip, run scripts/bench.sh):

Query	Mean	Notes
`PowerBlastRadius`	~193 ms	heaviest — recursive walk of the whole power chain
`TraceCablePath`	~28 ms	single port-graph path, ~constant in fleet size
`ThermalHeadroom`	~12 ms	grouped aggregate over one floor

Reproduce on your own hardware with just bench.

Deployment

Mon, 01 Jan 0001 00:00:00 +0000

Deployment#

rackattack ships as a CGO-free static binary on debian:bookworm-slim with graphviz installed (the blast-radius renderer shells out to dot). The Kubernetes manifests in deploy/k8s/ are a kustomize base + overlay: base/ runs a single-node CockroachDB StatefulSet plus the rackattack Deployment (dev/evaluation), and production/ layers secrets and auth on top.

The service is configured entirely through environment variables — see the Configuration reference for every setting and its default.

Kubernetes topology (validated locally on k3d)

What’s deployed#

StatefulSet crdb + a headless Service — CockroachDB running start-single-node --insecure (dev only).
Deployment rackattack — init containers create the database and apply migrations before serve starts; the Service exposes gRPC :8080 and REST :8081.

Local validation on k3d#

./scripts/k3d-up.sh # build image, create cluster, import image, apply, wait green
./scripts/k3d-down.sh # delete the cluster

k3d-up.sh builds the image (if missing), creates the cluster, imports the local image, kubectl apply -k deploy/k8s/base, then waits on rollout status for the StatefulSet and Deployment. Reach the service with:

Minimal deployment

Mon, 01 Jan 0001 00:00:00 +0000

Minimal deployment — single host (docker compose)#

The cheapest way to actually run rackattack: the whole stack on one host via docker compose — the app, a secure single-node CockroachDB, and an edge TLS proxy — with no Kubernetes, no operator, no managed database, no load balancer. It’s a real secure small-prod posture for a homelab, colo, or small cloud, not a throwaway.

This is one of three deploy paths (see the Deployment chooser). The stack lives in deploy/compose/ and is authored in chant (TypeScript → compose.yaml).

Observability

Mon, 01 Jan 0001 00:00:00 +0000

Observability#

serve is instrumented with Prometheus metrics and OpenTelemetry traces end to end, so a request can be watched as RPC → query → render.

Metrics (Prometheus)#

Metrics are exposed at /metrics on the HTTP port. The endpoint is unauthenticated — it sits outside the auth middleware so scrapers reach it without a token.

curl -s localhost:8081/metrics | grep rackattack_

What’s exported:

Per-RPC rate / latency / error — rackattack_rpc_requests_total{method,code}, rackattack_rpc_duration_seconds (gRPC); plus rackattack_http_requests_total{route,status} for REST + GraphQL.
DB pool saturation — rackattack_db_pool_{total,acquired,idle,max}_conns.
Cache hit ratio — rackattack_cache_{hits,misses}_total.
Go runtime + process collectors.

The k8s pod template carries prometheus.io/{scrape,port,path} annotations for annotation-based discovery (or use a ServiceMonitor with the Prometheus Operator).

Interaction model

Mon, 01 Jan 0001 00:00:00 +0000

Interaction model#

The hover and select frames in assets/ aren’t separate renders — they’re states of one interactive artifact. The interactive HTML embeds the dataset, so hover is purely client-side (zero calls); only a click that opens the inspector hydrates detail via GetDevice / GetPort.

Default → Hover → Select states and their call costs

States#

Default — the full render.
Hover (rollover) — client-side highlight of the node under the pointer. No server calls.
Select (click) — opens the inspector for the clicked node, hydrated with a GetDevice or GetPort call. As an operator clicks deeper, each click is one more lookup.

Locked conventions#

The visual design system and interaction vocabulary are locked in assets/DESIGN.md: palette, typography, heat gradients, device icons, and the semantic highlight rules (dead = red, survives = green). Renderers reproduce the approved mockups; they don’t invent a new look. The interaction-cost model is detailed in TOOLS.md.

Contributing

Mon, 01 Jan 0001 00:00:00 +0000

Contributing#

Toolchain#

Go 1.25 · Docker · protoc (+ protoc-gen-go, protoc-gen-go-grpc, protoc-gen-grpc-gateway) · dot (Graphviz) · rsvg-convert · hugo (extended, for these docs) · just.

Local setup#

# 1. start CockroachDB (single-node, insecure) for dev
just up # docker compose up

# 2. apply migrations and generate a fleet
rackattack migrate
rackattack fleet new --preset example

# 3. run the service (gRPC :8080, REST :8081)
rackattack serve

# 4. ask a blast-radius question over REST
curl -s localhost:8081/rackattack.v1.Rackattack/PowerBlastRadius \
 -d '{"source_ref":"feed:B-3"}'

Common just recipes: up / down (CockroachDB), bench (hyperfine on hot queries), image (container build), k3d-up / k3d-down (local cluster), and the docs recipes below.