Release 0.3.0 with daemon API and container packaging.

Document the full HTTP API surface, bump the version for the new daemon/upload/report capabilities, and add Docker build assets so goprecords can be packaged and deployed in f3s.

Made-with: Cursor

5 files changed, 127 insertions, 1 deletions

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..ddc0bae
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,6 @@
+.git
+.cursor
+goprecords
+tmp
+*.db
+*.log
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..6158745
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,20 @@
+FROM golang:1.21-alpine AS build
+WORKDIR /src
+
+RUN apk add --no-cache ca-certificates
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o /out/goprecords ./cmd/goprecords
+
+FROM alpine:3.20
+RUN apk add --no-cache ca-certificates
+
+WORKDIR /app
+COPY --from=build /out/goprecords /usr/local/bin/goprecords
+
+EXPOSE 8080
+
+ENTRYPOINT ["/usr/local/bin/goprecords"]
diff --git a/PLAN.md b/PLAN.md
new file mode 100644
index 0000000..bacd8a8
--- /dev/null
+++ b/PLAN.md
@@ -0,0 +1,14 @@
+# mage goprecords a microservice
+
+* Should run as a daemon, e.g. `goprecords --daemon`
+* Should have a configurable database path to a local directory
+* Local database is simply the input dir of the current goprecords CLI tool
+* Introduce an API to generate the available output formats, also include a HTML output format. All should be configurable using a query-parameter to the API.
+* Introduce an API to let clients upload new uprecords. see example database at /home/paul/git/uprecords/stats so every client should be able to upload 5 different files, HOSTNAME.{txt,cur.txt,records,os.txt,cpuinfo.txt}.
+* Use token-based authentication (e.g. API keys or JWT) for upload endpoints.
+* Upload should simply work using a curl CLI command given the auth is provided in the HTTP header.
+* have a way to manage different auth keys per client. not via API but via a local database and a `goprecords --create-client-key HOSTNAME`.
+
+
+
+
diff --git a/README.md b/README.md
index 791022e..655b2d5 100644
--- a/README.md
+++ b/README.md
@@ -79,6 +79,92 @@ goprecords --daemon -stats-dir="$HOME/git/uprecords/stats" -listen=":8080"
   - **`stats-order`**: comma-separated **`Category:Metric`** list when **`all`** is true
 - **`PUT /upload/{HOSTNAME}/{kind}`** — Writes one file under the stats directory; **`204`** on success. The **`HOSTNAME`** path segment must match the hostname the client key was issued for when auth is enforced.
 
+**HTTP API reference with curl**
+
+- **`GET /health`**
+  - Purpose: basic liveness probe.
+  - Success: `200 OK`, body `ok`.
+  - Example:
+
+```bash
+curl -i "http://127.0.0.1:8080/health"
+```
+
+- **`GET /livez`**
+  - Purpose: Kubernetes-style liveness probe (same semantics as `/health`).
+  - Success: `200 OK`, body `ok`.
+  - Example:
+
+```bash
+curl -i "http://127.0.0.1:8080/livez"
+```
+
+- **`GET /readyz`**
+  - Purpose: readiness probe (verifies required directories are readable and writable).
+  - Success: `200 OK`, body `ok`.
+  - Not ready: `503 Service Unavailable`.
+  - Example:
+
+```bash
+curl -i "http://127.0.0.1:8080/readyz"
+```
+
+- **`GET /report`**
+  - Purpose: generate reports from the daemon stats directory.
+  - Method: only `GET` (`405` for other methods).
+  - Main query parameters:
+    - `category`: `Host`, `Kernel`, `KernelMajor`, `KernelName`
+    - `metric`: `Boots`, `Uptime`, `Score`, `Downtime`, `Lifespan`
+    - `output-format`: `Plaintext`, `Markdown`, `Gemtext`, `HTML`
+    - `limit`: integer (default `20`)
+    - `all`, `include-kernel`: booleans
+    - `stats-order`: comma-separated `Category:Metric`
+    - aliases: `Category`, `Metric`, `OutputFormat`
+  - Content types:
+    - `Plaintext`/`Markdown`: `text/plain; charset=utf-8`
+    - `Gemtext`: `text/gemini; charset=utf-8`
+    - `HTML`: `text/html; charset=utf-8`
+  - Examples:
+
+```bash
+curl -fsS "http://127.0.0.1:8080/report?category=Host&metric=Uptime&limit=10&output-format=Plaintext"
+curl -fsS "http://127.0.0.1:8080/report?category=Kernel&metric=Boots&output-format=Gemtext"
+curl -fsS "http://127.0.0.1:8080/report?Category=Host&Metric=Score&OutputFormat=HTML&limit=5"
+curl -fsS "http://127.0.0.1:8080/report?all=true&include-kernel=true&output-format=Markdown"
+```
+
+- **`PUT /upload/{HOSTNAME}/{kind}`**
+  - Purpose: upload host files into the daemon stats directory.
+  - Method: only `PUT` (`405` for other methods).
+  - Success: `204 No Content`.
+  - Auth behavior:
+    - If no keys exist in auth DB: upload is accepted without `Authorization`.
+    - If one or more keys exist: requires `Authorization: Bearer <token>`.
+    - Missing/invalid header: `401 Unauthorized` (with `WWW-Authenticate: Bearer ...`).
+    - Wrong host/token pair: `403 Forbidden`.
+  - Examples:
+
+```bash
+# without auth (works only when no client keys exist in auth DB)
+curl -i -X PUT --data-binary @./myhost.records \
+  "http://127.0.0.1:8080/upload/myhost/records"
+
+# with auth (required when keys exist)
+TOKEN="..."  # from --create-client-key
+curl -i -X PUT --data-binary @./myhost.records \
+  -H "Authorization: Bearer $TOKEN" \
+  "http://127.0.0.1:8080/upload/myhost/records"
+```
+
+- **Create upload client key (CLI companion flow)**
+  - This is not an HTTP API endpoint. Key creation is intentionally CLI-only.
+  - Command examples:
+
+```bash
+goprecords --create-client-key myhost -stats-dir="$HOME/git/uprecords/stats"
+goprecords --create-client-key otherbox -auth-db=/var/lib/goprecords/goprecords-auth.db
+```
+
 **`GET /report` examples**
 
 ```bash
diff --git a/internal/version/version.go b/internal/version/version.go
index db740bd..c2e9b9f 100644
--- a/internal/version/version.go
+++ b/internal/version/version.go
@@ -1,4 +1,4 @@
 package version
 
 // Tag is the application release version.
-const Tag = "0.2.4"
+const Tag = "0.3.0"