jcoffey-dev
b6b092c912
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.
64 lines
2.4 KiB
Markdown
64 lines
2.4 KiB
Markdown
# 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.
|