Skip to main content

RepeStruct

Trait RepeStruct 

Source
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§

Source

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§

Source

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, None for reads.

Return Ok(Some(value)) to send a JSON response payload, Ok(None) to send null.

Provided Methods§

Source

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.

Source

fn repe_shared_into( &self, segments: &[&str], body: &mut Option<Value>, out: &mut ResponseBody<'_>, ) -> Option<StructResult<()>>

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 None return must leave out as it was found, so the exclusive attempt starts from an empty body. ObjectBody::entry_try_with exists to make that mechanical when the decline surfaces partway through an object: it rewinds the whole object, so propagating its None is all a caller has to do.
  • Leave the body alone when declining. body is handed over as &mut Option<Value> rather than by value precisely so the exclusive retry can re-dispatch the same request without a clone. Call Option::take on it only once this borrow has committed to answering — an Err counts as an answer — and never on a path that goes on to return None. A body taken and then declined reaches the exclusive path as None, where it surfaces as a spurious BodyExpected.

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.

Source

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.

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_declines with false when absent, since a null needs 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

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.

Source§

fn repe_handle( &mut self, segments: &[&str], body: Option<Value>, ) -> StructResult<Option<Value>>

Source§

fn repe_handle_into( &mut self, segments: &[&str], body: Option<Value>, out: &mut ResponseBody<'_>, ) -> StructResult<()>

Source§

fn repe_shared_into( &self, segments: &[&str], body: &mut Option<Value>, out: &mut ResponseBody<'_>, ) -> Option<StructResult<()>>

Source§

fn repe_listing_declines(&self) -> bool

Implementors§