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
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//!
16//! History
17//! -------
18//!
19//! This code used to be part of coap-handler, but while the interface needs to stabilize fast (as
20//! incompatible changes there propagate to implementations), the implementations still need to
21//! develop fast (but it doesn't hurt too much if one code part is using the old SimpleRenderable
22//! while another uses a newer NeverFound).
23//!
24//! Version 0.1 is what was available in coap-handler (if Cargo allowed cyclic dependencies,
25//! coap-handler would `pub use` this crate); users are encouraged to just use
26//! coap-handler-implementations directly.
27//!
28//! Options Hiding
29//! --------------
30//!
31//! A common mechanism in handlers is that handlers "consume" options. For example, the
32//! [ForkingHandler] built through [HandlerBuilder::at] "eats" the Uri-Path; likewise, an
33//! Accept-based dispatcher would consume the Accept option.
34//!
35//! This allows the handlers themselves to check for any left-over critical options and fail if
36//! they can't handle them -- without the need to mask them out there assuming (without an actual
37//! check) that prior wrappers took care of them.
38#![doc = document_features::document_features!()]
39#![no_std]
40#![cfg_attr(feature = "_nightly_docs", feature(doc_cfg))]
41#![cfg_attr(
42    feature = "_nontrivial_option_processing",
43    feature(impl_trait_in_assoc_type)
44)]
45
46use coap_message::{MinimalWritableMessage, MutableWritableMessage, ReadableMessage};
47
48mod embedded_io;
49
50pub mod helpers;
51pub mod wkc;
52mod wkc_implementation;
53#[cfg(feature = "leaky_names")]
54pub use wkc_implementation::WellKnownCore;
55
56/// Re-export of coap-message-utils.
57///
58/// This type is part of the renderable traits, and thus of the public interface.
59pub use coap_message_utils::Error;
60
61mod forking;
62mod forking_helpers;
63
64// Merely implemented separately; might move them publicly there later and deprecate them here in
65// preparation for a breakin grename.
66pub use forking::{
67    ForkingHandler, ForkingRequestData, ForkingTreeHandler, HandlerBuilder,
68    ReportingHandlerBuilder, new_dispatcher,
69};
70
71use coap_handler::Handler;
72use core::convert::Infallible;
73
74/// A resource that unconditionally responds 4.04 Not Found.
75///
76/// This is a convenience tool for building trees of resources -- rather than special casing the
77/// "none found" situation, this handler can be used.
78pub struct NeverFound {}
79
80impl Handler for NeverFound {
81    type RequestData = Infallible;
82
83    type ExtractRequestError = Error;
84    type BuildResponseError<M: MinimalWritableMessage> = Infallible;
85
86    fn extract_request_data<M: ReadableMessage>(
87        &mut self,
88        _request: &M,
89    ) -> Result<Self::RequestData, Self::ExtractRequestError> {
90        Err(Error::not_found())
91    }
92
93    fn estimate_length(&mut self, _request: &Self::RequestData) -> usize {
94        0
95    }
96
97    fn build_response<M: MutableWritableMessage>(
98        &mut self,
99        _response: &mut M,
100        request: Self::RequestData,
101    ) -> Result<(), Infallible> {
102        match request {}
103    }
104}
105
106mod simple_rendered;
107pub use simple_rendered::{
108    SimpleRenderable, SimpleRenderableData, SimpleRendered, TypedStaticRenderable,
109};
110
111mod typed_resource;
112pub use typed_resource::{
113    DeleteRenderable, Empty, FetchRenderable, GetRenderable, IPatchRenderable, PostRenderable,
114    PutRenderable, TypeHandler, TypeRenderable, TypeRequestData, generated::*,
115};
coap_handler_implementations/lib.rs

coap_handler_implementations/
lib.rs
