coap_handler/
lib.rs

1//! The `coap-handler` crate defines an interface between a [CoAP] server (that listens for
2//! requests on the network and parses the messages) and request handlers (that process the
3//! requests and creates responses from them).
4//!
5//! The interface is generic over message formats by using the [coap-message] crate, which allows
6//! the handler to construct the response right into the send buffer prepared by the server
7//! implementation. By separating the request processing and the response phase, a server can be
8//! implemented even on network stacks that have only a single network buffer.
9//!
10//!  Convenience, example and reference implementations are available in the [coap-handler-implementations] crate.
11//!
12//! [CoAP]: https://coap.technology/
13//! [coap-message]: https://crates.io/crates/coap-message
14//! [coap-handler-implementations]: https://crates.io/crates/coap-handler-implementations
15//!
16//! Known shortcomings of the current interface are:
17//!
18//! * No consideration for asynchronous processing.
19//! * Handler mutability is a bit iffy -- there's no way yet for the server to express any promise
20//!   about only running one handler at a time, thus handlers often hold shared references to a
21//!   [`RefCell`] that is [`borrow_mut()`]'d (if no other code that can be concurrent with the CoAP
22//!   server can have access to the `T`), or [`try_borrow_mut()`]'d (and errs back with a 5.03
23//!   Max-Age:0 response).
24//!
25//!   Alternatives (where multiple handlers could be built based on a single mutable reference to
26//!   their data) are being explored.
27//! * Multiple responses (as, for example, in observations) are not supported.
28//!
29//! [`RefCell`]: https://doc.rust-lang.org/core/cell/struct.RefCell.html
30//! [`borrow_mut()`]: https://doc.rust-lang.org/core/cell/struct.RefCell.html#method.borrow_mut
31//! [`try_borrow_mut()`]: https://doc.rust-lang.org/core/cell/struct.RefCell.html#method.try_borrow_mut
32//!
33//!
34//! The main item of this crate is the [Handler] trait. The [Reporting] trait can be implemented in
35//! addition to [Handler] to ease inclusion of the rendered resource in discovery, eg. through
36//! `/.well-known/core` as implemented in [coap-handler-implementations].
37#![no_std]
38
39mod core_implementations;
40mod handler;
41mod wkc;
42
43pub use handler::Handler;
44pub use wkc::{Attribute, Record, Reporting};