Kitura-CORS

Kitura-CORS is a cross-origin resource sharing (CORS) middleware. A webpage or script provided by a service may include references to resources or services hosted by another domain - such as a public service or resource. A browser’s request for such a resource is an example of a cross-origin request, and is typically prohibited under the same-origin security policy.

CORS allows you to bypass the same-origin restriction in a controlled manner, so that resources can be shared between different domains. A CORS-capable client makes a ‘pre-flight’ request to the service hosting the resource at domain B with an Origin header specifying domain A. That service can then respond to the client with an Access-Control-Allow-Origin header which indicates whether access to this resource should be permitted.

You can use CORS middleware in your Kitura application to authorize external services to access resources or APIs that you provide.

Swift version

The latest version of Kitura-CORS requires Swift 4.1.2. You can download this version of the Swift binaries by following this link. Compatibility with other Swift versions is not guaranteed.

Usage

Add dependencies

Add the Kitura-CORS package to the dependencies within your application’s Package.swift file. Substitute "x.x.x" with the latest Kitura-CORS release.

.package(url: "https://github.com/Kitura/Kitura-CORS.git", from: "x.x.x")

Add KituraCORS to your target’s dependencies:

.target(name: "example", dependencies: ["KituraCORS"]),

Import package

import KituraCORS

Using Kitura-CORS

To create an instance of Kitura-CORS middleware use:

public init(options : Options)

where possible Options are:

• allowedOrigin - an enum that configures the Access-Control-Allow-Origin CORS server response header. Possible values are:
  • all - all origins are allowed. Access-Control-Allow-Origin will be set to *. This is the default.
  • sameAsOrigin - Access-Control-Allow-Origin will be set to Origin from RouterRequest header.
  • set - a set of allowed origins.
  • origin - a single allowed origin.
  • regex - a regular expression that defines allowed origins.
• credentials - a boolean value that indicates whether to set the Access-Control-Allow-Credentials CORS header. The header is set only if credentials is true, otherwise the header is not passed. Defaults to false.
• methods - an array of methods to be passed in the Access-Control-Allow-Methods header. The default set of methods to be passed is ["GET","HEAD","PUT","PATCH","POST","DELETE"].
• allowedHeaders - an array of allowed headers to configure the Access-Control-Allow-Headers CORS header. If not specified, the headers specified in the request’s Access-Control-Request-Headers header are passed.
• maxAge - an integer to set the Access-Control-Allow-Max-Age header. If not set, the header is omitted.
• exposedHeaders - an array of exposed headers to configure the Access-Control-Expose-Headers header. If not set, the header is omitted.
• preflightContinue - a boolean indicating whether a CORS preflight request should be passed on to route handlers to further customize the response. Defaults to false, meaning that the CORS middleware will send an appropriate response back to the client immediately.

Please see the CORS documentation for more information about CORS.

Example

First create an instance of CORS. In the following example, the resource author has a resource which they would like http://www.abc.com to be able to access. Only the methods GET and PUT can be used in the actual request, the response can be cached for 5 seconds and only the Content-Type header will be used in the actual request:

import Kitura
import KituraCORS

let options = Options(allowedOrigin: .origin("http://www.abc.com"),
                      methods: ["GET","PUT"],
                      allowedHeaders: ["Content-Type"],
                      maxAge: 5)

let cors = CORS(options: options)

Kitura-CORS implements the RouterMiddleware protocol; therefore to connect the middleware to your path you need to use one of the Router methods, for example:

let router = Router()
router.all("/cors", middleware: cors)

API Documentation

For more information visit our API reference.

Community

We love to talk server-side Swift, and Kitura. Join our Slack to meet the team!

License

This library is licensed under Apache 2.0. Full license text is available in LICENSE.