repe_core/lib.rs
1//! The `RepeStruct` surface of [`repe`], on its own.
2//!
3//! A served struct's endpoints are declared where the *type* is declared, and
4//! that is not always the crate that runs the RPC. A pure-logic crate — no I/O,
5//! no `unsafe`, buildable on any host, and often kept that way deliberately —
6//! should not have to acquire a server, a client, and a transport just to
7//! publish a couple of paths. Its choices without this crate were to derive
8//! nothing and concede the sub-paths, or to take the whole dependency.
9//!
10//! So this carries what a type needs to *be* served and nothing that serves it:
11//!
12//! * [`RepeStruct`], the dispatch trait, and [`RepeMethods`], the method table
13//! `#[repe::methods]` generates beside it;
14//! * [`RequestBody`] and [`ResponseBody`], what a write decodes from and a read
15//! encodes into;
16//! * [`Servable`] and its halves, what a type must satisfy to cross a frame;
17//! * [`StructError`], what a handler reports;
18//! * [`constants`], the protocol enums those name.
19//!
20//! `repe` re-exports every one of them at the same paths, so a type derived
21//! against this crate mounts on a `repe::Router` with nothing in between, and
22//! `#[derive(RepeStruct)]` resolves its generated paths against whichever of the
23//! two crates it finds.
24//!
25//! # Encoding
26//!
27//! Bodies are read and written by [`structio`], which carries JSON and BEVE in
28//! one crate with no dependencies of its own and no intermediate `Value`. A
29//! request is parsed straight into the live field it is destined for and a
30//! response is written straight into the outgoing frame, so a read costs one
31//! pass rather than three.
32//!
33//! There are no features. The `typed` feature this crate used to carry existed
34//! only because the BEVE encoder arrived with `beve` and six transitive packages
35//! behind it, and a crate that merely *declares* a served type should not link
36//! one to say so. That cost is gone, so
37//! [`ResponseBody::write_typed_slice`](structs::ResponseBody::write_typed_slice)
38//! is always there.
39//!
40//! A served field's own type is declared with structio's macros rather than with
41//! a derive; `#[derive(RepeStruct)]` publishes the *endpoints*, and structio
42//! describes the *encoding*.
43//!
44//! ```
45//! use repe_core::RepeStruct;
46//!
47//! #[derive(Default, RepeStruct)]
48//! struct Build {
49//! version: String,
50//! revision: u64,
51//! }
52//!
53//! structio::object!(Build { version, revision });
54//! ```
55//!
56//! [`repe`]: https://docs.rs/repe
57//! [`RepeMethods`]: structs::RepeMethods
58
59// Lets the derive macros emit `::repe_core` paths that resolve inside this crate
60// as well as outside it. See `repe_derive::repe_crate_path`.
61extern crate self as repe_core;
62
63pub mod constants;
64pub mod structs;
65
66pub use constants::{BodyFormat, ErrorCode, HEADER_SIZE, QueryFormat, REPE_SPEC, REPE_VERSION};
67pub use structs::{
68 MethodArgs, RepeStruct, RequestBody, ResponseBody, Servable, ServableRead, ServableWrite,
69 StructError,
70};
71
72/// Derive macro generating a [`structs::RepeStruct`] implementation from a
73/// struct's fields.
74pub use repe_derive::RepeStruct;
75
76/// Attribute macro that publishes every method of an inherent `impl` block,
77/// generating the [`structs::RepeMethods`] table from the signatures themselves.
78///
79/// Pair it with `#[repe(methods)]` on the `#[derive(RepeStruct)]` struct; each
80/// half asserts the other, so neither can be forgotten silently.
81pub use repe_derive::methods;