pub trait RepeStruct: Send + Sync {
const REPE_SHARED_SERVES_BODIES: bool = true;
// Required method
fn repe_handle(
&mut self,
segments: &[&str],
body: Option<Value>,
) -> StructResult<Option<Value>>;
// Provided methods
fn repe_handle_into(
&mut self,
segments: &[&str],
body: Option<Value>,
out: &mut ResponseBody<'_>,
) -> StructResult<()> { ... }
fn repe_shared_into(
&self,
segments: &[&str],
body: &mut Option<Value>,
out: &mut ResponseBody<'_>,
) -> Option<StructResult<()>> { ... }
fn repe_listing_declines(&self) -> bool { ... }
}Expand description
Trait implemented by structs that can be exposed directly through the REPE router.
The implementation should interpret the provided JSON Pointer path segments and either return a JSON value (for reads) or mutate the struct (for writes).
Provided Associated Constants§
Sourceconst REPE_SHARED_SERVES_BODIES: bool = true
const REPE_SHARED_SERVES_BODIES: bool = true
Whether any path can answer a body-carrying frame through
repe_shared_into.
The router asks before it takes the read lock. REPE puts a body on a
write and on a call with arguments, so a body alone cannot say which
one arrived — but a struct whose every write needs &mut self knows the
answer for all of them in advance, and false lets the router skip the
lock, the walk and the certain decline.
This is a hint, and it cannot cost correctness. Everything the shared
borrow answers with a body, the exclusive path answers identically: a
&self method is callable through either, and every refusal
(BodyUnexpected on a read-only endpoint,
InvalidPath on an unknown one) is generated
from the same shape on both sides. false on an impl that could have
served one costs concurrency for that frame and nothing else.
The default is true, the accurate answer for a hand-written
repe_shared_into this crate cannot see inside. A derived impl narrows
it to false when nothing it generates can answer a body: no &self
method taking arguments, no read-only endpoint whose refusal is servable
shared, and no #[repe(nested)] child that has either.
Required Methods§
Sourcefn repe_handle(
&mut self,
segments: &[&str],
body: Option<Value>,
) -> StructResult<Option<Value>>
fn repe_handle( &mut self, segments: &[&str], body: Option<Value>, ) -> StructResult<Option<Value>>
Handle a read or write against this struct.
segments– JSON Pointer path split into unescaped segments.body–Some(value)when the request contains a JSON body,Nonefor reads.
Return Ok(Some(value)) to send a JSON response payload, Ok(None) to send null.
Provided Methods§
Sourcefn repe_handle_into(
&mut self,
segments: &[&str],
body: Option<Value>,
out: &mut ResponseBody<'_>,
) -> StructResult<()>
fn repe_handle_into( &mut self, segments: &[&str], body: Option<Value>, out: &mut ResponseBody<'_>, ) -> StructResult<()>
Encode-in-place counterpart of repe_handle: write the
response body straight into out instead of returning an owned
serde_json::Value for the caller to re-serialize.
This is the method the router calls. The default implementation delegates
to repe_handle and encodes whatever it returns, so a
hand-written impl only needs repe_handle; #[derive(RepeStruct)]
overrides it so a leaf read serializes the live field directly into the
outgoing frame buffer with no intermediate Value.
Writes are unaffected — a request body still arrives as a Value.
Serve a request through a shared borrow, or decline it.
The router tries this first for every request against a struct
registered behind a lock that has a shared mode, which is what keeps a
/version read from queueing behind a half-second method call on the
same object.
A body-carrying frame is offered here too, and that is deliberate: REPE
separates read from write at the frame level, but a &self method
taking arguments is a call, not a mutation. Deciding from the frame
alone put a long-running &self call behind the write guard and
stalled every read of the object for as long as it ran. The receiver is known
where these arms are generated, so it is the receiver that decides.
Return None for any path this borrow cannot serve: a field write, a
&mut self method, a nested field whose child declined. The router then
retakes the lock exclusively and dispatches through
repe_handle_into, so declining costs
correctness nothing — it is the default, and a hand-written impl that
never overrides this behaves exactly as it did before the path existed.
Three obligations come with overriding it:
- Answer identically. Whatever this returns for a path is what the client sees; the exclusive path is not consulted afterwards. Decline rather than approximate.
- Write nothing when declining. A
Nonereturn must leaveoutas it was found, so the exclusive attempt starts from an empty body.ObjectBody::entry_try_withexists to make that mechanical when the decline surfaces partway through an object: it rewinds the whole object, so propagating itsNoneis all a caller has to do. - Leave the body alone when declining.
bodyis handed over as&mut Option<Value>rather than by value precisely so the exclusive retry can re-dispatch the same request without a clone. CallOption::takeon it only once this borrow has committed to answering — anErrcounts as an answer — and never on a path that goes on to returnNone. A body taken and then declined reaches the exclusive path asNone, where it surfaces as a spuriousBodyExpected.
A derived impl settles the whole-object listing before it writes or
invokes anything, through
repe_listing_declines — because a
decline discovered later would leave the entries before it run twice,
once here and once on the exclusive retry, and a rewind cannot undo a
call. A hand-written impl that invokes anything before it can decide owes
the same care.
Sourcefn repe_listing_declines(&self) -> bool
fn repe_listing_declines(&self) -> bool
Whether a shared whole-object listing of this struct declines — asked before the listing writes or invokes anything.
A listing is the one read that composes many others, so a decline discovered partway through is not recoverable: the exclusive retry re-runs the entries before it, and an entry that was invoked rather than serialized runs a second time. Rewinding the response buffer undoes the bytes; it cannot undo a call.
So the answer has to be available at the top, and it has to cover the
whole subtree — a parent’s listing composes its children’s, so a child
that declines takes the parent’s listing with it. That is why this is on
RepeStruct rather than only on
RepeMethods::REPE_LISTING_NEEDS_EXCLUSIVE, which answers the same
question about one method table’s accessors and nothing beneath them. A
derived impl returns that const OR’d with every #[repe(nested)] child’s
answer, so the whole tree is settled before the first byte is written.
The default is true, which is the accurate answer for the default
repe_shared_into: it declines every path,
listings included. A hand-written impl that overrides repe_shared_into
to serve a listing should override this too, or every derived struct
nesting it gives up its own shared listing.
Overriding it is a promise, and it is the promise the invariant rests
on: returning false asserts that repe_shared_into(&[], &mut None, ..)
answers Some(..). Breaking it still yields a correct response — the listing
rewinds and the exclusive path retries — but anything the shared attempt
had already invoked runs twice.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".
Implementations on Foreign Types§
Source§impl<T: RepeStruct> RepeStruct for Option<T>
A conditionally-present child: a component that is not in every build, a
subsystem that is not configured, a resource that failed to open.
impl<T: RepeStruct> RepeStruct for Option<T>
A conditionally-present child: a component that is not in every build, a subsystem that is not configured, a resource that failed to open.
Option is a foreign type and RepeStruct is this crate’s trait, so a
host cannot write this impl itself — its choices without one are a newtype
per crate or one impl per concrete Option<Child>. Carrying it here is what
lets #[repe(nested)] be put on an Option<T> field directly, which is
where a host reaches for it first.
Present forwards everything to the inner value. Absent answers:
- a read at the child’s own path with
null, so a whole-object listing of the parent shows the key with nothing behind it rather than failing; - a write, or any subpath with
StructError::InvalidPath, because a silent no-op against a live resource is worse than an error — a client that configured an absent component would otherwise be told it succeeded; repe_listing_declineswithfalsewhen absent, since anullneeds no exclusive borrow, and with the inner value’s own answer when present.
Presence is the host’s, not the client’s. A null written at the child’s
own path is refused with StructError::BodyUnexpected whether the child is
there or not, so the one value this path can read back is the one value it
will not take. Removing a child would otherwise be a door that only opens one
way, since creating one is the write an absent child already refuses. A
whole-object write at the parent replaces the field, null included; that
is a replace of the parent rather than a write to this path.
This matches what Glaze publishes for an unmapped optional member, so a port’s wire shape does not change with the language.
Source§const REPE_SHARED_SERVES_BODIES: bool = T::REPE_SHARED_SERVES_BODIES
const REPE_SHARED_SERVES_BODIES: bool = T::REPE_SHARED_SERVES_BODIES
A present child answers for itself. An absent one refuses every write and every sub-path, and refuses them identically on both borrows, so it contributes nothing the exclusive path would not also say.