Crate toad_msg

Crate toad_msg 

Source
Expand description

Low-level representation of CoAP messages.

The most notable item in toad_msg is Message; a CoAP message very close to the actual byte layout.

§Allocation

CoAP messages have some attributes whose size is dynamic:

  • The message payload (in http terms: the request/response body)
  • the number of options (in http terms: headers)
  • the value of an option (in http terms: header value)

Message does not require an allocator and has no opinions about what kind of collection it uses internally to store these values.

It solves this problem by being generic over the collections it needs and uses an Array trait to capture its idea of what makes a collection useful.

This means that you may use a provided implementation (for Vec or tinyvec::ArrayVec) or provide your own collection (see the custom collections example)

//! Note: both of these type aliases are exported by `toad_msg` for convenience.

use tinyvec::ArrayVec;
use toad_msg::{Message, Opt};

//                        Message Payload byte buffer
//                        |
//                        |        Array of options in the message
//                        vvvvvvv  vvvvvvvvvvvvvvvvv
type VecMessage = Message<Vec<u8>, Vec<Opt<Vec<u8>>>>;

// Used like: `ArrayVecMessage<1024, 256, 16>`; a message that can store a payload up to 1024 bytes, and up to 16 options each with up to a 256 byte value.
type ArrayVecMessage<
       const PAYLOAD_SIZE: usize,
       const OPT_SIZE: usize,
       const NUM_OPTS: usize,
     > = Message<
           ArrayVec<[u8; PAYLOAD_SIZE]>,
           ArrayVec<[Opt<ArrayVec<[u8; OPT_SIZE]>>; NUM_OPTS]>,
         >;

It may look a little ugly, but a core goal of toad is to be platform- and alloc-agnostic.

§Performance

This crate uses criterion to measure performance of the heaped & heapless implementations in this crate as well as coap_lite::Packet.

In general, toad_msg::VecMessage performs identically to coap_lite (+/- 5%), and both are much faster than toad_msg::ArrayVecMessage.

Benchmarks:

§Serializing to bytes

Click to expand chart

chart

§Deserializing from bytes

Click to expand chart

chart

Re-exports§

pub use code::*;
pub use id::*;
pub use opt::*;
pub use parse_error::*;
pub use token::*;
pub use ty::*;
pub use ver::*;

Modules§

allocalloc
Type aliases for std or alloc platforms
cache_key
code
Message Code
id
Message ID
msg
Message structs
opt
Message Options
parse_error
Message parsing errors
token
Message Token
ty
Message Type
ver
Message Version

Structs§

DefaultCacheKey
Default hasher used for CacheKey
Message
CoAP Messages
Payload
Payloads and Representations

Enums§

SetOptionError
An error occurred during a call to Message::set

Traits§

CacheKey
The cache key can be used to compare messages for representing the same action against the same resource; for example requests with different IDs but the same method and cache-key affecting options (ex. path, query parameters) will yield the same cache-key.
MessageOptions
Methods that allow accessing & setting options known to the toad library.
TryFromBytes
Trait for converting a sequence of bytes into some data structure
TryIntoBytes
Trait allowing fallible conversion into bytes