citum_server/lib.rs
1/*
2SPDX-License-Identifier: MIT OR Apache-2.0
3SPDX-FileCopyrightText: © 2023-2026 Bruce D'Arcus and Citum contributors
4*/
5
6//! Citum JSON-RPC server.
7//!
8//! `citum-server` runs `citum-engine` behind a process boundary for clients
9//! that need a standalone renderer instead of linking the engine directly.
10//! The crate supports stdio JSON-RPC in every build and an axum HTTP transport
11//! through the default-on `http` feature. Both transports expose the same
12//! JSON-RPC method surface; only the framing changes.
13//!
14//! ## Methods
15//!
16//! | Method | Required params | Optional params | Result |
17//! |---|---|---|---|
18//! | `render_citation` | `style_path`, `refs`, `citation` | `output_format`, `inject_ast_indices` | rendered citation string |
19//! | `render_bibliography` | `style_path`, `refs` | `output_format`, `inject_ast_indices` | rendered bibliography object |
20//! | `validate_style` | `style_path` | none | validation object |
21//! | `format_document` | `style`, `refs`, `citations` | `output_format`, `locale`, `document_options` | `{formatted_citations, bibliography, warnings}` |
22//!
23//! `refs` in `render_citation` and `render_bibliography` is an inline JSON map
24//! of native Citum reference objects. `refs` in `format_document` accepts
25//! `citum-engine`'s tagged [`citum_engine::RefsInput`] shape, including local
26//! bibliography paths, inline YAML, inline JSON, and legacy bare JSON maps.
27//! Dates are EDTF strings such as `"1988"`, not CSL-JSON `date-parts` objects.
28//!
29//! `render_citation`, `render_bibliography`, and `validate_style` accept
30//! `style_path`, a string path to a local Citum YAML style. `format_document`
31//! accepts the richer `style` object, for example
32//! `{ "kind": "path", "value": "styles/embedded/apa-7th.yaml" }`.
33//!
34//! See [`rpc`] for the request envelope and stdio transport details.
35#![cfg_attr(feature = "http", doc = "See [`http`] for the default HTTP transport.")]
36#![cfg_attr(
37 not(feature = "http"),
38 doc = "The HTTP transport is unavailable in this build because the `http` feature is disabled."
39)]
40//!
41//! ## Features
42//!
43//! - `async`: Tokio runtime support used by HTTP transport.
44//! - `http`: axum HTTP transport; enabled by default and implies `async`.
45//! - `schema`: `/rpc/schema` plus schema derivations.
46//! - `schema-types`: schema derivations without the HTTP schema endpoint.
47
48/// Server error types and conversions.
49pub mod error;
50/// JSON-RPC request handling and stdio transport.
51pub mod rpc;
52
53#[cfg(feature = "http")]
54/// Default HTTP transport built on axum.
55pub mod http;
56
57pub use error::ServerError;
58pub use rpc::dispatch;