Skip to main content

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 the four things a type needs to *be* served and nothing that
11//! serves it:
12//!
13//! * [`RepeStruct`], the dispatch trait, and [`RepeMethods`], the method table
14//!   `#[repe::methods]` generates beside it;
15//! * [`StructError`], what a handler reports;
16//! * [`ResponseBody`], what a read encodes into;
17//! * [`constants`], the protocol enums those two name.
18//!
19//! `repe` re-exports every one of them at the same paths, so a type derived
20//! against this crate mounts on a `repe::Router` with nothing in between, and
21//! `#[derive(RepeStruct)]` resolves its generated paths against whichever of the
22//! two crates it finds.
23//!
24//! # Features
25//!
26//! **`typed`** — off by default — adds [`ResponseBody::write_typed_slice`], the
27//! BEVE typed-numeric array encoding a `#[repe(typed)]` field is read as, and
28//! with it the `beve` dependency and the six packages behind it.
29//!
30//! It is off because that encoder is the whole weight of this crate: without it
31//! the dependency list is `serde`, `serde_json` and `thiserror`, which is the
32//! point of depending here rather than on `repe`. A struct with no
33//! `#[repe(typed)]` field — the usual case for a crate that only declares a
34//! served type — compiles identically either way. One that has such a field
35//! gets a compile error naming the feature, from a bound with no implementors
36//! (`structs::TypedSliceElement`, which exists only in this configuration); it
37//! never falls back to a JSON array silently, since that would change the wire
38//! without saying so.
39//!
40//! `repe` enables it unconditionally, so nothing about `#[repe(typed)]` changes
41//! for a crate that depends on `repe`.
42//!
43//! ```
44//! use repe_core::RepeStruct;
45//!
46//! #[derive(serde::Serialize, serde::Deserialize, RepeStruct)]
47//! struct Build {
48//!     version: String,
49//!     revision: u64,
50//! }
51//! ```
52//!
53//! [`repe`]: https://docs.rs/repe
54//! [`RepeMethods`]: structs::RepeMethods
55
56// Lets the derive macros emit `::repe_core` paths that resolve inside this crate
57// as well as outside it. See `repe_derive::repe_crate_path`.
58extern crate self as repe_core;
59
60pub mod constants;
61pub mod structs;
62
63pub use constants::{BodyFormat, ErrorCode, HEADER_SIZE, QueryFormat, REPE_SPEC, REPE_VERSION};
64pub use structs::{RepeStruct, ResponseBody, StructError};
65
66/// Derive macro generating a [`structs::RepeStruct`] implementation from a
67/// struct's fields.
68pub use repe_derive::RepeStruct;
69
70/// Attribute macro that publishes every method of an inherent `impl` block,
71/// generating the [`structs::RepeMethods`] table from the signatures themselves.
72///
73/// Pair it with `#[repe(methods)]` on the `#[derive(RepeStruct)]` struct; each
74/// half asserts the other, so neither can be forgotten silently.
75pub use repe_derive::methods;
76
77/// Items named by `#[derive(RepeStruct)]`'s generated code. Not public API:
78/// nothing outside the derive should name anything here, and its contents may
79/// change in any release.
80///
81/// It exists so generated code reaches `serde_json` through the crate that
82/// *defines* the trait rather than through the deriving crate's own dependency
83/// list. That buys two things. A deriving crate no longer has to declare
84/// `serde_json` for paths nothing in its source mentions — which matters most
85/// to exactly the light-dependency crate `repe-core` was split out for. And
86/// `RepeStruct`'s signatures name `serde_json::Value`, so the emitted impl must
87/// use the *same* `serde_json` the trait was declared with; resolving through
88/// here makes that structural instead of a coincidence of everyone being on
89/// `serde_json` 1.x, and it keeps working for a crate that renames the
90/// dependency (`json = { package = "serde_json" }`), which the old absolute
91/// `::serde_json` path did not.
92#[doc(hidden)]
93pub mod __private {
94    pub use serde_json;
95}