cratestack/
lib.rs

1//! CrateStack server facade — Postgres (sqlx) + Axum.
2//!
3//! This crate is the server-side slice of the framework. It re-exports the
4//! shared schema / parser / policy / SQL surface plus the sqlx (Postgres)
5//! runtime, Axum HTTP bindings, and the generated Rust client runtime.
6//!
7//! It deliberately does **not** depend on `cratestack-rusqlite`. That keeps
8//! `libsqlite3-sys` out of the dep graph, so consumers can use the official
9//! `sqlx` umbrella crate (which optionally declares `sqlx-sqlite` and trips
10//! Cargo's `links = "sqlite3"` collision rule) without needing a local
11//! `sqlx-shim` workaround.
12//!
13//! For embedded / mobile / wasm targets, depend on `cratestack-sqlite`
14//! instead. The two crates are strictly disjoint by design.
15//!
16//! Schema macros emit `::cratestack::*` paths, so consumers rename this
17//! crate via Cargo's `package =` field:
18//!
19//! ```toml
20//! [dependencies]
21//! cratestack = { package = "cratestack-pg", version = "0.4" }
22//! ```
23
24// Both `cratestack_core` and `cratestack_axum` expose `codec` and
25// `transport` modules, and the facade re-exports both crates with a glob.
26// The overlap is intentional — consumers reach those via the originating
27// crate's path, not the facade root — so silence the ambiguity warning
28// rather than dropping either glob.
29#![allow(ambiguous_glob_reexports)]
30
31pub use chrono;
32pub use cratestack_client_rust as client_rust;
33pub use cratestack_core::*;
34pub use cratestack_macros::{
35    include_client_schema, include_embedded_schema, include_server_schema,
36};
37pub use cratestack_parser::{SchemaError, parse_schema, parse_schema_file, parse_schema_named};
38pub use cratestack_policy::{
39    PolicyExpr, PolicyLiteral, ProcedureArgs, ProcedurePolicy, ProcedurePolicyExpr,
40    ProcedurePolicyLiteral, ProcedurePredicate, ReadPolicy, ReadPredicate, RelationQuantifier,
41    authorize_procedure,
42};
43
44// SQL primitives shared by every backend — re-exported directly from
45// `cratestack-sql` so consumers don't transit through `cratestack-sqlx`.
46pub use cratestack_sql::{
47    CoalesceExpr, CoalesceFilter, ConflictTarget, CreateDefault, CreateDefaultType,
48    CreateModelInput, FieldRef, Filter, FilterExpr, FilterOp, IntoColumnName, IntoSqlValue,
49    JsonFilter, JsonTextPath, ModelColumn, ModelDescriptor, ModelPrimaryKey, NullOrder,
50    OrderCatalog, OrderClause, OrderRelationEdge, Orderable, Projection, ReadSource,
51    RelationFilter, RelationHop, RelationInclude, ResolvedOrderTarget, SortDirection,
52    SpatialFilter, SpatialPoint, SqlColumnValue, SqlValue, Unorderable, UpdateModelInput,
53    UpsertModelInput, ViewDescriptor, WriteSource, coalesce, is_orderable, order_value_sql, point,
54    resolve_order_target, wrap_filter,
55};
56
57pub use regex;
58pub use serde;
59pub use serde_json;
60pub use tracing;
61pub use uuid;
62
63// `Json<T>` resolves to `sqlx::types::Json<T>` on the server so
64// `sqlx::FromRow` decodes Postgres `jsonb` columns into it directly.
65pub use cratestack_sqlx::sqlx::types::Json;
66
67// -----------------------------------------------------------------------------
68// Server surface — sqlx, axum, audit/idempotency/migrations/isolation.
69// -----------------------------------------------------------------------------
70
71pub use cratestack_axum::axum;
72pub use cratestack_axum::*;
73
74// `transport grpc` server runtime (ticket #171) — only present when the
75// consumer opts into the `grpc` Cargo feature (`cratestack-macros/src/
76// include/server/grpc/` emits `::cratestack::grpc::...` paths that resolve
77// here). A `transport grpc` schema without the feature enabled fails
78// `include_server_schema!` with a `compile_error!` pointing at this
79// feature — see `crates/cratestack-macros/src/include/reject_grpc.rs`.
80#[cfg(feature = "grpc")]
81pub mod grpc {
82    pub use cratestack_grpc::*;
83}
84
85// Disambiguate the `rpc` module path. Both `cratestack_core` (wire shapes)
86// and `cratestack_axum` (binding helpers) expose an `rpc` module, so the
87// two `pub use ..::*` globs collide on the name and `::cratestack::rpc::*`
88// resolves non-deterministically. Macro-emitted code in `transport rpc`
89// schemas references symbols like `encode_rpc_error`,
90// `convert_handler_error_response`, `response_to_frame`, and
91// `RPC_BINDING_CAPABILITIES` — all of which live in `cratestack-axum::rpc`.
92// An explicit `pub use` re-export takes precedence over the globs, pinning
93// `::cratestack::rpc` to the axum module (which itself re-exports the wire
94// types from `cratestack-core::rpc`).
95pub use cratestack_axum::rpc;
96
97pub use cratestack_sqlx::AUDIT_TABLE_DDL;
98pub use cratestack_sqlx::sqlx;
99pub use cratestack_sqlx::{
100    Aggregate, AggregateColumn, AggregateCount, CreateRecord, DeleteMany, DeleteRecord, FindMany,
101    FindManyWith, FindUnique, FromPartialPgRow, ModelDelegate, ProjectedFindMany,
102    ProjectedFindUnique, ScopedAggregate, ScopedAggregateColumn, ScopedAggregateCount,
103    ScopedCreateRecord, ScopedDeleteMany, ScopedDeleteRecord, ScopedFindMany, ScopedFindManyWith,
104    ScopedFindUnique, ScopedModelDelegate, ScopedProjectedFindMany, ScopedProjectedFindUnique,
105    ScopedUpdateMany, ScopedUpdateManySet, ScopedUpdateRecord, ScopedUpdateRecordSet,
106    SqlxIdempotencyStore, UpdateMany, UpdateManySet, UpdateRecord, UpdateRecordSet, ViewDelegate,
107    ViewDelegateNoUnique, create_record_with_executor, update_record_with_executor,
108};
109pub use cratestack_sqlx::{
110    MIGRATIONS_TABLE_DDL, Migration, MigrationState, MigrationStatus, apply_pending,
111    ensure_migrations_table, status,
112};
113pub use cratestack_sqlx::{
114    cool_error_from_sqlx, run_in_isolated_tx, run_in_isolated_tx_with_retries,
115};
116
117/// Crypto provider selection — banks running on FIPS-validated hardware
118/// enable the `crypto-aws-lc-rs` feature. The function below surfaces an
119/// error early when the feature is missing so the wrong build can't slip
120/// into a regulated production cluster.
121///
122/// Operational steps for a real FIPS deployment (out of scope for the
123/// framework itself):
124///
125/// 1. Build with `--features crypto-aws-lc-rs`.
126/// 2. Use an `aws-lc-rs`/`rustls` build configured against the vendor's
127///    FIPS-validated `libcrypto`.
128/// 3. Call [`install_fips_crypto_provider`] from your service's `main`
129///    *before* any TLS-using code runs.
130/// 4. Pin the binary's `cargo audit` report and the validated module's
131///    certificate id in your release process.
132pub fn install_fips_crypto_provider() -> Result<(), cratestack_core::CoolError> {
133    #[cfg(feature = "crypto-aws-lc-rs")]
134    {
135        Ok(())
136    }
137    #[cfg(not(feature = "crypto-aws-lc-rs"))]
138    {
139        Err(cratestack_core::CoolError::Internal(
140            "cratestack was not compiled with `crypto-aws-lc-rs` feature; \
141             FIPS-validated crypto provider is unavailable"
142                .to_owned(),
143        ))
144    }
145}
146
147#[doc(hidden)]
148pub mod __private {
149    pub use cratestack_sqlx::SqlxRuntime;
150
151    /// Re-exports for the macro-emitted RPC dispatcher. Not part of the
152    /// public API surface — schema authors should never reference these
153    /// directly. Public helpers live at `cratestack::rpc::*`.
154    pub use cratestack_axum::rpc::{
155        bridge_grpc_response, decode_rpc_body, encode_rpc_value, response_to_frame,
156    };
157}
cratestack/lib.rs

cratestack/
lib.rs
