ci: fix setup-go cache and refresh docs
setup-go@v5 aborts when go.sum is missing, and this stdlib-only module has none. Disable the action cache and cap the job at 10 minutes. Lead the README with what the service does and a runnable quick start, fix stale contract and cache comments, and remove comments that only restate the code.
This commit is contained in:
1 parent
80c8eeb0b9
commit
f4693af748
12 files changed
+66
-26
No files matched your search
@@ -1,6 +1,39 @@
|
||||
# api-go
|
||||
# PulseCast API
|
||||
|
||||
Golang API that is the backbone for daily usage, while python works in batches and is heavy in compute while Golang handles concurrent usage cheap
|
||||
Go service for PulseCast. It serves sensor series, live forecasts, staffing
|
||||
plans and scenario state over SSE, and proxies training to FastAPI. It keeps the
|
||||
FastAPI `/bootstrap` snapshot in memory, so reads survive FastAPI outages.
|
||||
|
||||
## Quick start
|
||||
|
||||
```sh
|
||||
go run ./cmd/api
|
||||
curl -s localhost:8080/api/healthz # {"ok":true}
|
||||
curl -s localhost:8080/api/readyz # 503 until the first /bootstrap snapshot
|
||||
```
|
||||
|
||||
The API listens on `:8080` and expects FastAPI at `http://localhost:8000`
|
||||
(`FASTAPI_URL`). It starts without FastAPI; readiness stays `503` until the
|
||||
first snapshot arrives. Control endpoints return `503` until `CONTROL_USER` and
|
||||
`CONTROL_PASS` are set.
|
||||
|
||||
## Endpoints
|
||||
|
||||
| Endpoint | Purpose |
|
||||
|---|---|
|
||||
| `GET /api/healthz` | Liveness. |
|
||||
| `GET /api/readyz` | Data and model readiness; `503` until the first snapshot. |
|
||||
| `GET /api/meta` | Versions, coverage, metrics and cache status. |
|
||||
| `GET /api/sensors` | Sensors sorted by id. |
|
||||
| `GET /api/series` | Observed series; query `sensor`, `from`, `to`, `step=15m\|1h`. |
|
||||
| `GET /api/context` | Weather and holidays. |
|
||||
| `GET /api/forecast` | Live forecast or last-good fallback; query `sensor`, `horizon`, `scenario`. |
|
||||
| `GET /api/staffing` | Shift plan; query `sensor`, `scenario`, `standard`. |
|
||||
| `GET /api/scenario` | Current scenario. |
|
||||
| `POST /api/scenario` | Set scenario (control auth) and broadcast it over SSE. |
|
||||
| `GET /api/stream` | SSE scenario events and the 15 s heartbeat. |
|
||||
| `POST /api/train` | Proxy training to FastAPI (control auth). |
|
||||
| `GET /api/train/{job_id}` | Training job status (control auth). |
|
||||
|
||||
## Checks
|
||||
|
||||
@@ -10,7 +43,8 @@ make check
|
||||
|
||||
Runs `go vet ./...`, `go test -count=1 ./...`, and `go build ./...`. The same
|
||||
target runs in Gitea Actions on every push and pull request
|
||||
(`.gitea/workflows/ci.yml`).
|
||||
(`.gitea/workflows/ci.yml`). CI does not run the integration or load tests;
|
||||
those need the ML checkout and raw CSV.
|
||||
|
||||
## Runtime data
|
||||
|
||||
@@ -32,10 +66,12 @@ the last good snapshot and retries with exponential backoff
|
||||
|
||||
| Env | Default | Purpose |
|
||||
|---|---|---|
|
||||
| `PORT` | `8080` | HTTP listen port |
|
||||
| `FASTAPI_URL` | `http://localhost:8000` | FastAPI base URL |
|
||||
| `BOOTSTRAP_REFRESH` | `60s` | Healthy snapshot refresh interval |
|
||||
| `BOOTSTRAP_TIMEOUT` | `20s` | Per-request `/bootstrap` timeout |
|
||||
| `ML_TIMEOUT` | `1500ms` | Per-request `/predict` timeout |
|
||||
| `SSE_HEARTBEAT` | `15s` | SSE ping interval |
|
||||
| `CONTROL_USER` / `CONTROL_PASS` | unset | Basic auth for `POST /api/scenario` and `/api/train*` |
|
||||
| `CONTROL_TOKEN` | unset | Optional Bearer token forwarded to FastAPI `/train*` |
|
||||
|
||||
@@ -45,7 +81,7 @@ the last good snapshot and retries with exponential backoff
|
||||
`:18080` is busy):
|
||||
|
||||
1. starts FastAPI from the ML checkout on `:18000` and the Go API on `:18080`;
|
||||
2. uploads a 24k-row CSV subset to `POST /api/train` and polls the job
|
||||
2. uploads a date-range CSV subset to `POST /api/train` and polls the job
|
||||
(`small`, then `forecast` by default);
|
||||
3. verifies the live forecast still answers, scenario propagation, the 15 s
|
||||
heartbeat and reconnect behaviour;
|
||||
@@ -65,7 +101,6 @@ against an API that is already up. The verified run is written up in
|
||||
[`docs/integration.md`](docs/integration.md) with raw evidence under
|
||||
`docs/results/`.
|
||||
|
||||
|
||||
## Container
|
||||
|
||||
The image is a multi-stage build. The runtime is
|
||||
|
||||
Reference in new issue
Block a user