cratestack-api 0.6.5

CrateStack server facade for procedures-only, no-database services — Axum HTTP bindings, generated Rust client runtime, and the shared schema/parser/policy/SQL surface, with `cratestack-sqlx` genuinely absent from the dependency graph. Pick this crate via `cratestack = { package = "cratestack-api" }` for `db = None` servers; pick `cratestack-pg` instead the moment a schema needs even one `model`.
Documentation

cratestack-api

The no-database server facade for CrateStack: Axum HTTP bindings, the generated Rust client runtime, and the shared schema / parser / policy / SQL surface — with cratestack-sqlx genuinely absent from the dependency graph, not just switched off.

When to use this crate

Pick cratestack-api for procedures-only, no-database services: a pure RPC/REST facade in front of another service, a stateless computation endpoint, or a gateway that only validates and forwards requests. Anything whose schema declares datasource { provider = "none" } and has no model blocks at all.

The moment a schema needs even one persisted model, switch to cratestack-pg instead — datasource { provider = "none" } schemas can never declare a model (enforced at parse time, cratestack#327), and this crate has no cratestack-sqlx dependency to serve one even if the schema tried.

cratestack-pg with default-features = false also supports db = None and continues to work — this crate doesn't replace that path, it just names the "I never touch Postgres" case directly instead of asking a consumer to depend on a crate named for the database backend they're explicitly opting out of. See docs/design/no-database-mode.md for the full design and both entry points.

Installation

Schema macros emit ::cratestack::* paths. Alias this crate as cratestack via Cargo's package = field:

[dependencies]
cratestack = { package = "cratestack-api", version = "0.6" }

Then in code:

cratestack::include_server_schema!("schema/foo.cstack", db = None);

include_server_schema!(schema, db = Postgres) under this crate fails to compile — there is no cratestack-sqlx-backed PgPool type here to satisfy the generated code. If a schema needs db = Postgres, depend on cratestack-pg instead.

Reproducing the db = Postgres compile error

cratestack-macros' guard_server_postgres_backend (cratestack#347) turns what would otherwise be a wall of unrelated E0432/E0433 "cannot find sqlx/SqlxRuntime/ModelDelegate in cratestack" errors into one clear message. This crate ships the fixture (tests/fixtures/compile_fail_postgres.cstack, unused by any checked-in test — see below for why) to make this exact and reproducible:

datasource db {
  provider = "postgresql"
}

model Widget {
  id Int @id
  name String
}

Drop a file anywhere under tests/ with:

cratestack::include_server_schema!("tests/fixtures/compile_fail_postgres.cstack", db = Postgres);

cargo test -p cratestack-api --test <that file's name> then fails with:

error: include_server_schema!(..., db = Postgres) requires a facade crate with `cratestack-sqlx`
support, but `cratestack-macros` was compiled without its `postgres` feature — this facade
(e.g. `cratestack-api`) has no `cratestack-sqlx` dependency at all, under any feature, so there
is no `sqlx::PgPool`/`SqlxRuntime` for this schema's generated code to use. Depend on
`cratestack = { package = "cratestack-pg" }` instead for `db = Postgres` schemas, or switch this
schema to `datasource { provider = "none" }` + `db = None` if it never actually needs a database
(see https://github.com/cratestack/cratestack/issues/347).

This isn't wired up as a permanent tests/*.rs file: Cargo auto-discovers every file under tests/ as a test target and would try to compile it as part of cargo check --all-targets/just all-checks, which is exactly what this scenario should not do successfully. Same precedent as crates/cratestack-pg/tests/no_database_procedures.rs's doc comment, which notes the equivalent negative case for guard_server_datasource_provider — a proc_macro::TokenStream compile-error path can't be exercised from a plain cargo test run, so it's demonstrated manually instead.

What this crate does not support

  • db = Postgres — fails to compile; see above. This crate is db = None-only, by design, not by an accidentally-missing feature.
  • transport grpc — cratestack-grpc/prost are not dependencies of this crate. gRPC codegen is entirely model-driven (CRUD routes generated per model block) and procedures aren't wired into the generated gRPC service at all, so a transport grpc schema under db = None could only ever produce a service with zero methods. transport rpc and REST (the default) both work fully.
  • Database migrations — there's no database to migrate.

Features

  • decimal-rust-decimal (default) — Decimal-typed procedure args/returns use rust_decimal. Forwards only to cratestack-core — there's no sqlx-backed half to gate, unlike cratestack-pg's same-named feature.
  • decimal-bigdecimal — alternative bigdecimal backend.
  • codec-json (default) — forwards the JSON codec to the generated client runtime, alongside CBOR.