coap-handler-implementations 0.3.5

//! The `coap-handler-implementations` crate provides a few convenience, example or
//! reference implementations of the [coap-handler] interface.
//!
//! They range from the generic "4.04
//! Not Found" responder up to a handler that creates a [write] formatter for GET-only resources,
//! and even provides [block-wise transfer] that.
//! The [SimpleWrapper] enables the easy creation of [serde_cbor] based
//! resource implementations with GET, PUT and POST support in CBOR format.
//! The `HandlerBuilder` implements crude static path based routing
//! that may suffice for some applications, and is also useful to get started quickly.
//!
//! [coap-handler]: https://crates.io/crates/coap-handler
//! [write]: https://doc.rust-lang.org/core/fmt/trait.Write.html
//! [block-wise transfer]: https://tools.ietf.org/html/rfc7959
//! [serde_cbor]: https://crates.io/crates/serde_cbor
//!
//! History
//! -------
//!
//! This code used to be part of coap-handler, but while the interface needs to stabilize fast (as
//! incompatible changes there propagate to implementations), the implementations still need to
//! develop fast (but it doesn't hurt too much if one code part is using the old SimpleRenderable
//! while another uses a newer NeverFound).
//!
//! Version 0.1 is what was available in coap-handler (if Cargo allowed cyclic dependencies,
//! coap-handler would `pub use` this crate); users are encouraged to just use
//! coap-handler-implementations directly.
//!
//! Options Hiding
//! --------------
//!
//! A common mechanism in handlers is that handlers "consume" options. For example, the
//! [ForkingHandler] built through [HandlerBuilder::at] "eats" the Uri-Path; likewise, an
//! Accept-based dispatcher would consume the Accept option.
//!
//! This allows the handlers themselves to check for any left-over critical options and fail if
//! they can't handle them -- without the need to mask them out there assuming (without an actual
//! check) that prior wrappers took care of them.
#![no_std]
#![cfg_attr(
    feature = "nontrivial_option_processing",
    feature(type_alias_impl_trait)
)]

use coap_message::{MessageOption, MutableWritableMessage, ReadableMessage};
use core::marker::PhantomData;

pub mod helpers;
pub mod option_processing;
pub mod wkc;
mod wkc_implementation;

mod forking;
mod forking_helpers;

// Merely implemented separately; might move them publicly there later and deprecate them here in
// preparation for a breakin grename.
pub use forking::{
    new_dispatcher, ForkingHandler, ForkingRequestData, ForkingTreeHandler, HandlerBuilder,
    ReportingHandlerBuilder,
};

use crate::helpers::{block2_write_with_cf, codeconvert, Block2RequestData};
use coap_handler::Handler;

use coap_numbers::{code, option};

/// Used to store response codes internally until the type of the response message is determined and
/// it can be converted into an actual outgoing code
///
/// It was tried to use an enum here, but in the end that needs to go through something
/// [codeconvert]-like just again. As the output message type is generally not known in advance,
/// that can't be used either.
type Code = u8;

/// A resource that unconditionally responds 4.04 Not Found.
///
/// This is a convenience tool for building trees of resources -- rather than special casing the
/// "none found" situation, this handler can be used.
pub struct NeverFound {}

impl Handler for NeverFound {
    type RequestData = ();

    fn extract_request_data(&mut self, _request: &impl ReadableMessage) -> Self::RequestData {
        ()
    }

    fn estimate_length(&mut self, _request: &Self::RequestData) -> usize {
        0
    }

    fn build_response(
        &mut self,
        response: &mut impl MutableWritableMessage,
        _request: Self::RequestData,
    ) {
        response.set_code(codeconvert(code::NOT_FOUND));
        response.set_payload(b"");
    }
}

/// Information a SimpleRenderable needs to carry from request to response.
// Newtype wrapper to avoid exposing Block2RequestData
pub struct SimpleRenderableData(Result<Block2RequestData, Code>);

