blog

command
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 7 Imported by: 0

README

blog — the chok quickstart

A JWT-guarded blog API — register, log in, own your posts — in under a hundred lines of application code. main.go assembles it with plain Go: open the database, construct the identity and telemetry batteries, register them with the app, declare five routes. Nothing is generated.

The five-minute path

Requires Go 1.27. From the repository root:

cd examples/blog
export BLOG_AUTH_SIGNING_KEY=$(openssl rand -hex 32)   # ≥ 32 bytes, never in chok.yaml
go run .

The app logs the address it listens on (:8080 by default; set BLOG_HTTP_ADDR to move it). In a second terminal:

# 1. Health — every component reports in:
curl -s localhost:8080/healthz
# {"status":"up","components":[{"component":"db","status":"up",...},{"component":"identity",...},{"component":"telemetry",...}]}

# 2. Register, then log in (the identity battery mounts /auth/*). Without
#    the token every /api route is a 401 envelope — try it:
curl -s -X POST localhost:8080/auth/register -H 'Content-Type: application/json' \
  -d '{"email":"alice@example.com","password":"password123","name":"Alice"}'
TOKEN=$(curl -s -X POST localhost:8080/auth/login -H 'Content-Type: application/json' \
  -d '{"email":"alice@example.com","password":"password123"}' |
  python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])')
curl -s localhost:8080/api/v1/posts
# {"code":401,"reason":"Unauthorized","message":"a bearer token is required","request_id":"..."}

# 3. Create a post as alice:
curl -s -X POST localhost:8080/api/v1/posts -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"title":"Hello chok","content":"my first post"}'
# {"id":"pst_...","version":1,...,"title":"Hello chok","content":"my first post","status":"draft"}
RID=pst_...   # the id from the response

# 4. List your posts — owner-scoped, filterable by the query fields:
curl -s "localhost:8080/api/v1/posts?status=draft&order=created_at:desc" -H "Authorization: Bearer $TOKEN"
# {"items":[...],"total":1,"page":1,"size":20,"has_more":false}

# 5. Read one — bob, with a token of his own, gets a 404, as if it did
#    not exist:
curl -s localhost:8080/api/v1/posts/$RID -H "Authorization: Bearer $TOKEN"
curl -s -X POST localhost:8080/auth/register -H 'Content-Type: application/json' \
  -d '{"email":"bob@example.com","password":"password123","name":"Bob"}'
BOB=$(curl -s -X POST localhost:8080/auth/login -H 'Content-Type: application/json' \
  -d '{"email":"bob@example.com","password":"password123"}' |
  python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])')
curl -s localhost:8080/api/v1/posts/$RID -H "Authorization: Bearer $BOB"

# 6. Publish it, asserting the version you saw; send it again and the
#    now-stale version is a 409 Conflict:
curl -s -X PATCH localhost:8080/api/v1/posts/$RID -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"version":1,"status":"published"}'
curl -s -X PATCH localhost:8080/api/v1/posts/$RID -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"version":1,"status":"published"}'

# 7. Delete it (204), then reading it is a 404:
curl -s -X DELETE localhost:8080/api/v1/posts/$RID -H "Authorization: Bearer $TOKEN" -w '%{http_code}\n'
curl -s localhost:8080/api/v1/posts/$RID -H "Authorization: Bearer $TOKEN"

# 8. The OpenAPI 3.1 document the route table produced (UI at /docs):
curl -s localhost:8080/openapi.json

# 9. Prometheus metrics: every request above by method, route and status,
#    every SQL statement by operation and table. They have a port of
#    their own that only this host reaches (telemetry.metrics.addr);
#    localhost:8080/metrics is a 404:
curl -s localhost:9464/metrics | grep -E '^(http_server_request|db_client_operation)_duration_seconds_count'

Stop the server with Ctrl-C. Since /healthz has been requested, it and /readyz first answer 503 for http.drain_delay (5s by default), the pause a load balancer needs to move traffic away, and the log says so; a second Ctrl-C ends it. Then in-flight requests finish, components close in reverse order and the process exits 0. go run . --check-config validates the configuration and prints it with secrets masked, without starting anything.

What to look at

File Lesson
chok.yaml One strict config. A typo such as htpp: fails startup with "did you mean http?"; every key is BLOG_* overridable, and the signing key only comes from the environment.
main.go Config embeds chok.Base and adds a section per battery; setup is the whole assembly — values passed to constructors, tel.Instrument(d) adding the SQL metrics, lifecycle registered with app.Use, auth.Authn() guarding /api/v1.
posts.go Typed handlers: request structs bind path / json and validate; store.Patch turns a partial update into a locked change set.
blog_test.go The acceptance test that walks this path in process with choktest.App.

Without writing them you get: owner isolation (Post embeds db.OwnedSoftDeleteModel, and the owner is the token's user id), 404 / 409 / 401 error envelopes (store and identity errors describe themselves), request IDs on every log line, /readyz and /livez, login rate limiting, the OpenAPI document and the metrics on 127.0.0.1:9464/metrics. Set telemetry.tracing.enabled: true (with exporter: stdout to watch in the terminal) for a span per request and per SQL statement.

Documentation

Overview

Command blog is the chok quickstart: a JWT-guarded blog API where every post belongs to the user who wrote it.

cd examples/blog
BLOG_AUTH_SIGNING_KEY=$(openssl rand -hex 32) go run .

The walkthrough with curl commands is README.md next to this file.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL