diff --git a/src/cors.rs b/src/cors.rs index 57e1a10..f9f8170 100644 --- a/src/cors.rs +++ b/src/cors.rs @@ -91,36 +91,36 @@ configurations for different scopes, you need to register the middleware inside ```rust,no_run # use gotham::{router::builder::*, pipeline::*, pipeline::set::*, state::State}; # use gotham_restful::*; -fn main() { - let pipelines = new_pipeline_set(); - - let cors_a = CorsConfig { - origin: Origin::Star, - ..Default::default() - }; - let (pipelines, chain_a) = pipelines.add( - new_pipeline().add(cors_a).build() - ); - - let cors_b = CorsConfig { - origin: Origin::Copy, - ..Default::default() - }; - let (pipelines, chain_b) = pipelines.add( - new_pipeline().add(cors_b).build() - ); - - let pipeline_set = finalize_pipeline_set(pipelines); - gotham::start("127.0.0.1:8080", build_router((), pipeline_set, |route| { - // routing without any cors config - route.with_pipeline_chain((chain_a, ()), |route| { - // routing with cors config a - }); - route.with_pipeline_chain((chain_b, ()), |route| { - // routing with cors config b - }); - })); -} +let pipelines = new_pipeline_set(); + +// The first cors configuration +let cors_a = CorsConfig { + origin: Origin::Star, + ..Default::default() +}; +let (pipelines, chain_a) = pipelines.add( + new_pipeline().add(cors_a).build() +); + +// The second cors configuration +let cors_b = CorsConfig { + origin: Origin::Copy, + ..Default::default() +}; +let (pipelines, chain_b) = pipelines.add( + new_pipeline().add(cors_b).build() +); + +let pipeline_set = finalize_pipeline_set(pipelines); +gotham::start("127.0.0.1:8080", build_router((), pipeline_set, |route| { + // routing without any cors config + route.with_pipeline_chain((chain_a, ()), |route| { + // routing with cors config a + }); + route.with_pipeline_chain((chain_b, ()), |route| { + // routing with cors config b + }); +})); ``` [`State`]: ../gotham/state/struct.State.html @@ -186,12 +186,31 @@ pub fn handle_cors(state : &State, res : &mut Response) } } -/// Add CORS routing for your path. +/// Add CORS routing for your path. This is required for handling preflight requests. +/// +/// Example: +/// +/// ```rust,no_run +/// # use gotham::{hyper::{Body, Method, Response}, router::builder::*}; +/// # use gotham_restful::*; +/// build_simple_router(|router| { +/// // The handler that needs preflight handling +/// router.post("/foo").to(|state| { +/// let mut res : Response = unimplemented!(); +/// handle_cors(&state, &mut res); +/// (state, res) +/// }); +/// // Add preflight handling +/// router.cors("/foo", Method::POST); +/// }); +/// ``` pub trait CorsRoute where C : PipelineHandleChain

+ Copy + Send + Sync + 'static, P : RefUnwindSafe + Send + Sync + 'static { + /// Handle a preflight request on `path` for `method`. To configure the behaviour, use + /// [`CorsConfig`](struct.CorsConfig.html). fn cors(&mut self, path : &str, method : Method); } diff --git a/src/lib.rs b/src/lib.rs index 4025e9b..d7aa095 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -166,6 +166,49 @@ fn main() { # } ``` +## CORS Feature + +The cors feature allows an easy usage of this web server from other origins. By default, only +the `Access-Control-Allow-Methods` header is touched. To change the behaviour, add your desired +configuration as a middleware. + +A simple example that allows authentication from every origin (note that `*` always disallows +authentication), and every content type, could look like this: + +```rust,no_run +# #[macro_use] extern crate gotham_restful_derive; +# #[cfg(feature = "cors")] +# mod cors_feature_enabled { +# use gotham::{hyper::header::*, router::builder::*, pipeline::{new_pipeline, single::single_pipeline}, state::State}; +# use gotham_restful::*; +# use serde::{Deserialize, Serialize}; +#[derive(Resource)] +#[resource(read_all)] +struct FooResource; + +#[read_all(FooResource)] +fn read_all() { + // your handler +} + +fn main() { + let cors = CorsConfig { + origin: Origin::Copy, + headers: vec![CONTENT_TYPE], + max_age: 0, + credentials: true + }; + let (chain, pipelines) = single_pipeline(new_pipeline().add(cors).build()); + gotham::start("127.0.0.1:8080", build_router(chain, pipelines, |route| { + route.resource::("foo"); + })); +} +# } +``` + +The cors feature can also be used for non-resource handlers. Take a look at [`CorsRoute`] +for an example. + ## Database Feature The database feature allows an easy integration of [diesel] into your handler functions. Please @@ -238,6 +281,7 @@ Licensed under your option of: [example]: https://gitlab.com/msrd0/gotham-restful/tree/master/example [gotham]: https://gotham.rs/ [serde_json]: https://github.com/serde-rs/json#serde-json---- + [`CorsRoute`]: trait.CorsRoute.html [`QueryStringExtractor`]: ../gotham/extractor/trait.QueryStringExtractor.html [`RequestBody`]: trait.RequestBody.html [`State`]: ../gotham/state/struct.State.html