/// A simplified Handler trait that can react to GET requests and will render to a fmt::Write
/// object with blockwise backing.
///
/// Anything that implements it (which includes plain &str, for example) can be packed into a
/// [SimpleRendered] to form a Handler.
///
/// For binary data, render_bytes can be implemented instead of render, and utilize the
/// WindowedInfinityWithETag's write_bytes method (multiple times, if so desired). In that case, the render
/// function can be left unimplemented.
pub trait SimpleRenderable {
    fn render<W>(&mut self, writer: &mut W)
    where
        W: core::fmt::Write;

    fn render_bytes(&mut self, writer: &mut helpers::WindowedInfinityWithETag) {
        self.render(writer)
    }

    /// If something is returned, GETs with differing Accept options will be rejecected, and the
    /// value will be set in responses.
    fn content_format(&self) -> Option<u16> {
        None
    }
}

/// A container that turns any [SimpleRenderable] (including [&str]) into a CoAP resource
/// [Handler].
///
/// See [SimpleRenderable] for further information.
#[derive(Debug, Copy, Clone)]
pub struct SimpleRendered<T: SimpleRenderable>(pub T);

impl<'a> SimpleRendered<TypedStaticRenderable<'a>> {
    pub fn new_typed_slice(data: &'a [u8], content_format: Option<u16>) -> Self {
        SimpleRendered(TypedStaticRenderable {
            data,
            content_format,
        })
    }

    pub fn new_typed_str(data: &'a str, content_format: Option<u16>) -> Self {
        let data = data.as_bytes();
        Self::new_typed_slice(data, content_format)
    }
}

impl<T> Handler for SimpleRendered<T>
where
    T: SimpleRenderable,
{
    type RequestData = SimpleRenderableData;

    fn extract_request_data(&mut self, request: &impl ReadableMessage) -> Self::RequestData {
        let expected_accept = self.0.content_format();

        let mut block2 = Ok(None);

        for o in request.options() {
            match o.number() {
                coap_numbers::option::ACCEPT => {
                    if expected_accept.is_some() && o.value_uint() != expected_accept {
                        return SimpleRenderableData(Err(coap_numbers::code::NOT_ACCEPTABLE));
                    }
                }
                coap_numbers::option::BLOCK2 => {
                    block2 = match block2 {
                        Err(e) => Err(e),
                        Ok(Some(_)) => Err(coap_numbers::code::BAD_REQUEST),
                        Ok(None) => Block2RequestData::from_option(&o)
                            .map(Some)
                            .map_err(|_| code::BAD_REQUEST),
                    }
                }
                o if option::get_criticality(o) == option::Criticality::Critical => {
                    return SimpleRenderableData(Err(code::BAD_OPTION));
                }
                _ => (),
            }
        }

        let reqdata = match request.code().into() {
            code::GET => block2.map(|o| o.unwrap_or_default()),
            _ => Err(code::METHOD_NOT_ALLOWED),
        };
        SimpleRenderableData(reqdata)
    }

    fn estimate_length(&mut self, _request: &Self::RequestData) -> usize {
        1280 - 40 - 4 // does this correclty calculate the IPv6 minimum MTU?
    }

    fn build_response(
        &mut self,
        response: &mut impl MutableWritableMessage,
        request: Self::RequestData,
    ) {
        let block2data = match request.0 {
            Ok(x) => x,
            Err(c) => {
                response.set_code(codeconvert(c));
                response.set_payload(b"");
                return;
            }
        };

        let cf = self.0.content_format();
        response.set_code(codeconvert(code::CONTENT));
        block2_write_with_cf(block2data, response, |w| self.0.render_bytes(w), cf);
    }
}

impl<T> wkc::Reporting for SimpleRendered<T>
where
    T: SimpleRenderable,
{
    type Record<'a> = wkc::EmptyRecord
    where
        Self: 'a,
    ;
    type Reporter<'a> = core::iter::Once<wkc::EmptyRecord>
    where
        Self: 'a,
    ;

    fn report(&self) -> Self::Reporter<'_> {
        // Using a ConstantSliceRecord instead would be tempting, but that'd need a const return
        // value from self.0.content_format()
        core::iter::once(wkc::EmptyRecord {})
    }
}

