unitycatalog_delta_api/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2//! Portable Unity Catalog **Delta v1** REST API.
3//!
4//! This crate owns the Delta API *semantics* — the hand-written wire models, the
5//! catalog-managed table contract, the commit coordinator, and the `updateTable`
6//! action dispatcher — behind a narrow backend [port](DeltaBackend). Any
7//! server can serve the identical `/delta/v1` surface by implementing
8//! [`DeltaBackend`] over its own storage, credential vending, and authorization;
9//! all the Delta business logic is shared here, so the behavior is identical by
10//! construction.
11//!
12//! It depends only on `axum`, `async-trait`, `serde`, `uuid`, and `thiserror` — it
13//! does **not** depend on any server crate, so a downstream server (mangrove,
14//! lakekeeper, …) takes this single dependency and nothing else.
15//!
16//! # Examples
17//!
18//! Implement [`DeltaBackend`] over your own storage, then hand it to
19//! [`get_router`] to serve the entire `/delta/v1` surface. Here the in-memory
20//! backend from the `testing` feature stands in for a real one:
21//!
22//! ```
23//! # #[cfg(feature = "testing")] {
24//! use unitycatalog_delta_api::get_router;
25//! use unitycatalog_delta_api::testing::InMemoryDeltaBackend;
26//!
27//! // `InMemoryDeltaBackend` implements `DeltaBackend<()>`, so the context type
28//! // is `()`. A real server uses its own request-context type here.
29//! let router: axum::Router = get_router::<InMemoryDeltaBackend, ()>(InMemoryDeltaBackend::new());
30//! # let _ = router;
31//! # }
32//! ```
33//!
34//! # Layout
35//! - [`models`] — hand-written serde wire DTOs (kebab-case JSON).
36//! - [`error`] — the decoupled error contract ([`DeltaApiError`] +
37//!   [`DeltaBackendError`]).
38//! - [`mod@column`] — the portable UC column model used by the contract.
39//! - [`config`] — `getConfig` support: capability-driven endpoint list + protocol
40//!   version negotiation.
41//! - [`contract`] — the managed-table contract + Delta↔UC column mapping.
42//! - [`coordinator`] — the commit coordinator (arbitration + backfill).
43//! - [`authz`] — the [`DeltaAction`] vocabulary the handler authorizes with.
44//! - [`backend`] — the `DeltaBackend` port trait + its coordinate/request types.
45//! - [`handler`] — the `DeltaApiHandler` trait + the generic blanket impl.
46//! - [`router`] — the axum router mounting all 12 operations.
47
48pub mod authz;
49pub mod backend;
50pub mod column;
51pub mod config;
52pub mod contract;
53pub mod coordinator;
54pub mod error;
55pub mod handler;
56pub mod models;
57pub mod router;
58#[cfg(feature = "testing")]
59pub mod testing;
60
61pub use authz::DeltaAction;
62pub use backend::{DeltaBackend, DeltaCapabilities};
63pub use error::{DeltaApiError, DeltaApiResult, DeltaBackendError};
64pub use handler::DeltaApiHandler;
65pub use router::get_router;
unitycatalog_delta_api/lib.rs

unitycatalog_delta_api/
lib.rs
