add documentation for server-cors-allowed-origins config (#688)

docs/references/api/cors.rst

@@ -1,7 +1,10 @@
+.. _cors:
+
 CORS
-====
+####
+
+By default, PostgREST sets highly permissive cross origin resource sharing, that is why it accepts Ajax requests from any domain. This behavior can be configured by using :ref:`server_cors_allowed_origins`.
 
-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.
 
@@ -32,3 +35,16 @@ A ``POST`` preflight request would look like this:
   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
+
+.. _allowed_origins:
+
+Allowed Origins
+===============
+
+With the following config setting, PostgREST will accept CORS requests from domains :code:`http://example.com` and :code:`http://example2.com`.
+
+
+.. code-block::
+  
+  server-cors-allowed-origins="http://example.com, http://example2.com"
+

docs/references/configuration.rst

@@ -774,6 +774,23 @@ raw-media-types
 
    raw-media-types="image/png, font/woff2"
 
+.. _server_cors_allowed_origins:
+
+server-cors-allowed-origins
+---------------------------
+
+  =============== ===================================
+  **Type**        String
+  **Default**     `n/a` 
+  **Reloadable**  N
+  **Environment** PGRST_SERVER_CORS_ALLOWED_ORIGINS
+  **In-Database** `pgrst.server_cors_allowed_origins`
+  =============== ===================================
+
+  Specifies allowed CORS origins in this config. See :ref:`cors`.
+
+  When this is not set or set to :code:`""`, PostgREST **accepts** CORS requests from any domain.
+
 .. _server-host:
 
 server-host

postgrest.dict

@@ -22,6 +22,7 @@ coercible
 conf
 Cloudflare
 config
+cors
 CORS
 CPUs
 cryptographically