impl<'a> SimpleRenderable for &'a str {
    fn render<W>(&mut self, writer: &mut W)
    where
        W: core::fmt::Write,
    {
        writer
            .write_str(self)
            .expect("The backend of SimpleRenderable supports infallible writing");
    }

    fn content_format(&self) -> Option<u16> {
        Some(0)
    }
}

pub struct TypedStaticRenderable<'a> {
    data: &'a [u8],
    content_format: Option<u16>,
}

impl<'a> SimpleRenderable for TypedStaticRenderable<'a> {
    fn render<W>(&mut self, _: &mut W)
    where
        W: core::fmt::Write,
    {
        unimplemented!("render_bytes is implemented instead")
    }

    fn render_bytes(&mut self, writer: &mut helpers::WindowedInfinityWithETag) {
        writer.write(self.data)
    }

    fn content_format(&self) -> Option<u16> {
        self.content_format
    }
}

use serde::Serialize;

/// A simple Handler trait that supports GET, POST and/or PUT on a data structure that supports
/// serde.
///
/// A SimpleCBORHandler implementation can be turned into a [Handler] by wrapping it in
/// [SimpleWrapper::new].
///
/// The type a misnomer that can't be fixed until trait aliases are stabilized: It doesn't need to
/// turn into CBOR, just something the Simple...Wrapper can (de)serialize.
pub trait SimpleCBORHandler {
    type Get;
    type Post;
    type Put;

    fn get(&mut self) -> Result<Self::Get, Code> {
        Err(code::METHOD_NOT_ALLOWED)
    }
    fn post(&mut self, _representation: &Self::Post) -> Code {
        code::METHOD_NOT_ALLOWED
    }
    fn put(&mut self, _representation: &Self::Put) -> Code {
        code::METHOD_NOT_ALLOWED
    }
}

/// Keeping them hidden to stay flexible; they don't need to be named for their'e either default or
/// their users have aliases.
mod sealed {
    pub trait SimpleSerialization {
        const CF: Option<u16>;
    }

    pub struct SerdeCBORSerialization;
    pub struct MiniCBORSerialization;
}
use sealed::*;

impl SimpleSerialization for SerdeCBORSerialization {
    const CF: Option<u16> = Some(60);
}
impl SimpleSerialization for MiniCBORSerialization {
    const CF: Option<u16> = Some(60);
}

/// Wrapper for resource handlers that are implemented in terms of GETting, POSTing or PUTting
/// objects in CBOR format.
///
/// The wrapper handles all encoding and decoding, options processing (ignoring the critical
/// Uri-Path option under the assumption that that has been already processed by an underlying
/// request router), the corresponding errors and block-wise GETs.
///
/// More complex handlers (eg. implementing additional representations, or processing query
/// aprameters into additional data available to the [SimpleCBORHandler]) can be built by
/// forwarding to this (where any critical but already processed options would need to be masked
/// from the message's option) or taking inspiration from it.
pub struct SimpleWrapper<H, S: SimpleSerialization = SerdeCBORSerialization>
where
    H: SimpleCBORHandler,
{
    handler: H,
    _phantom: PhantomData<S>,
}
#[deprecated(note = "Renamed to SimpleWrapper")]
pub type SimpleCBORWrapper<H> = SimpleWrapper<H, SerdeCBORSerialization>;

