README

@whook/cors

A wrapper to provide CORS support to a Whook server

This Whook wrapper provides CORS support by adding it to your OpenAPI file and creating the handlers that runs the OPTIONS method when you cannot do it at the proxy/gateway level.

Usage

To use this module, simply add it to your WRAPPERS service (usually in src/services/WRAPPERS.ts):

import { service } from 'knifecycle';
+ import { wrapHandlerWithCors } from '@whook/cors';
import type { WhookWrapper } from '@whook/whook';

export default service(initWrappers, 'WRAPPERS');

async function initWrappers(): Promise<WhookWrapper<any, any>[]> {
-  const WRAPPERS = [];
+  const WRAPPERS = [wrapHandlerWithCors];

  return WRAPPERS;
}

And add the CORS config (usually in src/config/common/config.js):

+ import type {
+   CORSConfig,
+   WhookAPIOperationCORSConfig,
+ } from '@whook/cors';

// ...

export type AppConfigs = WhookConfigs &
+  CORSConfig &
  APIConfig;

const CONFIG: AppConfigs = {
  // ...
+   CORS: {
+     'Access-Control-Allow-Origin': '*',
+     'Access-Control-Allow-Methods': 'GET,POST,PUT,DELETE,OPTIONS',
+     'Access-Control-Allow-Headers': [
+       'Accept',
+       'Accept-Encoding',
+       'Accept-Language',
+       'Referrer',
+       'Content-Type',
+       'Content-Encoding',
+       'Authorization',
+       'Keep-Alive',
+       'User-Agent',
+     ].join(','),
+   },
};

// Export custom handlers definitions
export type APIHandlerDefinition = WhookAPIHandlerDefinition<
+  WhookAPIOperationCORSConfig &
  WhookAPIOperationSwaggerConfig
>;

export default CONFIG;

You should also use the wrapped error handler:

+ import { initErrorHandlerWithCORS } from '@whook/cors';

// ...

export async function prepareEnvironment<T extends Knifecycle<Dependencies>>(
    $: T = new Knifecycle() as T,
  ): Promise<T> {

//...

+  // Add the CORS wrapped error handler
+  $.register(initErrorHandlerWithCORS);

  return $;
}

Alternatively, you could wrape your custom error handler with the `wrap

Finally, you must adapt the API service to handle CORS options:

+ import { augmentAPIWithCORS } from '@whook/cors';

// (...)

export default name('API', autoService(initAPI));

// The API service is where you put your handlers
// altogether to form the final API
async function initAPI({
// (..)
) {

  // (..)

  // You can apply transformations to your API like
  // here for CORS support (OPTIONS method handling)
-  return augmentAPIWithFakeAuth({ ENV }, API);
+  return augmentAPIWithCORS(await augmentAPIWithFakeAuth({ ENV }, API));
}

To see a real example have a look at the @whook/example.

API

Members

_default ⇒ Promise.<Object>: A simple Whook handler that just returns a 200 OK HTTP response

Functions

wrapHandlerWithCORS(initHandler) ⇒ function: Wrap an handler initializer to append CORS to response.
augmentAPIWithCORS(API) ⇒ Promise.<Object>: Augment an OpenAPI to also serve OPTIONS methods with the CORS added.

_default ⇒ `Promise.<Object>`

A simple Whook handler that just returns a 200 OK HTTP response

Kind: global variable
Returns: Promise.<Object> - The HTTP response object

wrapHandlerWithCORS(initHandler) ⇒ `function`

Wrap an handler initializer to append CORS to response.

Kind: global function
Returns: function - The handler initializer wrapped

Param	Type	Description
initHandler	`function`	The handler initializer

augmentAPIWithCORS(API) ⇒ `Promise.<Object>`

Augment an OpenAPI to also serve OPTIONS methods with the CORS added.

Kind: global function
Returns: Promise.<Object> - The augmented OpenAPI object

Param	Type	Description
API	`Object`	The OpenAPI object

Authors

Nicolas Froidure

License

MIT

Usage no npm install needed!