root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 6 Packages Projects Releases Wiki Activity

Polish

This commit is contained in:
Rossen Stoyanchev 2017-11-28 22:16:07 -05:00
parent bec63fbb33
commit 3650ecc3bb
9 changed files with 159 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
spring-web/src/main/java/org/springframework/web/bind/annotation/CrossOrigin.java
View File

@ -1,5 +1,5 @@
/*
* Copyright 2002-2016 the original author or authors.
* Copyright 2002-2017 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@ -26,17 +26,15 @@ import org.springframework.core.annotation.AliasFor;
import org.springframework.web.cors.CorsConfiguration;
/**
* Marks the annotated method or type as permitting cross origin requests.
* Annotation for permitting cross-origin requests on specific handler classes
* and/or handler methods. Processed if an appropriate {@code HandlerMapping}
* is configured.
*
* <p>By default all origins and headers are permitted, credentials are not allowed,
* and the maximum age is set to 1800 seconds (30 minutes). The list of HTTP
* methods is set to the methods on the {@code @RequestMapping} if not
* explicitly set on {@code @CrossOrigin}.
*
* <p><b>NOTE:</b> {@code @CrossOrigin} is processed if an appropriate
* {@code HandlerMapping}-{@code HandlerAdapter} pair is configured such as the
* {@code RequestMappingHandlerMapping}-{@code RequestMappingHandlerAdapter}
* pair which are the default in the MVC Java config and the MVC namespace.
* <p>Both Spring Web MVC and Spring WebFlux support this annotation through the
* {@code RequestMappingHandlerMapping} in their respective modules. The values
* from each type and method level pair of annotations are added to a
* {@link CorsConfiguration} and then default values are applied via
* {@link CorsConfiguration#applyPermitDefaultValues()}.
*
* @author Russell Allen
* @author Sebastien Deleuze
@ -48,27 +46,19 @@ import org.springframework.web.cors.CorsConfiguration;
@Documented
public @interface CrossOrigin {
/**
* @deprecated as of Spring 5.0, in favor of using {@link CorsConfiguration#applyPermitDefaultValues}
*/
/** @deprecated as of Spring 5.0, in favor {@link CorsConfiguration#applyPermitDefaultValues} */
@Deprecated
String[] DEFAULT_ORIGINS = { "*" };
/**
* @deprecated as of Spring 5.0, in favor of using {@link CorsConfiguration#applyPermitDefaultValues}
*/
/** @deprecated as of Spring 5.0, in favor {@link CorsConfiguration#applyPermitDefaultValues} */
@Deprecated
String[] DEFAULT_ALLOWED_HEADERS = { "*" };
/**
* @deprecated as of Spring 5.0, in favor of using {@link CorsConfiguration#applyPermitDefaultValues}
*/
/** @deprecated as of Spring 5.0, in favor {@link CorsConfiguration#applyPermitDefaultValues} */
@Deprecated
boolean DEFAULT_ALLOW_CREDENTIALS = false;
/**
* @deprecated as of Spring 5.0, in favor of using {@link CorsConfiguration#applyPermitDefaultValues}
*/
/** @deprecated as of Spring 5.0, in favor {@link CorsConfiguration#applyPermitDefaultValues} */
@Deprecated
long DEFAULT_MAX_AGE = 1800;
@ -80,62 +70,69 @@ public @interface CrossOrigin {
String[] value() default {};
/**
* List of allowed origins, e.g. {@code "http://domain1.com"}.
* <p>These values are placed in the {@code Access-Control-Allow-Origin}
* header of both the pre-flight response and the actual response.
* {@code "*"} means that all origins are allowed.
* <p>If undefined, all origins are allowed.
* The list of allowed origins that be specific origins, e.g.
* {@code "http://domain1.com"}, or {@code "*"} for all origins.
* <p>A matched origin is listed in the {@code Access-Control-Allow-Origin}
* response header of preflight actual CORS requests.
* <p>By default all origins are allowed.
* @see #value
*/
@AliasFor("value")
String[] origins() default {};
/**
* List of request headers that can be used during the actual request.
* <p>This property controls the value of the pre-flight response's
* {@code Access-Control-Allow-Headers} header.
* {@code "*"} means that all headers requested by the client are allowed.
* <p>If undefined, all requested headers are allowed.
* The list of request headers that are permitted in actual requests,
* possibly {@code "*"} to allow all headers.
* <p>Allowed headers are listed in the {@code Access-Control-Allow-Headers}
* response header of preflight requests.
* <p>A header name is not required to be listed if it is one of:
* {@code Cache-Control}, {@code Content-Language}, {@code Expires},
* {@code Last-Modified}, or {@code Pragma} as per the CORS spec.
* <p>By default all requested headers are allowed.
*/
String[] allowedHeaders() default {};
/**
* List of response headers that the user-agent will allow the client to access.
* <p>This property controls the value of actual response's
* {@code Access-Control-Expose-Headers} header.
* <p>If undefined, an empty exposed header list is used.
* The List of response headers that the user-agent will allow the client
* to access on an actual response, other than "simple" headers, i.e.
* {@code Cache-Control}, {@code Content-Language}, {@code Content-Type},
* {@code Expires}, {@code Last-Modified}, or {@code Pragma},
* <p>Exposed headers are listed in the {@code Access-Control-Expose-Headers}
* response header of actual CORS requests.
* <p>By default no headers are listed as exposed.
*/
String[] exposedHeaders() default {};
/**
* List of supported HTTP request methods, e.g.
* {@code "{RequestMethod.GET, RequestMethod.POST}"}.
* <p>Methods specified here override those specified via {@code RequestMapping}.
* <p>If undefined, methods defined by {@link RequestMapping} annotation
* are used.
* The list of supported HTTP request methods.
* <p>By default the supported methods are the same as the ones to which a
* controller method is mapped.
*/
RequestMethod[] methods() default {};
/**
* Whether the browser should include any cookies associated with the
* domain of the request being annotated. Be aware that enabling this option could
* increase the surface attack of the web application (for example via exposing
* sensitive user-specific information like CSRF tokens).
* <p>Set to {@code "true"} means that the pre-flight response will include the header
* {@code Access-Control-Allow-Credentials=true} so such cookies should be included.
* <p>If undefined or set to {@code "false"}, such header is not included and
* credentials are not allowed.
* Whether the browser should send credentials, such as cookies along with
* cross domain requests, to the annotated endpoint. The configured value is
* set on the {@code Access-Control-Allow-Credentials} response header of
* preflight requests.
* <p><strong>NOTE:</strong> Be aware that this option establishes a high
* level of trust with the configured domains and also increases the surface
* attack of the web application by exposing sensitive user-specific
* information such as cookies and CSRF tokens.
* <p>By default this is not set in which case the
* {@code Access-Control-Allow-Credentials} header is also not set and
* credentials are therefore not allowed.
*/
String allowCredentials() default "";
/**
* The maximum age (in seconds) of the cache duration for pre-flight responses.
* The maximum age (in seconds) of the cache duration for preflight responses.
* <p>This property controls the value of the {@code Access-Control-Max-Age}
* header in the pre-flight response.
* <p>Setting this to a reasonable value can reduce the number of pre-flight
* response header of preflight requests.
* <p>Setting this to a reasonable value can reduce the number of preflight
* request/response interactions required by the browser.
* A negative value means <em>undefined</em>.
* <p>If undefined, max age is set to {@code 1800} seconds (i.e., 30 minutes).
* <p>By default this is set to {@code 1800} seconds (30 minutes).
*/
long maxAge() default -1;

16
spring-web/src/main/java/org/springframework/web/cors/CorsConfiguration.java
View File

@ -35,24 +35,20 @@ import org.springframework.util.StringUtils;
*
* <p>By default a newly created {@code CorsConfiguration} does not permit any
* cross-origin requests and must be configured explicitly to indicate what
* should be allowed.
*
* <p>Use {@link #applyPermitDefaultValues()} to flip the initialization model
* to start with open defaults that permit all cross-origin requests for GET,
* HEAD, and POST requests.
* should be allowed. Use {@link #applyPermitDefaultValues()} to flip the
* initialization model to start with open defaults that permit all cross-origin
* requests for GET, HEAD, and POST requests.
*
* @author Sebastien Deleuze
* @author Rossen Stoyanchev
* @author Juergen Hoeller
* @author Sam Brannen
* @since 4.2
* @see <a href="http://www.w3.org/TR/cors/">CORS W3C recommendation</a>
* @see <a href="http://www.w3.org/TR/cors/">CORS spec</a>
*/
public class CorsConfiguration {
/**
* Wildcard representing <em>all</em> origins, methods, or headers.
*/
/** Wildcard representing <em>all</em> origins, methods, or headers. */
public static final String ALL = "*";
private static final List<HttpMethod> DEFAULT_METHODS;
@ -321,7 +317,7 @@ public class CorsConfiguration {
*
* <p>The following defaults are applied if not already set:
* <ul>
* <li>Allow all origins, i.e. {@code "*"}.</li>
* <li>Allow all origins.</li>
* <li>Allow "simple" methods {@code GET}, {@code HEAD} and {@code POST}.</li>
* <li>Allow all headers.</li>
* <li>Set max age to 1800 seconds (30 minutes).</li>

52
spring-webflux/src/main/java/org/springframework/web/reactive/config/CorsRegistration.java
View File

@ -1,5 +1,5 @@
/*
* Copyright 2002-2016 the original author or authors.
* Copyright 2002-2017 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@ -22,10 +22,8 @@ import java.util.Arrays;
import org.springframework.web.cors.CorsConfiguration;
/**
* Assists with the creation of a {@link CorsConfiguration} instance mapped to
* a path pattern. By default all origins, headers, and credentials for
* {@code GET}, {@code HEAD}, and {@code POST} requests are allowed while the
* max age is set to 30 minutes.
* Assists with the creation of a {@link CorsConfiguration} instance for a given
* URL path pattern.
*
* @author Sebastien Deleuze
* @author Rossen Stoyanchev
@ -39,15 +37,6 @@ public class CorsRegistration {
private final CorsConfiguration config;
/**
* Create a new {@link CorsRegistration} that allows all origins, headers, and
* credentials for {@code GET}, {@code HEAD}, and {@code POST} requests with
* max age set to 1800 seconds (30 minutes) for the specified path.
*
* @param pathPattern the path that the CORS configuration should apply to;
* exact path mapping URIs (such as {@code "/admin"}) are supported as well
* as Ant-style path patterns (such as {@code "/admin/**"}).
*/
public CorsRegistration(String pathPattern) {
this.pathPattern = pathPattern;
this.config = new CorsConfiguration().applyPermitDefaultValues();
@ -55,8 +44,10 @@ public class CorsRegistration {
/**
* Set the origins to allow, e.g. {@code "http://domain1.com"}.
* <p>The special value {@code "*"} allows all domains.
* The list of allowed origins that be specific origins, e.g.
* {@code "http://domain1.com"}, or {@code "*"} for all origins.
* <p>A matched origin is listed in the {@code Access-Control-Allow-Origin}
* response header of preflight actual CORS requests.
* <p>By default all origins are allowed.
*/
public CorsRegistration allowedOrigins(String... origins) {
@ -102,6 +93,24 @@ public class CorsRegistration {
return this;
}
/**
* Whether the browser should send credentials, such as cookies along with
* cross domain requests, to the annotated endpoint. The configured value is
* set on the {@code Access-Control-Allow-Credentials} response header of
* preflight requests.
* <p><strong>NOTE:</strong> Be aware that this option establishes a high
* level of trust with the configured domains and also increases the surface
* attack of the web application by exposing sensitive user-specific
* information such as cookies and CSRF tokens.
* <p>By default this is not set in which case the
* {@code Access-Control-Allow-Credentials} header is also not set and
* credentials are therefore not allowed.
*/
public CorsRegistration allowCredentials(boolean allowCredentials) {
this.config.setAllowCredentials(allowCredentials);
return this;
}
/**
* Configure how long in seconds the response from a pre-flight request
* can be cached by clients.
@ -112,17 +121,6 @@ public class CorsRegistration {
return this;
}
/**
* Whether user credentials are supported. Be aware that enabling this option
* could increase the surface attack of the web application (for example via
* exposing sensitive user-specific information like CSRF tokens).
* <p>By default credentials are not allowed.
*/
public CorsRegistration allowCredentials(boolean allowCredentials) {
this.config.setAllowCredentials(allowCredentials);
return this;
}
protected String getPathPattern() {
return this.pathPattern;
}

15
spring-webflux/src/main/java/org/springframework/web/reactive/config/CorsRegistry.java
View File

@ -24,10 +24,11 @@ import java.util.Map;
import org.springframework.web.cors.CorsConfiguration;
/**
* {@code CorsRegistry} assists with the registration of {@link CorsConfiguration}
* mapped to a path pattern.
* Assists with the registration of global, URL pattern based
* {@link CorsConfiguration} mappings.
*
* @author Sebastien Deleuze
* @author Rossen Stoyanchev
* @since 5.0
*/
public class CorsRegistry {
@ -41,9 +42,13 @@ public class CorsRegistry {
* <p>Exact path mapping URIs (such as {@code "/admin"}) are supported as
* well as Ant-style path patterns (such as {@code "/admin/**"}).
*
* <p>By default, all origins, all headers, credentials and {@code GET},
* {@code HEAD}, and {@code POST} methods are allowed, and the max age
* is set to 30 minutes.
* <p>The following defaults are applied to the {@link CorsRegistration}:
* <ul>
* <li>Allow all origins.</li>
* <li>Allow "simple" methods {@code GET}, {@code HEAD} and {@code POST}.</li>
* <li>Allow all headers.</li>
* <li>Set max age to 1800 seconds (30 minutes).</li>
* </ul>
*/
public CorsRegistration addMapping(String pathPattern) {
CorsRegistration registration = new CorsRegistration(pathPattern);

63
spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/CorsRegistration.java
View File

@ -1,5 +1,5 @@
/*
* Copyright 2002-2016 the original author or authors.
* Copyright 2002-2017 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@ -21,10 +21,8 @@ import java.util.Arrays;
import org.springframework.web.cors.CorsConfiguration;
/**
* Assists with the creation of a {@link CorsConfiguration} instance mapped to
* a path pattern. By default all origins, headers, and credentials for
* {@code GET}, {@code HEAD}, and {@code POST} requests are allowed while the
* max age is set to 30 minutes.
* Assists with the creation of a {@link CorsConfiguration} instance for a given
* URL path pattern.
*
* @author Sebastien Deleuze
* @author Rossen Stoyanchev
@ -40,14 +38,6 @@ public class CorsRegistration {
private final CorsConfiguration config;
/**
* Create a new {@link CorsRegistration} that allows all origins, headers, and
* credentials for {@code GET}, {@code HEAD}, and {@code POST} requests with
* max age set to 1800 seconds (30 minutes) for the specified path.
* @param pathPattern the path that the CORS configuration should apply to;
* exact path mapping URIs (such as {@code "/admin"}) are supported as well
* as Ant-style path patterns (such as {@code "/admin/**"}).
*/
public CorsRegistration(String pathPattern) {
this.pathPattern = pathPattern;
// Same implicit default values as the @CrossOrigin annotation + allows simple methods
@ -56,8 +46,10 @@ public class CorsRegistration {
/**
* Set the origins to allow, e.g. {@code "http://domain1.com"}.
* <p>The special value {@code "*"} allows all domains.
* The list of allowed origins that be specific origins, e.g.
* {@code "http://domain1.com"}, or {@code "*"} for all origins.
* <p>A matched origin is listed in the {@code Access-Control-Allow-Origin}
* response header of preflight actual CORS requests.
* <p>By default, all origins are allowed.
*/
public CorsRegistration allowedOrigins(String... origins) {
@ -68,9 +60,9 @@ public class CorsRegistration {
/**
* Set the HTTP methods to allow, e.g. {@code "GET"}, {@code "POST"}, etc.
* <p>The special value {@code "*"} allows all methods.
* <p>By default "simple" methods {@code GET}, {@code HEAD}, and {@code POST}
* are allowed.
* The special value {@code "*"} allows all methods.
* <p>By default "simple" methods, i.e. {@code GET}, {@code HEAD}, and
* {@code POST} are allowed.
*/
public CorsRegistration allowedMethods(String... methods) {
this.config.setAllowedMethods(Arrays.asList(methods));
@ -78,9 +70,9 @@ public class CorsRegistration {
}
/**
* Set the list of headers that a pre-flight request can list as allowed
* for use during an actual request.
* <p>The special value {@code "*"} may be used to allow all headers.
* Set the list of headers that a preflight request can list as allowed
* for use during an actual request. The special value {@code "*"} may be
* used to allow all headers.
* <p>A header name is not required to be listed if it is one of:
* {@code Cache-Control}, {@code Content-Language}, {@code Expires},
* {@code Last-Modified}, or {@code Pragma} as per the CORS spec.
@ -104,6 +96,24 @@ public class CorsRegistration {
return this;
}
/**
* Whether the browser should send credentials, such as cookies along with
* cross domain requests, to the annotated endpoint. The configured value is
* set on the {@code Access-Control-Allow-Credentials} response header of
* preflight requests.
* <p><strong>NOTE:</strong> Be aware that this option establishes a high
* level of trust with the configured domains and also increases the surface
* attack of the web application by exposing sensitive user-specific
* information such as cookies and CSRF tokens.
* <p>By default this is not set in which case the
* {@code Access-Control-Allow-Credentials} header is also not set and
* credentials are therefore not allowed.
*/
public CorsRegistration allowCredentials(boolean allowCredentials) {
this.config.setAllowCredentials(allowCredentials);
return this;
}
/**
* Configure how long in seconds the response from a pre-flight request
* can be cached by clients.
@ -114,17 +124,6 @@ public class CorsRegistration {
return this;
}
/**
* Whether user credentials are supported. Be aware that enabling this option
* could increase the surface attack of the web application (for example via
* exposing sensitive user-specific information like CSRF tokens).
* <p>By default credentials are not allowed.
*/
public CorsRegistration allowCredentials(boolean allowCredentials) {
this.config.setAllowCredentials(allowCredentials);
return this;
}
protected String getPathPattern() {
return this.pathPattern;
}

17
spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/CorsRegistry.java
View File

@ -24,10 +24,11 @@ import java.util.Map;
import org.springframework.web.cors.CorsConfiguration;
/**
* {@code CorsRegistry} assists with the registration of {@link CorsConfiguration}
* mapped to a path pattern.
* Assists with the registration of global, URL pattern based
* {@link CorsConfiguration} mappings.
*
* @author Sebastien Deleuze
* @author Rossen Stoyanchev
* @since 4.2
* @see CorsRegistration
*/
@ -38,14 +39,20 @@ public class CorsRegistry {
/**
* Enable cross-origin request handling for the specified path pattern.
*
* <p>Exact path mapping URIs (such as {@code "/admin"}) are supported as
* well as Ant-style path patterns (such as {@code "/admin/**"}).
* <p>By default, all origins, all headers, credentials and {@code GET},
* {@code HEAD}, and {@code POST} methods are allowed, and the max age
* is set to 30 minutes.
* @param pathPattern the path pattern to enable CORS handling for
* @return CorsRegistration the corresponding registration object,
* allowing for further fine-tuning
*
* <p>The following defaults are applied to the {@link CorsRegistration}:
* <ul>
* <li>Allow all origins.</li>
* <li>Allow "simple" methods {@code GET}, {@code HEAD} and {@code POST}.</li>
* <li>Allow all headers.</li>
* <li>Set max age to 1800 seconds (30 minutes).</li>
* </ul>
*/
public CorsRegistration addMapping(String pathPattern) {
CorsRegistration registration = new CorsRegistration(pathPattern);

21
spring-webmvc/src/main/resources/org/springframework/web/servlet/config/spring-mvc.xsd
View File

@ -1310,8 +1310,11 @@
<xsd:annotation>
<xsd:documentation><![CDATA[
Enable cross origin requests processing on the specified path pattern.
By default, all origins, GET HEAD POST methods, all headers and credentials
are allowed and max age is set to 30 minutes.
The following defaults are applied to the resulting CorsRegistration:
- Allow all origins.
- Allow "simple" methods {@code GET}, {@code HEAD} and {@code POST}.
- Allow all headers.
- Set max age to 1800 seconds (30 minutes).
]]></xsd:documentation>
</xsd:annotation>
<xsd:complexType>
@ -1361,7 +1364,19 @@
<xsd:attribute name="allow-credentials" type="xsd:boolean">
<xsd:annotation>
<xsd:documentation><![CDATA[
Whether user credentials are supported (true by default).
Whether the browser should send credentials, such as cookies along with
cross domain requests, to the annotated endpoint. The configured value is
set on the "Access-Control-Allow-Credentials" response header of
preflight requests.
NOTE: Be aware that this option establishes a high
level of trust with the configured domains and also increases the surface
attack of the web application by exposing sensitive user-specific
information such as cookies and CSRF tokens.
By default this is not set in which case the
"Access-Control-Allow-Credentials" header is also not set and
credentials are therefore not allowed.
]]></xsd:documentation>
</xsd:annotation>
</xsd:attribute>

3
src/docs/asciidoc/web/webflux-cors.adoc
View File

@ -59,11 +59,14 @@ all global and all local origins. The only exception are those attributes where
single value can be accepted such as `allowCredentials` and `maxAge`, in which case the
local overrides the global value.
[TIP]
====
To learn more from the source or make advanced customizations, check:
* `CorsConfiguration`
* `CorsProcessor`, `DefaultCorsProcessor`
* `AbstractHandlerMapping`
====

3
src/docs/asciidoc/web/webmvc-cors.adoc
View File

@ -59,11 +59,14 @@ all global and all local origins. The only exception are those attributes where
single value can be accepted such as `allowCredentials` and `maxAge`, in which case the
local overrides the global value.
[TIP]
====
To learn more from the source or make advanced customizations, check:
* `CorsConfiguration`
* `CorsProcessor`, `DefaultCorsProcessor`
* `AbstractHandlerMapping`
====