From 3650ecc3bbd94d16de797f6528dcca5abf02d3f0 Mon Sep 17 00:00:00 2001 From: Rossen Stoyanchev Date: Tue, 28 Nov 2017 22:16:07 -0500 Subject: [PATCH] Polish --- .../web/bind/annotation/CrossOrigin.java | 105 +++++++++--------- .../web/cors/CorsConfiguration.java | 16 +-- .../web/reactive/config/CorsRegistration.java | 52 +++++---- .../web/reactive/config/CorsRegistry.java | 15 ++- .../config/annotation/CorsRegistration.java | 63 ++++++----- .../config/annotation/CorsRegistry.java | 17 ++- .../web/servlet/config/spring-mvc.xsd | 21 +++- src/docs/asciidoc/web/webflux-cors.adoc | 3 + src/docs/asciidoc/web/webmvc-cors.adoc | 3 + 9 files changed, 159 insertions(+), 136 deletions(-) diff --git a/spring-web/src/main/java/org/springframework/web/bind/annotation/CrossOrigin.java b/spring-web/src/main/java/org/springframework/web/bind/annotation/CrossOrigin.java index 2614dc8c5d..e881fb40d6 100644 --- a/spring-web/src/main/java/org/springframework/web/bind/annotation/CrossOrigin.java +++ b/spring-web/src/main/java/org/springframework/web/bind/annotation/CrossOrigin.java @@ -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. * - *

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}. - * - *

NOTE: {@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. + *

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"}. - *

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. - *

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. + *

A matched origin is listed in the {@code Access-Control-Allow-Origin} + * response header of preflight actual CORS requests. + *

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. - *

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. - *

If undefined, all requested headers are allowed. + * The list of request headers that are permitted in actual requests, + * possibly {@code "*"} to allow all headers. + *

Allowed headers are listed in the {@code Access-Control-Allow-Headers} + * response header of preflight requests. + *

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. + *

By default all requested headers are allowed. */ String[] allowedHeaders() default {}; /** - * List of response headers that the user-agent will allow the client to access. - *

This property controls the value of actual response's - * {@code Access-Control-Expose-Headers} header. - *

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}, + *

Exposed headers are listed in the {@code Access-Control-Expose-Headers} + * response header of actual CORS requests. + *

By default no headers are listed as exposed. */ String[] exposedHeaders() default {}; /** - * List of supported HTTP request methods, e.g. - * {@code "{RequestMethod.GET, RequestMethod.POST}"}. - *

Methods specified here override those specified via {@code RequestMapping}. - *

If undefined, methods defined by {@link RequestMapping} annotation - * are used. + * The list of supported HTTP request methods. + *

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). - *

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. - *

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. + *

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 + * {@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. *

This property controls the value of the {@code Access-Control-Max-Age} - * header in the pre-flight response. - *

Setting this to a reasonable value can reduce the number of pre-flight + * response header of preflight requests. + *

Setting this to a reasonable value can reduce the number of preflight * request/response interactions required by the browser. * A negative value means undefined. - *

If undefined, max age is set to {@code 1800} seconds (i.e., 30 minutes). + *

By default this is set to {@code 1800} seconds (30 minutes). */ long maxAge() default -1; diff --git a/spring-web/src/main/java/org/springframework/web/cors/CorsConfiguration.java b/spring-web/src/main/java/org/springframework/web/cors/CorsConfiguration.java index 9cb065465c..c9f0e48567 100644 --- a/spring-web/src/main/java/org/springframework/web/cors/CorsConfiguration.java +++ b/spring-web/src/main/java/org/springframework/web/cors/CorsConfiguration.java @@ -35,24 +35,20 @@ import org.springframework.util.StringUtils; * *

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. - * - *

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 CORS W3C recommendation + * @see CORS spec */ public class CorsConfiguration { - /** - * Wildcard representing all origins, methods, or headers. - */ + /** Wildcard representing all origins, methods, or headers. */ public static final String ALL = "*"; private static final List DEFAULT_METHODS; @@ -321,7 +317,7 @@ public class CorsConfiguration { * *

The following defaults are applied if not already set: *