Skip to main content

hyper_cors/
cors.rs

1//! The [`Cors`] middleware.
2
3use std::{
4    future::Future,
5    pin::Pin,
6    task::{ready, Context, Poll},
7};
8
9use bytes::Bytes;
10use http::{header, request::Parts, HeaderMap, HeaderValue, Method, Request, Response};
11use hyper::body::Body;
12use hyper::service::Service;
13use pin_project_lite::pin_project;
14
15use crate::{allow_origin::AllowOriginFuture, config::CorsBuilder, header_buf::HeaderBuf};
16
17/// CORS middleware.
18///
19/// Construct via [`builder`].
20#[derive(Debug, Clone)]
21#[must_use]
22pub struct Cors<S> {
23    inner: S,
24    config: CorsBuilder,
25}
26
27impl<S> Cors<S> {
28    /// Returns a reference to the inner service.
29    pub fn inner(&self) -> &S {
30        &self.inner
31    }
32
33    /// Returns a mutable reference to the inner service.
34    pub fn inner_mut(&mut self) -> &mut S {
35        &mut self.inner
36    }
37
38    /// Returns the configured builder.
39    pub fn config(&self) -> &CorsBuilder {
40        &self.config
41    }
42
43    pub(crate) fn from_parts(inner: S, config: CorsBuilder) -> Self {
44        Self { inner, config }
45    }
46}
47
48/// Returns a new [`CorsBuilder`] with default settings.
49pub fn builder() -> CorsBuilder {
50    CorsBuilder::new()
51}
52
53impl<S, ReqB, ResB> Service<Request<ReqB>> for Cors<S>
54where
55    S: Service<Request<ReqB>, Response = Response<ResB>> + Clone,
56    ResB: Body<Data = Bytes> + Default + Send + 'static,
57{
58    type Response = Response<ResB>;
59    type Error = S::Error;
60    type Future = CorsFuture<S, ReqB, S::Future, ResB>;
61
62    fn call(&self, req: Request<ReqB>) -> Self::Future {
63        let (parts, body) = req.into_parts();
64        let origin = parts.headers.get(&header::ORIGIN).cloned();
65        let is_preflight = is_preflight_request(&parts);
66        let is_websocket_upgrade = is_websocket_upgrade_request(&parts);
67
68        let allow_origin_future = self.config.allow_origin.to_future(origin.as_ref(), &parts);
69        let has_origin = allow_origin_future.has_origin();
70
71        // `Vary` applies to every CORS-shaped response regardless of origin match, so caches
72        // don't conflate responses for different origins.
73        let mut common_headers = HeaderBuf::default();
74        common_headers.push_opt(self.config.vary.to_header());
75
76        let lazy_factory = LazyHeaders {
77            allow_credentials: self.config.allow_credentials.clone(),
78            allow_methods: self.config.allow_methods.clone(),
79            allow_headers: self.config.allow_headers.clone(),
80            expose_headers: self.config.expose_headers.clone(),
81            max_age: self.config.max_age.clone(),
82        };
83
84        if is_preflight && !self.config.deliver_preflight {
85            CorsFuture::Preflight {
86                allow_origin_future,
87                headers: common_headers,
88                lazy: lazy_factory,
89                parts,
90                has_origin,
91                origin,
92                deliver_non_allowed_origin: self.config.deliver_non_allowed_origin,
93                rejection_status: self.config.rejection_status,
94                _body: std::marker::PhantomData,
95            }
96        } else {
97            // The inner service is not invoked here. Calling it before the origin decision
98            // is known would defeat `deliver_non_allowed_origin(false)`: a rejected origin
99            // would still run the handler. We hold the service and unconsumed request and
100            // dispatch from `poll` once the verdict is in. For synchronous origin variants
101            // this costs nothing; only the async-predicate path gives up overlap with the
102            // inner call.
103            CorsFuture::Forward {
104                allow_origin_future,
105                allow_origin_complete: false,
106                service: Some(self.inner.clone()),
107                body: Some(body),
108                inner: None,
109                headers: common_headers,
110                lazy: Some(lazy_factory),
111                parts: Some(parts),
112                is_preflight,
113                has_origin,
114                origin,
115                deliver_non_allowed_origin: self.config.deliver_non_allowed_origin,
116                rejection_status: self.config.rejection_status,
117                reject_websocket_upgrade: is_websocket_upgrade
118                    && !self.config.deliver_non_allowed_origin_websocket_upgrade,
119                _body: std::marker::PhantomData,
120            }
121        }
122    }
123}
124
125/// CORS configuration knobs whose headers depend on the `allow_origin` decision.
126#[derive(Clone)]
127struct LazyHeaders {
128    allow_credentials: crate::AllowCredentials,
129    allow_methods: crate::AllowMethods,
130    allow_headers: crate::AllowHeaders,
131    expose_headers: crate::ExposeHeaders,
132    max_age: crate::MaxAge,
133}
134
135impl LazyHeaders {
136    /// Appends the CORS headers appropriate for an allowed-origin request into `out`.
137    fn compute_into(
138        &self,
139        out: &mut HeaderBuf,
140        parts: &Parts,
141        origin: Option<&HeaderValue>,
142        is_preflight: bool,
143    ) {
144        out.push_opt(self.allow_credentials.to_header(origin, parts));
145        if is_preflight {
146            out.push_opt(self.allow_methods.to_header(parts));
147            out.push_opt(self.allow_headers.to_header(parts));
148            out.push_opt(self.max_age.to_header(origin, parts));
149        } else {
150            out.push_opt(self.expose_headers.to_header(parts));
151        }
152    }
153}
154
155pin_project! {
156    /// Future returned by [`Cors::call`].
157    #[project = CorsFutureProj]
158    pub enum CorsFuture<S, ReqB, F, B> {
159        Forward {
160            #[pin]
161            allow_origin_future: AllowOriginFuture,
162            allow_origin_complete: bool,
163            service: Option<S>,
164            // Body is held apart from `parts` so `parts` can be borrowed for header
165            // computation and then recombined via `Request::from_parts` without cloning
166            // the request head.
167            body: Option<ReqB>,
168            #[pin]
169            inner: Option<F>,
170            headers: HeaderBuf,
171            lazy: Option<LazyHeaders>,
172            parts: Option<Parts>,
173            is_preflight: bool,
174            has_origin: bool,
175            origin: Option<HeaderValue>,
176            deliver_non_allowed_origin: bool,
177            rejection_status: http::StatusCode,
178            reject_websocket_upgrade: bool,
179            _body: std::marker::PhantomData<fn() -> B>,
180        },
181        Preflight {
182            #[pin]
183            allow_origin_future: AllowOriginFuture,
184            headers: HeaderBuf,
185            lazy: LazyHeaders,
186            parts: Parts,
187            has_origin: bool,
188            origin: Option<HeaderValue>,
189            deliver_non_allowed_origin: bool,
190            rejection_status: http::StatusCode,
191            _body: std::marker::PhantomData<fn() -> B>,
192        },
193    }
194}
195
196impl<S, ReqB, F, B, E> Future for CorsFuture<S, ReqB, F, B>
197where
198    S: Service<Request<ReqB>, Response = Response<B>, Future = F>,
199    F: Future<Output = Result<Response<B>, E>>,
200    B: Body<Data = Bytes> + Default + Send + 'static,
201{
202    type Output = Result<Response<B>, E>;
203
204    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
205        match self.project() {
206            CorsFutureProj::Forward {
207                allow_origin_future,
208                allow_origin_complete,
209                service,
210                body,
211                mut inner,
212                headers,
213                lazy,
214                parts,
215                is_preflight,
216                has_origin,
217                origin,
218                deliver_non_allowed_origin,
219                rejection_status,
220                reject_websocket_upgrade,
221                _body: _,
222            } => {
223                if !*allow_origin_complete {
224                    let origin_allowed = match ready!(allow_origin_future.poll(cx)) {
225                        Some((name, value)) => {
226                            headers.push((name, value));
227                            true
228                        }
229                        None => false,
230                    };
231                    *allow_origin_complete = true;
232
233                    // Reject when the request has an `Origin` and either
234                    // `deliver_non_allowed_origin` is off, or this is a WebSocket upgrade and
235                    // WebSocket upgrades are not exempted. The WebSocket case applies even
236                    // when ordinary requests are being delivered, because browsers don't
237                    // enforce CORS on WebSocket handshakes.
238                    if !origin_allowed
239                        && *has_origin
240                        && (!*deliver_non_allowed_origin || *reject_websocket_upgrade)
241                    {
242                        // Drop the pending request and service handle: no application code
243                        // runs for a disallowed origin.
244                        service.take();
245                        body.take();
246                        parts.take();
247                        let mut response = Response::new(B::default());
248                        *response.status_mut() = *rejection_status;
249                        // Only `Vary` (already in `headers`) survives.
250                        merge_headers(response.headers_mut(), headers);
251                        return Poll::Ready(Ok(response));
252                    }
253
254                    // Allowed origin (or non-CORS request). Compute the lazy CORS headers.
255                    if origin_allowed {
256                        if let (Some(lazy), Some(parts)) = (lazy.take(), parts.as_ref()) {
257                            lazy.compute_into(headers, parts, origin.as_ref(), *is_preflight);
258                        }
259                    }
260
261                    if let (Some(svc), Some(parts), Some(body)) =
262                        (service.take(), parts.take(), body.take())
263                    {
264                        inner.set(Some(svc.call(Request::from_parts(parts, body))));
265                    }
266                }
267                let inner_pinned = inner
268                    .as_mut()
269                    .as_pin_mut()
270                    .expect("polled after completion");
271                let mut response = ready!(inner_pinned.poll(cx))?;
272                merge_headers(response.headers_mut(), headers);
273                Poll::Ready(Ok(response))
274            }
275            CorsFutureProj::Preflight {
276                allow_origin_future,
277                headers,
278                lazy,
279                parts,
280                has_origin,
281                origin,
282                deliver_non_allowed_origin,
283                rejection_status,
284                _body: _,
285            } => {
286                let origin_allowed = match ready!(allow_origin_future.poll(cx)) {
287                    Some((name, value)) => {
288                        headers.push((name, value));
289                        true
290                    }
291                    None => false,
292                };
293                if !origin_allowed && *has_origin {
294                    let mut response = Response::new(B::default());
295                    if !*deliver_non_allowed_origin {
296                        *response.status_mut() = *rejection_status;
297                    }
298                    merge_headers(response.headers_mut(), headers);
299                    return Poll::Ready(Ok(response));
300                }
301                lazy.compute_into(headers, parts, origin.as_ref(), true);
302                let mut response = Response::new(B::default());
303                merge_headers(response.headers_mut(), headers);
304                Poll::Ready(Ok(response))
305            }
306        }
307    }
308}
309
310/// Returns `true` if `parts` is a CORS preflight request (`OPTIONS` carrying
311/// `Access-Control-Request-Method`), per [Fetch Sec. 3.1.3][fetch].
312///
313/// [fetch]: https://fetch.spec.whatwg.org/#cors-preflight-request
314fn is_preflight_request(parts: &Parts) -> bool {
315    parts.method == Method::OPTIONS
316        && parts
317            .headers
318            .contains_key(header::ACCESS_CONTROL_REQUEST_METHOD)
319}
320
321/// Returns `true` if `parts` is a WebSocket handshake request (carries
322/// `Sec-WebSocket-Version`).
323///
324/// Browsers do not apply CORS to WebSocket handshakes, so these are handled separately; see
325/// [`CorsBuilder::deliver_non_allowed_origin_websocket_upgrade`].
326///
327/// [`CorsBuilder::deliver_non_allowed_origin_websocket_upgrade`]: crate::CorsBuilder::deliver_non_allowed_origin_websocket_upgrade
328fn is_websocket_upgrade_request(parts: &Parts) -> bool {
329    parts.headers.contains_key("sec-websocket-version")
330}
331
332/// Merge `(name, value)` pairs into `target`, *appending* any `Vary` value (so an inner
333/// service's `Vary` is not clobbered) and overwriting the rest.
334///
335/// `Vary` tokens already present on the response are skipped so an inner service that itself
336/// emits e.g. `Vary: Origin` does not end up with a redundant duplicate.
337fn merge_headers(target: &mut HeaderMap, headers: &HeaderBuf) {
338    for (name, value) in headers.iter() {
339        if name == header::VARY {
340            if let Some(value) = dedup_vary(target, value) {
341                target.append(name.clone(), value);
342            }
343        } else {
344            target.insert(name.clone(), value.clone());
345        }
346    }
347}
348
349/// Inline capacity for [`dedup_vary`]'s output buffer. Sized to comfortably hold the default
350/// CORS `Vary` (~62 bytes) plus one or two inner-service tokens.
351const DEDUP_VARY_STACK: usize = 128;
352
353/// Returns `value` with tokens already present in `target`'s `Vary` removed, or `None` when
354/// every token is already covered.
355fn dedup_vary(target: &HeaderMap, value: &HeaderValue) -> Option<HeaderValue> {
356    fn already_listed(target: &HeaderMap, tok: &[u8]) -> bool {
357        target
358            .get_all(header::VARY)
359            .iter()
360            .flat_map(|v| v.as_bytes().split(|&b| b == b','))
361            .any(|e| e.trim_ascii().eq_ignore_ascii_case(tok))
362    }
363
364    // Fast path: nothing to deduplicate against.
365    if target.get(header::VARY).is_none() {
366        return Some(value.clone());
367    }
368
369    let mut stack = [0u8; DEDUP_VARY_STACK];
370    let mut len = 0usize;
371    // Set when the output outgrows the stack buffer; subsequent writes go to `heap` instead.
372    let mut heap: Option<Vec<u8>> = None;
373
374    for tok in value.as_bytes().split(|&b| b == b',') {
375        let tok = tok.trim_ascii();
376        if tok.is_empty() || already_listed(target, tok) {
377            continue;
378        }
379        let needs_sep = match &heap {
380            Some(v) => !v.is_empty(),
381            None => len > 0,
382        };
383        let sep_len = if needs_sep { 2 } else { 0 };
384        let total = sep_len + tok.len();
385
386        if heap.is_none() {
387            // Fast path: still in stack buffer.
388            if len + total <= DEDUP_VARY_STACK {
389                if needs_sep {
390                    stack[len..len + 2].copy_from_slice(b", ");
391                }
392                stack[len + sep_len..len + total].copy_from_slice(tok);
393                len += total;
394                continue;
395            }
396            // Spill to heap, copying what we already have.
397            let mut v = Vec::with_capacity(len + total);
398            v.extend_from_slice(&stack[..len]);
399            heap = Some(v);
400        }
401
402        let v = heap.as_mut().expect("set on spill");
403        if needs_sep {
404            v.extend_from_slice(b", ");
405        }
406        v.extend_from_slice(tok);
407    }
408
409    let bytes: &[u8] = match &heap {
410        Some(v) => v.as_slice(),
411        None => &stack[..len],
412    };
413    if bytes.is_empty() {
414        return None;
415    }
416    HeaderValue::from_bytes(bytes).ok()
417}
418
419#[cfg(test)]
420mod tests {
421    use super::*;
422    use bytes::Bytes;
423    use http::Request;
424    use http_body_util::{Empty, Full};
425    use hyper::service::Service;
426    use std::future::{ready, Ready};
427
428    #[derive(Clone)]
429    struct Marker;
430    impl Service<Request<Empty<Bytes>>> for Marker {
431        type Response = Response<Full<Bytes>>;
432        type Error = std::convert::Infallible;
433        type Future = Ready<Result<Self::Response, Self::Error>>;
434        fn call(&self, _req: Request<Empty<Bytes>>) -> Self::Future {
435            ready(Ok(Response::new(Full::new(Bytes::new()))))
436        }
437    }
438
439    #[test]
440    fn inner_accessor_returns_shared_reference() {
441        let svc: Cors<Marker> = crate::builder().allow_origin(crate::Any).build(Marker);
442        // `inner` returns a shared reference; calling it must not consume the middleware.
443        let _r: &Marker = svc.inner();
444    }
445
446    #[test]
447    fn config_accessor_returns_builder_reference() {
448        let svc: Cors<Marker> = crate::builder().allow_origin(crate::Any).build(Marker);
449        // `config` exposes the builder for inspection. The fields are `pub(crate)`, so
450        // we just confirm we get a valid reference back.
451        let _cfg: &CorsBuilder = svc.config();
452    }
453
454    #[test]
455    fn inner_mut_returns_exclusive_mutable_reference() {
456        let mut svc: Cors<Marker> = crate::builder().allow_origin(crate::Any).build(Marker);
457        // The returned reference is exclusive (`&mut`); `mem::replace` proves it.
458        let r: &mut Marker = svc.inner_mut();
459        let prev = std::mem::replace(r, Marker);
460        // Avoid an unused-variable lint while confirming the swap happened.
461        let _ = prev;
462    }
463}