rustledger_ffi_wasi/
lib.rs

1// The surviving load-result types (`LedgerOptions`, `Plugin`, `Include`,
2// `Error`) carry many self-describing fields the component maps straight into
3// WIT. Per-field rustdoc would duplicate the WIT contract and drift from it;
4// the crate is FFI-support glue, not a stable public API, so treat the
5// rust-side type docs as authoritative for shape only.
6#![allow(missing_docs)]
7
8//! Slimmed FFI-support helpers for the rustledger WASI component FFI.
9//!
10//! # Phase 5 (#1419) is complete
11//!
12//! This crate used to expose a wasip1 JSON-RPC 2.0 embedding API (a server
13//! binary in `main.rs` + a `jsonrpc` router) plus a `Directive → JSON` output
14//! DTO. Both are gone: the JSON-RPC surface was retired earlier in Phase 5
15//! ([#1419](https://github.com/rustledger/rustledger/issues/1419)) now that the
16//! typed WASI Preview 2 / Component Model binding,
17//! [`rustledger-ffi-component`](https://github.com/rustledger/rustledger/issues/1384)
18//! (#1384), is the default embedding path (default in rustfava as of Phase 4);
19//! the output DTO was removed once the component switched to converting
20//! core→WIT directly.
21//!
22//! What remains is a **library only** of FFI-support glue the component reuses:
23//! the loader orchestration ([`helpers`]), the WIT-input construction path
24//! ([`input_entry_to_directive`] + the `Input*` types) and directive hashing
25//! ([`compute_directive_hash`]). These survivors are deliberately FFI glue kept
26//! OUT of the core `rustledger-loader` crate, so the crate is retained slimmed
27//! rather than relocated or deleted (the "retained … document the decision"
28//! outcome of #1419 item 6).
29
30// `helpers` is `pub` so the WIT/Component-Model crate
31// (`rustledger-ffi-component`, #1384) can reuse the loader orchestration
32// (`load_source`) instead of duplicating it.
33pub mod helpers;
34// Directive hashing is core→hash (no DTO involved).
35pub mod hash;
36pub(crate) mod types;
37
38// Re-export the load-result DTOs the component crate maps into WIT types.
39pub use types::{Error, Include, LedgerOptions, Plugin};
40// Directive hashing is core→hash (no DTO involved); re-exported at the crate
41// root so the component can compute the `meta.hash` field when converting
42// core→WIT directly.
43pub use hash::compute_directive_hash;
44// Input/construction types + converter the component crate maps WIT input into
45// (`entry.create`).
46pub use types::input::{InputAmount, InputCost, InputCostNumber, InputEntry, InputPosting};
47pub use types::input_entry_to_directive;
48
49/// API version this server compiled against. Reported as the
50/// `api_version` field on every method's response (`util.version`,
51/// `ledger.load`, etc.).
52///
53/// Increment minor version for backwards-compatible changes.
54/// Increment major version for breaking changes.
55///
56/// # Server vs. client semantics
57///
58/// This constant is the SERVER's compile-time advertised version.
59/// Cross-version clients negotiating wire shape MUST read the
60/// `api_version` field FROM THE RESPONSE PAYLOAD they receive — not
61/// from a locally-linked `API_VERSION` constant. A client binary
62/// statically linked against `rustledger-ffi-wasi` v1.0 carries
63/// `API_VERSION = "1.0"` in its image but, if it talks to a
64/// dynamically-deployed v2.0 server, must use the v2.0-shaped response
65/// — the server's version comes from the wire, not the client's
66/// link-time copy.
67///
68/// # Version history
69///
70/// * **2.2** — `ledger.load`/`ledger.loadFile` accept an optional
71///   `expand_pads` request field; when `true`, `pad` directives are
72///   materialized into synthesized `Padding` transactions in the returned
73///   entries (balance-computing consumers opt in). Additive and backward
74///   compatible — the field defaults to `false` (source-faithful) — hence a
75///   minor bump per the policy above (#1628). (The WIT component delivers the
76///   same capability via a *breaking* parameter, so it bumps to 3.0.)
77/// * **2.1** — `Inventory`/`Position` query values now include an optional
78///   `cost` object per position when the holding was booked at cost, using the
79///   same wire shape as a directive `PostingCost` (`number` is a tagged
80///   `CostNumber`, always `per_unit` for a booked position). Additive and
81///   backward compatible — units-only consumers ignore the new field — hence a
82///   minor bump per the policy above.
83/// * **2.0** — `error.data.errors` on `beancount_parse_error` (-32000)
84///   responses is now `ParseErrorEntry[]` (per-error object with
85///   `message`, `kind_code`, `hint`, `span`) instead of the previous
86///   `string[]` of rendered messages. This is a wire-shape break,
87///   hence the major bump per the policy above (round-19 correction:
88///   the change shipped briefly as 1.1, which violated the major-on-
89///   break rule). Cross-version clients negotiate via `api_version`
90///   on the response; v1.x clients that parse errors as `string[]`
91///   should refuse to talk to a v2.x server. See `README.md` for the
92///   migration recipe.
93/// * **1.0** — initial API.
94pub const API_VERSION: &str = "2.2";
rustledger_ffi_wasi/lib.rs

rustledger_ffi_wasi/
lib.rs
