fundamentum_edge_mcu_http_client/

http_client.rs

use core::{marker::PhantomData, str};

use httparse::{Response, Status};
use serde::{Deserialize, Serialize};
use serde_json_core::ser;

use crate::{
    api_version::{ApiVersion, V3},
    http_client_config::HttpClientConfig,
    models::{
        ApiResponse, ApiResponseFailedData, ApiResponseFailedEmpty, ApiStatus, HttpBody,
        HttpMethod, HttpRequest, StatusCode,
    },
    HttpClientError, HttpClientErrorWrapper, HttpHandler,
};

/// The common successful Fundamentum API's response is 300 bytes long. Thus, 2K should be fine.
const MAX_BODY_LENGTH: usize = 2048;
/// The usage [example][httparse-github] of the `httparse` crate recommends 64 headers.
///
/// [httparse-github]: https://github.com/seanmonstar/httparse?tab=readme-ov-file#usage
const MAX_NUMBER_OF_HEADERS: usize = 64;
const DEFAULT_API_PATH: &str = "/api";
const PATH_SEPARATOR: &str = "/";
const CONTENT_LENGTH_HEADER: &str = "Content-Length";

/// Client wrapping a [`HttpHandler`] structure to to perform requests with
/// the Fundamentum API for a specific version.
//
// TODO: ASP00009-1809: The HttpClient should not have a version, and this be handled by the FundamentumApi
pub struct HttpClient<'a, V: ApiVersion, H: HttpHandler> {
    config: HttpClientConfig<'a>,
    http_handler: H,
    // We use PhantomData to make the compiler think that we are using the V type.
    // Read more here: <https://doc.rust-lang.org/nomicon/phantom-data.html#table-of-phantomdata-patterns>
    _marker: PhantomData<fn() -> V>,
}

impl<'a, H: HttpHandler> HttpClient<'a, V3, H> {
    /// Create a new HTTP client.
    #[must_use]
    pub fn new(config: HttpClientConfig<'a>, http_handler: H) -> Self {
        Self {
            config,
            http_handler,
            _marker: PhantomData,
        }
    }

    /// Get the current configuration of this client.
    #[must_use]
    pub const fn config(&self) -> &HttpClientConfig {
        &self.config
    }

