The starting point and shared base crate for every Grimoirix Rust server.
  • Rust 81.8%
  • Shell 16.7%
  • Dockerfile 1.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
vivy 16f7138f52
All checks were successful
CI / cargo fmt (push) Successful in 3s
CI / cargo deny (push) Successful in 33s
CI / cargo clippy (push) Successful in 42s
CI / cargo test (push) Successful in 44s
Merge pull request 'GRI-2187: document the Bearer prefix for the publish token' (#5) from docs/GRI-2187-publish-token-format into dev
2026-11-17 17:26:27 +00:00
.cargo GRI-2187: grimoirix-server crate and template skeleton 2026-11-17 14:05:14 +00:00
.githooks GRI-2187: grimoirix-server crate and template skeleton 2026-11-17 14:05:14 +00:00
.github/workflows GRI-2187: document the Bearer prefix for the publish token 2026-11-17 17:23:05 +00:00
crates/grimoirix-server GRI-2187: grimoirix-server crate and template skeleton 2026-11-17 14:05:14 +00:00
scripts GRI-2187: grimoirix-server crate and template skeleton 2026-11-17 14:05:14 +00:00
template GRI-2187: grimoirix-server crate and template skeleton 2026-11-17 14:05:14 +00:00
.gitignore GRI-2187: grimoirix-server crate and template skeleton 2026-11-17 14:05:14 +00:00
.repo-boundary GRI-2192: rename repository to grimoirix-backend-libs 2026-11-17 17:11:47 +00:00
Cargo.lock GRI-2187: grimoirix-server crate and template skeleton 2026-11-17 14:05:14 +00:00
Cargo.toml GRI-2192: rename repository to grimoirix-backend-libs 2026-11-17 17:11:47 +00:00
deny.toml GRI-2187: grimoirix-server crate and template skeleton 2026-11-17 14:05:14 +00:00
LICENSE.md GRI-2187: grimoirix-server crate and template skeleton 2026-11-17 14:05:14 +00:00
README.md GRI-2187: document the Bearer prefix for the publish token 2026-11-17 17:23:05 +00:00
rust-toolchain.toml GRI-2187: grimoirix-server crate and template skeleton 2026-11-17 14:05:14 +00:00

grimoirix-backend-libs

A spellbook library of open-source tools. In a closed world, Grimoirix builds bridges. "Freedom is a choice. Share it."

The starting point and shared base crate for every Grimoirix Rust server. Every server needs the same handful of things before it can take traffic — configuration, logging, graceful shutdown, a health check, a baseline set of security headers, and a way to turn an error into an HTTP response without leaking internals — and this repository gives them once, the way grimoirix-frontend-template does for the front end.

What is in it

crates/grimoirix-server/   the library: config, telemetry, shutdown, health,
                            security headers, error-to-response mapping —
                            every helper has its own tests
template/                   a minimal server binary that uses the crate —
                            the copy-able starting point for a new project

What is deliberately not in it: database, auth, sessions, mail, object storage. Those differ per product and are added directly to a project until a second product needs the same one — at which point it is proposed here instead of being written twice.

Start a new project from template/

  1. Copy the template/ directory into the new repository.

  2. Rename the package in its Cargo.toml (grimoirix-server-template → your project's name).

  3. Point the grimoirix-server dependency at the published crate instead of the path dependency the template uses to build against this repository's own copy:

    [dependencies]
    grimoirix-server = { version = "0.1", registry = "grimoirix" }
    
  4. Copy .cargo/config.toml from this repository too (or merge its [registries.grimoirix] section into your own) — that is what tells Cargo where the grimoirix registry actually is:

    [registries.grimoirix]
    index = "sparse+https://git.grimoirix.org/api/packages/Grimoirix/cargo/"
    

    This is the default, not a fixed value: nothing stops a project from pointing it at a different index if it ever needs to.

  5. Build your own AppConfig on top of grimoirix_server::CommonConfig the way template/src/main.rs does (#[serde(flatten)]), pick your own environment-variable prefix (never reuse another project's — see GRI-1884), and build your routes on top of router().

The repository and the package are public, so no token is needed to depend on the crate — only to publish a new version (below).

Depend on the crate directly

If you are not starting from the template but still want the shared helpers:

[dependencies]
grimoirix-server = { version = "0.1", registry = "grimoirix" }

with the same .cargo/config.toml registry block as above.

Module What it is
grimoirix_server::config the figment loader: defaults → TOML → env
grimoirix_server::telemetry tracing-subscriber init, text or JSON
grimoirix_server::shutdown the SIGTERM/Ctrl-C future for graceful shutdown
grimoirix_server::health /healthz and /readyz, with your own readiness check
grimoirix_server::security_headers CSP, HSTS, nosniff, referrer-policy, X-Frame-Options
grimoirix_server::error ApiError → (StatusCode, JSON body)

Change the crate

Build and test it the normal cargo way:

cargo fmt --all
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --all-targets --locked
cargo deny check

or all of it at once: scripts/local-gates.sh. Every helper is expected to keep its own tests — a change with no test is not finished.

A shared helper is changed here first, never only in a project: if a project needs a new piece of common start-up behaviour, it goes into this crate, is released, and the project takes the new version.

Release it

When a change is merged to dev:

  1. Raise version in crates/grimoirix-server/Cargo.toml (semantic versioning: PATCH/MINOR need no change in a consuming project, MAJOR says in its notes what to change).
  2. Tag the commit v<version> and push the tag.

.github/workflows/release.yml publishes the crate itself: it runs cargo publish on a v* tag push, authenticated with the repository secret CARGO_REGISTRY_TOKEN. The secret holds a forge token with the write:package scope with the Bearer prefix, as Bearer <token>. The forge's Cargo registry refuses a bare token with 401 and the body authGroup.Verify; that is what the first v0.1.0 run failed on. The token belongs to the publish-only account grimoirix-release (team package-publishers, packages write, no code access). To publish by hand instead:

cargo publish --registry grimoirix \
  --token "Bearer <token-with-write:package-scope>" \
  -p grimoirix-server

Projects using it

  • grimoirix-www (GRI-2176 M1) — its file server can depend on grimoirix-server = { version = "0.1", registry = "grimoirix" }.

License

See LICENSE.md.