multilink 1.0.1

IPC library for communicating with local or remote processes, over stdio or HTTP
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

pub use hyper;

use hyper::{Body, StatusCode, Uri};
pub use hyper::{Request as HttpRequest, Response as HttpResponse};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use thiserror::Error;

use crate::{
    error::{ProtocolErrorType, SerializableProtocolError},
    ProtocolError, ServiceResponse,
};

/// HTTP client components.
#[cfg(any(feature = "http-client"))]
pub mod client;
/// HTTP server components
#[cfg(any(feature = "http-server"))]
pub mod server;
/// HTTP utilities for request/response conversion.
pub mod util;

const API_KEY_HEADER: &str = "X-API-Key";
const SSE_DATA_PREFIX: &str = "data: ";

/// Body for an HTTP error response.
#[derive(Debug, Error, Serialize, Deserialize)]
#[error("{error}")]
pub struct ProtocolHttpError {
    pub error: String,
}

impl Into<StatusCode> for ProtocolErrorType {
    fn into(self) -> StatusCode {
        match self {
            ProtocolErrorType::BadRequest => StatusCode::BAD_REQUEST,
            ProtocolErrorType::Unauthorized => StatusCode::UNAUTHORIZED,
            ProtocolErrorType::Internal => StatusCode::INTERNAL_SERVER_ERROR,
            ProtocolErrorType::NotFound => StatusCode::NOT_FOUND,
            ProtocolErrorType::HttpMethodNotAllowed => StatusCode::METHOD_NOT_ALLOWED,
        }
    }
}

impl From<StatusCode> for ProtocolErrorType {
    fn from(code: StatusCode) -> Self {
        match code {
            StatusCode::BAD_REQUEST => ProtocolErrorType::BadRequest,
            StatusCode::UNAUTHORIZED => ProtocolErrorType::Unauthorized,
            StatusCode::INTERNAL_SERVER_ERROR => ProtocolErrorType::Internal,
            StatusCode::NOT_FOUND => ProtocolErrorType::NotFound,
            StatusCode::METHOD_NOT_ALLOWED => ProtocolErrorType::HttpMethodNotAllowed,
            _ => ProtocolErrorType::Internal,
        }
    }
}

/// A multilink HTTP response.
pub enum ModalHttpResponse {
    /// Contains a single HTTP response returned by the server.
    Single(HttpResponse<Body>),
    /// Contains a single serializable event returned by the server,
    /// as part of a stream.
    Event(Value),
}

/// A request that can convert to and from a [`HttpRequest<Body>`].
#[async_trait::async_trait]
pub trait RequestHttpConvert<Request> {
    /// Deserializes a [`HttpRequest<Body>`] into `Request`. Returns a protocol error
    /// if the request conversion fails (i.e. request validation fails,
    /// unexpected error, etc.). Returns `None` if the request type is unknown or unsupported for remote host scenarios,
    /// which is synonymous with a "not found" error.
    async fn from_http_request(
        request: HttpRequest<Body>,
    ) -> Result<Option<Request>, ProtocolError>;

    /// Serializes a `Request` into a [`HttpRequest<Body>`]. Returns `None` if
    /// the request is unsupported for this protocol, which is synonymous with a
    /// "not found" error.
    fn to_http_request(&self, base_url: &Uri) -> Result<Option<HttpRequest<Body>>, ProtocolError>;
}

/// A response that can convert to and from a [`ModalHttpResponse`].
#[async_trait::async_trait]
pub trait ResponseHttpConvert<Request, Response>
where
    Request: Clone,
    Response: ResponseHttpConvert<Request, Response>,
{
    /// Deserializes a [`ModalHttpResponse`] into `ServiceResponse<Response>`.
    /// Returns a protocol error if the response conversion fails (i.e.
    /// response validation fails, unexpected error, etc.). A reference to the associated
    /// request is provided, in case it's helpful. Returns `None` if the response type is unknown or unsupported
    /// for remote host scenarios, which is synonymous with a "not found" error.
    async fn from_http_response(
        response: ModalHttpResponse,
        original_request: &Request,
    ) -> Result<Option<ServiceResponse<Response>>, ProtocolError>;

    /// Serializes a `Response` into a [`ModalHttpResponse`].
    /// Returns `None` if the response type is unsupported, which is synonymous
    /// with a "not found" error.
    fn to_http_response(
        response: ServiceResponse<Response>,
    ) -> Result<Option<ModalHttpResponse>, ProtocolError>;
}

/// The JSON payload for a server-side event/notification.
#[derive(Debug, Serialize, Deserialize)]
pub struct HttpNotificationPayload {
    pub result: Option<Value>,
    pub error: Option<SerializableProtocolError>,
}

impl From<Result<Option<Value>, ProtocolError>> for HttpNotificationPayload {
    fn from(result: Result<Option<Value>, ProtocolError>) -> Self {
        let result =
            result.and_then(|r| r.ok_or_else(|| generic_error(ProtocolErrorType::NotFound)));
        let (result, error) = match result {
            Ok(result) => (Some(result), None),
            Err(e) => (None, Some(e.into())),
        };
        Self { result, error }
    }
}

impl Into<Result<Value, ProtocolError>> for HttpNotificationPayload {
    fn into(self) -> Result<Value, ProtocolError> {
        if let Some(e) = self.error {
            return Err(e.into());
        }
        self.result
            .ok_or_else(|| generic_error(ProtocolErrorType::NotFound))
    }
}

/// Creates a generic [`ProtocolError`] using the HTTP status code
/// description (i.e. "Bad Request" or "Not Found") as the error text.
pub fn generic_error(error_type: ProtocolErrorType) -> ProtocolError {
    let status: StatusCode = error_type.clone().into();
    let error = Box::new(ProtocolHttpError {
        error: status.to_string(),
    });
    ProtocolError { error_type, error }
}