    /// Send JSON request with the configuration and the handler.
    ///
    /// # Errors
    ///
    /// See [`HttpClientError`] for the error type.
    pub async fn send<'d, B, T>(
        &'a self,
        method: HttpMethod,
        base_path: Option<&'a str>,
        path: &'a str,
        body: B,
        // TODO: ASP00009-1811: The HTTP library's API should expose a structure to manage all buffer usages
        out_buffer: &'d mut [u8],
    ) -> Result<T, HttpClientErrorWrapper<'d, H>>
    where
        B: Serialize,
        T: Deserialize<'d>,
    {
        // Serialize body
        let mut serialized: [u8; MAX_BODY_LENGTH] = [0; MAX_BODY_LENGTH];
        let size = serde_json_core::to_slice(&body, &mut serialized).map_err(|e| match e {
            ser::Error::BufferFull => HttpClientError::SerializationBufferFull(MAX_BODY_LENGTH),
            _ => HttpClientError::Serialization,
        })?;
        #[allow(clippy::shadow_reuse)]
        let serialized = &serialized[0..size];

        let request = HttpRequest {
            method,
            domain_name: self.config.domain_name,
            port: self.config.port,
            user_agent: self.config.user_agent,
            base_path: base_path.or(Some(const_format::concatcp!(
                DEFAULT_API_PATH,
                PATH_SEPARATOR,
                V3::VERSION
            ))),
            path,
            accept: "application/json",
            body: Some(HttpBody {
                content_type: "application/json",
                body: serialized,
            }),
        };

        // Send HTTPS request
        self.http_handler
            .http_call(request, out_buffer)
            .await
            .map_err(HttpClientError::SendRequest)?;

        // Extract body
        let (body, status_code) = Self::extract_body(out_buffer)?;

        // TODO: See related GitHub Issue : https://github.com/rust-embedded-community/serde-json-core/issues/87
        //
        // TODO: ASP00009-1808: The Fundamentum API's response should be handled without specific errors
        //
        // Should be this :
        //
        // ```
        // let (api_response, _size): (ApiResponseFailedData<'d>, usize) =
        //     serde_json_core::from_slice(body).map_err(HttpClientError::DeserializationFailed)?;
        // ```
        let (api_response, _bytes): (ApiResponse<'d, T>, usize) =
            match serde_json_core::from_slice(body) {
                Ok(response) => response,
                Err(_) => match serde_json_core::from_slice::<ApiResponseFailedData<'d>>(body) {
                    Ok((response_failed, size)) => (ApiResponse::from(response_failed), size),

                    Err(_) => match serde_json_core::from_slice::<ApiResponseFailedEmpty<'d>>(body)
                    {
                        Ok((response_failed, size)) => (ApiResponse::from(response_failed), size),

                        Err(e) => return Err(HttpClientError::DeserializationFailed(e).into()),
                    },
                },
            };

        // Handle errors
        match api_response.status {
            Some(ApiStatus::Success) => {
                Ok(api_response.data.ok_or(HttpClientError::MissingDataField)?)
            }

            Some(ApiStatus::Error) => api_response.message.map_or_else(
                || Err(HttpClientError::FailedAndMissingMessageField.into()),
                |message: &'d str| {
                    Err(HttpClientErrorWrapper::GenericApiError {
                        message,
                        status_code,
                    })
                },
            ),

            None => Err(HttpClientError::MissingStatusField.into()),
        }
    }
}

impl<'a, V: ApiVersion, H: HttpHandler> HttpClient<'a, V, H> {
    /// Extracts the body from a HTTP response buffer.
    ///
    /// # Errors
    ///
    /// See [`HttpClientError`] for the error type.
    fn extract_body(buffer: &[u8]) -> Result<(&[u8], StatusCode), HttpClientError<H>> {
        // Create response
        let mut headers = [httparse::EMPTY_HEADER; MAX_NUMBER_OF_HEADERS];
        let mut response = Response::new(&mut headers);

        let body_index = match response.parse(buffer).map_err(HttpClientError::ParseHttp)? {
            Status::Complete(body_start_index) => body_start_index,
            Status::Partial => {
                return Err(HttpClientError::PartialHttpRequest);
            }
        };
        let status_code = response.code.ok_or(HttpClientError::NoStatusCode)?;

        // Extract content length
        let content_length_header = response
            .headers
            .iter()
            .find(|header| header.name == CONTENT_LENGTH_HEADER)
            .ok_or(HttpClientError::NoContentHeader)?;

        let content_length = str::from_utf8(content_length_header.value)
            .map_err(|e| HttpClientError::Utf8Conversion(e.valid_up_to()))?
            .parse::<usize>()
            .map_err(HttpClientError::ContentLengthConversion)?;

        let body = &buffer[body_index..(body_index + content_length)];

        Ok((body, StatusCode(status_code)))
    }
}

// MARK: tests

#[cfg(test)]
mod tests {
    use httparse::Error as HttpParseError;
    use indoc::indoc;

    use super::*;