impl<H, S> SimpleWrapper<H, S>
where
    H: SimpleCBORHandler,
    S: SimpleSerialization,
{
    fn check_get_options(request: &impl ReadableMessage) -> Result<Block2RequestData, Code> {
        let mut block2 = Ok(None);

        for o in request.options() {
            match o.number() {
                option::ACCEPT => {
                    if let Some(cf) = S::CF {
                        if o.value_uint() != Some(cf) {
                            return Err(code::UNSUPPORTED_CONTENT_FORMAT);
                        }
                    }
                }
                option::BLOCK2 => {
                    block2 = match block2 {
                        Err(e) => Err(e),
                        Ok(Some(_)) => Err(coap_numbers::code::BAD_REQUEST),
                        Ok(None) => Block2RequestData::from_option(&o)
                            .map(Some)
                            .map_err(|_| code::BAD_REQUEST),
                    }
                }
                o if option::get_criticality(o) == option::Criticality::Critical => {
                    return Err(code::BAD_OPTION);
                }
                _ => {}
            }
        }

        Ok(block2?.unwrap_or_default())
    }

    fn check_postput_options(request: &impl ReadableMessage) -> Result<(), Code> {
        for o in request.options() {
            match o.number() {
                option::CONTENT_FORMAT => {
                    if let Some(cf) = S::CF {
                        if o.value_uint() != Some(cf) {
                            return Err(code::NOT_ACCEPTABLE);
                        }
                    } else {
                        /* Nothing was configured, not letting the option pass */
                        return Err(code::NOT_ACCEPTABLE);
                    }
                }
                o if option::get_criticality(o) == option::Criticality::Critical => {
                    return Err(code::BAD_OPTION);
                }
                _ => {}
            }
        }

        Ok(())
    }
}

impl<H> SimpleWrapper<H, SerdeCBORSerialization>
where
    H: SimpleCBORHandler,
    H::Get: for<'de> serde::Serialize,
    H::Post: for<'de> serde::Deserialize<'de>,
    H::Put: for<'de> serde::Deserialize<'de>,
{
    pub fn new(handler: H) -> Self {
        SimpleWrapper {
            handler,
            _phantom: PhantomData,
        }
    }
}

#[cfg(feature = "minicbor")]
impl<H> SimpleWrapper<H, MiniCBORSerialization>
where
    H: SimpleCBORHandler,
    H::Get: for<'de> minicbor::Encode,
    H::Post: for<'de> minicbor::Decode<'de>,
    H::Put: for<'de> minicbor::Decode<'de>,
{
    pub fn new_minicbor(handler: H) -> Self {
        SimpleWrapper {
            handler,
            _phantom: PhantomData,
        }
    }
}

/// Data carried around between a request and its response for [SimpleWrapper]s
pub enum SimpleRequestData {
    Get(Block2RequestData), // GET to be processed later, but all request opions were in order
    Done(Code), // All done, just a response to emit -- if POST/PUT has been processed, or GET had a bad accept/option
}
#[deprecated(note = "Renamed to SimpleRequestData")]
pub type SimpleCBORRequestData = SimpleRequestData;
use self::SimpleRequestData::{Done, Get};

// FIXME for all the below: deduplicate (but not sure how, without HKTs)

