pub struct ResponseBody<'a> { /* private fields */ }Expand description
Response body under construction for a RepeStruct read.
Handed to RepeStruct::repe_handle_into so a read serializes the live
field straight into the outgoing frame buffer, with no intermediate tree —
which is what a client polling a wide object at kilohertz used to pay for.
The body starts out empty, encoding in the format the request asked for.
new defaults that to BodyFormat::Json;
with_format is what a server uses to answer a BEVE
request in BEVE. The write that fills the body settles the format it
actually reports, which is normally the requested one and is always
BodyFormat::Beve for write_typed_slice.
Exactly one top-level write is expected — a value, a null, or an
object.
A whole-object object listing honours the requested format
too: a BEVE object carries its member count in its header, so the listing
declares its count up front and rewinds whole if an entry declines.
Writing itself cannot fail: a structio::json::Write impl returns ().
What can still fail is the handler around it — a nested child that
declines, a method that errors — so object entries that run
arbitrary code keep their Result, and rewind the buffer to where the write
began, so a caller that recovers from a StructError never ships
half-serialized bytes.
Implementations§
Source§impl<'a> ResponseBody<'a>
impl<'a> ResponseBody<'a>
Sourcepub fn new(buf: &'a mut Vec<u8>) -> Self
pub fn new(buf: &'a mut Vec<u8>) -> Self
Wrap an output buffer, answering in JSON. buf is normally empty; writes
append to it.
Sourcepub fn with_format(buf: &'a mut Vec<u8>, requested: BodyFormat) -> Self
pub fn with_format(buf: &'a mut Vec<u8>, requested: BodyFormat) -> Self
Wrap an output buffer, answering in the format the request declared.
BodyFormat::RawBinary and BodyFormat::Utf8 describe bodies with
no value structure to mirror, so a request in either is answered in
JSON.
Sourcepub fn format(&self) -> BodyFormat
pub fn format(&self) -> BodyFormat
The body format settled by the write that filled this body.
Sourcepub fn write<T>(&mut self, value: &T)where
T: ServableWrite + ?Sized,
pub fn write<T>(&mut self, value: &T)where
T: ServableWrite + ?Sized,
Serialize value as the whole body, in the requested format.
Inside an enclosing object the frame is already committed to JSON, and this writes JSON regardless.
Sourcepub fn write_null(&mut self)
pub fn write_null(&mut self)
Write a null body — the response to a write, or to a read that has
nothing to return.
Sourcepub fn write_typed_slice<T>(&mut self, slice: &[T])where
T: NumericBytes + ServableWrite,
pub fn write_typed_slice<T>(&mut self, slice: &[T])where
T: NumericBytes + ServableWrite,
Write slice as a BEVE typed numeric array and set the body format to
BodyFormat::Beve.
The same bulk encode repe::message::MessageBuilder::body_typed_slice
produces — one copy_nonoverlapping on little-endian targets rather than
a per-element walk, and byte-identical to what Glaze emits for the same
array. This is what #[repe(typed)] routes a numeric field to. (Named
rather than linked: the builder lives in repe, which this crate
deliberately does not depend on.)
Inside an enclosing object — the whole-struct listing — the frame is already committed to JSON, so the slice is written as a JSON array instead. A field only reaches the typed encoding when it is read on its own.
This used to sit behind a typed feature, because the encoder arrived
with beve and six transitive packages behind it and a crate that only
declares a served type should not link one to say so. structio has no
dependencies, so there is nothing left to gate and the feature is gone.
Sourcepub fn object(&mut self, entries: usize) -> ObjectBody<'_>
pub fn object(&mut self, entries: usize) -> ObjectBody<'_>
Begin an object body of exactly entries members, written key by key.
Used by the whole-struct listing so a wide object is emitted in one pass.
entries is what lets the object be BEVE as readily as JSON: a BEVE
object carries its member count in its header, before any member, so a
listing that discovered its count by finishing could only ever have been
JSON. A derived listing knows the count when it is generated, and an
entry that fails or declines rewinds the whole object rather than
emitting a short one, so the declared count is never wrong.
Under JSON the count is unused. Under BEVE, writing a number of entries
other than entries would produce a corrupt document, so
finish panics on a disagreement rather than
letting it reach a peer. The derive never miscounts; a hand-written
listing that does has a bug, and the panic names it.