    #[derive(Debug, PartialEq, Eq)]
    struct TestHttpHandler<'a> {
        response: &'a [u8],
    }

    #[derive(Debug, PartialEq, Eq)]
    #[cfg_attr(feature = "log", derive(defmt::Format))]
    enum TestHttpHandlerError {
        InvalidPath,
    }

    #[derive(Debug, PartialEq, Eq, Deserialize)]
    #[cfg_attr(feature = "log", derive(defmt::Format))]
    struct TestDataStructure {
        test: u8,
    }

    impl<'b> HttpHandler for TestHttpHandler<'b> {
        type Error = TestHttpHandlerError;

        async fn http_call<'a, 'd>(
            &'a self,
            request: HttpRequest<'_>,
            out_buffer: &'d mut [u8],
        ) -> Result<(), Self::Error> {
            if request.path == INVALID_PATH {
                return Err(TestHttpHandlerError::InvalidPath);
            }

            out_buffer[0..self.response.len()].copy_from_slice(self.response);

            Ok(())
        }
    }

    const VALID_TEST_DATA_STRUCTURE_RESPONSE: &str = indoc! {r#"
        HTTP/1.1 200 OK
        Content-Type: application/json; charset=utf-8
        Content-Length: 39
        Connection: close

        {"status":"success","data":{"test":42}}
    "#};

    const ANY_METHOD: HttpMethod = HttpMethod::GET;
    const ANY_PATH: &str = "any";
    const ANY_BODY: &str = "any";
    const INVALID_PATH: &str = "invalid_path";

    fn given_http_client(response: &[u8]) -> (HttpClient<V3, TestHttpHandler<'_>>, [u8; 2048]) {
        let http_handler = TestHttpHandler { response };
        let http_client =
            HttpClient::<'_, V3, TestHttpHandler>::new(HttpClientConfig::default(), http_handler);
        let response_buffer: [u8; 2048] = [0; 2048];

        (http_client, response_buffer)
    }

    #[tokio::test]
    async fn given_valid_parameters_and_response_when_send_http_then_ok_t() {
        let (http_client, mut response_buffer) =
            given_http_client(VALID_TEST_DATA_STRUCTURE_RESPONSE.as_bytes());

        let response: TestDataStructure = http_client
            .send(ANY_METHOD, None, ANY_PATH, ANY_BODY, &mut response_buffer)
            .await
            .unwrap();

        assert_eq!(42, response.test);
    }

    #[tokio::test]
    async fn given_serialization_buffer_too_small_when_send_http_then_serialization_err() {
        let (http_client, mut response_buffer) =
            given_http_client(VALID_TEST_DATA_STRUCTURE_RESPONSE.as_bytes());
        let body_buffer: [u8; MAX_BODY_LENGTH + 1] = [0; MAX_BODY_LENGTH + 1];
        let body = str::from_utf8(&body_buffer).unwrap();

        let response = http_client
            .send::<_, ()>(ANY_METHOD, None, ANY_PATH, body, &mut response_buffer)
            .await;

        assert_eq!(
            HttpClientErrorWrapper::OtherErrors(HttpClientError::SerializationBufferFull(2048)),
            response.unwrap_err()
        );
    }

    #[tokio::test]
    async fn given_http_call_error_when_send_http_then_request_err() {
        let (http_client, mut response_buffer) =
            given_http_client(VALID_TEST_DATA_STRUCTURE_RESPONSE.as_bytes());

        let response = http_client
            .send::<_, ()>(
                ANY_METHOD,
                Some("/"),
                INVALID_PATH,
                ANY_BODY,
                &mut response_buffer,
            )
            .await;

        assert_eq!(
            HttpClientErrorWrapper::OtherErrors(HttpClientError::SendRequest(
                TestHttpHandlerError::InvalidPath
            )),
            response.unwrap_err()
        );
    }

    #[tokio::test]
    async fn given_no_status_field_when_send_http_then_missing_status_field() {
        let response = indoc! {r#"
            HTTP/1.1 200 OK
            Content-Type: application/json; charset=utf-8
            Content-Length: 91
            Connection: close

            {"data":{"configuration":null,"mqtt":{"host":"mqtts.fundamentum-iot-dev.com","port":8883}}}
        "#};

        let (http_client, mut response_buffer) = given_http_client(response.as_bytes());

        let response = http_client
            .send::<_, ()>(ANY_METHOD, None, ANY_PATH, ANY_BODY, &mut response_buffer)
            .await;

        assert_eq!(
            HttpClientErrorWrapper::OtherErrors(HttpClientError::MissingStatusField),
            response.unwrap_err()
        );
    }

    #[tokio::test]
    async fn given_no_data_field_when_send_http_then_missing_data_field() {
        let response = indoc! {r#"
            HTTP/1.1 200 OK
            Content-Type: application/json; charset=utf-8
            Content-Length: 20
            Connection: close

            {"status":"success"}
        "#};
        let (http_client, mut response_buffer) = given_http_client(response.as_bytes());

        let response = http_client
            .send::<_, ()>(ANY_METHOD, None, ANY_PATH, ANY_BODY, &mut response_buffer)
            .await;

        assert_eq!(
            HttpClientErrorWrapper::OtherErrors(HttpClientError::MissingDataField),
            response.unwrap_err()
        );
    }

    #[tokio::test]
    async fn given_no_message_field_when_send_http_then_missing_message_field() {
        let response = indoc! {r#"
            HTTP/1.1 200 OK
            Content-Type: application/json; charset=utf-8
            Content-Length: 28
            Connection: close

            {"status":"error","data":{}}
        "#};
        let (http_client, mut response_buffer) = given_http_client(response.as_bytes());

        let response = http_client
            .send::<_, ()>(ANY_METHOD, None, ANY_PATH, ANY_BODY, &mut response_buffer)
            .await;

        assert_eq!(
            HttpClientErrorWrapper::OtherErrors(HttpClientError::FailedAndMissingMessageField),
            response.unwrap_err()
        );
    }

    // MARK: extract_body()

    #[test]
    fn given_valid_response_when_extract_body_then_body_and_status_code() {
        let buffer = indoc! {r#"
            HTTP/1.1 200 OK
            Content-Type: application/json; charset=utf-8
            Content-Length: 110
            Connection: close

            {"status":"success","data":{"configuration":null,"mqtt":{"host":"mqtts.fundamentum-iot-dev.com","port":8883}}}
        "#};
        let expected_body = r#"{"status":"success","data":{"configuration":null,"mqtt":{"host":"mqtts.fundamentum-iot-dev.com","port":8883}}}"#;

        let (body, status_code) =
            HttpClient::<'_, V3, TestHttpHandler>::extract_body(buffer.as_bytes()).unwrap();

        assert_eq!(expected_body, str::from_utf8(body).unwrap());
        assert_eq!(StatusCode(200), status_code);
    }

    #[test]
    fn given_bad_http_response_when_extract_body_then_parse_http_err() {
        let buffer_missing_space = indoc! {r#"
            HTTP/1.1 200 OK
            Content-Type: application/json; charset=utf-8
            Content-Length: 110
            Connection: close
            {"status":"success","data":{"configuration":null,"mqtt":{"host":"mqtts.fundamentum-iot-dev.com","port":8883}}}
        "#};

        let result =
            HttpClient::<'_, V3, TestHttpHandler>::extract_body(buffer_missing_space.as_bytes());

        assert_eq!(
            HttpClientError::ParseHttp(HttpParseError::HeaderName),
            result.unwrap_err()
        );
    }

    #[test]
    fn given_partial_http_response_when_extract_body_then_partial_http_err() {
        let buffer_missing_headers_and_body = indoc! {"
            HTTP/1.1 200 OK
            Content-Type: application/json; charset=utf-8
            Content-Length: 110"
        };

        let result = HttpClient::<'_, V3, TestHttpHandler>::extract_body(
            buffer_missing_headers_and_body.as_bytes(),
        );

        assert_eq!(HttpClientError::PartialHttpRequest, result.unwrap_err());
    }

    #[test]
    fn given_missing_content_length_header_when_extract_body_then_no_content_header_err() {
        let buffer_missing_content_length = indoc! {r#"
            HTTP/1.1 200 OK
            Content-Type: application/json; charset=utf-8
            Connection: close

            {"status":"success","data":{"configuration":null,"mqtt":{"host":"mqtts.fundamentum-iot-dev.com","port":8883}}}
        "#};

        let result = HttpClient::<'_, V3, TestHttpHandler>::extract_body(
            buffer_missing_content_length.as_bytes(),
        );

        assert_eq!(HttpClientError::NoContentHeader, result.unwrap_err());
    }

    #[test]
    fn given_invalid_utf8_string_when_extract_body_then_utf8_err() {
        let buffer_with_invalid_utf8 = [
            0x48, 0x54, 0x54, 0x50, 0x2f, 0x31, 0x2e, 0x31, 0x20, 0x32, 0x30, 0x30, 0x20, 0x4f,
            0x4b, 0x0a, 0x43, 0x6f, 0x6e, 0x74, 0x65, 0x6e, 0x74, 0x2d, 0x54, 0x79, 0x70, 0x65,
            0x3a, 0x20, 0x61, 0x70, 0x70, 0x6c, 0x69, 0x63, 0x61, 0x74, 0x69, 0x6f, 0x6e, 0x2f,
            0x6a, 0x73, 0x6f, 0x6e, 0x3b, 0x20, 0x63, 0x68, 0x61, 0x72, 0x73, 0x65, 0x74, 0x3d,
            0x75, 0x74, 0x66, 0x2d, 0x38, 0x0a, 0x43, 0x6f, 0x6e, 0x74, 0x65, 0x6e, 0x74, 0x2d,
            0x4c, 0x65, 0x6e, 0x67, 0x74, 0x68, 0x3a, 0x20, 0x31, 0xff, // "0x31 => 0xFF"
            0x30, 0x0a, 0x43, 0x6f, 0x6e, 0x6e, 0x65, 0x63, 0x74, 0x69, 0x6f, 0x6e, 0x3a, 0x20,
            0x63, 0x6c, 0x6f, 0x73, 0x65, 0x0a, 0x0a, 0x7b, 0x22, 0x73, 0x74, 0x61, 0x74, 0x75,
            0x73, 0x22, 0x3a, 0x22, 0x73, 0x75, 0x63, 0x63, 0x65, 0x73, 0x73, 0x22, 0x2c, 0x22,
            0x64, 0x61, 0x74, 0x61, 0x22, 0x3a, 0x7b, 0x22, 0x63, 0x6f, 0x6e, 0x66, 0x69, 0x67,
            0x75, 0x72, 0x61, 0x74, 0x69, 0x6f, 0x6e, 0x22, 0x3a, 0x6e, 0x75, 0x6c, 0x6c, 0x2c,
            0x22, 0x6d, 0x71, 0x74, 0x74, 0x22, 0x3a, 0x7b, 0x22, 0x68, 0x6f, 0x73, 0x74, 0x22,
            0x3a, 0x22, 0x6d, 0x71, 0x74, 0x74, 0x73, 0x2e, 0x66, 0x75, 0x6e, 0x64, 0x61, 0x6d,
            0x65, 0x6e, 0x74, 0x75, 0x6d, 0x2d, 0x69, 0x6f, 0x74, 0x2d, 0x64, 0x65, 0x76, 0x2e,
            0x63, 0x6f, 0x6d, 0x22, 0x2c, 0x22, 0x70, 0x6f, 0x72, 0x74, 0x22, 0x3a, 0x38, 0x38,
            0x38, 0x33, 0x7d, 0x7d, 0x7d,
        ];
        // same as:
        //                 let buffer_with_invalid_utf8 = r#"HTTP/1.1 200 OK
        // Content-Type: application/json; charset=utf-8
        // Content-Length: 1?0
        // Connection: close

        // {"status":"success","data":{"configuration":null,"mqtt":{"host":"mqtts.fundamentum-iot-dev.com","port":8883}}}"#;

        let result = HttpClient::<'_, V3, TestHttpHandler>::extract_body(&buffer_with_invalid_utf8);

        assert_eq!(HttpClientError::Utf8Conversion(1), result.unwrap_err());
    }
}