- Rust 81.8%
- Shell 16.7%
- Dockerfile 1.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .cargo | ||
| .githooks | ||
| .github/workflows | ||
| crates/grimoirix-server | ||
| scripts | ||
| template | ||
| .gitignore | ||
| .repo-boundary | ||
| Cargo.lock | ||
| Cargo.toml | ||
| deny.toml | ||
| LICENSE.md | ||
| README.md | ||
| rust-toolchain.toml | ||
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/
-
Copy the
template/directory into the new repository. -
Rename the package in its
Cargo.toml(grimoirix-server-template→ your project's name). -
Point the
grimoirix-serverdependency 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" } -
Copy
.cargo/config.tomlfrom this repository too (or merge its[registries.grimoirix]section into your own) — that is what tells Cargo where thegrimoirixregistry 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.
-
Build your own
AppConfigon top ofgrimoirix_server::CommonConfigthe waytemplate/src/main.rsdoes (#[serde(flatten)]), pick your own environment-variable prefix (never reuse another project's — see GRI-1884), and build your routes on top ofrouter().
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:
- Raise
versionincrates/grimoirix-server/Cargo.toml(semantic versioning: PATCH/MINOR need no change in a consuming project, MAJOR says in its notes what to change). - 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 ongrimoirix-server = { version = "0.1", registry = "grimoirix" }.
License
See LICENSE.md.