CORS (Cross Origin Resource Sharing) is a mechanism to enable cross origin requests.
This is a Scala implementation for the server-side targeting the Akka Http library. Main features:
- Works without any additional configuration. Sensible defaults are provided.
- Respects the full standard defined by the W3C, even the border cases.
- Tests, lots of tests.
| Version | Release date | Akka Http version | Scala versions |
|---|---|---|---|
0.2.2 |
2017-09-25 | 10.0.10 |
2.11.11, 2.12.3 |
0.2.1 |
2017-04-03 | 10.0.5 |
2.11.8, 2.12.1 |
0.1.11 |
2017-01-31 | 10.0.3 |
2.11.8, 2.12.1 |
0.1.8 |
2016-10-30 | 2.4.11 |
2.11.8, 2.12.0-RC2 |
0.1.6 |
2016-09-10 | 2.4.10 |
2.11.8 |
0.1.4 |
2016-07-08 | 2.4.8 |
2.11.8 |
0.1.0 |
2016-03-20 | 2.4.2 |
2.11.8 |
Some less interesting versions are not listed in the above table. The complete list can be found in the CHANGELOG file.
akka-http-cors is deployed to Maven Central. Add it to your build.sbt or Build.scala:
libraryDependencies += "ch.megard" %% "akka-http-cors" % "0.2.2"The simplest way to enable CORS in your application is to use the cors directive.
Settings are passed as a parameter to the directive, with defaults provided for convenience.
import ch.megard.akka.http.cors.scaladsl.CorsDirectives._
val route: Route = cors() {
complete(...)
}The default settings can be used as a baseline to customize the CORS directive behaviour:
val settings = CorsSettings.defaultSettings.copy(allowGenericHttpRequests = false)
val strictRoute: Route = cors(settings) {
complete(...)
}A second directive, corsDecorate, implements the same behaviour as the first one but additionally provides information about the current request to the inner route.
val route: Route = corsDecorate() {
case CorsRequest(origins) ⇒ complete("actual")
case NotCorsRequest ⇒ complete("not cors")
}A full example, with proper exception and rejection handling, is available in the akka-http-cors-example sub-project.
The CORS directives can reject requests using the CorsRejection class. Requests can be either malformed or not allowed to access the resource.
A rejection handler is provided by the library to return meaningful HTTP responses. Read the akka documentation to learn more about rejections, or if you need to write your own handler.
import akka.http.scaladsl.server.directives.ExecutionDirectives._
import ch.megard.akka.http.cors.scaladsl.CorsDirectives._
val route: Route = handleRejections(corsRejectionHandler) {
cors() {
complete(...)
}
}Starting from version 0.2.1 Java is supported, mirroring the Scala API. For usage, look at the full Java CorsServer example.
Boolean with default value true.
If true, allow generic requests (that are outside the scope of the specification) to pass through the directive. Else, strict CORS filtering is applied and any invalid request will be rejected.
Boolean with default value true.
Indicates whether the resource supports user credentials. If true, the header Access-Control-Allow-Credentials is set in the response, indicating the actual request can include user credentials.
Examples of user credentials are: cookies, HTTP authentication or client-side certificates.
HttpOriginRange with default value HttpOriginRange.*.
List of origins that the CORS filter must allow. Can also be set to * to allow access to the resource from any origin. Controls the content of the Access-Control-Allow-Origin response header:
- if parameter is
*and credentials are not allowed, a*is set inAccess-Control-Allow-Origin. - otherwise, the origins given in the
Originrequest header are echoed.
The actual or preflight request is rejected if any of the origins from the request is not allowed.
HttpHeaderRange with default value HttpHeaderRange.*.
List of request headers that can be used when making an actual request. Controls the content of the Access-Control-Allow-Headers header in a preflight response:
- if parameter is
*, the headers fromAccess-Control-Request-Headersare echoed. - otherwise the parameter list is returned as part of the header.
Seq[HttpMethod] with default value Seq(GET, POST, HEAD, OPTIONS).
List of methods that can be used when making an actual request. The list is returned as part of the Access-Control-Allow-Methods preflight response header.
The preflight request will be rejected if the Access-Control-Request-Method header's method is not part of the list.
Seq[String] with default value Seq.empty.
List of headers (other than simple response headers) that browsers are allowed to access. If not empty, this list is returned as part of the Access-Control-Expose-Headers header in the actual response.
Option[Long] (in seconds) with default value Some (30 * 60).
When set, the amount of seconds the browser is allowed to cache the results of a preflight request. This value is returned as part of the Access-Control-Max-Age preflight response header. If None, the header is not added to the preflight response.
Using the sbt-jmh plugin, preliminary benchmarks have been performed to measure the impact of the cors directive on the performance. The first results are shown below.
Results are not all coming from the same machine.
> jmh:run -i 40 -wi 30 -f2 -t1
Benchmark Mode Cnt Score Error Units
CorsBenchmark.baseline thrpt 80 3601.121 ± 102.274 ops/s
CorsBenchmark.default_cors thrpt 80 3582.090 ± 95.304 ops/s
CorsBenchmark.default_preflight thrpt 80 3482.716 ± 89.124 ops/s
> jmh:run -i 40 -wi 30 -f2 -t1
Benchmark Mode Cnt Score Error Units
CorsBenchmark.baseline thrpt 80 3657.762 ± 141.409 ops/s
CorsBenchmark.default_cors thrpt 80 3687.351 ± 35.176 ops/s
CorsBenchmark.default_preflight thrpt 80 3645.629 ± 30.411 ops/s
> jmh:run -i 40 -wi 30 -f2 -t1
Benchmark Mode Cnt Score Error Units
CorsBenchmark.baseline thrpt 80 9730.001 ± 25.281 ops/s
CorsBenchmark.default_cors thrpt 80 9159.320 ± 25.459 ops/s
CorsBenchmark.default_preflight thrpt 80 9172.938 ± 26.794 ops/s
This code is open source software licensed under the Apache 2.0 License.