pub struct RequestBody<'a> { /* private fields */ }Expand description
The request body handed to a RepeStruct, as the bytes that arrived plus
the format the frame header declared.
This is the mirror of ResponseBody, and it is what replaced the
Option<serde_json::Value> the trait used to take. A body is now parsed
once, into the live member it is destined for — Glaze’s read_params —
rather than into a tree that is then walked and re-parsed. Nothing here
allocates until a reader does, and a request that no endpoint claims never
parses at all.
The bytes are borrowed from the frame, so a RequestBody cannot outlive it.
That is deliberate: it is what lets a &'de str field borrow from the
request instead of copying out of it.
Implementations§
Source§impl<'a> RequestBody<'a>
impl<'a> RequestBody<'a>
Sourcepub fn new(bytes: &'a [u8], format: BodyFormat) -> Self
pub fn new(bytes: &'a [u8], format: BodyFormat) -> Self
Wrap the body bytes of a frame, under the format its header declared.
Sourcepub fn bytes(&self) -> &'a [u8] ⓘ
pub fn bytes(&self) -> &'a [u8] ⓘ
The raw body bytes, unparsed.
For an endpoint that forwards a body onward without looking inside it —
a proxy, a plugin boundary — and for BodyFormat::RawBinary, where
there is nothing to parse.
Sourcepub fn format(&self) -> BodyFormat
pub fn format(&self) -> BodyFormat
The body format the frame header declared.
Sourcepub fn is_null(&self) -> bool
pub fn is_null(&self) -> bool
Whether the body is the literal null.
Asked by the paths that distinguish “no body” from “a body saying nothing” — an optional child refusing a presence write, most of all. Cheap in both formats: one tag byte in BEVE, a four-byte compare in JSON. JSON whitespace is ASCII, so the compare needs no UTF-8 pass over a body that may be megabytes long.
Sourcepub fn read_into<T>(&self, path: &str, value: &mut T) -> StructResult<()>where
T: ServableRead<'a>,
pub fn read_into<T>(&self, path: &str, value: &mut T) -> StructResult<()>where
T: ServableRead<'a>,
Parse the body into value, in place.
path names the endpoint for the error message and is only read when
parsing fails.
Reading into rather than returning a new value is what makes this the
live-member read: a Vec or String already in the destination keeps
its allocation, and a field absent from the body keeps the value it had.
That last part is a merge, and it is the behaviour a whole-object
write wants — a client updating one key of a wide object should not
blank the rest.
Read under WirePolicy, so a member the sender added and this build
never declared is stepped over rather than refusing the frame.
An endpoint that wants some members to be mandatory marks them
#[required] in its structio declaration, which is per field and unions
with whatever policy is in force.
A failed read is not transactional. structio parses straight into
value, so a body that is malformed partway through leaves the members
before the fault already updated and the rest as they were, and the
error goes back to the client. That is the price of the merge: there is
no scratch copy to discard, and building one would need T: Clone and
cost the allocation the live read exists to avoid. An endpoint that
must not expose a torn write reads into a fresh T::default() with
read and assigns on success — replace semantics — or
validates the body against the schema before applying it.
Sourcepub fn read_into_with<O, T>(
&self,
path: &str,
value: &mut T,
) -> StructResult<()>where
O: Options,
T: ServableRead<'a>,
pub fn read_into_with<O, T>(
&self,
path: &str,
value: &mut T,
) -> StructResult<()>where
O: Options,
T: ServableRead<'a>,
read_into under an explicit structio
read policy.
For a policy that changes what the body may contain:
AllowComments for a body written by hand,
or Standard to refuse a key this build does not
declare — the opposite of WirePolicy, and a deliberate narrowing of
what the protocol permits.
Not for making members mandatory. RequireKeys
demands every declared member, and an Option<T> is not exempt — the
test is whether the key is present, not what it holds, so null
satisfies it and absence does not, and a struct with one optional member
cannot be read under it at all. Mark the mandatory members #[required]
instead.
Sourcepub fn read<T>(&self, path: &str) -> StructResult<T>where
T: ServableRead<'a> + Default,
pub fn read<T>(&self, path: &str) -> StructResult<T>where
T: ServableRead<'a> + Default,
Parse the body as a fresh T.
read_into is the one to reach for when a
destination already exists; this is for the case where it does not, such
as a method’s parameter struct. The Default bound is what structio’s
read-into model costs here: the value has to exist before it can be read
into.