View Javadoc
1   /*
2    * Copyright 2013 The Netty Project
3    *
4    * The Netty Project licenses this file to you under the Apache License, version
5    * 2.0 (the "License"); you may not use this file except in compliance with the
6    * License. You may obtain a copy of the License at:
7    *
8    * https://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations under
14   * the License.
15   */
16  package io.netty.handler.codec.http.cors;
17  
18  import io.netty.handler.codec.http.DefaultHttpHeaders;
19  import io.netty.handler.codec.http.EmptyHttpHeaders;
20  import io.netty.handler.codec.http.HttpHeaders;
21  import io.netty.handler.codec.http.HttpMethod;
22  import io.netty.util.internal.StringUtil;
23  
24  import java.util.Collections;
25  import java.util.Date;
26  import java.util.LinkedHashSet;
27  import java.util.Map;
28  import java.util.Map.Entry;
29  import java.util.Set;
30  import java.util.concurrent.Callable;
31  
32  /**
33   * Configuration for Cross-Origin Resource Sharing (CORS).
34   */
35  public final class CorsConfig {
36  
37      private final Set<String> origins;
38      private final boolean anyOrigin;
39      private final boolean enabled;
40      private final Set<String> exposeHeaders;
41      private final boolean allowCredentials;
42      private final long maxAge;
43      private final Set<HttpMethod> allowedRequestMethods;
44      private final Set<String> allowedRequestHeaders;
45      private final boolean allowNullOrigin;
46      private final Map<CharSequence, Callable<?>> preflightHeaders;
47      private final boolean shortCircuit;
48      private final boolean allowPrivateNetwork;
49  
50      CorsConfig(final CorsConfigBuilder builder) {
51          origins = new LinkedHashSet<String>(builder.origins);
52          anyOrigin = builder.anyOrigin;
53          enabled = builder.enabled;
54          exposeHeaders = builder.exposeHeaders;
55          allowCredentials = builder.allowCredentials;
56          maxAge = builder.maxAge;
57          allowedRequestMethods = builder.requestMethods;
58          allowedRequestHeaders = builder.requestHeaders;
59          allowNullOrigin = builder.allowNullOrigin;
60          preflightHeaders = builder.preflightHeaders;
61          shortCircuit = builder.shortCircuit;
62          allowPrivateNetwork = builder.allowPrivateNetwork;
63      }
64  
65      /**
66       * Determines if support for CORS is enabled.
67       *
68       * @return {@code true} if support for CORS is enabled, false otherwise.
69       */
70      public boolean isCorsSupportEnabled() {
71          return enabled;
72      }
73  
74      /**
75       * Determines whether a wildcard origin, '*', is supported.
76       *
77       * @return {@code boolean} true if any origin is allowed.
78       */
79      public boolean isAnyOriginSupported() {
80          return anyOrigin;
81      }
82  
83      /**
84       * Returns the allowed origin. This can either be a wildcard or an origin value.
85       *
86       * @return the value that will be used for the CORS response header 'Access-Control-Allow-Origin'
87       */
88      public String origin() {
89          return origins.isEmpty() ? "*" : origins.iterator().next();
90      }
91  
92      /**
93       * Returns the set of allowed origins.
94       *
95       * @return {@code Set} the allowed origins.
96       */
97      public Set<String> origins() {
98          return origins;
99      }
100 
101     /**
102      * Web browsers may set the 'Origin' request header to 'null' if a resource is loaded
103      * from the local file system.
104      *
105      * If isNullOriginAllowed is true then the server will response with the wildcard for
106      * the CORS response header 'Access-Control-Allow-Origin'.
107      *
108      * @return {@code true} if a 'null' origin should be supported.
109      */
110     public boolean isNullOriginAllowed() {
111         return allowNullOrigin;
112     }
113 
114     /**
115      * Web browsers may set the 'Access-Control-Request-Private-Network' request header if a resource is loaded
116      * from a local network.
117      * By default direct access to private network endpoints from public websites is not allowed.
118      *
119      * If isPrivateNetworkAllowed is true the server will response with the CORS response header
120      * 'Access-Control-Request-Private-Network'.
121      *
122      * @return {@code true} if private network access should be allowed.
123      */
124     public boolean isPrivateNetworkAllowed() {
125         return allowPrivateNetwork;
126     }
127 
128     /**
129      * Returns a set of headers to be exposed to calling clients.
130      *
131      * During a simple CORS request only certain response headers are made available by the
132      * browser, for example using:
133      * <pre>
134      * xhr.getResponseHeader("Content-Type");
135      * </pre>
136      * The headers that are available by default are:
137      * <ul>
138      * <li>Cache-Control</li>
139      * <li>Content-Language</li>
140      * <li>Content-Type</li>
141      * <li>Expires</li>
142      * <li>Last-Modified</li>
143      * <li>Pragma</li>
144      * </ul>
145      * To expose other headers they need to be specified, which is what this method enables by
146      * adding the headers names to the CORS 'Access-Control-Expose-Headers' response header.
147      *
148      * @return {@code List<String>} a list of the headers to expose.
149      */
150     public Set<String> exposedHeaders() {
151         return Collections.unmodifiableSet(exposeHeaders);
152     }
153 
154     /**
155      * Determines if cookies are supported for CORS requests.
156      *
157      * By default cookies are not included in CORS requests but if isCredentialsAllowed returns
158      * true cookies will be added to CORS requests. Setting this value to true will set the
159      * CORS 'Access-Control-Allow-Credentials' response header to true.
160      *
161      * Please note that cookie support needs to be enabled on the client side as well.
162      * The client needs to opt-in to send cookies by calling:
163      * <pre>
164      * xhr.withCredentials = true;
165      * </pre>
166      * The default value for 'withCredentials' is false in which case no cookies are sent.
167      * Setting this to true will included cookies in cross origin requests.
168      *
169      * @return {@code true} if cookies are supported.
170      */
171     public boolean isCredentialsAllowed() {
172         return allowCredentials;
173     }
174 
175     /**
176      * Gets the maxAge setting.
177      *
178      * When making a preflight request the client has to perform two request with can be inefficient.
179      * This setting will set the CORS 'Access-Control-Max-Age' response header and enables the
180      * caching of the preflight response for the specified time. During this time no preflight
181      * request will be made.
182      *
183      * @return {@code long} the time in seconds that a preflight request may be cached.
184      */
185     public long maxAge() {
186         return maxAge;
187     }
188 
189     /**
190      * Returns the allowed set of Request Methods. The Http methods that should be returned in the
191      * CORS 'Access-Control-Request-Method' response header.
192      *
193      * @return {@code Set} of {@link HttpMethod}s that represent the allowed Request Methods.
194      */
195     public Set<HttpMethod> allowedRequestMethods() {
196         return Collections.unmodifiableSet(allowedRequestMethods);
197     }
198 
199     /**
200      * Returns the allowed set of Request Headers.
201      *
202      * The header names returned from this method will be used to set the CORS
203      * 'Access-Control-Allow-Headers' response header.
204      *
205      * @return {@code Set<String>} of strings that represent the allowed Request Headers.
206      */
207     public Set<String> allowedRequestHeaders() {
208         return Collections.unmodifiableSet(allowedRequestHeaders);
209     }
210 
211     /**
212      * Returns HTTP response headers that should be added to a CORS preflight response.
213      *
214      * @return {@link HttpHeaders} the HTTP response headers to be added.
215      */
216     public HttpHeaders preflightResponseHeaders() {
217         if (preflightHeaders.isEmpty()) {
218             return EmptyHttpHeaders.INSTANCE;
219         }
220         final HttpHeaders preflightHeaders = new DefaultHttpHeaders();
221         for (Entry<CharSequence, Callable<?>> entry : this.preflightHeaders.entrySet()) {
222             final Object value = getValue(entry.getValue());
223             if (value instanceof Iterable) {
224                 preflightHeaders.add(entry.getKey(), (Iterable<?>) value);
225             } else {
226                 preflightHeaders.add(entry.getKey(), value);
227             }
228         }
229         return preflightHeaders;
230     }
231 
232     /**
233      * Determines whether a CORS request should be rejected if it's invalid before being
234      * further processing.
235      *
236      * CORS headers are set after a request is processed. This may not always be desired
237      * and this setting will check that the Origin is valid and if it is not valid no
238      * further processing will take place, and an error will be returned to the calling client.
239      *
240      * @return {@code true} if a CORS request should short-circuit upon receiving an invalid Origin header.
241      */
242     public boolean isShortCircuit() {
243         return shortCircuit;
244     }
245 
246     /**
247      * @deprecated Use {@link #isShortCircuit()} instead.
248      */
249     @Deprecated
250     public boolean isShortCurcuit() {
251         return isShortCircuit();
252     }
253 
254     private static <T> T getValue(final Callable<T> callable) {
255         try {
256             return callable.call();
257         } catch (final Exception e) {
258             throw new IllegalStateException("Could not generate value for callable [" + callable + ']', e);
259         }
260     }
261 
262     @Override
263     public String toString() {
264         return StringUtil.simpleClassName(this) + "[enabled=" + enabled +
265                 ", origins=" + origins +
266                 ", anyOrigin=" + anyOrigin +
267                 ", exposedHeaders=" + exposeHeaders +
268                 ", isCredentialsAllowed=" + allowCredentials +
269                 ", maxAge=" + maxAge +
270                 ", allowedRequestMethods=" + allowedRequestMethods +
271                 ", allowedRequestHeaders=" + allowedRequestHeaders +
272                 ", preflightHeaders=" + preflightHeaders +
273                 ", isPrivateNetworkAllowed=" + allowPrivateNetwork + ']';
274     }
275 
276     /**
277      * @deprecated Use {@link CorsConfigBuilder#forAnyOrigin()} instead.
278      */
279     @Deprecated
280     public static Builder withAnyOrigin() {
281         return new Builder();
282     }
283 
284     /**
285      * @deprecated Use {@link CorsConfigBuilder#forOrigin(String)} instead.
286      */
287     @Deprecated
288     public static Builder withOrigin(final String origin) {
289         if ("*".equals(origin)) {
290             return new Builder();
291         }
292         return new Builder(origin);
293     }
294 
295     /**
296      * @deprecated Use {@link CorsConfigBuilder#forOrigins(String...)} instead.
297      */
298     @Deprecated
299     public static Builder withOrigins(final String... origins) {
300         return new Builder(origins);
301     }
302 
303     /**
304      * @deprecated Use {@link CorsConfigBuilder} instead.
305      */
306     @Deprecated
307     public static class Builder {
308 
309         private final CorsConfigBuilder builder;
310 
311         /**
312          * @deprecated Use {@link CorsConfigBuilder} instead.
313          */
314         @Deprecated
315         public Builder(final String... origins) {
316             builder = new CorsConfigBuilder(origins);
317         }
318 
319         /**
320          * @deprecated Use {@link CorsConfigBuilder} instead.
321          */
322         @Deprecated
323         public Builder() {
324             builder = new CorsConfigBuilder();
325         }
326 
327         /**
328          * @deprecated Use {@link CorsConfigBuilder#allowNullOrigin()} instead.
329          */
330         @Deprecated
331         public Builder allowNullOrigin() {
332             builder.allowNullOrigin();
333             return this;
334         }
335 
336         /**
337          * @deprecated Use {@link CorsConfigBuilder#disable()} instead.
338          */
339         @Deprecated
340         public Builder disable() {
341             builder.disable();
342             return this;
343         }
344 
345         /**
346          * @deprecated Use {@link CorsConfigBuilder#exposeHeaders(String...)} instead.
347          */
348         @Deprecated
349         public Builder exposeHeaders(final String... headers) {
350             builder.exposeHeaders(headers);
351             return this;
352         }
353 
354         /**
355          * @deprecated Use {@link CorsConfigBuilder#allowCredentials()} instead.
356          */
357         @Deprecated
358         public Builder allowCredentials() {
359             builder.allowCredentials();
360             return this;
361         }
362 
363         /**
364          * @deprecated Use {@link CorsConfigBuilder#maxAge(long)} instead.
365          */
366         @Deprecated
367         public Builder maxAge(final long max) {
368             builder.maxAge(max);
369             return this;
370         }
371 
372         /**
373          * @deprecated Use {@link CorsConfigBuilder#allowedRequestMethods(HttpMethod...)} instead.
374          */
375         @Deprecated
376         public Builder allowedRequestMethods(final HttpMethod... methods) {
377             builder.allowedRequestMethods(methods);
378             return this;
379         }
380 
381         /**
382          * @deprecated Use {@link CorsConfigBuilder#allowedRequestHeaders(String...)} instead.
383          */
384         @Deprecated
385         public Builder allowedRequestHeaders(final String... headers) {
386             builder.allowedRequestHeaders(headers);
387             return this;
388         }
389 
390         /**
391          * @deprecated Use {@link CorsConfigBuilder#preflightResponseHeader(CharSequence, Object...)} instead.
392          */
393         @Deprecated
394         public Builder preflightResponseHeader(final CharSequence name, final Object... values) {
395             builder.preflightResponseHeader(name, values);
396             return this;
397         }
398 
399         /**
400          * @deprecated Use {@link CorsConfigBuilder#preflightResponseHeader(CharSequence, Iterable)} instead.
401          */
402         @Deprecated
403         public <T> Builder preflightResponseHeader(final CharSequence name, final Iterable<T> value) {
404             builder.preflightResponseHeader(name, value);
405             return this;
406         }
407 
408         /**
409          * @deprecated Use {@link CorsConfigBuilder#preflightResponseHeader(CharSequence, Callable)} instead.
410          */
411         @Deprecated
412         public <T> Builder preflightResponseHeader(final String name, final Callable<T> valueGenerator) {
413             builder.preflightResponseHeader(name, valueGenerator);
414             return this;
415         }
416 
417         /**
418          * @deprecated Use {@link CorsConfigBuilder#noPreflightResponseHeaders()} instead.
419          */
420         @Deprecated
421         public Builder noPreflightResponseHeaders() {
422             builder.noPreflightResponseHeaders();
423             return this;
424         }
425 
426         /**
427          * @deprecated Use {@link CorsConfigBuilder#build()} instead.
428          */
429         @Deprecated
430         public CorsConfig build() {
431             return builder.build();
432         }
433 
434         /**
435          * @deprecated Use {@link CorsConfigBuilder#shortCircuit()} instead.
436          */
437         @Deprecated
438         public Builder shortCurcuit() {
439             builder.shortCircuit();
440             return this;
441         }
442     }
443 
444     /**
445      * @deprecated Removed without alternatives.
446      */
447     @Deprecated
448     public static final class DateValueGenerator implements Callable<Date> {
449 
450         @Override
451         public Date call() throws Exception {
452             return new Date();
453         }
454     }
455 }