GRI-2187: grimoirix-server crate and server skeleton #2

Merged
vivy merged 1 commit from feature/GRI-2187-grimoirix-server-skeleton into dev 2026-11-17 14:14:23 +00:00
Member

v0.1 scope, per the issue's "Done when" list.

Included

  • crates/grimoirix-server/: a small lib crate with one helper per issue item —
    • config — figment loader: built-in defaults → optional TOML file → <caller-chosen-prefix>-scoped env vars (__-nested). The prefix is a function parameter, never hard-coded, per GRI-1884.
    • telemetry — tracing-subscriber init, text or JSON, RUST_LOG overriding the configured level.
    • shutdown — a future resolving on SIGTERM/SIGINT (Ctrl-C on non-unix), for axum::serve(..).with_graceful_shutdown(..).
    • health — /healthz (always ok) and /readyz (a caller-supplied async readiness check, 200/503 + JSON body).
    • security_headers — a tower::Layer setting CSP (configurable, restrictive default), HSTS, X-Content-Type-Options, Referrer-Policy, X-Frame-Options.
    • error — ApiError (thiserror) → (StatusCode, JSON {"error": ...}), with Internal's cause logged via tracing and never shown to the client.
    • Every module has unit tests; 21 tests total, all green.
  • template/: a minimal binary depending on the crate (path dep inside this workspace; a real new project depends on the published version instead), with its own AppConfig extending CommonConfig via #[serde(flatten)], a sample config.sample.toml, and a Containerfile.
  • scripts/local-gates.sh: fmt, clippy -D warnings, test (incl. doc tests), cargo deny check — the only gates this repo needs (no database, no front end).
  • .github/workflows/ci.yml: the same gates as separate jobs.
  • .githooks/pre-push + scripts/install-git-hooks.sh: the house branch-naming/protected-branch hook, trimmed of the GitHub-mirror exception (not applicable here).
  • .repo-boundary, deny.toml (licenses allow-list incl. AGPL-3.0-only for this workspace's own crates), .cargo/config.toml (the grimoirix registry alias), LICENSE.md.
  • Root README.md: what's in the repo, how to start a new project from template/, how to depend on the published crate, and the release steps.

Deliberately excluded (per the issue)

Database, auth/sessions, mail, object store — product-specific, added per-project until a second product needs the same one. Moving helpdesk or signage onto this crate is a separate, later decision.

Verified locally

./scripts/local-gates.sh — all five gates pass (fmt clean, clippy clean with -D warnings, 21/21 tests + 0 doc tests, cargo deny check: advisories/bans/licenses/sources all ok).

Outstanding

cargo publish to the forge's Cargo registry has not been run. The forge token available in this environment has scopes write:issue, write:repository, read:user — not write:package. Publishing grimoirix-server 0.1.0 needs a token with that scope; README.md documents the exact command. This is a credential/governance step, not an implementation gap.

Once published, grimoirix-www (GRI-2176 M1) can take a dependency on it.

v0.1 scope, per the issue's "Done when" list. ## Included - `crates/grimoirix-server/`: a small lib crate with one helper per issue item — - `config` — figment loader: built-in defaults → optional TOML file → `<caller-chosen-prefix>`-scoped env vars (`__`-nested). The prefix is a function parameter, never hard-coded, per GRI-1884. - `telemetry` — `tracing-subscriber` init, text or JSON, `RUST_LOG` overriding the configured level. - `shutdown` — a future resolving on SIGTERM/SIGINT (Ctrl-C on non-unix), for `axum::serve(..).with_graceful_shutdown(..)`. - `health` — `/healthz` (always ok) and `/readyz` (a caller-supplied async readiness check, 200/503 + JSON body). - `security_headers` — a `tower::Layer` setting CSP (configurable, restrictive default), HSTS, X-Content-Type-Options, Referrer-Policy, X-Frame-Options. - `error` — `ApiError` (`thiserror`) → `(StatusCode, JSON {"error": ...})`, with `Internal`'s cause logged via `tracing` and never shown to the client. - Every module has unit tests; 21 tests total, all green. - `template/`: a minimal binary depending on the crate (path dep inside this workspace; a real new project depends on the published version instead), with its own `AppConfig` extending `CommonConfig` via `#[serde(flatten)]`, a sample `config.sample.toml`, and a `Containerfile`. - `scripts/local-gates.sh`: fmt, clippy -D warnings, test (incl. doc tests), `cargo deny check` — the only gates this repo needs (no database, no front end). - `.github/workflows/ci.yml`: the same gates as separate jobs. - `.githooks/pre-push` + `scripts/install-git-hooks.sh`: the house branch-naming/protected-branch hook, trimmed of the GitHub-mirror exception (not applicable here). - `.repo-boundary`, `deny.toml` (licenses allow-list incl. `AGPL-3.0-only` for this workspace's own crates), `.cargo/config.toml` (the `grimoirix` registry alias), `LICENSE.md`. - Root `README.md`: what's in the repo, how to start a new project from `template/`, how to depend on the published crate, and the release steps. ## Deliberately excluded (per the issue) Database, auth/sessions, mail, object store — product-specific, added per-project until a second product needs the same one. Moving helpdesk or signage onto this crate is a separate, later decision. ## Verified locally `./scripts/local-gates.sh` — all five gates pass (fmt clean, clippy clean with `-D warnings`, 21/21 tests + 0 doc tests, `cargo deny check`: advisories/bans/licenses/sources all ok). ## Outstanding **`cargo publish` to the forge's Cargo registry has not been run.** The forge token available in this environment has scopes `write:issue`, `write:repository`, `read:user` — not `write:package`. Publishing `grimoirix-server 0.1.0` needs a token with that scope; README.md documents the exact command. This is a credential/governance step, not an implementation gap. Once published, `grimoirix-www` (GRI-2176 M1) can take a dependency on it.
GRI-2187: grimoirix-server crate and template skeleton
All checks were successful
CI / cargo fmt (pull_request) Successful in 4s
CI / cargo clippy (pull_request) Successful in 52s
CI / cargo test (pull_request) Successful in 1m3s
CI / cargo deny (pull_request) Successful in 1m24s
be062afb0a
v0.1 scope: config (figment defaults -> TOML -> env, caller-chosen prefix),
telemetry init, graceful shutdown, /healthz + /readyz, a security-headers
tower layer, and an ApiError -> HTTP response mapping. template/ is the
copy-able skeleton binary using it. Gates: cargo fmt, clippy -D warnings,
test (incl. doc tests), cargo deny, wired into scripts/local-gates.sh and
.github/workflows/ci.yml. Branch-naming pre-push hook and .repo-boundary
carried over from the house convention.
vivy merged commit 44f3226a8a into dev 2026-11-17 14:14:23 +00:00
vivy deleted branch feature/GRI-2187-grimoirix-server-skeleton 2026-11-17 14:14:24 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
Grimoirix/grimoirix-backend-libs!2
No description provided.