How to handle HTTP OPTIONS preflight requests (CORS)? about rest-daemon

[colorcube]

Here's a suggestion for CORS documentation

CORS handling

What is CORS?

Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources
to be requested from another domain outside the domain from which the first resource was served.
That means when a client (browser with angular app for example) access the server,
some special headers needs to be sent in the response.
Otherwise the browser will deny to access the server on POST requests for example.

A detailed description what CORS is and how it can be used for access restriction
is out of scope of this document. Please look out for other documentation.

Add CORS header

Use the CORSHeaderSetter middleware to add Access-Control-Allow-Origin header to responses.

TODO provide example script

OPTIONS requests

Before POST requests a browser will send an OPTIONS request in beforhand (preflight).
The response has to be 200 with some special headers.
By default the server will not generate such responses to OPTIONS requests.

Enabling OPTIONS request handling

With RestServerBuilder

When you use RestServerBuilder the easiest way to enable to enable CORS handling is this:

$builder = new RestServerBuilder($di);
$builder->getEndpointFactory()->allowGlobalRequestAllowHeaderReflecting(true);

The RestServerBuilder will generate OPTIONS handler (`OptionsMethodHandler) for every endpoint automatically.

When allowGlobalRequestAllowHeaderReflecting(true) ist not set it can be enabled for endpoints
setting 'allowHeaders' => '*'.

'endpoints' => [
    '/users/{guid}' => [
        'name' => 'users',
        'allowHeaders' => '*'
        'handlers' => [
            'POST' => \Vendor\MyServer\Api\v1\Endpoints\Users\PostHandler::class,
            'GET' => \Vendor\MyServer\Api\v1\Endpoints\Users\GetHandler::class,
        ],
    ],

For more detail you may have a look in EndpointFactory.

Without RestServerBuilder

When you build your endpoints without RestServerBuilder using the api, you have to add OPTIONS
handlers by yourself. You can use the OptionsMethodHandler for that.

TODO provide example script

Markdown

## CORS handling

### What is CORS?

Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources 
to be requested from another domain outside the domain from which the first resource was served. 
That means when a client (browser with angular app for example) access the server, 
some special headers needs to be sent in the response.
Otherwise the browser will deny to access the server on POST requests for example.

A detailed description what CORS is and how it can be used for access restriction 
is out of scope of this document. Please look out for other documentation.


### Add CORS header

Use the `CORSHeaderSetter` middleware to add `Access-Control-Allow-Origin` header to responses.

TODO provide example script

### OPTIONS requests

Before POST requests a browser will send an OPTIONS request in beforhand (preflight). 
The response has to be 200 with some special headers. 
By default the server will not generate such responses to OPTIONS requests.


### Enabling OPTIONS request handling

#### With RestServerBuilder

When you use RestServerBuilder the easiest way to enable to enable CORS handling is this:


    $builder = new RestServerBuilder($di);
    $builder->getEndpointFactory()->allowGlobalRequestAllowHeaderReflecting(true);
 
The `RestServerBuilder` will generate OPTIONS handler (`OptionsMethodHandler) for every endpoint automatically.

When `allowGlobalRequestAllowHeaderReflecting(true)` ist not set it can be enabled for endpoints 
setting `'allowHeaders' => '*'`.

    'endpoints' => [
        '/users/{guid}' => [
            'name' => 'users',
            'allowHeaders' => '*'
            'handlers' => [
                'POST' => \Vendor\MyServer\Api\v1\Endpoints\Users\PostHandler::class,
                'GET' => \Vendor\MyServer\Api\v1\Endpoints\Users\GetHandler::class,
            ],
        ],

For more detail you may have a look in `EndpointFactory`.

#### Without RestServerBuilder

When you build your endpoints without `RestServerBuilder` using the api, you have to add OPTIONS 
handlers by yourself. You can use the `OptionsMethodHandler` for that.

TODO provide example script

[colorcube]

I guess HttpServerConfig::getAllowedOrigins() is meant to be used for something like that?
It seems it is never used.

[colorcube]

Is this helpful?
http://socketo.me/docs/origin
I don't know

[colorcube]

When I hack Ratchet\Http\Router

The request will be handled

        } catch (ResourceNotFoundException $nfe) {
            return $this->close($conn, 200, array(
                'Allow' => 'POST,OPTIONS',
                'Access-Control-Allow-Origin' => '*',
                'Access-Control-Allow-Headers' => 'Origin, X-Requested-With, Content-Type, Accept'
            ));

Of course this make no sense. Just for testing.

I can't find any resource how this is handled in Ratchet or Aerys the proper way. Am I missing something?

[colorcube]

I realized that in v0.10 there is an OPTIONS handler but I had 0.8 installed (rest-auth composer file). Sorry for that.
Although the options handler is registered it's never called and it's still not working. I might have messed up something?!

[colorcube]

I find out that CORS with the OPTIONS handler indeed work, but only with the Aerys driver not with the Ratchet. I'm fine with that.
rest-auth could be updated to prevent confusion.

[samizdam]

Rest-auth now (from v0.1.0) see to rest-daemon master branch for faster development.

I use rest-auth in private project and test it with real browser from another host - in this case CORS and OPTIONS method are used.

Are your issue with CORS can be resolved?

[colorcube]

Yes with latest rest-deamon version everything works as expected when I use the Aerys driver.

It doesn't work with the Ratchet driver. With Ratchet driver I get 404 on OPTIONS requests.

[samizdam]

Good job, @colorcube !

Thank You for contribution

Can you create PR with this changes to master? I will read diff.
I think directory like docs with .md files and hyper-links from README.md is great start point for extended documentation.

And I will try test this behavior with Ratchet driver, for check this behavior. And fix it if possible or submit PR to @cboden