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 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199
//! Extension for `hyper` to follow HTTP redirects. //! //! # Behaviour and Limitations //! //! ## Supported Redirects //! //! This crate supports all 5 redirect styles that are defined by the HTTP/1.1 spec. //! These include both "permanent" redirects (status codes `301` and `308`) as well as //! "temporary" redirects (status codes `302`, `303` and `307`). //! //! Encountering a `303 See Other` response from the server will cause the client to change //! the request method to `GET`, and discard the request body before following the redirect. //! //! ## Location Header //! //! The client uses the `Location` HTTP header to determine the next url to follow the redirect to. //! Both relative (without a hostname) as well as absolute URLs (including schema and hostname) urls //! are supported. //! //! When the `Location` header is missing in a response from the server, but the status code indicates //! a redirect, the client will return the response to the caller. You can detect this situation by //! checking the status code and headers of the returned response. //! //! ## Buffering //! //! In order to be able to replay the request body when following redirects other than `303 See Other`, //! the client will buffer the request body in-memory before making the first request to the //! server. //! //! ## Redirect Limit //! //! To avoid following an endless chain of redirects, the client has a limit for the maximum number //! of redirects it will follow until giving up. //! //! When the maximum number of redirects is reached, the client will simply return the last response //! to the caller. You can detect this situation by checking the status code of the returned response. //! //! ## Security Considerations //! //! In order to protect the confidentiality of authentication or session information passed along in //! a request, the client will strip authentication and cookie headers when following a redirect to //! a different host and port. //! //! Redirects to the same host and port, but different paths will retain session information. //! //! # Example //! //! ```rust //! extern crate hyper; //! extern crate follow_redirects; //! # extern crate tokio_core; //! //! // 1. import the extension trait //! use follow_redirects::ClientExt; //! //! # fn main() { //! # let core = tokio_core::reactor::Core::new().unwrap(); //! # let handle = core.handle(); //! // ... //! // 2. create a standard hyper client //! let client = hyper::Client::new(&handle); //! //! // ... //! // 3. make a request that will follow redirects //! let url = "http://docs.rs/hyper".parse().unwrap(); //! let future = client.follow_redirects().get(url); //! # drop(future); //! # } //! ``` #![deny(missing_docs)] #![deny(warnings)] #![deny(missing_debug_implementations)] extern crate bytes; #[macro_use] extern crate futures; extern crate http; extern crate hyper; use std::fmt; use bytes::Bytes; use futures::{Future, Poll, Stream}; use hyper::{Error, Method, Request, Response, Uri}; use hyper::client::{Connect, Service}; mod uri; mod buffer; mod machine; mod future; use future::FutureInner; /// Extension trait for adding follow-redirect features to `hyper::Client`. pub trait ClientExt<C, B> { /// Wrap the `hyper::Client` in a new client that follows redirects. fn follow_redirects(&self) -> Client<C, B>; /// Wrap the `hyper::Client` in a new client that follows redirects, /// and set the maximum number of redirects to follow. fn follow_redirects_max(&self, max_redirects: usize) -> Client<C, B> { let mut client = self.follow_redirects(); client.set_max_redirects(max_redirects); client } } impl<C, B> ClientExt<C, B> for hyper::Client<C, B> { fn follow_redirects(&self) -> Client<C, B> { Client { inner: self.clone(), max_redirects: 10 } } } /// A client to make outgoing HTTP requests, and which follows redirects. /// /// By default, the client will follow up to 10 redirects. This limit can be configured /// via the `set_max_redirects` method. pub struct Client<C, B> { inner: hyper::Client<C, B>, max_redirects: usize } impl<C, B> Clone for Client<C, B> { fn clone(&self) -> Client<C, B> { Client { inner: self.inner.clone(), max_redirects: self.max_redirects } } } impl<C, B> fmt::Debug for Client<C, B> { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { f.debug_struct("Client") .field("max_redirects", &self.max_redirects) .finish() } } impl<C, B> Client<C, B> where C: Connect, B: Stream<Error = Error> + From<Bytes> + 'static, B::Item: AsRef<[u8]> { /// Send a GET Request using this client. pub fn get(&self, url: Uri) -> FutureResponse { self.request(Request::new(Method::Get, url)) } /// Send a constructed Request using this client. pub fn request(&self, req: Request<B>) -> FutureResponse { FutureResponse(Box::new(FutureInner::new(self.inner.clone(), req, self.max_redirects))) } } impl<C, B> Client<C, B> { /// Set the maximum number of redirects the client will follow before giving up. /// /// By default, this limit is set to 10. pub fn set_max_redirects(&mut self, max_redirects: usize) { self.max_redirects = max_redirects; } } impl<C, B> Service for Client<C, B> where C: Connect, B: Stream<Error = Error> + From<Bytes> + 'static, B::Item: AsRef<[u8]> { type Request = Request<B>; type Response = Response; type Error = Error; type Future = FutureResponse; fn call(&self, req: Request<B>) -> FutureResponse { self.request(req) } } /// A `Future` that will resolve to an HTTP Response. pub struct FutureResponse(Box<Future<Item=Response, Error=Error>>); impl fmt::Debug for FutureResponse { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { f.pad("Future<Response>") } } impl Future for FutureResponse { type Item = Response; type Error = Error; fn poll(&mut self) -> Poll<Response, Error> { self.0.poll() } }