///////////////////////////////////////////////////////////////////////////////
    Copyright (c) 2020 Oracle and/or its affiliates.

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

///////////////////////////////////////////////////////////////////////////////


//Contains content that is shared between multiple CORS pages.
:keywords: helidon, java, cors, se
:helidon-tag: https://github.com/oracle/helidon/tree/{helidon-version}
:quickstart-example: {helidon-tag}/examples/quickstarts/helidon-quickstart-se
:cors-spec: https://www.w3.org/TR/cors/
:helidon-se-cors-example: {helidon-tag}/examples/cors
:helidon-tag: https://github.com/oracle/helidon/tree/{helidon-version}
:quickstart-example: {helidon-tag}/examples/quickstarts/helidon-quickstart-se
:javadoc-base-url-api: {javadoc-base-url}io.helidon.webserver.cors/io/helidon/webserver/cors
:javadoc-base-url-webserver: {javadoc-base-url}io.helidon.webserver/io/helidon/webserver
:helidon-variant: SE
:common-page-prefix-inc:
:actual-cors-dependency-src:

= CORS Shared content

// tag::cors-intro[]
The CORS protocol helps developers control if and how REST resources served by their applications can be shared across origins.
Helidon {helidon-variant} includes an implementation of CORS that you can use to add CORS behavior
to the services you develop. You can define your application's CORS behavior programmatically using the Helidon CORS API alone, or
together with configuration. Helidon also provides three built-in services that add their
own endpoints to your application - health, metrics, and OpenAPI - that have integrated CORS support.
By adding very little code to your application, you control how all the resources in
your application -- the ones you write and the ones provided by the Helidon built-in services -- can be shared across origins.

== Before You Begin
Before you revise your application to add CORS support, you need to decide what type of cross-origin sharing you want
to allow for each resource your application exposes.
For example, suppose for a given resource you want to allow unrestricted sharing for GET, HEAD, and POST requests
(what CORS refers to as "simple" requests), but permit other types of requests only from the two
origins `foo.com` and `there.com`.
Your application would implement two types of CORS sharing: more relaxed for the
simple requests and stricter for others.

Once you know the type of sharing you want to allow for each of your resources -- including any from built-in
services -- you can change your application accordingly.
// end::cors-intro[]

// The add-cors-dependency tag's contents is reused from other SE and MP pages.
// The actual dependency is different for SE and MP, so we tag it separately from the intro text so the
// MP pages can reuse this intro text but use their own "actual" dependency. We could have parameterized
// the groupID and artifactID but this approach allows the actual dependencies themselves to be
// in the source literally rather than parameterized.
// tag::add-cors-dependency[]
The <<about/04_managing-dependencies.adoc, Managing Dependencies>> page describes how you
should declare dependency management for Helidon applications.
For CORS support in Helidon {helidon-variant}, you must include
the following dependency in your project:
// end::add-cors-dependency[]

//tag::cors-configuration-formats-intro[]
== Understanding the CORS Configuration Formats [[cors-configuration-formats]]
Support in Helidon for CORS configuration uses two closely-related cross-origin configuration formats: basic and mapped.
Each format corresponds to a class
in the Helidon CORS library.
The basic format corresponds to the link:{javadoc-base-url-api}/CrossOriginConfig.html[`CrossOriginConfig`]
class, and the mapped format corresponds to the
link:{javadoc-base-url-api}/MappedCrossOriginConfig.html[`MappedCrossOriginConfig`] class.
//end::cors-configuration-formats-intro[]

//tag::basic-cross-origin-config[]
[[basic-cross-origin-config]]
=== Basic Cross-Origin Configuration
In configuration, Helidon represents basic CORS information as a section, identified by a configuration
key of your choosing, that contains
one or more key/value pairs. Each key-value pair assigns one characteristic of CORS behavior.

[subs=attributes+]
{basic-table-intro}

[[config-key-table]]
include::{common-page-prefix-inc}[tag=cors-config-table]

The following example of basic cross-origin
ifeval::["{helidon-variant}" == "SE"]
configuration, when loaded and used by the application,
endif::[]
ifeval::["{helidon-variant}" != "SE"]
configuration
endif::[]
limits cross-origin resource sharing for `PUT` and
`DELETE` operations to only `foo.com` and `there.com`:

