From 0a5ae531a4059a5be4a4b87387fb87d1387a3334 Mon Sep 17 00:00:00 2001
From: Laurence Isla <lau.isla.c@gmail.com>
Date: Wed, 21 Sep 2022 19:09:50 -0500
Subject: [PATCH] Add information on preflight requests in CORS subsection

---
 docs/api.rst   | 30 ++++++++++++++++++++++++++++++
 postgrest.dict |  1 +
 2 files changed, 31 insertions(+)

diff --git a/docs/api.rst b/docs/api.rst
index 89a48524c..8638445b7 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -2705,6 +2705,36 @@ CORS
 
 PostgREST sets highly permissive cross origin resource sharing, that is why it accepts Ajax requests from any domain.
 
+It also handles `preflight requests <https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request>`_ done by the browser, which are cached using the returned ``Access-Control-Max-Age: 86400`` header (86400 seconds = 24 hours). This is useful to reduce the latency of the subsequent requests.
+
+A ``POST`` preflight request would look like this:
+
+.. tabs::
+
+  .. code-tab:: http
+
+     OPTIONS /items HTTP/1.1
+     Origin: http://example.com
+     Access-Control-Allow-Method: POST
+     Access-Control-Allow-Headers: Content-Type
+
+  .. code-tab:: bash Curl
+
+     curl -i "http://localhost:3000/items" \
+       -X OPTIONS \
+       -H "Origin: http://example.com" \
+       -H "Access-Control-Request-Method: POST" \
+       -H "Access-Control-Request-Headers: Content-Type"
+
+.. code-block:: http
+
+  HTTP/1.1 200 OK
+  Access-Control-Allow-Origin: http://example.com
+  Access-Control-Allow-Credentials: true
+  Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE, OPTIONS, HEAD
+  Access-Control-Allow-Headers: Authorization, Content-Type, Accept, Accept-Language, Content-Language
+  Access-Control-Max-Age: 86400
+
 .. _multiple-schemas:
 
 Switching Schemas
diff --git a/postgrest.dict b/postgrest.dict
index 2105b5839..39588be67 100644
--- a/postgrest.dict
+++ b/postgrest.dict
@@ -127,6 +127,7 @@ PostgREST
 postgrest
 PostgREST's
 pre
+preflight
 psql
 Qin
 RabbitMQ