Skip to main content

graphrt_plugin/
http.rs

1//! HTTP plugins: each request is a JSON-RPC `POST`. Responses are either a
2//! single `application/json` message or an `application/x-ndjson` stream of
3//! notifications followed by the final response.
4
5use std::fmt;
6use std::sync::Arc;
7use std::sync::atomic::{AtomicU64, Ordering};
8
9use futures::StreamExt;
10use futures::future::BoxFuture;
11use graphrt_core::node::Clock;
12
13use crate::conn::NotifySink;
14use crate::error::CallError;
15use crate::manifest::{HttpRuntime, LoadedManifest};
16use crate::protocol::{self, Incoming};
17use crate::transport::{INITIALIZE_TIMEOUT, Transport, check_initialize, initialize_params, with_timeout};
18
19/// A plugin served over HTTP.
20pub struct HttpTransport {
21    name: String,
22    runtime: HttpRuntime,
23    client: reqwest::Client,
24    max_message_bytes: usize,
25    next_id: AtomicU64,
26    initialized: tokio::sync::OnceCell<serde_json::Value>,
27}
28
29impl fmt::Debug for HttpTransport {
30    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
31        f.debug_struct("HttpTransport")
32            .field("plugin", &self.name)
33            .field("url", &self.runtime.url)
34            .finish_non_exhaustive()
35    }
36}
37
38impl HttpTransport {
39    pub fn new(plugin: &LoadedManifest, runtime: HttpRuntime) -> Result<Self, CallError> {
40        let _already_installed = rustls::crypto::ring::default_provider().install_default();
41        let client = reqwest::Client::builder()
42            .connect_timeout(std::time::Duration::from_secs(10))
43            .redirect(reqwest::redirect::Policy::none())
44            .build()
45            .map_err(|e| CallError::Transport(format!("cannot build HTTP client: {}", e.without_url())))?;
46        Ok(Self {
47            name: plugin.manifest.name.clone(),
48            runtime,
49            client,
50            max_message_bytes: plugin.manifest.limits.max_message_bytes,
51            next_id: AtomicU64::new(1),
52            initialized: tokio::sync::OnceCell::new(),
53        })
54    }
55
56    async fn post(
57        &self,
58        id: &str,
59        method: &str,
60        params: &serde_json::Value,
61        sink: Option<&NotifySink>,
62    ) -> Result<serde_json::Value, CallError> {
63        let mut req = self
64            .client
65            .post(&self.runtime.url)
66            .header("content-type", "application/json")
67            .header("accept", "application/x-ndjson, application/json")
68            .body(protocol::request(id, method, params));
69        for (k, v) in &self.runtime.headers {
70            req = req.header(k.as_str(), v.as_str());
71        }
72        if let Some(var) = &self.runtime.bearer_token_env {
73            match std::env::var(var) {
74                Ok(token) if !token.is_empty() => req = req.bearer_auth(token),
75                _ => return Err(CallError::Start(format!("environment variable `{var}` (bearer token) is not set"))),
76            }
77        }
78        let resp = req.send().await.map_err(|e| CallError::Transport(e.without_url().to_string()))?;
79        let status = resp.status();
80        if !status.is_success() {
81            return Err(error_from_status(status.as_u16(), resp).await);
82        }
83        let mut stream = resp.bytes_stream();
84        let mut buf: Vec<u8> = Vec::new();
85        let mut final_result: Option<Result<serde_json::Value, CallError>> = None;
86        loop {
87            // Process complete lines already buffered.
88            while let Some(pos) = buf.iter().position(|b| *b == b'\n') {
89                let line: Vec<u8> = buf.drain(..=pos).collect();
90                if let Some(r) = self.handle_line(&line, id, sink)? {
91                    final_result = Some(r);
92                }
93            }
94            if final_result.is_some() {
95                break;
96            }
97            match stream.next().await {
98                Some(Ok(bytes)) => {
99                    buf.extend_from_slice(&bytes);
100                    if buf.len() > self.max_message_bytes {
101                        return Err(CallError::Protocol(format!(
102                            "plugin message exceeds the {}-byte limit",
103                            self.max_message_bytes
104                        )));
105                    }
106                }
107                Some(Err(e)) => return Err(CallError::Transport(e.without_url().to_string())),
108                None => {
109                    // A single JSON body without a trailing newline.
110                    let rest = std::mem::take(&mut buf);
111                    if let Some(r) = self.handle_line(&rest, id, sink)? {
112                        final_result = Some(r);
113                    }
114                    break;
115                }
116            }
117        }
118        final_result.unwrap_or_else(|| Err(CallError::Protocol("response ended without a JSON-RPC result".into())))
119    }
120
121    fn handle_line(
122        &self,
123        line: &[u8],
124        id: &str,
125        sink: Option<&NotifySink>,
126    ) -> Result<Option<Result<serde_json::Value, CallError>>, CallError> {
127        let text = std::str::from_utf8(line).map_err(|_| CallError::Protocol("invalid UTF-8 in response".into()))?;
128        let text = text.trim();
129        if text.is_empty() {
130            return Ok(None);
131        }
132        match protocol::parse(text)? {
133            Incoming::Response { id: rid, result } if rid == id => Ok(Some(result)),
134            Incoming::Response { .. } => Err(CallError::Protocol("response id does not match the request".into())),
135            Incoming::Notification(n) => {
136                if n.method == "log" {
137                    let level = n.params.get("level").and_then(|v| v.as_str()).unwrap_or("info");
138                    let message = n.params.get("message").and_then(|v| v.as_str()).unwrap_or_default();
139                    crate::conn::forward_log(&self.name, level, message);
140                }
141                if n.request_id() == Some(id) {
142                    if let Some(sink) = sink {
143                        sink(n);
144                    }
145                }
146                Ok(None)
147            }
148            Incoming::Request { method, .. } => {
149                Err(CallError::Protocol(format!("plugin sent a `{method}` request over HTTP, which is not supported")))
150            }
151        }
152    }
153
154    async fn ensure_initialized(&self, clock: &Arc<dyn Clock>) -> Result<serde_json::Value, CallError> {
155        let result = self
156            .initialized
157            .get_or_try_init(|| async {
158                let id = self.next_id();
159                let params = initialize_params(self.max_message_bytes);
160                let result =
161                    with_timeout(clock, INITIALIZE_TIMEOUT, self.post(&id, "initialize", &params, None)).await?;
162                check_initialize(&result)?;
163                Ok::<_, CallError>(result)
164            })
165            .await?;
166        Ok(result.clone())
167    }
168}
169
170/// Largest error body read to explain a failed request.
171const ERROR_BODY_BYTES: usize = 4 * 1024;
172
173/// Turn a non-2xx response into a call error, keeping a JSON-RPC error the
174/// plugin sent (its `kind` / `retryable`) or a snippet of the body.
175async fn error_from_status(status: u16, mut resp: reqwest::Response) -> CallError {
176    let mut body = Vec::new();
177    while body.len() < ERROR_BODY_BYTES {
178        match resp.chunk().await {
179            Ok(Some(chunk)) => body.extend_from_slice(&chunk),
180            _ => break,
181        }
182    }
183    body.truncate(ERROR_BODY_BYTES);
184    let text = String::from_utf8_lossy(&body).trim().to_owned();
185    if let Ok(Incoming::Response { result: Err(err @ CallError::Remote { .. }), .. }) = protocol::parse(&text) {
186        return err;
187    }
188    let snippet = if text.is_empty() { String::new() } else { format!(": {text}") };
189    let message = format!("plugin endpoint answered HTTP {status}{snippet}");
190    // Client errors (other than timeouts and rate limits) will not succeed on retry.
191    let retryable = !(400..500).contains(&status) || status == 408 || status == 429;
192    if retryable {
193        CallError::Transport(message)
194    } else {
195        CallError::Remote {
196            code: -32000,
197            message,
198            data: Some(serde_json::json!({"kind": "plugin_http_status", "retryable": false})),
199        }
200    }
201}
202
203impl Transport for HttpTransport {
204    fn next_id(&self) -> String {
205        format!("r-{}", self.next_id.fetch_add(1, Ordering::Relaxed))
206    }
207
208    fn call<'a>(
209        &'a self,
210        id: String,
211        method: &'a str,
212        params: serde_json::Value,
213        sink: Option<NotifySink>,
214        _cancel_on_drop: bool,
215        clock: &'a Arc<dyn Clock>,
216    ) -> BoxFuture<'a, Result<serde_json::Value, CallError>> {
217        // Cancellation over HTTP is dropping the request (the connection closes).
218        Box::pin(async move {
219            self.ensure_initialized(clock).await?;
220            self.post(&id, method, &params, sink.as_ref()).await
221        })
222    }
223
224    fn initialize<'a>(&'a self, clock: &'a Arc<dyn Clock>) -> BoxFuture<'a, Result<serde_json::Value, CallError>> {
225        Box::pin(self.ensure_initialized(clock))
226    }
227}