Add pekko-http-cors module

Co-Authored-By: Lomig Mégard <[email protected]>

Author: mdedetrich

NOTICE

@@ -21,3 +21,9 @@ Copyright (c) 2011-2023 Lightbend, Inc.
 Scala includes software developed at
 LAMP/EPFL (https://lamp.epfl.ch/) and
 Lightbend, Inc. (https://www.lightbend.com/).
+
+---------------
+
+pekko-http-cors contains code that was donated by Lomig Mégard to the Apache Software Foundation
+via a Software Grant Agreement <https://www.apache.org/licenses/contributor-agreements.html#grants>
+See <https://github.com/lomigmegard/pekko-http-cors/issues/33>.

build.sbt

@@ -55,6 +55,7 @@ lazy val userProjects: Seq[ProjectReference] = List[ProjectReference](
   http2Tests,
   http,
   httpCaching,
+  httpCors,
   httpTestkit,
   httpMarshallersScala,
   httpMarshallersJava,
@@ -250,7 +251,7 @@ lazy val httpTests = project("http-tests")
 
 lazy val httpJmhBench = project("http-bench-jmh")
   .settings(commonSettings)
-  .dependsOn(http, http2Tests % "compile->compile,test")
+  .dependsOn(http, httpCors, http2Tests % "compile->compile,test")
   .addPekkoModuleDependency("pekko-stream")
   .enablePlugins(JmhPlugin)
   .enablePlugins(NoPublish) // don't release benchs
@@ -300,6 +301,17 @@ lazy val httpCaching = project("http-caching")
   .dependsOn(http, httpCore, httpTestkit % "test")
   .enablePlugins(BootstrapGenjavadoc)
 
+lazy val httpCors = project("http-cors")
+  .settings(
+    name := "pekko-http-cors")
+  .settings(commonSettings)
+  .settings(AutomaticModuleName.settings("pekko.http.cors"))
+  .addPekkoModuleDependency("pekko-stream", "provided")
+  .addPekkoModuleDependency("pekko-stream-testkit", "provided")
+  .settings(Dependencies.httpCors)
+  .dependsOn(http, httpCore, httpTestkit % "test")
+  .enablePlugins(BootstrapGenjavadoc)
+
 def project(moduleName: String) =
   Project(id = moduleName, base = file(moduleName)).settings(
     name := s"pekko-$moduleName")
@@ -389,7 +401,7 @@ lazy val docs = project("docs")
   .addPekkoModuleDependency("pekko-stream-testkit", "provided", PekkoDependency.docs)
   .addPekkoModuleDependency("pekko-actor-testkit-typed", "provided", PekkoDependency.docs)
   .dependsOn(
-    httpCore, http, httpXml, http2Tests, httpMarshallersJava, httpMarshallersScala, httpCaching,
+    httpCore, http, httpXml, http2Tests, httpMarshallersJava, httpMarshallersScala, httpCaching, httpCors,
     httpTests % "compile;test->test", httpTestkit % "compile;test->test", httpScalafixRules % ScalafixConfig)
   .settings(Dependencies.docs)
   .settings(

docs/src/main/paradox/common/cors.md

@@ -0,0 +1,108 @@
+# Cors
+
+Apache Pekko HTTP's cors module provides support for the [W3C cors standard](https://www.w3.org/TR/cors/)
+
+## Dependency
+
+To use Apache Pekko HTTP Cors, add the module to your project:
+
+@@dependency [sbt,Gradle,Maven] {
+bomGroup2="org.apache.pekko" bomArtifact2="pekko-http-bom_$scala.binary.version$" bomVersionSymbols2="PekkoHttpVersion"
+symbol="PekkoHttpVersion"
+value="$project.version$"
+group="org.apache.pekko"
+artifact="pekko-http-cors_$scala.binary.version$"
+version="PekkoHttpVersion"
+}
+
+## Quick Start
+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 your overrides loaded from the `application.conf`.
+
+@@@ div { .group-scala }
+```scala
+import org.apache.pekko.http.cors.scaladsl.CorsDirectives._
+
+val route: Route = cors() {
+  complete(...)
+}
+```
+@@@
+@@@ div { .group-java }
+```java
+import static org.apache.pekko.http.cors.javadsl.CorsDirectives.*;
+
+final Route route = cors(() -> {
+    complete(...)
+})
+```
+@@@
+
+The settings can be updated programmatically too.
+@@@ div { .group-scala }
+```scala
+val settings = CorsSettings(...).withAllowGenericHttpRequests(false)
+val strictRoute: Route = cors(settings) {
+  complete(...)
+}
+```
+@@@
+@@@ div { .group-java }
+```java
+final CorsSettings settings = CorsSettings.create(...).withAllowGenericHttpRequests(false);
+final Route route = cors(settings, () -> {
+    complete(...)
+});
+```
+@@@
+
+## Rejection
+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 pekko documentation (link TODO) to learn more about rejections, or if you need to write your own handler.
+
+Scala
+:   @@snip [CorsServerExample.scala](/docs/src/test/scala/docs/http/scaladsl/server/cors/CorsServerExample.scala) { #cors-server-example }
+
+Java
+:   @@snip [CorsServerExample.java](/docs/src/test/java/docs/http/javadsl/server/cors/CorsServerExample.java) { #cors-server-example }
+
+#### allowGenericHttpRequests / getAllowGenericHttpRequests
+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.
+
+#### allowCredentials / getAllowCredentials
+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.
+
+#### allowedOrigins / getAllowedOrigins
+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 in `Access-Control-Allow-Origin`.
+* otherwise, the origins given in the `Origin` request header are echoed.
+
+Hostname starting with `*.` will match any sub-domain. The scheme and the port are always strictly matched.
+
+The actual or preflight request is rejected if any of the origins from the request is not allowed.
+
+#### allowedHeaders / getAllowedHeaders
+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 from `Access-Control-Request-Headers` are echoed.
+* otherwise the parameter list is returned as part of the header.
+
+#### allowedMethods / getAllowedMethods
+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.
+
+#### exposedHeaders / getAllowedMethods
+List of headers (other than [simple response headers](https://www.w3.org/TR/cors/#simple-response-header)) 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.
+
+#### maxAge / getMaxAge
+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 @scala[`None`]@java[`OptionalLong.empty()`], the header is not added to the preflight response.
+
+## Benchmarks
+
+Benchmarks for Apache Pekko cors are located within the @github[http-bench-jmh project](/http-bench-jmh/src/main/scala/org/apache/pekko/http/cors/CorsBenchmark.scala) along with
+@github[instructions](/http-bench-jmh/README.md) on how to run them.
+
+Please look at the original project [Akka Http Cors](https://github.com/lomigmegard/akka-http-cors) for previous benchmarks with Akka Http.

docs/src/main/paradox/common/index.md

@@ -20,5 +20,6 @@ which are specific to one side only.
 * [xml-support](sse-support.md)
 * [timeouts](timeouts.md)
 * [caching](caching.md)
+* [cors](cors.md)
 
 @@@

docs/src/main/paradox/configuration.md

@@ -15,4 +15,7 @@ pekko-http
 pekko-http-caching
 :  @@snip [reference.conf](/http-caching/src/main/resources/reference.conf)
 
+pekko-http-cors
+:  @@snip [reference.conf](/http-cors/src/main/resources/reference.conf)
+
 The other Apache Pekko HTTP modules do not offer any configuration via [Typesafe Config](https://github.com/lightbend/config).

docs/src/main/paradox/migration-guide/index.md

@@ -11,3 +11,8 @@
 * Where class names have "Akka" in the name, the Pekko ones have "Pekko" - e.g. PekkoException instead of AkkaException
 * Configs in `application.conf` use "pekko" prefix instead of "akka"
 * We will soon provide a more detailed guide for migrating from Akka HTTP v10.2 to Apache Pekko HTTP
+* If you happen to be using [akka-http-cors](https://github.com/lomigmegard/akka-http-cors) this has been directly integrated into
+  Apache Pekko Http which means you should use the @ref:[pekko-http-cors artifact](../common/cors.md) instead. Note that the root configuration naming 
+  has also been updated (i.e. changing from `akka-http-cors` to `pekko.http.cors`) to make it consistent with the rest of Apache Pekko Http.
+  * In addition there is a single breaking change, the return type of the `org.apache.pekko.http.cors.javadsl.settings.CorsSettings.getMaxAge`
+  method has been changed from `java.util.Optional<Long>` to `java.util.OptionalLong` since it's more idiomatic.

docs/src/test/java/docs/http/javadsl/server/cors/CorsServerExample.java

@@ -0,0 +1,82 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package docs.http.javadsl.server.cors;
+
+// #cors-server-example
+import org.apache.pekko.http.javadsl.model.StatusCodes;
+import org.apache.pekko.http.javadsl.server.*;
+
+import java.util.NoSuchElementException;
+import java.util.concurrent.ExecutionException;
+import java.util.function.Function;
+import java.util.function.Supplier;
+
+import static org.apache.pekko.http.cors.javadsl.CorsDirectives.cors;
+import static org.apache.pekko.http.cors.javadsl.CorsDirectives.corsRejectionHandler;
+
+public class CorsServerExample extends HttpApp {
+
+  public static void main(String[] args) throws ExecutionException, InterruptedException {
+    final CorsServerExample app = new CorsServerExample();
+    app.startServer("127.0.0.1", 9000);
+  }
+
+  protected Route routes() {
+
+    // Your CORS settings are loaded from `application.conf`
+
+    // Your rejection handler
+    final RejectionHandler rejectionHandler =
+        corsRejectionHandler().withFallback(RejectionHandler.defaultHandler());
+
+    // Your exception handler
+    final ExceptionHandler exceptionHandler =
+        ExceptionHandler.newBuilder()
+            .match(
+                NoSuchElementException.class,
+                ex -> complete(StatusCodes.NOT_FOUND, ex.getMessage()))
+            .build();
+
+    // Combining the two handlers only for convenience
+    final Function<Supplier<Route>, Route> handleErrors =
+        inner ->
+            Directives.allOf(
+                s -> handleExceptions(exceptionHandler, s),
+                s -> handleRejections(rejectionHandler, s),
+                inner);
+
+    // Note how rejections and exceptions are handled *before* the CORS directive (in the inner
+    // route).
+    // This is required to have the correct CORS headers in the response even when an error occurs.
+    return handleErrors.apply(
+        () ->
+            cors(
+                () ->
+                    handleErrors.apply(
+                        () ->
+                            concat(
+                                path("ping", () -> complete("pong")),
+                                path(
+                                    "pong",
+                                    () ->
+                                        failWith(
+                                            new NoSuchElementException(
+                                                "pong not found, try with ping")))))));
+  }
+}
+// #cors-server-example

docs/src/test/scala/docs/http/scaladsl/server/cors/CorsServerExample.scala

@@ -0,0 +1,62 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package docs.http.scaladsl.server.cors
+
+// #cors-server-example
+import org.apache.pekko
+import pekko.http.scaladsl.model.StatusCodes
+import pekko.http.scaladsl.server._
+
+object CorsServerExample extends HttpApp {
+  def main(args: Array[String]): Unit = {
+    CorsServerExample.startServer("127.0.0.1", 9000)
+  }
+
+  protected def routes: Route = {
+    import pekko.http.cors.scaladsl.CorsDirectives._
+
+    // Your CORS settings are loaded from `application.conf`
+
+    // Your rejection handler
+    val rejectionHandler = corsRejectionHandler.withFallback(RejectionHandler.default)
+
+    // Your exception handler
+    val exceptionHandler = ExceptionHandler { case e: NoSuchElementException =>
+      complete(StatusCodes.NotFound -> e.getMessage)
+    }
+
+    // Combining the two handlers only for convenience
+    val handleErrors = handleRejections(rejectionHandler) & handleExceptions(exceptionHandler)
+
+    // Note how rejections and exceptions are handled *before* the CORS directive (in the inner route).
+    // This is required to have the correct CORS headers in the response even when an error occurs.
+    handleErrors {
+      cors() {
+        handleErrors {
+          path("ping") {
+            complete("pong")
+          } ~
+          path("pong") {
+            failWith(new NoSuchElementException("pong not found, try with ping"))
+          }
+        }
+      }
+    }
+  }
+}
+// #cors-server-example