Struct capnp::message::ReaderOptions

pub struct ReaderOptions {
    pub traversal_limit_in_words: Option<usize>,
    pub nesting_limit: i32,
}

Options controlling how data is read.

Fields

traversal_limit_in_words: Option<usize>

Limits how many total (8-byte) words of data are allowed to be traversed. Traversal is counted when a new struct or list builder is obtained, e.g. from a get() accessor. This means that calling the getter for the same sub-struct multiple times will cause it to be double-counted. Once the traversal limit is reached, an error will be reported.

This limit exists for security reasons. It is possible for an attacker to construct a message in which multiple pointers point at the same location. This is technically invalid, but hard to detect. Using such a message, an attacker could cause a message which is small on the wire to appear much larger when actually traversed, possibly exhausting server resources leading to denial-of-service.

It makes sense to set a traversal limit that is much larger than the underlying message. Together with sensible coding practices (e.g. trying to avoid calling sub-object getters multiple times, which is expensive anyway), this should provide adequate protection without inconvenience.

A traversal limit of None means that no limit is enforced.

nesting_limit: i32

Limits how deeply nested a message structure can be, e.g. structs containing other structs or lists of structs.

Like the traversal limit, this limit exists for security reasons. Since it is common to use recursive code to traverse recursive data structures, an attacker could easily cause a stack overflow by sending a very-depply-nested (or even cyclic) message, without the message even being very large. The default limit of 64 is probably low enough to prevent any chance of stack overflow, yet high enough that it is never a problem in practice.

Implementations

impl ReaderOptions

pub fn new() -> ReaderOptions

pub fn nesting_limit<'a>(&'a mut self, value: i32) -> &'a mut ReaderOptions

pub fn traversal_limit_in_words<'a>(
    &'a mut self,
    value: Option<usize>
) -> &'a mut ReaderOptions

Trait Implementations

impl Clone for ReaderOptions

fn clone(&self) -> ReaderOptions

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ReaderOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ReaderOptions

fn default() -> ReaderOptions

Returns the “default value” for a type.

impl Copy for ReaderOptions