impl<H> Handler for SimpleWrapper<H, SerdeCBORSerialization>
where
    H: SimpleCBORHandler,
    H::Get: for<'de> serde::Serialize,
    H::Post: for<'de> serde::Deserialize<'de>,
    H::Put: for<'de> serde::Deserialize<'de>,
{
    type RequestData = SimpleRequestData;

    fn extract_request_data(&mut self, request: &impl ReadableMessage) -> Self::RequestData {
        match request.code().into() {
            code::GET => match Self::check_get_options(request) {
                Err(e) => Done(e),
                Ok(block) => Get(block),
            },
            code::POST => {
                if let Err(e) = Self::check_postput_options(request) {
                    return Done(e);
                }

                // FIXME: allow getting a mutable payload here, which may be hard for general
                // Message but usually cheap for GNRC-based.
                let parsed: Result<H::Post, _> =
                    serde_cbor::de::from_slice_with_scratch(request.payload(), &mut []);
                match parsed {
                    Ok(p) => Done(self.handler.post(&p)),
                    Err(_) => Done(code::BAD_REQUEST),
                }
            }
            code::PUT => {
                if let Err(e) = Self::check_postput_options(request) {
                    return Done(e);
                }

                let parsed: Result<H::Put, _> =
                    serde_cbor::de::from_slice_with_scratch(request.payload(), &mut []);
                match parsed {
                    Ok(p) => Done(self.handler.put(&p)),
                    Err(_) => Done(code::BAD_REQUEST),
                }
            }
            _ => Done(code::METHOD_NOT_ALLOWED),
        }
    }

    fn estimate_length(&mut self, request: &Self::RequestData) -> usize {
        match request {
            Done(_) => 4,
            Get(block) => (block.size() + 25).into(), // FIXME: hard-coded copied over from block2_write_with_cf's estimated overhead
        }
    }

    fn build_response(
        &mut self,
        response: &mut impl MutableWritableMessage,
        request: Self::RequestData,
    ) {
        match request {
            Done(r) => {
                response.set_code(codeconvert(r));
                response.set_payload(b"");
            }
            Get(block2) => {
                let repr = self.handler.get();
                match repr {
                    Err(e) => {
                        response.set_code(codeconvert(e));
                        response.set_payload(b"");
                    }
                    Ok(repr) => {
                        response.set_code(codeconvert(code::CONTENT));
                        match block2_write_with_cf(
                            block2,
                            response,
                            |win| repr.serialize(&mut serde_cbor::ser::Serializer::new(win)),
                            SerdeCBORSerialization::CF,
                        ) {
                            Ok(()) => (),
                            Err(_) => {
                                // FIXME: Rewind all the written options
                                response.set_code(codeconvert(code::INTERNAL_SERVER_ERROR));
                            }
                        }
                    }
                }
            }
        }
    }
}

#[cfg(feature = "minicbor")]
impl<H> Handler for SimpleWrapper<H, MiniCBORSerialization>
where
    H: SimpleCBORHandler,
    H::Get: for<'de> minicbor::Encode,
    H::Post: for<'de> minicbor::Decode<'de>,
    H::Put: for<'de> minicbor::Decode<'de>,
{
    type RequestData = SimpleRequestData;

    fn extract_request_data(&mut self, request: &impl ReadableMessage) -> Self::RequestData {
        match request.code().into() {
            code::GET => match Self::check_get_options(request) {
                Err(e) => Done(e),
                Ok(block) => Get(block),
            },
            code::POST => {
                if let Err(e) = Self::check_postput_options(request) {
                    return Done(e);
                }

                let parsed: Result<H::Post, _> = minicbor::decode(request.payload());
                match parsed {
                    Ok(p) => Done(self.handler.post(&p)),
                    Err(_) => Done(code::BAD_REQUEST),
                }
            }
            code::PUT => {
                if let Err(e) = Self::check_postput_options(request) {
                    return Done(e);
                }

                let parsed: Result<H::Put, _> = minicbor::decode(request.payload());
                match parsed {
                    Ok(p) => Done(self.handler.put(&p)),
                    Err(_) => Done(code::BAD_REQUEST),
                }
            }
            _ => Done(code::METHOD_NOT_ALLOWED),
        }
    }

    fn estimate_length(&mut self, request: &Self::RequestData) -> usize {
        match request {
            Done(_) => 4,
            Get(block) => (block.size() + 25).into(), // FIXME: hard-coded copied over from block2_write_with_cf's estimated overhead
        }
    }

    fn build_response(
        &mut self,
        response: &mut impl MutableWritableMessage,
        request: Self::RequestData,
    ) {
        match request {
            Done(r) => {
                response.set_code(codeconvert(r));
                response.set_payload(b"");
            }
            Get(block2) => {
                let repr = self.handler.get();
                match repr {
                    Err(e) => {
                        response.set_code(codeconvert(e));
                        response.set_payload(b"");
                    }
                    Ok(repr) => {
                        response.set_code(codeconvert(code::CONTENT));
                        match block2_write_with_cf(
                            block2,
                            response,
                            |win| minicbor::encode(&repr, win),
                            MiniCBORSerialization::CF,
                        ) {
                            Ok(()) => (),
                            Err(_) => {
                                // FIXME: Rewind all the written options
                                response.set_code(codeconvert(code::INTERNAL_SERVER_ERROR));
                            }
                        }
                    }
                }
            }
        }
    }
}