[source,hocon]
----
...
ifeval::["{helidon-variant}" == "SE"]
restrictive-cors:
endif::[]
  allow-origins: ["http://foo.com", "http://there.com"]
  allow-methods: ["PUT", "DELETE"]
...
----
//end::basic-cross-origin-config[]


// The following table is parameterized.
//
// To exclude the first column of the table -- the method or annotation parameter list -- and
// the text that describes it, define the cors-config-table-exclude-methods attribute in the including file.
// The value does not matter.
//
// To exclude the second column -- the config keys -- and the text that describes it, define
// cors-config-table-exclude-keys in the including file. The value does not matter.
//
// To customize the text that explains the first column, set config-table-methods-column-explainer
// to the text you want inserted.
//
// To customize the column heading for the first column, set config-table-methods-column-header to
// the header you want used.
//
// tag::cors-config-table[]

ifndef::cors-config-table-exclude-methods+cors-config-table-exclude-keys[]
[width="100%",options="header",cols="4*"]
endif::[]
ifdef::cors-config-table-exclude-methods[]
[width="100%",options="header",cols="3*"]
endif::[]
ifdef::cors-config-table-exclude-keys[]
[width="100%",options="header",cols="3*"]
endif::[]

|====================
ifndef::cors-config-table-exclude-methods[| {config-table-methods-column-header} ]
ifndef::cors-config-table-exclude-keys[| Configuration Key]
| Default | CORS Header Name

ifndef::cors-config-table-exclude-methods[|`allowCredentials`]
ifndef::cors-config-table-exclude-keys[|`allow-credentials`]
|`false`|`Access-Control-Allow-Credentials`

ifndef::cors-config-table-exclude-methods[|`allowHeaders`]
ifndef::cors-config-table-exclude-keys[|`allow-headers`]
|`["*"]`|`Access-Control-Allow-Headers`

ifndef::cors-config-table-exclude-methods[|`allowMethods`]
ifndef::cors-config-table-exclude-keys[|`allow-methods`]
|`["*"]`|`Access-Control-Allow-Methods`

ifndef::cors-config-table-exclude-methods[|`allowOrigins`]
ifndef::cors-config-table-exclude-keys[|`allow-origins`]
|`["*"]`|`Access-Control-Allow-Origins`

ifndef::cors-config-table-exclude-methods[|`exposeHeaders`]
ifndef::cors-config-table-exclude-keys[|`expose-headers`]
|`none`|`Access-Control-Expose-Headers`

ifndef::cors-config-table-exclude-methods[|`maxAgeSeconds`]
ifndef::cors-config-table-exclude-keys[|`max-age`]
|`3600`|`Access-Control-Max-Age`

ifndef::cors-config-table-exclude-methods[|`enabled`]
ifndef::cors-config-table-exclude-keys[|`enabled`]
|`true`|n/a|
|====================

If the cross-origin configuration is disabled (`enabled` = false), then the Helidon CORS implementation ignores the cross-origin configuration entry.
// end::cors-config-table[]

// tag::mapped-config[]
// tag::mapped-config-prefix[]
Helidon represents mapped CORS information as a section, identified by a configuration
key of your choosing, that contains:

* An optional `enabled` setting which defaults to `true` and applies to the whole mapped CORS config section, and

* An optional `paths` subsection containing zero or more entries, each of which contains:

** a basic CORS config section, and

** a `path-pattern` path pattern that maps that basic CORS config section to the resource(s) it affects.

You can use mapped configuration to your advantage if you want to allow your users to override the CORS behavior set up
in the application code.

The following example illustrates the mapped cross-origin configuration format.

[source,hocon,subs="attributes+"]
----
...
{mapped-config-top-key}: <1>
  paths: <2>
    - path-pattern: /greeting <3>
      allow-origins: ["http://foo.com", "http://there.com", "http://other.com"] <4>
      allow-methods: ["PUT", "DELETE"]
    - path-pattern: / <5>
      allow-methods: ["GET", "HEAD", "OPTIONS", "POST"] <6>
