coap_handler_implementations/
lib.rs

1//! The `coap-handler-implementations` crate provides a few convenience, example or
2//! reference implementations of the [coap-handler] interface.
3//!
4//! They range from the generic "4.04
5//! Not Found" responder up to a handler that creates a [write] formatter for GET-only resources,
6//! and even provides [block-wise transfer] that.
7//! The [TypeHandler] enables the easy creation of [serde_cbor] based
8//! resource implementations with GET, PUT and POST support in CBOR format.
9//! The `HandlerBuilder` implements crude static path based routing
10//! that may suffice for some applications, and is also useful to get started quickly.
11//!
12//! [coap-handler]: https://crates.io/crates/coap-handler
13//! [write]: https://doc.rust-lang.org/core/fmt/trait.Write.html
14//! [block-wise transfer]: https://tools.ietf.org/html/rfc7959
15//! [serde_cbor]: https://crates.io/crates/serde_cbor
16//!
17//! History
18//! -------
19//!
20//! This code used to be part of coap-handler, but while the interface needs to stabilize fast (as
21//! incompatible changes there propagate to implementations), the implementations still need to
22//! develop fast (but it doesn't hurt too much if one code part is using the old SimpleRenderable
23//! while another uses a newer NeverFound).
24//!
25//! Version 0.1 is what was available in coap-handler (if Cargo allowed cyclic dependencies,
26//! coap-handler would `pub use` this crate); users are encouraged to just use
27//! coap-handler-implementations directly.
28//!
29//! Options Hiding
30//! --------------
31//!
32//! A common mechanism in handlers is that handlers "consume" options. For example, the
33//! [ForkingHandler] built through [HandlerBuilder::at] "eats" the Uri-Path; likewise, an
34//! Accept-based dispatcher would consume the Accept option.
35//!
36//! This allows the handlers themselves to check for any left-over critical options and fail if
37//! they can't handle them -- without the need to mask them out there assuming (without an actual
38//! check) that prior wrappers took care of them.
39#![doc = document_features::document_features!()]
40#![no_std]
41#![cfg_attr(feature = "_nightly_docs", feature(doc_auto_cfg))]
42#![cfg_attr(
43    feature = "_nontrivial_option_processing",
44    feature(impl_trait_in_assoc_type)
45)]
46
47use coap_message::{MinimalWritableMessage, MutableWritableMessage, ReadableMessage};
48
49pub mod helpers;
50pub mod wkc;
51mod wkc_implementation;
52#[cfg(feature = "leaky_names")]
53pub use wkc_implementation::WellKnownCore;
54
55use coap_message_utils::Error;
56
57mod forking;
58mod forking_helpers;
59
60// Merely implemented separately; might move them publicly there later and deprecate them here in
61// preparation for a breakin grename.
62pub use forking::{
63    ForkingHandler, ForkingRequestData, ForkingTreeHandler, HandlerBuilder,
64    ReportingHandlerBuilder, new_dispatcher,
65};
66
67use coap_handler::Handler;
68use core::convert::Infallible;
69
70/// A resource that unconditionally responds 4.04 Not Found.
71///
72/// This is a convenience tool for building trees of resources -- rather than special casing the
73/// "none found" situation, this handler can be used.
74pub struct NeverFound {}
75
76impl Handler for NeverFound {
77    type RequestData = Infallible;
78
79    type ExtractRequestError = Error;
80    type BuildResponseError<M: MinimalWritableMessage> = Infallible;
81
82    fn extract_request_data<M: ReadableMessage>(
83        &mut self,
84        _request: &M,
85    ) -> Result<Self::RequestData, Self::ExtractRequestError> {
86        Err(Error::not_found())
87    }
88
89    fn estimate_length(&mut self, _request: &Self::RequestData) -> usize {
90        0
91    }
92
93    fn build_response<M: MutableWritableMessage>(
94        &mut self,
95        _response: &mut M,
96        request: Self::RequestData,
97    ) -> Result<(), Infallible> {
98        match request {}
99    }
100}
101
102mod simple_rendered;
103pub use simple_rendered::{
104    SimpleRenderable, SimpleRenderableData, SimpleRendered, TypedStaticRenderable,
105};
106
107mod typed_resource;
108pub use typed_resource::{Empty, TypeHandler, TypeRenderable, TypeRequestData};
coap_handler_implementations/lib.rs

coap_handler_implementations/
lib.rs
