Scaffold Phase 0: agent -> Redpanda -> ingest -> ClickHouse -> api -> web
End-to-end log pipeline for Linux hosts, per /docs/architecture.md: - proto: shared gRPC contract (agent <-> ingest), Go bindings checked in - agent: Rust, musl-targeted, journald/file sourcing, RFC5424 parser, mTLS gRPC client, no required config for the common case - ingest: Go, single binary with --mode server|consumer|all; gRPC front end forwards to Redpanda unchanged, consumer normalizes and batch-writes to ClickHouse with at-least-once delivery - storage: ClickHouse schema + a plain SQL-file migration runner - api: minimal SELECT-only query endpoint, plain REST (not gRPC+gateway yet -- see api/README.md) - web: SvelteKit static SPA, one query page - transport: Redpanda compose + topic provisioning - cli: sentryctl ping stub - hack/dev-certs: throwaway CA + cert generation for local mTLS - root docker-compose.yml + docs/phase-0-runbook.md tie it together Not yet run end-to-end against real Docker/ClickHouse/Redpanda -- see the runbook's caveats section before relying on this working as-is.
This commit is contained in:
@@ -0,0 +1,63 @@
|
||||
# api
|
||||
|
||||
Sentry's Phase 0 query API: one crude, intentionally placeholder endpoint.
|
||||
|
||||
## Why plain REST, not gRPC + REST gateway
|
||||
|
||||
CLAUDE.md pins the control plane to "Go, gRPC + REST gateway." This
|
||||
service is plain `net/http` instead — a deliberate Phase 0 simplification,
|
||||
not a change to the pinned stack. Wiring up a `.proto` service,
|
||||
`google.api.http` annotations, and `protoc-gen-grpc-gateway` codegen for a
|
||||
single endpoint that Phase 2 replaces outright with a real SPL-like query
|
||||
layer would be exactly the kind of premature machinery this project's
|
||||
conventions warn against. Adopt the gRPC+gateway pattern once `/api` grows
|
||||
a second real, durable endpoint.
|
||||
|
||||
## Endpoints
|
||||
|
||||
- `POST /query` — body `{"sql": "SELECT ..."}`, response
|
||||
`{"columns": [...], "rows": [[...], ...]}` or `{"error": "..."}`.
|
||||
SELECT-only, single-statement, basic keyword-based injection guarding
|
||||
(see `internal/queryapi/validate.go` for exactly what that does and
|
||||
doesn't catch — it's not a SQL parser).
|
||||
- `GET /healthz` — for docker-compose/k8s liveness checks.
|
||||
|
||||
No auth. Not scoped for Phase 0 — don't expose this beyond a trusted
|
||||
dev/homelab network.
|
||||
|
||||
## Configuration
|
||||
|
||||
Environment variables (see `internal/config/config.go`):
|
||||
|
||||
| Var | Default | Purpose |
|
||||
|---|---|---|
|
||||
| `HTTP_LISTEN_ADDR` | `:8080` | |
|
||||
| `CLICKHOUSE_ADDR` | `localhost:9000` | Native protocol port |
|
||||
| `CLICKHOUSE_DATABASE` / `_USERNAME` / `_PASSWORD` | `sentry` / `default` / `` | |
|
||||
| `QUERY_TIMEOUT_SECONDS` | `30` | Per-request ClickHouse query timeout |
|
||||
| `CORS_ALLOWED_ORIGIN` | `*` | Wide open by default since there's no auth yet; tighten together |
|
||||
|
||||
## Building & testing
|
||||
|
||||
```sh
|
||||
go build ./...
|
||||
go vet ./...
|
||||
go test ./...
|
||||
```
|
||||
|
||||
```sh
|
||||
# from the repo root, not api/
|
||||
docker build -f api/Dockerfile -t sentry-api .
|
||||
```
|
||||
|
||||
## Testing notes
|
||||
|
||||
`internal/queryapi`'s HTTP handler depends on ClickHouse only through a
|
||||
one-method `queryExecutor` interface, so routing, validation, JSON
|
||||
encoding, and error-status mapping are all unit-tested against a fake —
|
||||
no live ClickHouse needed. `Executor` itself (the reflection-based row
|
||||
scanning against `driver.Rows`) is not unit-tested — faking ClickHouse's
|
||||
`driver.Rows` interface fully would be significant test-only scaffolding
|
||||
for a Phase 0 placeholder, and the driver package's own docs note it isn't
|
||||
meant to be implemented by adopters. It's exercised end-to-end via the
|
||||
docker-compose flow in `/docs/phase-0-runbook.md` instead.
|
||||
Reference in New Issue
Block a user