...
----
// We want to use the following to insert the SE or MP callout 1 text; we need to use the blank, plus,
// and subs because the MP attribute value contains backticks, and this is the only way we've found
// for the substitution in the callout to work the way we want. And this works when
// rendered in our editing tools and via the asciidoctor command to HTML but not on our built site.
//
// <1> {blank}
// +
// [subs=attributes+]
// {mapped-config-id-callout}
//
// So instead we have the prefix and suffix tags and the including document provides its own callout 1.
// If at some point the rendering for our site handles this, we can just remove the tag and end
// for the prefix and suffix and just have the including file include the mapped-config instead of
// include the prefix, then provide its own callout 1, then include the suffix.
//
// end::mapped-config-prefix[]

// tag::mapped-config-suffix[]
<2> Collects the sequence of entries, each of which maps a basic CORS config to a path pattern.
<3> Marks the beginning of an entry (the `-` character) and maps the associated basic CORS config
to the `/greeting` subresource (the `path-pattern` key and value).
<4> Begins the basic CORS config section for `/greeting`; it
restricts sharing via `PUT` and `DELETE` to the listed origins.
<5> Marks the beginning of the next entry (the `-` character) and maps the associated basic CORS config to
the top-level resource in the app (the `path-pattern` key and value).
<6> Begins the basic CORS config section for `/`; it permits sharing of resources at the top-level path with all origins
for the indicated HTTP methods.

Path patterns can be any expression accepted by the link:{javadoc-base-url-webserver}/PathMatcher.html[`PathMatcher`] class.

NOTE: Be sure to arrange the entries in the order that you want Helidon to check them.
Helidon CORS support searches the cross-origin entries in the order you define them until it finds an entry that
matches an incoming request's path pattern and HTTP method.

// end::mapped-config-suffix[]
// end::mapped-config[]

// tag::understanding-cors-support-in-services[]
== Understanding CORS Support in Helidon Services
Helidon lets you easily include <<{health-page},health>>, <<{metrics-page},metrics>>, and
<<{openapi-page},OpenAPI>> services in your Helidon application.
These services add endpoints to your application so that clients can retrieve information about it.
As with the application endpoints you write, these endpoints represent resources that can be shared across origins.

For example, several websites related to OpenAPI run a web application in your browser.
You provide the URL for your application to the browser application.
The browser application uses the URL to retrieve the OpenAPI document
that describes the application's endpoints directly from your application.
The browser application then displays a user interface that you use to "drive" your application. That is,
you provide input, have the web application
send requests to your application endpoints, and then view the responses.
This scenario is exactly the situation CORS addresses: an application in the browser from one origin -- the user interface downloaded from the
website -- requests a resource from another origin -- the `/openapi` endpoint which Helidon's OpenAPI built-in
service automatically adds to your application.

Integrating CORS support into these built-in services allows such third-party web sites and their browser applications -- or
more generally, apps from any other origin -- to work with your Helidon application.

Because all three of these built-in Helidon services serve only `GET` endpoints, by default the
integrated CORS support in all three services permits
any origin to share their resources using `GET`, `HEAD`, and `OPTIONS` HTTP requests. You can customize the CORS set-up
for these built-in services independently from each other using
ifdef::cors-services-is-se[ either the Helidon API, configuration, or both.]
ifndef::cors-services-is-se[ configuration.]
You can use this override feature to control the CORS behavior of the built-in services even if you do not add CORS behavior
to your own endpoints.

// end::understanding-cors-support-in-services[]

// tag::builtin-getting-started[]
== Getting Started
To use built-in services with CORS support and customize the
CORS behavior:

. Add the built-in service or services to your application. The health, metrics, and OpenAPI services automatically
include default CORS support.
. {blank}
+
--
Add a dependency on the Helidon {helidon-variant} CORS artifact to your Maven `pom.xml` file.

NOTE: If you want the built-in services to support CORS, then you need to add the CORS dependency even if your own endpoints do not use CORS.

include::{common-page-prefix-inc}[tag=add-cors-dependency]
include::{actual-cors-dependency-src}[tag=actual-cors-dependency]
--
. Use
ifdef::cors-services-is-se[the Helidon API or]
configuration to customize the CORS behavior as needed.

