Skip to main content

hyper_cors/
cors.rs

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