Trait Handler

pub trait Handler {
    type RequestData;
    type ExtractRequestError: Debug + RenderableOnMinimal;
    type BuildResponseError<M: MinimalWritableMessage>: Debug + RenderableOnMinimal;

    // Required methods
    fn extract_request_data<M: ReadableMessage>(
        &mut self,
        request: &M,
    ) -> Result<Self::RequestData, Self::ExtractRequestError>;
    fn estimate_length(&mut self, request: &Self::RequestData) -> usize;
    fn build_response<M: MutableWritableMessage>(
        &mut self,
        response: &mut M,
        request: Self::RequestData,
    ) -> Result<(), Self::BuildResponseError<M>>;
}

A CoAP request handler. This gets called by a CoAP server implementation that the handler is assigned to; the server has the handler processes the request’s data into a RequestData structure, possibly calls asks for the expected length before allocating a response message, and then asks the handler to populate the allocated response message with data persisted in the RequestData structure.

Both data extraction and response building are fallible operations. In the error case, it is up to the CoAP server implementation to reset the message into a state into which the error can be rendered. There is currently no trait method in coap_message that describes how that would be done, but the CoAP implementation knows the concrete type and can use its methods directly.

Required Associated Types

type RequestData

Type constructed in extract_request_data() passed on to build_response().

This type can usually be made very compact, with exceptions for POST style requests where not only do request and response have large payloads, but also both are needed at the same time.

type ExtractRequestError: Debug + RenderableOnMinimal

Error type for extract_request_data().

Typical types to use here are core::convert::Infallible (which, due to the possibility of unknown critical CoAP options, is only practical when their presence is carried in the extracted data) or types provided by libraries (eg. coap-handler-implementations::Error).

type BuildResponseError<M: MinimalWritableMessage>: Debug + RenderableOnMinimal

Error type for writing response data.

This is generic over writable messages because the most typical errors to show up here are generated when writing to the messages. A suitable type here is M::UnionError.

Required Methods

fn extract_request_data<M: ReadableMessage>( &mut self, request: &M, ) -> Result<Self::RequestData, Self::ExtractRequestError>

Process an incoming request.

Unless the server implementation performs request deduplication, this may be called multiple times per request. Whether a server performs request deduplication (and thus the handlers need to be idempotent, which is best practice in CoAP anyway) is not expressed in the type system.

Effects of requests may already be performed at this step – to the point where Self::RequestData is () to indicate success.

fn estimate_length(&mut self, request: &Self::RequestData) -> usize

Estimate an upper bound for the number of bytes in the response

Sizes are counted as in UDP after the header, i.e., encoded options plus payload indicator plus payload.

fn build_response<M: MutableWritableMessage>( &mut self, response: &mut M, request: Self::RequestData, ) -> Result<(), Self::BuildResponseError<M>>

Build a response for the request

While this is typically called exactly once per request, it can also be called not at all (eg. if a TCP connection was dropped between parsing the request and sending the response) or multiple times (if the response was sent in a CON, needed to be retransmitted, and the RequestData is Clone).

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<H> Handler for Option<H>

where H: Handler,

An easy way to have resources that may or may not be there in a tree, considering that Handler is not object safe and thus, if let Some(x) { all = all.at(...) } won’t work.

This returns 4.04 Not Found if the inner handler is absent, and otherwise forwards request and response building.

type RequestData = Option<<H as Handler>::RequestData>

type ExtractRequestError = <H as Handler>::ExtractRequestError

type BuildResponseError<M: MinimalWritableMessage> = <H as Handler>::BuildResponseError<M>

fn extract_request_data<M: ReadableMessage>( &mut self, request: &M, ) -> Result<Self::RequestData, Self::ExtractRequestError>

fn estimate_length(&mut self, request: &Self::RequestData) -> usize

fn build_response<M: MutableWritableMessage>( &mut self, response: &mut M, request: Self::RequestData, ) -> Result<(), H::BuildResponseError<M>>

Implementors