The documentation for the individual built-in services describes how to add each
service to your application, including
adding a Maven
ifdef::cors-services-is-se[dependency and including the service in your application's routing rules.]
ifndef::cors-services-is-se[dependency.]
In your
application's configuration file, the configuration for each service appears under its own key.
|====
| Helidon Service Documentation | Configuration Key

| <<{health-page}, health>> | `health`
| <<{metrics-page}, metrics>> | `metrics`
| <<{openapi-page}, OpenAPI>> | `openapi`
|====

The link:{quickstart-example}[Helidon {helidon-variant} QuickStart example]
uses these services, so you can use that as a template for your
own application, or use the example project itself to experiment with customizing the CORS
behavior in the built-in services.
// end::builtin-getting-started[]

// tag::configuring-cors-for-builtin-services[]
== Configuring CORS for Built-in Services
You can
ifdef::cors-services-is-se[also ]
use configuration to control whether and how each of the built-in services works with CORS.

ifdef::cors-services-is-se[]
Your application can pass configuration to the builder for each built-in service.
endif::[]
For the health, metrics, and OpenAPI services, your configuration can include a section for CORS.

// Tag the following example so we can exclude it from MP which supplies its own complete example.
// tag::se-config-example[]
The following example restricts sharing of the
`/health` resource, provided by the health built-in service, to only the origin `\http://there.com`.
[source,hocon]
----
...
health:
  cors:
    allow-origins: [http://there.com]
...
----

// end::se-config-example[]

// tag::se-code-changes-for-builtin-services-config[]
Modify your application to load the `health` config node and use it to construct the `HealthSupport` service.
The following code shows this change in the the QuickStart SE example.
[source,java]
----
HealthSupport health = HealthSupport.builder()
        .config(config.get("health")) // <1>
        .addLiveness(HealthChecks.healthChecks())   // Adds a convenient set of checks
        .build();
----
<1> Use the `health` config section (if present) to configure the health service.

// end::se-code-changes-for-builtin-services-config[]

You have full control over the CORS configuration for a built-in Helidon service. Use a basic CORS config section
as described in
ifdef::cors-services-is-se[<<se/cors/03_using-configuration.adoc,Using Configuration for CORS>>.]
ifndef::cors-services-is-se[<<{mp-cors-config-ref},Using Configuration with CORS in Helidon MP>>.]


// end::configuring-cors-for-builtin-services[]

// tag::accessing-shared-resources-intro[]
== Accessing the Shared Resources
If you have edited the Helidon {helidon-variant} QuickStart application as described in the previous topics and saved your changes,
you can build and run the application. Once you do so you can execute `curl` commands to demonstrate the behavior changes
in the metric and health services with the addition of the CORS functionality. Note the addition of the
`Origin` header value in the `curl` commands, and the `Access-Control-Allow-Origin` in the successful responses.

=== Build and Run the Application
Build and run the QuickStart application as usual.
// end::accessing-shared-resources-intro[]

// tag::accessing-shared-resources-main[]
=== Retrieve Metrics
The metrics service rejects attempts to access metrics on behalf of a disallowed origin.
[source,bash]
----
curl -i -H "Origin: http://other.com" http://localhost:8080/metrics

HTTP/1.1 403 Forbidden
Date: Mon, 11 May 2020 11:08:09 -0500
transfer-encoding: chunked
connection: keep-alive
----

But accesses from `foo.com` succeed.
[source,bash]
----
curl -i -H "Origin: http://foo.com" http://localhost:8080/metrics

HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://foo.com
Content-Type: text/plain
Date: Mon, 11 May 2020 11:08:16 -0500
Vary: Origin
connection: keep-alive
content-length: 6065

# TYPE base_classloader_loadedClasses_count gauge
# HELP base_classloader_loadedClasses_count Displays the number of classes that are currently loaded in the Java virtual machine.
base_classloader_loadedClasses_count 3568
...
----

=== Retrieve Health
The health service rejects requests from origins not specifically approved.

[source,bash]
----
curl -i -H "Origin: http://foo.com" http://localhost:8080/health

HTTP/1.1 403 Forbidden
Date: Mon, 11 May 2020 12:06:55 -0500
transfer-encoding: chunked
connection: keep-alive
----

And responds successfully only to cross-origin requests from `\http://there.com`.

[source,bash]
----
curl -i -H "Origin: http://there.com" http://localhost:8080/health

HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://there.com
Content-Type: application/json
Date: Mon, 11 May 2020 12:07:32 -0500
Vary: Origin
connection: keep-alive
content-length: 461

{"outcome":"UP",...}
----
// end::accessing-shared-resources-main[]
