Skip to main content

cpa_plugin/
interceptors.rs

1//! Request, response, stream-chunk, lifecycle and WebSocket hooks
2//! (internal/pluginhost/adapters_interceptors.go).
3//!
4//! Interceptors run in snapshot order (priority, then ID). Each sees the previous one's
5//! headers and body; a failing interceptor is skipped. `skip` is the plugin that started
6//! a nested host execution (Go's `*Except` variants), which must not intercept itself.
7
8use bytes::Bytes;
9
10use crate::abi::{self, method};
11use crate::api::{
12    RequestCompletion, RequestInterceptRequest, RequestInterceptResponse, ResponseInterceptRequest,
13    ResponseInterceptResponse, STREAM_CHUNK_HEADER_INIT_INDEX, StreamChunkInterceptRequest,
14    StreamChunkInterceptResponse, WebSocketResponseEvent,
15};
16use crate::callbacks::RequestScope;
17use crate::gojson::Header;
18use crate::host::{Host, Record};
19use crate::rpc::Empty;
20
21/// Go `coreexecutor.RequestPathMetadataKey`.
22pub const REQUEST_PATH_METADATA_KEY: &str = "request_path";
23
24/// `http.Header.Del` then `Add` for every update, after deleting `clear`
25/// (Go `mergeHeaders`). Keys are canonicalized the way `http.Header` methods do; keys
26/// already in `current` keep their spelling.
27pub fn merge_headers(current: &Header, updates: &Header, clear: &[String]) -> Header {
28    let mut out = current.clone();
29    for key in clear {
30        out.remove(&cpa_exec::proxy::canonical_header(key));
31    }
32    for (key, values) in updates {
33        let key = cpa_exec::proxy::canonical_header(key);
34        out.remove(&key);
35        if !values.is_empty() {
36            out.entry(key).or_default().extend(values.iter().cloned());
37        }
38    }
39    out
40}
41
42impl Host {
43    /// Records with a hook, except `skip`; each call rechecks [`Host::live`].
44    fn interceptor_records(&self, skip: &str, has: impl Fn(&Record) -> bool) -> Vec<Record> {
45        let skip = skip.trim();
46        self.active_records()
47            .into_iter()
48            .filter(|r| has(r) && r.id != skip)
49            .collect()
50    }
51
52    /// Go `InterceptRequestBeforeAuth[Except]`.
53    pub async fn intercept_request_before_auth(
54        &self,
55        req: RequestInterceptRequest,
56        skip: &str,
57        scope: &RequestScope,
58    ) -> RequestInterceptResponse {
59        self.intercept_request(req, method::REQUEST_INTERCEPT_BEFORE, skip, scope)
60            .await
61    }
62
63    /// Go `InterceptRequestAfterAuth[Except]`.
64    pub async fn intercept_request_after_auth(
65        &self,
66        req: RequestInterceptRequest,
67        skip: &str,
68        scope: &RequestScope,
69    ) -> RequestInterceptResponse {
70        self.intercept_request(req, method::REQUEST_INTERCEPT_AFTER, skip, scope)
71            .await
72    }
73
74    /// Go `interceptRequest`: the result carries the merged headers, the body only when
75    /// an interceptor replaced it, the last path override, and the first termination.
76    async fn intercept_request(
77        &self,
78        req: RequestInterceptRequest,
79        method: &str,
80        skip: &str,
81        scope: &RequestScope,
82    ) -> RequestInterceptResponse {
83        let mut current = RequestInterceptResponse {
84            headers: req.headers.clone(),
85            ..Default::default()
86        };
87        let mut body = req.body.clone();
88        let mut body_modified = false;
89        for record in self.interceptor_records(skip, |r| r.plugin.caps.request_interceptor) {
90            if !self.live(&record) {
91                continue;
92            }
93            let mut next = req.clone();
94            next.headers = current.headers.clone();
95            next.body = body.clone();
96            if !current.path.is_empty() {
97                next.metadata
98                    .insert(REQUEST_PATH_METADATA_KEY.into(), current.path.clone().into());
99            }
100            let resp: RequestInterceptResponse = match self.call_with_callback(&record, method, &next, scope).await {
101                Ok(resp) => resp,
102                Err(e) => {
103                    tracing::warn!("pluginhost: request interceptor {} failed: {e}", record.id);
104                    continue;
105                }
106            };
107            current.headers = merge_headers(&current.headers, &resp.headers, &resp.clear_headers);
108            if !resp.body.is_empty() {
109                body = resp.body.clone();
110                body_modified = true;
111            }
112            if !resp.path.trim().is_empty() {
113                current.path = resp.path.trim().to_owned();
114            }
115            if resp.terminate {
116                current.terminate = true;
117                current.status_code = resp.status_code;
118                current.response_headers = resp.response_headers;
119                current.response_body = resp.response_body;
120                break;
121            }
122        }
123        if body_modified {
124            current.body = body;
125        }
126        current
127    }
128
129    /// Go `CompleteRequest[Except]`: one asynchronous `request.complete` per lifecycle
130    /// plugin; delivery never blocks the response.
131    pub fn complete_request(&self, completion: RequestCompletion, skip: &str, scope: &RequestScope) {
132        for record in self.interceptor_records(skip, |r| r.plugin.caps.request_lifecycle_plugin) {
133            if !self.live(&record) {
134                continue;
135            }
136            let host = self.clone();
137            let completion = completion.clone();
138            let scope = scope.clone();
139            tokio::spawn(async move {
140                let result: Result<Empty, _> = host
141                    .call_with_callback(&record, method::REQUEST_COMPLETE, &completion, &scope)
142                    .await;
143                if let Err(e) = result {
144                    tracing::warn!("pluginhost: request lifecycle plugin {} failed: {e}", record.id);
145                }
146            });
147        }
148    }
149
150    /// Go `InterceptResponse[Except]`: successful non-streaming responses.
151    pub async fn intercept_response(
152        &self,
153        req: ResponseInterceptRequest,
154        skip: &str,
155        scope: &RequestScope,
156    ) -> ResponseInterceptResponse {
157        let mut current = ResponseInterceptResponse {
158            headers: req.response_headers.clone(),
159            body: req.body.clone(),
160            ..Default::default()
161        };
162        for record in self.interceptor_records(skip, |r| r.plugin.caps.response_interceptor) {
163            if !self.live(&record) {
164                continue;
165            }
166            let mut next = req.clone();
167            next.response_headers = current.headers.clone();
168            next.body = current.body.clone();
169            match self
170                .call_with_callback::<ResponseInterceptResponse, _>(
171                    &record,
172                    method::RESPONSE_INTERCEPT_AFTER,
173                    &next,
174                    scope,
175                )
176                .await
177            {
178                Ok(resp) => {
179                    current.headers = merge_headers(&current.headers, &resp.headers, &resp.clear_headers);
180                    if !resp.body.is_empty() {
181                        current.body = resp.body;
182                    }
183                }
184                Err(e) => tracing::warn!("pluginhost: response interceptor {} failed: {e}", record.id),
185            }
186        }
187        current
188    }
189
190    /// Go `InterceptStreamChunk[Except]`. Payload chunks (`ChunkIndex >= 0`) omit request
191    /// bodies for schema 3+ and history for schema 5+; the header-init call always
192    /// carries them. A dropped chunk ends the chain.
193    pub async fn intercept_stream_chunk(
194        &self,
195        req: StreamChunkInterceptRequest,
196        skip: &str,
197        scope: &RequestScope,
198    ) -> StreamChunkInterceptResponse {
199        let mut current = StreamChunkInterceptResponse {
200            headers: req.response_headers.clone(),
201            body: req.body.clone(),
202            ..Default::default()
203        };
204        for record in self.interceptor_records(skip, |r| r.plugin.caps.stream_chunk_interceptor) {
205            if current.drop_chunk {
206                break;
207            }
208            if !self.live(&record) {
209                continue;
210            }
211            let schema = record.plugin.schema_version;
212            let payload = req.chunk_index != STREAM_CHUNK_HEADER_INIT_INDEX;
213            let mut next = req.clone();
214            next.response_headers = current.headers.clone();
215            next.body = current.body.clone();
216            if payload && schema >= abi::SCHEMA_STREAM_CHUNK_OMIT_REQUEST_BODY {
217                next.original_request = Bytes::new();
218                next.request_body = Bytes::new();
219            }
220            if payload && schema >= abi::SCHEMA_STREAM_CHUNK_OMIT_HISTORY {
221                next.history_chunks = Vec::new();
222            }
223            match self
224                .call_with_callback::<StreamChunkInterceptResponse, _>(
225                    &record,
226                    method::RESPONSE_INTERCEPT_STREAM_CHUNK,
227                    &next,
228                    scope,
229                )
230                .await
231            {
232                Ok(resp) => {
233                    current.headers = merge_headers(&current.headers, &resp.headers, &resp.clear_headers);
234                    if !resp.body.is_empty() {
235                        current.body = resp.body;
236                    }
237                    current.drop_chunk |= resp.drop_chunk;
238                }
239                Err(e) => tracing::warn!("pluginhost: stream chunk interceptor {} failed: {e}", record.id),
240            }
241        }
242        current
243    }
244
245    /// Go `ObserveWebSocketResponseEvent[Except]`: synchronous, in order, errors logged.
246    pub async fn observe_websocket_response_event(
247        &self,
248        event: WebSocketResponseEvent,
249        skip: &str,
250        scope: &RequestScope,
251    ) {
252        for record in self.interceptor_records(skip, |r| r.plugin.caps.websocket_response_observer) {
253            if !self.live(&record) {
254                continue;
255            }
256            let result: Result<Empty, _> = self
257                .call_with_callback(&record, method::WEBSOCKET_RESPONSE_EVENT, &event, scope)
258                .await;
259            if let Err(e) = result {
260                tracing::warn!("pluginhost: websocket response observer {} failed: {e}", record.id);
261            }
262        }
263    }
264
265    fn any_active(&self, has: impl Fn(&Record) -> bool) -> bool {
266        self.active_records().iter().any(|r| has(r) && !self.is_fused(&r.id))
267    }
268
269    /// Go `HasRequestInterceptors`.
270    pub fn has_request_interceptors(&self) -> bool {
271        self.any_active(|r| r.plugin.caps.request_interceptor)
272    }
273
274    /// Go `HasStreamInterceptors`.
275    pub fn has_stream_interceptors(&self) -> bool {
276        self.any_active(|r| r.plugin.caps.stream_chunk_interceptor)
277    }
278
279    /// Go `HasWebSocketResponseObservers`.
280    pub fn has_websocket_response_observers(&self) -> bool {
281        self.any_active(|r| r.plugin.caps.websocket_response_observer)
282    }
283
284    /// Go `HasResponseInterceptors` equivalent for the handler's fast path.
285    pub fn has_response_interceptors(&self) -> bool {
286        self.any_active(|r| r.plugin.caps.response_interceptor)
287    }
288
289    /// Go `HasRequestLifecyclePlugins` equivalent.
290    pub fn has_request_lifecycle_plugins(&self) -> bool {
291        self.any_active(|r| r.plugin.caps.request_lifecycle_plugin)
292    }
293
294    /// Go `StreamChunkPayloadIncludesRequestBody`: some stream interceptor speaks schema < 3.
295    pub fn stream_chunk_payload_includes_request_body(&self) -> bool {
296        self.any_active(|r| {
297            r.plugin.caps.stream_chunk_interceptor
298                && r.plugin.schema_version < abi::SCHEMA_STREAM_CHUNK_OMIT_REQUEST_BODY
299        })
300    }
301
302    /// Go `StreamChunkPayloadIncludesHistory`: some stream interceptor speaks schema < 5.
303    pub fn stream_chunk_payload_includes_history(&self) -> bool {
304        self.any_active(|r| {
305            r.plugin.caps.stream_chunk_interceptor && r.plugin.schema_version < abi::SCHEMA_STREAM_CHUNK_OMIT_HISTORY
306        })
307    }
308}
309
310#[cfg(test)]
311mod tests {
312    use super::*;
313
314    /// Go `mergeHeaders`: clears first, replaces per canonical key, keeps the rest.
315    #[test]
316    fn merge_headers_follows_http_header() {
317        let current: Header = [
318            ("X-Keep".to_owned(), vec!["1".to_owned()]),
319            ("X-Clear".to_owned(), vec!["2".to_owned()]),
320            ("X-Replace".to_owned(), vec!["3".to_owned()]),
321        ]
322        .into();
323        let updates: Header = [
324            ("x-replace".to_owned(), vec!["a".to_owned(), "b".to_owned()]),
325            ("x-new".to_owned(), vec!["n".to_owned()]),
326        ]
327        .into();
328        let merged = merge_headers(&current, &updates, &["x-clear".to_owned()]);
329        let got: Vec<_> = merged.iter().map(|(k, v)| format!("{k}={}", v.join(","))).collect();
330        assert_eq!(got, ["X-Keep=1", "X-New=n", "X-Replace=a,b"]);
331    }
332}