@goa/cors

@goa/cors is Cross-Origin Resource Sharing (CORS) For Goa.

yarn add @goa/cors

Table Of Contents

• Table Of Contents
• API
• cors(config=: !CorsConfig): !Middleware
  • CorsConfig
• Usage Events
• Copyright & License

API

The package is available by importing its default function:

import cors from '@goa/cors'

cors(
  config=: !CorsConfig,
): !Middleware

Cross-Origin Resource Sharing (CORS) For Goa.

• config !CorsConfig (optional): The config.

CorsConfig: Options for the program.

Name	Type & Description	Default
origin	(string | function(!Context))	-
	Access-Control-Allow-Origin header, default is taken from the Origin request header.
allowMethods	(string | !Array<string>)	GET,HEAD,PUT,POST,DELETE,PATCH
	Access-Control-Allow-Methods header.
exposeHeaders	(string | !Array<string>)	-
	Access-Control-Expose-Headers header.
allowHeaders	(string | !Array<string>)	-
	Access-Control-Allow-Headers header.
maxAge	(string | number)	-
	Access-Control-Max-Age header in seconds.
credentials	boolean	false
	Access-Control-Max-Age header in seconds.
keepHeadersOnError	boolean	true
	Add set headers to err.header if an error is thrown.

There are 3 main use cases:

1. Accept any origin form the client

import Goa from '@goa/koa'
import { aqt } from 'rqt'
import cors from '@goa/cors'

const goa = new Goa()
goa.use(cors())

goa.listen(async function() {
  const { port } = this.address()
  const url = `http://localhost:${port}`

  // 1. accept origin from the host
  const { headers } = await aqt(url, {
    headers: {
      origin: 'www.example.com',
    },
  })
  console.log(headers)
  this.close()
})

{ vary: 'Origin',
  'access-control-allow-origin': 'www.example.com',
  'content-type': 'text/plain; charset=utf-8',
  'content-length': '9',
  date: 'Thu, 09 Jan 2020 14:43:05 GMT',
  connection: 'close' }

2. Send out only specific origin

import Goa from '@goa/koa'
import { aqt } from 'rqt'
import cors from '@goa/cors'

const goa = new Goa()
goa.use(cors({
  origin: 'www.hello-world.com',
}))

goa.listen(async function() {
  const { port } = this.address()
  const url = `http://localhost:${port}`

  // 2. only serve specific origin
  const { headers } = await aqt(url, {
    headers: {
      origin: 'www.example.com',
    },
  })
  console.log(headers)
  this.close()
})

{ vary: 'Origin',
  'access-control-allow-origin': 'www.hello-world.com',
  'content-type': 'text/plain; charset=utf-8',
  'content-length': '9',
  date: 'Thu, 09 Jan 2020 14:43:05 GMT',
  connection: 'close' }

3. Pre-flight Requests Via OPTIONS (both above apply)

import Goa from '@goa/koa'
import { aqt } from 'rqt'
import cors from '@goa/cors'

const goa = new Goa()
goa.use(cors({
  origin: 'www.hello-world.com',
  credentials: true,
  maxAge: 1000,
  allowMethods: ['POST', 'PUT'],
}))

goa.listen(async function() {
  const { port } = this.address()
  const url = `http://localhost:${port}`

  // 3. respond to pre-flight request
  const { statusCode, headers } = await aqt(url, {
    method: 'OPTIONS',
    headers: {
      'Access-Control-Request-Method': 'POST',
      origin: 'www.example.com',
    },
  })
  console.log(statusCode, headers)
  this.close()
})

204 { vary: 'Origin',
  'access-control-allow-origin': 'www.hello-world.com',
  'access-control-allow-credentials': 'true',
  'access-control-max-age': '1000',
  'access-control-allow-methods': 'POST,PUT',
  date: 'Thu, 09 Jan 2020 14:43:05 GMT',
  connection: 'close' }

Usage Events

This middleware integrates with Idio that collects middleware usage statistics to reward package maintainers. It will emit certain events to bill its usage:

1. headers: When setting the headers if origin was present.
2. options: When responding to pre-flight requests via the OPTIONS http method.

The usage is recorded via the ctx.neoluddite context property set by a server such as Idio. In future, more fine-grained usage events might appear.

Copyright & License

GNU Affero General Public License v3.0

Affero GPL means that you're not allowed to use this middleware on the web unless you release the source code for your application. This is a restrictive license which has the purpose of defending Open Source work and its creators.

Please refer to the Idio license agreement for more info on dual-licensing. You're allowed to use this middleware without disclosing the source code if you sign up on neoluddite.dev package reward scheme.

Original Work by dead-horse & contributors licensed under MIT found in COPYING.

© Idio 2020