allow session variables in operators which expect array input (#2475)

docs/_static/hasura-custom.css

@@ -104,6 +104,10 @@ ul {
   font-size: 20px !important;
 }
 
+[role="main"] h4 {
+  font-size: 18px !important;
+}
+
 #docs-content,
 #docs-header {
   font-size: 16px !important;

docs/graphql/manual/api-reference/schema-metadata-api/index.rst

@@ -314,4 +314,4 @@ See :doc:`../../deployment/graphql-engine-flags/reference` for info on setting t
   Remote Schemas <remote-schemas>
   Query Collections <query-collections>
   Manage Metadata <manage-metadata>
-  Syntax definitions <syntax-defs>
+  Common syntax definitions <syntax-defs>

docs/graphql/manual/api-reference/schema-metadata-api/syntax-defs.rst

@@ -1,5 +1,5 @@
-Schema/Metadata API reference: Syntax definitions
-=================================================
+Schema/Metadata API Reference: Common syntax definitions
+========================================================
 
 .. contents:: Table of contents
   :backlinks: none
@@ -257,7 +257,7 @@ ColumnExp
 Operator
 ^^^^^^^^
 
-Generic operators (all column types except json, jsonb) :
+**Generic operators (all column types except json, jsonb) :**
 
 - ``"$eq"``
 - ``"$ne"``
@@ -268,7 +268,7 @@ Generic operators (all column types except json, jsonb) :
 - ``"$gte"``
 - ``"$lte"``
 
-Text related operators :
+**Text related operators :**
 
 - ``"$like"``
 - ``"$nlike"``
@@ -277,7 +277,7 @@ Text related operators :
 - ``"$similar"``
 - ``"$nsimilar"``
 
-Operators for comparing columns (all column types except json, jsonb):
+**Operators for comparing columns (all column types except json, jsonb):**
 
 - ``"$ceq"``
 - ``"$cne"``
@@ -286,11 +286,11 @@ Operators for comparing columns (all column types except json, jsonb):
 - ``"$cgte"``
 - ``"$clte"``
 
-Checking for NULL values :
+**Checking for NULL values :**
 
 - ``_is_null`` (takes true/false as values)
 
-JSONB operators :
+**JSONB operators :**
 
 .. list-table::
    :header-rows: 1
@@ -303,8 +303,14 @@ JSONB operators :
      - ``<@``
    * - ``_has_key``
      - ``?``
+   * - ``_has_keys_any``
+     - ``?|``
+   * - ``_has_keys_all``
+     - ``?&``
 
-PostGIS related operators on GEOMETRY columns:
+(For more details on what these operators do, refer to `Postgres docs <https://www.postgresql.org/docs/current/static/functions-json.html#FUNCTIONS-JSONB-OP-TABLE>`__.)
+
+**PostGIS related operators on GEOMETRY columns:**
 
 .. list-table::
    :header-rows: 1

docs/graphql/manual/auth/authorization/roles-variables.rst

@@ -188,11 +188,59 @@ configured authentication to relay this information. We can then check for the f
 the same rule - *is the organization that this repository belongs to part of the list of the organizations the
 user is a member of*.
 
+The permission for ``org-member`` role changes to this:
+
+.. code-block:: json
+
+  {
+    "_or": [
+      {
+        "creator_id": {
+          "_eq": "X-Hasura-User-Id"
+        }
+      },
+      {
+        "organization_id": {
+          "_in": "X-Hasura-Allowed-Organisations"
+        }
+      }
+    ]
+  }
+
 .. admonition:: Arrays in permission rules
 
-  The ability to use arrays and operators like ``contains`` or ``contained_by`` are currently work-in-progress
-  and will be available soon.
+   Support for using session variables for array operators like ``_in``, ``_nin``, ``_has_any_keys``,
+   ``_has_all_keys`` is only added in ``beta.3`` release.
 
+Format of session variables
+---------------------------
 
+Session variables are currently expected to be Strings and should be encoded as Postgres's literals for
+the relevant type.
 
+For example, in the above example, let's say ``creator_id`` and ``organisation_id`` columns are of
+type ``integer``, then the values of ``X-Hasura-User-Id`` and  ``X-Hasura-Allowed-Organisations`` should
+be of type ``integer`` and ``integer[]`` (an integer array) respectively. To pass say a value ``1`` for
+``X-Hasura-User-Id``, it'll be "``1``" and if the allowed organisations are ``1``, ``2`` and ``3``, then
+``X-Hasura-Allowed-Organisations`` will be "``{1,2,3}``". ``{}`` is the syntax for specifying
+`arrays in Postgres <https://www.postgresql.org/docs/current/arrays.html#ARRAYS-INPUT>`_.
 
+The types and their formats are detailed `here <https://www.postgresql.org/docs/current/datatype.html>`_. When
+in doubt about the Postgres format for a type, you can always test it in the SQL window. To check
+if ``s`` is a valid literal for type ``t`` then, you can check it as follows:
+
+.. code-block:: sql
+
+   select 's'::t;
+
+If the above command returns data, then ``s`` is a valid literal of type ``t``. For example, to check
+if ``{hello,world}`` is a valid format of type ``text[]``, you can run:
+
+.. code-block:: sql
+
+   select '{hello,world}'::text[];
+
+.. admonition:: JSON format
+
+   In future, we'll add support for passing session variables as JSON values where possible (i.e, auth
+   webhook and JWT but not in headers).

docs/graphql/manual/auth/authorization/use-cases.rst.wip

@@ -74,8 +74,6 @@ You can notice above how the same query now only includes the right slice of dat
 
   This rule reads as: allow selecting an article if it was published after "31-12-2018" and its author is the current user.
 
-  **Note:** The operators ``_has_keys_all`` and ``_has_keys_any`` are currently not supported in permission rules
-
 .. _restrict_columns:
 
 Restrict access to certain columns