bump version to 12.2.12

This now requires setting `admin-server-config-enabled`.

.cirrus.yml

@@ -1,5 +1,5 @@
 freebsd_instance:
-  image_family: freebsd-14-1
+  image_family: freebsd-14-2
 
 build_task:
   # Don't change this name without adjusting .github/workflows/build.yaml

.github/actions/artifact-from-cirrus/action.yaml

@@ -112,7 +112,7 @@ runs:
         echo "artifacts=${artifacts}" >> "$GITHUB_OUTPUT"
     - name: Save artifact to GitHub Actions
       if: steps.find-task.outputs.task_found
-      uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0
+      uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
       with:
         name: ${{ inputs.upload }}
         path: ${{ steps.download.outputs.artifacts }}

.github/actions/cache-on-main/action.yaml

@@ -19,14 +19,14 @@ inputs:
 runs:
   using: composite
   steps:
-    - uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4.2.0
+    - uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
       if: ${{ startsWith(github.ref, 'refs/heads/') || (inputs.save-prs && startsWith(github.ref, 'refs/pull/')) }}
       with:
         path: ${{ inputs.path }}
         key: ${{ runner.os }}-${{ inputs.prefix }}-${{ inputs.suffix }}
         restore-keys: |
           ${{ runner.os }}-${{ inputs.prefix }}-
-    - uses: actions/cache/restore@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4.2.0
+    - uses: actions/cache/restore@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
       if: ${{ !startsWith(github.ref, 'refs/heads/') && !(inputs.save-prs && startsWith(github.ref, 'refs/pull/'))  }}
       with:
         path: ${{ inputs.path }}

.github/actions/setup-nix/action.yaml

@@ -11,12 +11,12 @@ inputs:
 runs:
   using: composite
   steps:
-    - uses: nixbuild/nix-quick-install-action@25aff27c252e0c8cdda3264805f7b6bcd92c8718 # v29
+    - uses: nixbuild/nix-quick-install-action@5bb6a3b3abe66fd09bbf250dce8ada94f856a703 # v30
       with:
         nix_conf: |-
           always-allow-substitutes = true
           max-jobs = auto
-    - uses: cachix/cachix-action@ad2ddac53f961de1989924296a1f236fcfbaa4fc # v15
+    - uses: cachix/cachix-action@0fc020193b5a1fa3ac4575aa3a7d3aa6a35435ad # v16
       with:
         name: postgrest
         authToken: ${{ inputs.authToken }}

.github/workflows/build.yaml

@@ -42,7 +42,7 @@ jobs:
       - name: Build static executable
         run: nix-build -A postgrestStatic
       - name: Save built executable as artifact
-        uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: postgrest-linux-static-x86-64
           path: result/bin/postgrest
@@ -51,7 +51,7 @@ jobs:
       - name: Build Docker image
         run: nix-build -A docker.image --out-link postgrest-docker.tar.gz
       - name: Save built Docker image as artifact
-        uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: postgrest-docker-x86-64
           path: postgrest-docker.tar.gz
@@ -118,7 +118,7 @@ jobs:
     runs-on: ${{ matrix.runs-on }}
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-      - uses: haskell-actions/setup@bbd90a29996ac33b1c644a42206e312fc0379748 # v2.7.9
+      - uses: haskell-actions/setup@d9b5b3fcf7ca56b8fe585c9b77d3b0ce466affd2 # v2.7.10
         with:
           # This must match the version in stack.yaml's resolver
           ghc-version: 9.6.5
@@ -146,7 +146,7 @@ jobs:
       - name: Strip Executable
         run: strip result/postgrest*
       - name: Save built executable as artifact
-        uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: ${{ matrix.artifact }}
           path: |
@@ -177,7 +177,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-      - uses: haskell-actions/setup@bbd90a29996ac33b1c644a42206e312fc0379748 # v2.7.9
+      - uses: haskell-actions/setup@d9b5b3fcf7ca56b8fe585c9b77d3b0ce466affd2 # v2.7.10
         with:
           ghc-version: ${{ matrix.ghc }}
       - name: Cache .cabal

.github/workflows/release.yaml

@@ -49,7 +49,7 @@ jobs:
           echo "Relevant extract from CHANGELOG.md:"
           cat CHANGES.md
       - name: Save CHANGES.md as artifact
-        uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: release-changes
           path: CHANGES.md
@@ -66,7 +66,7 @@ jobs:
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - name: Download all artifacts
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e # v4.2.1
         with:
           path: artifacts
       - name: Create release bundle with archives for all builds
@@ -91,7 +91,7 @@ jobs:
             artifacts/postgrest-windows-x86-64/postgrest.exe
 
       - name: Save release bundle
-        uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: release-bundle
           path: release-bundle
@@ -137,15 +137,15 @@ jobs:
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - name: Download x86-64 Docker image
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e # v4.2.1
         with:
           name: postgrest-docker-x86-64
       - name: Download aarch64 binary
-        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e # v4.2.1
         with:
           name: postgrest-ubuntu-aarch64
-      - uses: docker/setup-buildx-action@6524bf65af31da8d45b59e8c27de4bd072b392f5 # v3.8.0
-      - uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567 # v3.3.0
+      - uses: docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2 # v3.10.0
+      - uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3.4.0
         with:
           username: ${{ vars.DOCKER_USER }}
           password: ${{ secrets.DOCKER_PASS }}
@@ -192,7 +192,7 @@ jobs:
       github.ref == 'refs/tags/devel'
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-      - uses: peter-evans/dockerhub-description@e98e4d1628a5f3be2be7c231e50981aee98723ae # v4.0.0
+      - uses: peter-evans/dockerhub-description@432a30c9e07499fd01da9f8a49f0faf9e0ca5b77 # v4.0.2
         with:
           username: ${{ vars.DOCKER_USER }}
           password: ${{ secrets.DOCKER_PASS }}

.github/workflows/test.yaml

@@ -49,7 +49,7 @@ jobs:
       - name: Run coverage (IO tests and Spec tests against PostgreSQL 15)
         run: postgrest-coverage
       - name: Upload coverage to codecov
-        uses: codecov/codecov-action@1e68e06f1dbfde0e4cefc87efeba9e4643565303 # v5.1.2
+        uses: codecov/codecov-action@0565863a31f2c772f9f0395002a31e3f06189574 # v5.4.0
         with:
           files: ./coverage/codecov.json
           token: ${{ secrets.CODECOV_TOKEN }}

CHANGELOG.md

@@ -5,6 +5,56 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 
+## [12.2.12] - 2025-05-01
+
+### Fixed
+
+- #3956, Fix exposing admin server `/config` by default - @steve-chavez
+  + The above endpoint is now disabled unless the `admin-server-config-enabled` config is set to `true`
+
+## [12.2.11] - 2025-04-21
+
+### Fixed
+
+- #4030, Fix regression with parameter `charset=utf-8` in mediatype - @taimoorzaeem
+
+## [12.2.10] - 2025-04-18
+
+### Fixed
+
+- #3889, Fix: JWT cache purging on every request decreases performance - @mkleczek
+
+## [12.2.9] - 2025-04-16
+
+### Fixed
+
+ - #3498, Fix incorrect parsing of the `for` parameter of the `application/vnd.pgrst.plan` media type - @taimoorzaeem
+ - #4014, Fix JWT cache allows old tokens after the jwt-secret is changed in a config reload - @taimoorzaeem
+
+## [12.2.8] - 2025-02-10
+
+### Fixed
+
+ - #3841, Log `503` client error to stderr - @taimoorzaeem
+
+## [12.2.7] - 2025-02-03
+
+### Fixed
+
+ - #2524, Fix schema reloading notice on windows - @diogob
+
+## [12.2.6] - 2025-01-29
+
+### Fixed
+
+ - #3788, Fix jwt cache does not remove expired entries - @taimoorzaeem
+
+## [12.2.5] - 2025-01-20
+
+### Fixed
+
+ - #3867, Fix startup for arm64 docker image - @wolfgangwalther
+
 ## [12.2.4] - 2025-01-18
 
 ### Fixed

Dockerfile

@@ -2,7 +2,7 @@
 # The x86-64 is a single-static-binary image built via Nix, see:
 # nix/tools/docker/README.md
 
-FROM ubuntu:noble@sha256:80dd3c3b9c6cecb9f1667e9290b3bc61b78c2678c02cbdae5f0fea92cc6734ab AS postgrest
+FROM ubuntu:noble@sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782 AS postgrest
 
 RUN apt-get update -y \
     && apt install -y --no-install-recommends libpq-dev zlib1g-dev jq gcc libnuma-dev \
@@ -10,6 +10,7 @@ RUN apt-get update -y \
     && rm -rf /var/lib/apt/lists/*
 
 COPY postgrest /usr/bin/postgrest
+RUN chmod +x /usr/bin/postgrest
 
 EXPOSE 3000
 

cabal.project.freeze

@@ -1 +1 @@
-index-state: hackage.haskell.org 2024-05-17T23:41:49Z
+index-state: hackage.haskell.org 2025-02-01T14:59:33Z

docs/conf.py

@@ -292,12 +292,17 @@ def setup(app):
     app.add_css_file("css/custom.css")
 
 
-# taken from https://github.com/sphinx-doc/sphinx/blob/82dad44e5bd3776ecb6fd8ded656bc8151d0e63d/sphinx/util/requests.py#L42
-user_agent = "Mozilla/5.0 (X11; Linux x86_64; rv:25.0) Gecko/20100101 Firefox/25.0"
+user_agent = (
+    "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:135.0) Gecko/20100101 Firefox/135.0"
+)
 
 linkcheck_ignore = [
-    r"https://www.patreon.com/postgrest",
-    r"https://blog.frankel.ch/poor-man-api",
+    # Odd SSL error
+    r"https://www.dripdepot.com",
+    # New GitHub UI delays comment load, so anchor fails
+    r"https://github.com/.*#issuecomment",
+    # Random 500 Internal Server Error
+    r"https://jwt.io",
 ]
 
 # sphinx-tabs configuration

docs/ecosystem.rst

@@ -8,9 +8,6 @@ Community Tutorials
 
 * `PostgREST + Auth0: Create REST API in mintutes, and add social login using Auth0 <https://samkhawase.com/blog/postgrest/>`_ - A step-by-step tutorial to show how to dockerize and integrate Auth0 to PostgREST service.
 
-* `PostgREST + PostGIS API tutorial in 5 minutes <https://gis-ops.com/postgrest-postgis-api-tutorial-geospatial-api-in-5-minutes/>`_ -
-  In this tutorial, GIS • OPS shows how to perform PostGIS calculations through PostgREST :ref:`functions` interface.
-
 * `"CodeLess" backend using postgres, postgrest and oauth2 authentication with keycloak <https://www.mathieupassenaud.fr/codeless_backend/>`_ -
   A step-by-step tutorial for using PostgREST with KeyCloak(hosted on a managed service).
 
@@ -37,6 +34,7 @@ Templates
 Example Apps
 ------------
 
+* `archtika <https://github.com/archtika/archtika>`_ - self‑hosted CMS
 * `delibrium-postgrest <https://gitlab.com/delibrium/delibrium-postgrest/>`_ - example school API and front-end in Vue.js
 * `ETH-transactions-storage <https://github.com/Adamant-im/ETH-transactions-storage>`_ - indexer for Ethereum to get transaction list by ETH address
 * `general <https://github.com/PierreRochard/general>`_ - example auth back-end
@@ -90,7 +88,7 @@ Client-Side Libraries
 * `postgrest-go <https://github.com/supabase-community/postgrest-go>`_ - Go
 * `postgrest-js <https://github.com/supabase/postgrest-js>`_ - TypeScript/JavaScript
 * `postgrest-kt <https://github.com/supabase-community/postgrest-kt>`_ - Kotlin
-* `postgrest-py <https://github.com/supabase-community/postgrest-py>`_ - Python
+* `postgrest-py <https://github.com/supabase/postgrest-py>`_ - Python
 * `postgrest-rs <https://github.com/supabase-community/postgrest-rs>`_ - Rust
 * `postgrest-swift <https://github.com/supabase-community/postgrest-swift>`_ - Swift
 * `redux-postgrest <https://github.com/andytango/redux-postgrest>`_ - TypeScript/JS, client integrated with (React) Redux.

docs/explanations/db_authz.rst

@@ -15,7 +15,7 @@ Roles for Each Web User
 
 PostgREST can accommodate either viewpoint. If you treat a role as a single user then the :ref:`jwt_impersonation` does most of what you need. When an authenticated user makes a request PostgREST will switch into the database role for that user, which in addition to restricting queries, is available to SQL through the :code:`current_user` variable.
 
-You can use row-level security to flexibly restrict visibility and access for the current user. Here is an `example <https://www.2ndquadrant.com/en/blog/application-users-vs-row-level-security/>`_ from Tomas Vondra, a chat table storing messages sent between users. Users can insert rows into it to send messages to other users, and query it to see messages sent to them by other users.
+You can use row-level security to flexibly restrict visibility and access for the current user. Here is an `example <https://www.enterprisedb.com:443/blog/application-users-vs-row-level-security>`_ from Tomas Vondra, a chat table storing messages sent between users. Users can insert rows into it to send messages to other users, and query it to see messages sent to them by other users.
 
 .. code-block:: postgres
 

docs/index.rst

@@ -39,7 +39,7 @@ Sponsors
       :target: https://www.cybertec-postgresql.com/en/?utm_source=postgrest.org&utm_medium=referral&utm_campaign=postgrest
 
   .. image:: ../static/gnuhost.png
-    :target: https://gnuhost.eu/?utm_source=sponsor&utm_campaign=postgrest
+    :target: https://euronodes.com/?utm_source=sponsor&utm_campaign=postgrest
 
   .. container:: img-dark
 
@@ -217,7 +217,6 @@ Here are some companies that use PostgREST in production.
 * `Nimbus <https://www.nimbusfacility.com/sg/home>`_
   - See how Nimbus uses PostgREST in `Paul Copplestone's blog post <https://paul.copplest.one/blog/nimbus-tech-2019-04.html>`_.
 * `OpenBooking <https://openbooking.ch>`_
-* `Redsmin <https://www.redsmin.com>`_
 * `Supabase <https://supabase.com>`_
 
 .. Failing links

docs/integrations/greenplum.rst

@@ -1,6 +1,6 @@
 Greenplum
 #########
 
-`Greenplum <https://greenplum.org/>`_ has been reported to work by adding ``LOGIN`` to the :ref:`anonymous and user roles <roles>`.
+`Greenplum <https://blogs.vmware.com/tanzu/tanzu-greenplum/>`_ has been reported to work by adding ``LOGIN`` to the :ref:`anonymous and user roles <roles>`.
 
 For more details, see https://github.com/PostgREST/postgrest/issues/2021.

docs/postgrest.dict

@@ -12,10 +12,10 @@ booleans
 BOM
 Bytea
 Cardano
-casted
 cd
 centric
 CLI
+CMS
 coercible
 conf
 Cloudflare
@@ -146,8 +146,6 @@ SHA
 signup
 SIGUSR
 sl
-spreaded
-Spreaded
 SQL
 sql
 SQLSTATE

docs/references/admin_server.rst

@@ -55,10 +55,12 @@ Metrics
 
 Provides :ref:`metrics`.
 
+.. _runtime_config:
+
 Runtime Configuration
 =====================
 
-Provides a ``config`` endpoint that returns the runtime :ref:`configuration`.
+Provides a ``config`` endpoint that returns the runtime :ref:`configuration`. This requires setting :ref:`admin-server-config-enabled`.
 
 .. code-block:: bash
 
@@ -72,6 +74,8 @@ Provides a ``config`` endpoint that returns the runtime :ref:`configuration`.
   db-channel-enabled = false
   ...
 
+.. _runtime_schema_cache:
+
 Runtime Schema Cache
 ====================
 

docs/references/api/aggregate_functions.rst

@@ -3,20 +3,20 @@
 Aggregate Functions
 ###################
 
-Aggregate functions allow you to summarize data by performing calculations across groups of rows. For instance, if you have an ``orders`` table that has an ``amount`` column, you could use an aggregate function to get the sum of the ``amount`` column, either for all rows, or for each group of rows that share specific values, for instance all rows that share the same ``order_date``.
+PostgREST supports the following aggregate functions: ``avg()``, ``count()``, ``max()``, ``min()``, and ``sum()``.
+Please refer to the `section on aggregate functions in the PostgreSQL documentation <https://www.postgresql.org/docs/current/functions-aggregate.html>`_ for a detailed explanation of these functions.
 
 .. note::
- Aggregate functions are *disabled* by default in PostgREST, as without appropriate safeguards, aggregate functions can create performance problems. See :ref:`db-aggregates-enabled` for further details.
+ Aggregate functions are *disabled* by default in PostgREST, because they can create performance problems without appropriate safeguards.
+ See :ref:`db-aggregates-enabled` for further details.
 
-PostgREST supports the following aggregate functions: ``avg()``, ``count()``, ``max()``, ``min()``, and ``sum()``. Please refer to the `section on aggregate functions in the PostgreSQL documentation <https://www.postgresql.org/docs/current/functions-aggregate.html>`_ for a detailed explanation of these functions.
-
-To use an aggregate function, you append the function to a value in the ``select`` parameter, like so:
+To use an aggregate function, append it to a column in the ``select`` parameter, like so:
 
 .. code-block:: bash
 
   curl "http://localhost:3000/orders?select=amount.sum()"
 
-With the above query, PostgREST will return a single row with a single column named ``sum`` that contains the sum of all the values in the ``amount`` column:
+This will return a ``sum`` of all the values of the ``amount`` column in a single row:
 
 .. code-block:: json
 
@@ -26,15 +26,29 @@ With the above query, PostgREST will return a single row with a single column na
     }
   ]
 
-You can use multiple aggregate functions by just adding more columns with aggregate functions to the ``select`` parameter.
+You can ``select`` multiple aggregate functions at the same time (you may need to :ref:`rename them <renaming_columns>` to disambiguate).
 
-To group by other columns, you simply add those columns to the ``select`` parameter. For instance:
+.. code-block:: bash
+
+  curl "http://localhost:3000/orders?select=total_amount:amount.sum(),avg_amount:amount.avg(),total_quantity:quantity.sum()"
+
+.. note::
+  Aggregate functions work alongside other PostgREST features, like :ref:`h_filter`, :ref:`json_columns`, and :ref:`ordering`.
+  However they are not compatible with :ref:`domain_reps` for the moment.
+  Additionally, PostgreSQL's ``HAVING`` clause and ordering by aggregated columns are not yet supported.
+
+Automatic ``GROUP BY``
+======================
+
+In SQL, a ``GROUP BY`` clause is required to aggregate the selected columns.
+However, PostgREST handles grouping automatically if the columns are already present in the ``select`` parameter.
+For instance:
 
 .. code-block:: bash
 
   curl "http://localhost:3000/orders?select=amount.sum(),amount.avg(),order_date"
 
-This will return a row for each unique value in the ``order_date`` column, with the sum and average of the ``amount`` column for all rows that share the same ``order_date``:
+This will get the sum and average of the amounts grouped by each unique value in the ``order_date`` column:
 
 .. code-block:: json
 
@@ -51,67 +65,55 @@ This will return a row for each unique value in the ``order_date`` column, with
     }
   ]
 
-.. note::
-  Aggregate functions work alongside other PostgREST features, like :ref:`h_filter`, :ref:`json_columns`, and :ref:`ordering`. Please note at this time aggregate functions are not compatible with :ref:`domain_reps`. Additionally, PostgreSQL's ``HAVING`` clause and ordering by aggregated columns are not yet supported.
-
-The Case of ``count()``
-===========================
+The ``count()`` Aggregate
+=========================
 
 .. note::
-  Before the addition of aggregate functions, it was possible to count by adding ``count`` (without parentheses) to the ``select`` parameter. While this is still supported, it may be deprecated in the future, and thus use of this legacy feature is **not recommended.** Please use ``count()`` (with parentheses) instead.
+  Before the addition of aggregate functions, it was possible to count by adding ``count`` (without parentheses) to the ``select`` parameter.
+  While this is still supported, it may be deprecated in the future, and thus use of this legacy feature is **not recommended**.
+  Please use ``count()`` (with parentheses) instead.
 
-
-``count()`` is treated specially, as it can be used without an associated column. Take for example the following query:
+``count()`` is a special case because it can be used with or without an aggregated column. For example:
 
 .. code-block:: bash
 
-  curl "http://localhost:3000/orders?select=count(),order_date"
-
-This would return a row for each unique value in the ``order_date`` column, with the count of all rows that share the same ``order_date``:
+  curl "http://localhost:3000/orders?select=count(),observation_count:observation.count(),order_date"
 
 .. code-block:: json
 
   [
     {
       "count": 4,
+      "observation_count": 2,
       "order_date": "2023-01-01"
     },
     {
       "count": 2,
+      "observation_count": 1,
       "order_date": "2023-01-02"
     }
   ]
 
-When ``count()`` is used with an associated column, its behavior is slightly different: It will return the count of all values that are not ``NULL``. This is due to how PostgreSQL itself implements the ``count()`` function.
-
-Renaming and Casting
-====================
-
-Renaming Aggregates
--------------------
-
-Just like with other columns, you can rename aggregated columns too. See :ref:`renaming_columns` for details.
-
-Renaming columns is especially helpful in the context of aggregate functions, as by default a column with an aggregate function applied will take on the name of the applied aggregate function. You may want to provide a more semantically meaningful name or prevent collisions when using multiple aggregate functions of the same type.
+Note that there is a difference between the result of ``count()`` and ``observation.count()``.
+The former counts the whole row, while the latter counts the non ``NULL`` values of the ``observation`` column (both grouped by ``order_date``).
+This is due to how PostgreSQL itself implements the ``count()`` function.
 
 Casting Aggregates
-------------------
+==================
 
-When applying an aggregate function to a column, you are able to cast both the value of the input to the aggregate function *and* the value of the output from the aggregate function. In both cases, the syntax works as described in :ref:`casting_columns`, with the only difference being the placement of the cast.
+It is :ref:`possible to cast <casting_columns>` the aggregated column or the aggregate itself, or both at the same time.
 
-Casting the Value of the Input
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Casting the Aggregated Column
+-----------------------------
 
-For instance, imagine that the ``orders`` table has a JSON column, ``order_details``, and this column contains a JSON object that has a key, ``tax_amount``. Let's say you want to get the sum of the tax amount for every order. You can use the ``->`` or ``->>`` operators to extract the value with this key (see :ref:`json_columns`), but these operators will return values of the types JSON and ``text`` respectively, and neither of these types can be used with ``sum()``.
-
-Therefore, you will need to first cast the input value to a type that is compatible with ``sum()`` (e.g. ``numeric``). Casting the input value is done in exactly the same way as casting any other value:
+For example, let's say that ``orders`` has an ``order_details`` :ref:`JSON column <json_columns>` with a ``tax_amount`` key.
+We cannot sum ``tax_amount`` directly because using ``->`` or ``->>`` will return the data in ``json`` or ``text`` format.
+So we need to cast it to a compatible type (e.g. ``numeric``) right before the aggregate function:
 
 .. code-block:: bash
 
   curl "http://localhost:3000/orders?select=order_details->tax_amount::numeric.sum()"
 
-With this, you will receive the sum of the casted ``tax_amount`` value:
-
 .. code-block:: json
 
   [
@@ -120,17 +122,15 @@ With this, you will receive the sum of the casted ``tax_amount`` value:
     }
   ]
 
-Casting the Value of the Output
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Casting the Aggregate
+---------------------
 
-Now let's return to an example involving the ``amount`` column of the ``orders`` table. Imagine that we want to get the rounded average of the ``amount`` column. One way to do this is to use the ``avg()`` aggregate function and then to cast the output value of the function to ``int``. To cast the value of the output of the function, we simply place the cast *after* the aggregate function:
+For instance, if we wanted to round the average of the ``amount`` column, we could do so by casting ``avg()`` to an ``int``:
 
 .. code-block:: bash
 
   curl "http://localhost:3000/orders?select=amount.avg()::int"
 
-You will then receive the rounded average as the result:
-
 .. code-block:: json
 
   [
@@ -139,27 +139,22 @@ You will then receive the rounded average as the result:
     }
   ]
 
-Of course, you can use both input and output casts at the same time, if you so desire.
+Aggregates and Resource Embedding
+=================================
 
+You can group an aggregate function by an :ref:`embedded resource <resource_embedding>` and also use the aggregates inside them.
 
-Using Aggregate Functions with Resource Embedding
-=================================================
+Grouping by an Embedded Resource
+--------------------------------
 
-Aggregate functions can be used in conjunction with :ref:`resource_embedding`. You can use embedded resources as grouping columns, use aggregate functions within the context of an embedded resource, or use columns from a spreaded resource as grouping columns or as inputs to aggregate functions.
-
-Using Embedded Resources as Grouping Columns
---------------------------------------------
-
-Using an embedded resource as a grouping column allows you to use data from an association to group the results of an aggregation.
-
-For example, imagine that the ``orders`` table from the examples above is related to a ``customers`` table. If you want to get the sum of the ``amount`` column grouped by the ``name`` column from the ``customers`` table, you can include the customer name, using the standard :ref:`resource_embedding` syntax, and perform a sum on the ``amount`` column.
+Similar to grouping by columns, aggregate functions can also be grouped by embedded resources.
+For example, let's say that the ``orders`` table is related to a ``customers`` table.
+To get the sum of the ``amount`` column grouped by the ``name`` column from the ``customers`` table, we would do the following:
 
 .. code-block:: bash
 
   curl "http://localhost:3000/orders?select=amount.sum(),customers(name)"
 
-You will then get the summed amount, along with the embedded customer resource:
-
 .. code-block:: json
 
   [
@@ -177,15 +172,16 @@ You will then get the summed amount, along with the embedded customer resource:
     }
   ]
 
-.. note::
- The previous example uses a has-one association to demonstrate this functionality, but you may also use has-many associations as grouping columns, although there are few obvious use cases for this.
+The previous example uses a "to-one" relationship, but this can be done on "to-many" relationships as well (although there are few obvious use cases).
 
-Using Aggregate Functions Within the Context of an Embedded Resource
---------------------------------------------------------------------
+This also works in a similar way for :ref:`spread embedded resources <spread_embed>`.
+For example, ``select=amount.sum(),...customers(name)`` would sum the ``amount`` grouped by the ``name`` column.
 
-When embedding a resource, you can apply aggregate functions to columns from the associated resource to perform aggregations within the context of an embedded resource.
+Using Aggregates Inside Embedded Resources
+------------------------------------------
 
-Continuing with the example relationship between ``orders`` and ``customers`` from the previous section, imagine that you want to fetch the ``name``, ``city``, and ``state`` for each customer, along with the sum of amount of the customer's orders, grouped by the order date. This can be done in the following way:
+Using the relationship from the previous example, let's take all the ``customers`` and embed their ``orders``.
+If we also want to get the total ``amount`` grouped by the ``order_date`` of the ``orders``, we would do the following:
 
 .. code-block:: bash
 
@@ -226,51 +222,20 @@ Continuing with the example relationship between ``orders`` and ``customers`` fr
     }
   ]
 
-In this example, the ``amount`` column is summed and grouped by the ``order_date`` *within* the context of the embedded resource. That is, the ``name``, ``city``, and ``state`` from the ``customers`` table have no bearing on the aggregation performed in the context of the ``orders`` association; instead, each aggregation can be seen as being performed independently on just the orders belonging to a particular customer, using only the data from the embedded resource for both grouping and aggregation.
+Note that the aggregate is done within the embedded resource ``orders``.
+It is not affected by any of the columns from the top-level relationship ``customers``.
 
-Using Columns from a Spreaded Resource
---------------------------------------
+Using Aggregates in Spreads
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When you :ref:`spread an embedded resource <spread_embed>`, the columns from the spreaded resource are treated as if they were columns of the top-level resource, both when using them as grouping columns and when applying aggregate functions to them.
-
-Grouping with Columns from a Spreaded Resource
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For instance, assume you want to sum the ``amount`` column from the ``orders`` table, using the ``city`` and ``state`` columns from the ``customers`` table as grouping columns. To achieve this, you may select these two columns from the ``customers`` table and spread them; they will then be used as grouping columns:
+All the aggregates inside a :ref:`spread embedded resource <spread_embed>` will be hoisted to the top-level relationship.
+In other words, it will behave as if the aggregate was done in the top-level relationship itself. For example:
 
 .. code-block:: bash
 
-  curl "http://localhost:3000/orders?select=amount.sum(),...customers(city,state)
+  curl "http://localhost:3000/orders?select=order_date,...customers(subscription_date.max(),subscription_date.min())
 
-The result will be the same as if ``city`` and ``state`` were columns from the ``orders`` table:
-
-.. code-block:: json
-
-  [
-    {
-      "sum": 2000.29,
-      "city": "New York",
-      "state": "NY"
-    },
-    {
-      "sum": 9241.21,
-      "city": "Los Angeles",
-      "state": "CA"
-    }
-  ]
-
-Aggregate Functions with Columns from a Spreaded Resource
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Now imagine that the ``customers`` table has a ``joined_date`` column that represents the date that the customer joined. You want to get both the most recent and the oldest ``joined_date`` for customers that placed an order on every distinct order date. This can be expressed as follows:
-
-.. code-block:: bash
-
-  curl "http://localhost:3000/orders?select=order_date,...customers(joined_date.max(),joined_date.min())
-
-As columns from a spreaded resource are treated as if they were columns from the top-level resource, the ``max()`` and ``min()`` are applied *within* the context of the top-level, rather than within the context of the embedded resource, as in the previous section.
-
-The result will be the same as if the aggregations were applied to columns from the top-level:
+This will take the ``max`` and ``min`` subscription date of every customer and group it by the ``order_date`` column:
 
 .. code-block:: json
 

docs/references/api/preferences.rst

@@ -12,7 +12,7 @@ The following preferences are supported.
 - ``Prefer: return``. See :ref:`prefer_return`.
 - ``Prefer: count``. See :ref:`prefer_count`.
 - ``Prefer: resolution``. See :ref:`prefer_resolution`.
-- ``Prefer: missing``. See :ref:`bulk_insert_default`.
+- ``Prefer: missing``. See :ref:`prefer_missing`.
 - ``Prefer: max-affected``, See :ref:`prefer_max_affected`.
 - ``Prefer: tx``. See :ref:`prefer_tx`.
 - ``Prefer: params``. See :ref:`prefer_params`.
@@ -197,6 +197,47 @@ The ``tx`` preference can be set to specify if the :ref:`transaction <transactio
   {"id": 35, "name": "Project X"}
 
 
+.. _prefer_missing:
+
+Missing
+=======
+
+When doing ``POST`` and ``PATCH`` requests, any missing columns in the payload will be inserted as ``null`` value by default. To use the ``DEFAULT`` column value instead, use the ``Prefer: missing=default`` header.
+
+Having:
+
+.. code-block:: postgres
+
+  create table foo (
+    id bigint generated by default as identity primary key
+  , bar text
+  , baz int default 100
+  );
+
+A request:
+
+.. code-block:: bash
+
+  curl "http://localhost:3000/foo?columns=id,bar,baz" \
+    -H "Content-Type: application/json" \
+    -H "Prefer: missing=default, return=representation" \
+    -d @- << EOF
+      [
+        { "bar": "val1" },
+        { "bar": "val2", "baz": 15 }
+      ]
+  EOF
+
+Will result in:
+
+.. code-block:: json
+
+  [
+    { "id":  1, "bar": "val1", "baz": 100 },
+    { "id":  2, "bar": "val2", "baz": 15 }
+  ]
+
+
 .. _prefer_max_affected:
 
 Max Affected

docs/references/api/resource_representation.rst

@@ -16,6 +16,32 @@ Use the Accept request header to specify the acceptable format (or formats) for
   curl "http://localhost:3000/people" \
     -H "Accept: application/json"
 
+.. note::
+  
+  The ordering of columns in the response isn't guaranteed to align with the order specified in the ``select`` clause. For example, with resource embedding:
+
+  .. code-block:: bash
+    
+    http://localhost:3000/films?select=directors(last_name,id),title
+  
+  We may get:
+
+  .. code-block:: bash
+
+    [
+      {
+        "title": "title",
+        "directors": {
+          "id": 5,
+          "last_name": "name"
+        }
+      }
+    ]
+
+  This is in line with the `JSON schema spec <https://json-schema.org/draft/2020-12/json-schema-core#name-instance-data-model>`_:
+
+    *"object: An unordered set of properties mapping a string to an instance"*
+
 .. _builtin_media:
 
 Builtin Media Type Handlers

docs/references/api/tables_views.rst

@@ -525,45 +525,6 @@ To bulk insert JSON post an array of objects having all-matching keys
     ]
   EOF
 
-.. _bulk_insert_default:
-
-Bulk Insert with Default Values
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Any missing columns in the payload will be inserted as ``null`` values. To use the ``DEFAULT`` column value instead, use the ``Prefer: missing=default`` header.
-
-Having:
-
-.. code-block:: postgres
-
-  create table foo (
-    id bigint generated by default as identity primary key
-  , bar text
-  , baz int default 100
-  );
-
-A request:
-
-.. code-block:: bash
-
-  curl "http://localhost:3000/foo?columns=id,bar,baz" \
-    -H "Content-Type: application/json" \
-    -H "Prefer: missing=default, return=representation" \
-    -d @- << EOF
-      [
-        { "bar": "val1" },
-        { "bar": "val2", "baz": 15 }
-      ]
-  EOF
-
-Will result in:
-
-.. code-block:: json
-
-  [
-    { "id":  1, "bar": "val1", "baz": 100 },
-    { "id":  2, "bar": "val2", "baz": 15 }
-  ]
 
 .. _specify_columns:
 
@@ -606,7 +567,13 @@ To update a row or rows in a table, use the PATCH verb. Use :ref:`h_filter` to s
     -X PATCH -H "Content-Type: application/json" \
     -d '{ "category": "child" }'
 
-Updates also support :ref:`prefer_return`, :ref:`resource_embedding` and :ref:`v_filter`.
+Updates also support:
+
+- :ref:`prefer_return`
+- :ref:`resource_embedding`
+- :ref:`v_filter`
+- :ref:`Missing Preference <prefer_missing>`
+- :ref:`specify_columns`
 
 .. warning::
 
@@ -637,7 +604,7 @@ You can make an upsert with :code:`POST` and the :code:`Prefer: resolution=merge
 By default, upsert operates based on the primary key columns, so you must specify all of them.
 You can also choose to ignore the duplicates with :code:`Prefer: resolution=ignore-duplicates`.
 Upsert works best when the primary key is natural (e.g. ``sku``).
-However, it can work with surrogate primary keys (e.g. ``id serial primary key``), if you also do a :ref:`bulk_insert_default`:
+However, it can work with surrogate primary keys (e.g. ``id serial primary key``), if you also do a :ref:`bulk_insert` with :ref:`prefer_missing`:
 
 .. code-block:: bash
 
@@ -755,6 +722,7 @@ Using ``offset`` to target a different subset of rows is also possible.
       '#estimated-count': 'pagination_count.html#estimated-count',
       '#prefer-return-headers-only': 'preferences.html#headers-only',
       '#prefer-return-representation': 'preferences.html#full',
+      '#bulk-insert-default': 'preferences.html#prefer-missing',
     };
 
     let willRedirectTo = redirects[hash];

docs/references/auth.rst

@@ -159,7 +159,15 @@ You can specify the literal value as we saw earlier, or reference a filename to
 JWT Claims Validation
 ~~~~~~~~~~~~~~~~~~~~~
 
-PostgREST honors the :code:`exp` claim for token expiration, rejecting expired tokens.
+PostgREST honors the following `JWT claims <https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4>`_:
+
+- ``exp`` Expiration Time
+- ``iat`` Issued At
+- ``nbf`` Not Before
+- ``aud`` Audience, see :ref:`jwt-aud`
+
+.. note::
+  PostgREST allows for a 30-second clock skew when validating the ``exp`` and ``iat`` claims. In other words, it gives an extra 30 seconds before the token is rejected if there is a slight discrepancy in the timestamps.
 
 JWT Security
 ~~~~~~~~~~~~

docs/references/configuration.rst

@@ -161,6 +161,30 @@ admin-server-port
 
   Specifies the port for the :ref:`admin_server`.
 
+.. _admin-server-config-enabled:
+
+admin-server-config-enabled
+---------------------------
+
+  .. danger::
+
+    The ``/config`` endpoint contains sensitive information, don't enable this if you're exposing the Admin Server publicly.
+
+    To safely enable this you can use a proxy like :ref:`nginx` to:
+
+    - Ensure ``/config`` are only available to local networks.
+    - Only expose ``/live`` and ``/ready`` to public networks.
+
+  =============== =================================
+  **Type**        Boolean
+  **Default**     False
+  **Reloadable**  N
+  **Environment** PGRST_ADMIN_SERVER_CONFIG_ENABLED
+  **In-Database** `n/a`
+  =============== =================================
+
+  Enables the admin server :ref:`runtime_config` and :ref:`runtime_schema_cache` endpoints.
+
 .. _app.settings.*:
 
 app.settings.*

docs/shared/installation.rst

@@ -34,7 +34,7 @@
 
         .. code:: bash
 
-          nix-env -i haskellPackages.postgrest
+          nix-env -i postgrest
 
   .. group-tab:: Windows
 

nix/overlays/haskell-packages.nix

@@ -74,8 +74,8 @@ let
       hasql-notifications = lib.dontCheck (prev.callHackageDirect
         {
           pkg = "hasql-notifications";
-          ver = "0.2.2.0";
-          sha256 = "sha256-73OQ9/su2qvO7HavF3xuuNWLXSXyB9reBUQDaHys06I=";
+          ver = "0.2.2.2";
+          sha256 = "sha256-myKwlug7OgTa/qP6mHfCD+5Q8IhM17JvpJBfSo+M01k=";
         }
         { }
       );

postgrest.cabal

@@ -1,5 +1,5 @@
 name:               postgrest
-version:            12.2.4
+version:            12.2.12
 synopsis:           REST API for any Postgres database
 description:        Reads the schema of a PostgreSQL database and creates RESTful routes
                     for tables, views, and functions, supporting all HTTP methods that security
@@ -110,7 +110,7 @@ library
                     , gitrev                    >= 1.2 && < 1.4
                     , hasql                     >= 1.6.1.1 && < 1.7
                     , hasql-dynamic-statements  >= 0.3.1 && < 0.4
-                    , hasql-notifications       >= 0.2.2.0 && < 0.3
+                    , hasql-notifications       >= 0.2.2.2 && < 0.2.3
                     , hasql-pool                >= 1.0.1 && < 1.1
                     , hasql-transaction         >= 1.0.1 && < 1.1
                     , heredoc                   >= 0.2 && < 0.3

src/PostgREST/Admin.hs

@@ -56,8 +56,11 @@ admin appState req respond  = do
       in
       respond $ Wai.responseLBS status [] mempty
     ["config"] -> do
-      config <- AppState.getConfig appState
-      respond $ Wai.responseLBS HTTP.status200 [] (LBS.fromStrict $ encodeUtf8 $ Config.toText config)
+      config@Config.AppConfig{configAdminServerConfigEnabled} <- AppState.getConfig appState
+      if configAdminServerConfigEnabled then
+        respond $ Wai.responseLBS HTTP.status200 [] (LBS.fromStrict $ encodeUtf8 $ Config.toText config)
+      else
+        respond $ Wai.responseLBS HTTP.status404 [] mempty
     ["schema_cache"] -> do
       sCache <- AppState.getSchemaCache appState
       respond $ Wai.responseLBS HTTP.status200 [] (maybe mempty JSON.encode sCache)

src/PostgREST/AppState.hs

@@ -5,6 +5,7 @@
 module PostgREST.AppState
   ( AppState
   , AuthResult(..)
+  , JwtCacheState(..)
   , destroy
   , getConfig
   , getSchemaCache
@@ -13,7 +14,7 @@ module PostgREST.AppState
   , getNextDelay
   , getNextListenerDelay
   , getTime
-  , getJwtCache
+  , getJwtCacheState
   , getSocketREST
   , getSocketAdmin
   , init
@@ -83,6 +84,12 @@ data AuthResult = AuthResult
   , authRole   :: BS.ByteString
   }
 
+-- | JWT Cache and IO action that triggers purging old entries from the cache
+data JwtCacheState = JwtCacheState
+  { jwtCache   :: C.Cache ByteString AuthResult
+  , purgeCache :: IO ()
+  }
+
 data AppState = AppState
   -- | Database connection pool
   { statePool              :: SQL.Pool
@@ -107,7 +114,7 @@ data AppState = AppState
   -- | Keeps track of the next delay for the listener
   , stateNextListenerDelay :: IORef Int
   -- | JWT Cache
-  , jwtCache               :: C.Cache ByteString AuthResult
+  , jwtCacheState          :: JwtCacheState
   -- | Network socket for REST API
   , stateSocketREST        :: NS.Socket
   -- | Network socket for the admin UI
@@ -139,6 +146,16 @@ init conf@AppConfig{configLogLevel, configDbPoolSize} = do
 
 initWithPool :: AppSockets -> SQL.Pool -> AppConfig -> Logger.LoggerState -> Metrics.MetricsState -> ObservationHandler -> IO AppState
 initWithPool (sock, adminSock) pool conf loggerState metricsState observer = do
+  cache <- C.newCache Nothing
+  -- purgeExpired has O(n^2) complexity
+  -- so we wrap it in debounce to make sure it:
+  -- 1) is executed asynchronously
+  -- 2) only a single purge operation is running at a time
+  debounce <- mkDebounce defaultDebounceSettings
+    -- debounceFreq is set to default 1 second
+    { debounceAction = C.purgeExpired cache
+    , debounceEdge = leadingEdge
+    }
 
   appState <- AppState pool
     <$> newIORef minimumPgVersion -- assume we're in a supported version when starting, this will be corrected on a later step
@@ -151,7 +168,7 @@ initWithPool (sock, adminSock) pool conf loggerState metricsState observer = do
     <*> myThreadId
     <*> newIORef 0
     <*> newIORef 1
-    <*> C.newCache Nothing
+    <*> pure (JwtCacheState cache debounce)
     <*> pure sock
     <*> pure adminSock
     <*> pure observer
@@ -265,8 +282,9 @@ usePool AppState{stateObserver=observer, stateMainThreadId=mainThreadId, ..} ses
         SQL.ServerError{} ->
           when (Error.status (Error.PgError False err) >= HTTP.status500) $
             observer $ QueryErrorCodeHighObs err
-    SQL.SessionUsageError (SQL.QueryError _ _ (SQL.ClientError _)) ->
-      pure ()
+    err@(SQL.SessionUsageError (SQL.QueryError _ _ (SQL.ClientError _))) ->
+      -- An error on the client-side, usually indicates problems wth connection
+        observer $ QueryErrorCodeHighObs err
     )
 
   return res
@@ -313,8 +331,8 @@ putConfig = atomicWriteIORef . stateConf
 getTime :: AppState -> IO UTCTime
 getTime = stateGetTime
 
-getJwtCache :: AppState -> C.Cache ByteString AuthResult
-getJwtCache = jwtCache
+getJwtCacheState :: AppState -> JwtCacheState
+getJwtCacheState = jwtCacheState
 
 getSocketREST :: AppState -> NS.Socket
 getSocketREST = stateSocketREST
@@ -438,12 +456,12 @@ retryingSchemaCacheLoad appState@AppState{stateObserver=observer, stateMainThrea
 -- | Reads the in-db config and reads the config file again
 -- | We don't retry reading the in-db config after it fails immediately, because it could have user errors. We just report the error and continue.
 readInDbConfig :: Bool -> AppState -> IO ()
-readInDbConfig startingUp appState@AppState{stateObserver=observer} = do
-  AppConfig{..} <- getConfig appState
+readInDbConfig startingUp appState@AppState{stateObserver=observer, jwtCacheState=JwtCacheState{jwtCache}} = do
+  conf <- getConfig appState
   pgVer <- getPgVersion appState
   dbSettings <-
-    if configDbConfig then do
-      qDbSettings <- usePool appState (queryDbSettings (dumpQi <$> configDbPreConfig) configDbPreparedStatements)
+    if configDbConfig conf then do
+      qDbSettings <- usePool appState (queryDbSettings (dumpQi <$> configDbPreConfig conf) (configDbPreparedStatements conf))
       case qDbSettings of
         Left e -> do
           observer $ ConfigReadErrorObs e
@@ -452,8 +470,8 @@ readInDbConfig startingUp appState@AppState{stateObserver=observer} = do
     else
       pure mempty
   (roleSettings, roleIsolationLvl) <-
-    if configDbConfig then do
-      rSettings <- usePool appState (queryRoleSettings pgVer configDbPreparedStatements)
+    if configDbConfig conf then do
+      rSettings <- usePool appState (queryRoleSettings pgVer (configDbPreparedStatements conf))
       case rSettings of
         Left e -> do
           observer $ QueryRoleSettingsErrorObs e
@@ -461,7 +479,7 @@ readInDbConfig startingUp appState@AppState{stateObserver=observer} = do
         Right x -> pure x
     else
       pure mempty
-  readAppConfig dbSettings configFilePath (Just configDbUri) roleSettings roleIsolationLvl >>= \case
+  readAppConfig dbSettings (configFilePath conf) (Just $ configDbUri conf) roleSettings roleIsolationLvl >>= \case
     Left err   ->
       if startingUp then
         panic err -- die on invalid config if the program is starting up
@@ -469,6 +487,14 @@ readInDbConfig startingUp appState@AppState{stateObserver=observer} = do
         observer $ ConfigInvalidObs err
     Right newConf -> do
       putConfig appState newConf
+      -- After the config has reloaded, jwt-secret might have changed, so
+      -- if it has changed, it is important to invalidate the jwt cache
+      -- entries, because they were cached using the old secret
+      if configJwtSecret conf == configJwtSecret newConf then
+        pass
+      else
+        C.purge jwtCache -- atomic O(1) operation
+
       if startingUp then
         pass
       else

src/PostgREST/Auth.hs

@@ -44,8 +44,9 @@ import System.Clock            (TimeSpec (..))
 import System.IO.Unsafe        (unsafePerformIO)
 import System.TimeIt           (timeItT)
 
-import PostgREST.AppState (AppState, AuthResult (..), getConfig,
-                           getJwtCache, getTime)
+import PostgREST.AppState (AppState, AuthResult (..),
+                           JwtCacheState (..), getConfig,
+                           getJwtCacheState, getTime)
 import PostgREST.Config   (AppConfig (..), JSPath, JSPathExp (..))
 import PostgREST.Error    (Error (..))
 
@@ -131,11 +132,35 @@ middleware appState app req respond = do
 -- | Used to retrieve and insert JWT to JWT Cache
 getJWTFromCache :: AppState -> ByteString -> Int -> IO (Either Error AuthResult) -> UTCTime -> IO (Either Error AuthResult)
 getJWTFromCache appState token maxLifetime parseJwt utc = do
-  checkCache <- C.lookup (getJwtCache appState) token
+  let JwtCacheState{..} = getJwtCacheState appState
+  checkCache <- C.lookup jwtCache token
   authResult <- maybe parseJwt (pure . Right) checkCache
 
   case (authResult,checkCache) of
-    (Right res, Nothing) -> C.insert' (getJwtCache appState) (getTimeSpec res maxLifetime utc) token res
+    -- From comment:
+    -- https://github.com/PostgREST/postgrest/pull/3801#discussion_r1857987914
+    --
+    -- We purge expired cache entries on a cache miss
+    -- The reasoning is that:
+    --
+    -- 1. We expect it to be rare (otherwise there is no point of the cache)
+    -- 2. It makes sure the cache is not growing (as inserting new entries
+    --    does garbage collection)
+    -- 3. Since this is time expiration based cache there is no real risk of
+    --    starvation - sooner or later we are going to have a cache miss.
+
+    (Right res, Nothing) -> do -- cache miss
+
+      let timeSpec = getTimeSpec res maxLifetime utc
+
+      -- insert new cache entry
+      C.insert' jwtCache timeSpec token res
+
+      -- Execute IO action to purge the cache
+      -- It is assumed this action returns immidiately
+      -- so that request processing is not blocked.
+      purgeCache
+
     _                    -> pure ()
 
   return authResult

src/PostgREST/CLI.hs

@@ -128,6 +128,9 @@ exampleConfigFile =
   [str|## Admin server used for checks. It's disabled by default unless a port is specified.
       |# admin-server-port = 3001
       |
+      |## Whether to enable the /config endpoint of the admin server
+      |# admin-server-config-enabled = false
+      |
       |## The database role to use when no client authentication is provided
       |# db-anon-role = "anon"
       |

src/PostgREST/Config.hs

@@ -110,6 +110,7 @@ data AppConfig = AppConfig
   , configServerUnixSocket         :: Maybe FilePath
   , configServerUnixSocketMode     :: FileMode
   , configAdminServerPort          :: Maybe Int
+  , configAdminServerConfigEnabled :: Bool
   , configRoleSettings             :: RoleSettings
   , configRoleIsoLvl               :: RoleIsolationLvl
   , configInternalSCSleep          :: Maybe Int32
@@ -180,6 +181,7 @@ toText conf =
       ,("server-unix-socket",        q . maybe mempty T.pack . configServerUnixSocket)
       ,("server-unix-socket-mode",   q . T.pack . showSocketMode)
       ,("admin-server-port",             maybe "\"\"" show . configAdminServerPort)
+      ,("admin-server-config-enabled",             T.toLower . show . configAdminServerConfigEnabled)
       ]
 
     -- quote all app.settings
@@ -286,6 +288,7 @@ parser optPath env dbSettings roleSettings roleIsolationLvl =
     <*> (fmap T.unpack <$> optString "server-unix-socket")
     <*> parseSocketFileMode "server-unix-socket-mode"
     <*> optInt "admin-server-port"
+    <*> (fromMaybe False <$> optBool "admin-server-config-enabled")
     <*> pure roleSettings
     <*> pure roleIsolationLvl
     <*> optInt "internal-schema-cache-sleep"

src/PostgREST/MediaType.hs

@@ -1,7 +1,7 @@
 {-# LANGUAGE DeriveAnyClass        #-}
 {-# LANGUAGE DeriveGeneric         #-}
 {-# LANGUAGE DuplicateRecordFields #-}
-
+{-# OPTIONS_GHC -Wno-unused-do-bind #-}
 module PostgREST.MediaType
   ( MediaType(..)
   , MTVndPlanOption (..)
@@ -11,17 +11,16 @@ module PostgREST.MediaType
   , decodeMediaType
   ) where
 
-import qualified Data.Aeson      as JSON
-import qualified Data.ByteString as BS
+import qualified Data.Aeson                    as JSON
+import qualified Data.ByteString               as BS
+import qualified Data.Text                     as T
+import qualified Text.ParserCombinators.Parsec as P
 
+import Data.Map                  (fromList, (!?))
+import Data.Text.Encoding        (decodeLatin1)
 import Network.HTTP.Types.Header (Header, hContentType)
 
-import           Data.Map           (fromList, (!?))
-import qualified Data.Text          as T (break, drop, dropWhile,
-                                          dropWhileEnd, null, splitOn,
-                                          toLower)
-import           Data.Text.Encoding (decodeLatin1)
-import           Protolude
+import Protolude
 
 -- | Enumeration of currently supported media types
 data MediaType
@@ -104,6 +103,9 @@ toMimePlanFormat PlanText = "text"
 -- >>> decodeMediaType "application/vnd.pgrst.plan;for=\"application/json\""
 -- MTVndPlan MTApplicationJSON PlanText []
 --
+-- >>> decodeMediaType "application/vnd.pgrst.plan ; for=\"text/xml\" ; options=analyze"
+-- MTVndPlan MTTextXML PlanText [PlanAnalyze]
+--
 -- >>> decodeMediaType "application/vnd.pgrst.plan+json;for=\"text/csv\""
 -- MTVndPlan MTTextCSV PlanJSON []
 --
@@ -150,7 +152,10 @@ decodeMediaType mt = decodeMediaType' $ decodeLatin1 mt
         ("*","*",_)                                 -> MTAny
         _                                           -> MTOther mt'
       where
-        (mainType, subType, params') = tokenizeMediaType mt'
+        mediaTypeOrError = P.parse tokenizeMediaType "parsec: tokenizeMediaType failed" $ T.unpack mt'
+        (mainType, subType, params') = case mediaTypeOrError of
+          Right mt'' -> mt''
+          Left _     -> (mt',"",[])
         params = fromList $ map (first T.toLower) params' -- normalize parameter names to lowercase, per RFC 7321
         getPlan fmt = MTVndPlan mtFor fmt $
           [PlanAnalyze  | inOpts "analyze" ] ++
@@ -166,21 +171,39 @@ decodeMediaType mt = decodeMediaType' $ decodeLatin1 mt
         checkArrayNullStrip = if strippedNulls then MTVndArrayJSONStrip else MTApplicationJSON
 
 -- | Split a Media Type string into components
--- >>> tokenizeMediaType "application/vnd.pgrst.plan+json;for=\"text/csv\""
--- ("application","vnd.pgrst.plan+json",[("for","text/csv")])
--- >>> tokenizeMediaType "*/*"
--- ("*","*",[])
--- >>> tokenizeMediaType "application/vnd.pgrst.plan;wat=\"application/json;text/csv\""
--- ("application","vnd.pgrst.plan",[("wat","application/json"),("text/csv\"","")])
-tokenizeMediaType :: Text -> (Text, Text, [(Text, Text)])
-tokenizeMediaType t = (mainType, subType, params)
-  where
-    (mainType, rest) = T.break (== '/') t
-    (subType, restParams) = T.break (== ';') $ T.drop 1 rest
-    params =
-      let rp = T.drop 1 restParams
-      in if T.null rp then [] else map param $ T.splitOn ";" rp -- FIXME: breaks if there's a ';' in a quoted value
-    param p =
-      let (k, v) = T.break (== '=') p
-      in (k, dropAround (== '"') $ T.drop 1 v) -- FIXME: doesn't unescape quotes in values
-    dropAround p = T.dropWhile p . T.dropWhileEnd p
+-- >>> P.parse tokenizeMediaType "" "application/vnd.pgrst.plan+json;for=\"text/csv\""
+-- Right ("application","vnd.pgrst.plan+json",[("for","text/csv")])
+--
+-- >>> P.parse tokenizeMediaType "" "*/*"
+-- Right ("*","*",[])
+--
+-- >>> P.parse tokenizeMediaType "" "application/vnd.pgrst.plan;wat=\"application/json;text/csv\""
+-- Right ("application","vnd.pgrst.plan",[("wat","application/json;text/csv")])
+--
+-- >>> P.parse tokenizeMediaType "" "application/vnd.pgrst.plan+text; for=\"text/xml\"; options=analyze|verbose|settings|buffers|wal"
+-- Right ("application","vnd.pgrst.plan+text",[("for","text/xml"),("options","analyze|verbose|settings|buffers|wal")])
+
+-- TODO: Improve mediatype parser as per RFC 2045 https://datatracker.ietf.org/doc/html/rfc2045#section-5.1
+tokenizeMediaType :: P.Parser (Text, Text, [(Text, Text)])
+tokenizeMediaType = do
+  mainType <- P.many1 (P.alphaNum <|> P.oneOf ".*")
+  P.char '/'
+  subType <- P.many1 (P.alphaNum <|> P.oneOf ".*+-")
+  params <- P.many pSemicolonSeparatedKeyVals
+  P.optional $ P.try $ P.spaces *> P.char ';' -- ending semicolon, discard input after that because it has already failed or we have hit EOF
+  return (T.pack mainType, T.pack subType, params)
+    where
+      pSemicolonSeparatedKeyVals :: P.Parser (Text, Text)
+      pSemicolonSeparatedKeyVals = P.try $ P.spaces *> P.char ';' *> P.spaces *> pKeyVal
+        where
+          pKeyVal :: P.Parser (Text, Text)
+          pKeyVal = do
+            key <- P.many1 (P.alphaNum <|> P.oneOf "-")
+            P.spaces
+            P.char '='
+            P.spaces
+            val <- P.try pQuoted <|> P.try pUnQuoted
+            return (T.pack key, T.pack val)
+              where
+                pUnQuoted = P.many1 (P.alphaNum <|> P.oneOf "|-")
+                pQuoted = P.char '\"' *> P.manyTill P.anyChar (P.char '\"')

stack-21.7.yaml

@@ -19,6 +19,6 @@ nix:
 extra-deps:
   - configurator-pg-0.2.10
   - fuzzyset-0.2.4
-  - hasql-notifications-0.2.2.0
+  - hasql-notifications-0.2.2.2
   - hasql-pool-1.0.1
   - postgresql-libpq-0.10.1.0

stack-21.7.yaml.lock

@@ -19,12 +19,12 @@ packages:
   original:
     hackage: fuzzyset-0.2.4
 - completed:
-    hackage: hasql-notifications-0.2.2.0@sha256:a4e591ef3f06647b056567d3b66948c4a85371f05deb5434edb6ce190f7c845d,2021
+    hackage: hasql-notifications-0.2.2.2@sha256:d1d6bc0d3ee5e418fc12ea023b78739e0decba6c34e2b43bec55b89e18bd4412,2025
     pantry-tree:
-      sha256: bd7192a5e82ef6dbac711c3433408a0330c8db1cd3482be1ccd4fbd0a63bc2f6
+      sha256: 83a9cbb179b1efd0b2acd6509583c7afcdbe63469ab033d8581d48d675a80b44
       size: 452
   original:
-    hackage: hasql-notifications-0.2.2.0
+    hackage: hasql-notifications-0.2.2.2
 - completed:
     hackage: hasql-pool-1.0.1@sha256:3cfb4c7153a6c536ac7e126c17723e6d26ee03794954deed2d72bcc826d05a40,2302
     pantry-tree:

stack.yaml

@@ -11,5 +11,5 @@ nix:
 
 extra-deps:
   - fuzzyset-0.2.4
-  - hasql-notifications-0.2.2.0
+  - hasql-notifications-0.2.2.2
   - hasql-pool-1.0.1

stack.yaml.lock

@@ -12,12 +12,12 @@ packages:
   original:
     hackage: fuzzyset-0.2.4
 - completed:
-    hackage: hasql-notifications-0.2.2.0@sha256:a4e591ef3f06647b056567d3b66948c4a85371f05deb5434edb6ce190f7c845d,2021
+    hackage: hasql-notifications-0.2.2.2@sha256:d1d6bc0d3ee5e418fc12ea023b78739e0decba6c34e2b43bec55b89e18bd4412,2025
     pantry-tree:
-      sha256: bd7192a5e82ef6dbac711c3433408a0330c8db1cd3482be1ccd4fbd0a63bc2f6
+      sha256: 83a9cbb179b1efd0b2acd6509583c7afcdbe63469ab033d8581d48d675a80b44
       size: 452
   original:
-    hackage: hasql-notifications-0.2.2.0
+    hackage: hasql-notifications-0.2.2.2
 - completed:
     hackage: hasql-pool-1.0.1@sha256:3cfb4c7153a6c536ac7e126c17723e6d26ee03794954deed2d72bcc826d05a40,2302
     pantry-tree:

test/io/configs/expected/aliases.config

@@ -36,3 +36,4 @@ server-timing-enabled = false
 server-unix-socket = ""
 server-unix-socket-mode = "660"
 admin-server-port = ""
+admin-server-config-enabled = false

test/io/configs/expected/boolean-numeric.config

@@ -36,3 +36,4 @@ server-timing-enabled = false
 server-unix-socket = ""
 server-unix-socket-mode = "660"
 admin-server-port = ""
+admin-server-config-enabled = false

test/io/configs/expected/boolean-string.config

@@ -36,3 +36,4 @@ server-timing-enabled = false
 server-unix-socket = ""
 server-unix-socket-mode = "660"
 admin-server-port = ""
+admin-server-config-enabled = false

test/io/configs/expected/defaults.config

@@ -36,3 +36,4 @@ server-timing-enabled = false
 server-unix-socket = ""
 server-unix-socket-mode = "660"
 admin-server-port = ""
+admin-server-config-enabled = false

test/io/configs/expected/no-defaults-with-db-other-authenticator.config

@@ -36,5 +36,6 @@ server-timing-enabled = true
 server-unix-socket = "/tmp/pgrst_io_test.sock"
 server-unix-socket-mode = "777"
 admin-server-port = 3001
+admin-server-config-enabled = true
 app.settings.test = "test"
 app.settings.test2 = "test"

test/io/configs/expected/no-defaults-with-db.config

@@ -36,5 +36,6 @@ server-timing-enabled = false
 server-unix-socket = "/tmp/pgrst_io_test.sock"
 server-unix-socket-mode = "777"
 admin-server-port = 3001
+admin-server-config-enabled = true
 app.settings.test = "test"
 app.settings.test2 = "test"

test/io/configs/expected/no-defaults.config

@@ -36,5 +36,6 @@ server-timing-enabled = true
 server-unix-socket = "/tmp/pgrst_io_test.sock"
 server-unix-socket-mode = "777"
 admin-server-port = 3001
+admin-server-config-enabled = true
 app.settings.test = "test"
 app.settings.test2 = "test"

test/io/configs/expected/types.config

@@ -36,4 +36,5 @@ server-timing-enabled = false
 server-unix-socket = ""
 server-unix-socket-mode = "660"
 admin-server-port = ""
+admin-server-config-enabled = false
 app.settings.test = "Bool False"

test/io/configs/no-defaults-env.yaml

@@ -39,3 +39,4 @@ PGRST_SERVER_TIMING_ENABLED: true
 PGRST_SERVER_UNIX_SOCKET: /tmp/pgrst_io_test.sock
 PGRST_SERVER_UNIX_SOCKET_MODE: 777
 PGRST_ADMIN_SERVER_PORT: 3001
+PGRST_ADMIN_SERVER_CONFIG_ENABLED: true

test/io/configs/no-defaults.config

@@ -36,5 +36,6 @@ server-timing-enabled = true
 server-unix-socket = "/tmp/pgrst_io_test.sock"
 server-unix-socket-mode = "777"
 admin-server-port = 3001
+admin-server-config-enabled = true
 app.settings.test = "test"
 app.settings.test2 = "test"

test/io/test_io.py

@@ -673,6 +673,15 @@ def test_admin_config(defaultenv):
     "Should get a success response from the admin server containing current configuration"
 
     with run(env=defaultenv) as postgrest:
+        response = postgrest.admin.get("/config")
+        assert response.status_code == 404
+
+    env = {
+        **defaultenv,
+        "PGRST_ADMIN_SERVER_CONFIG_ENABLED": "true",
+    }
+
+    with run(env=env) as postgrest:
         response = postgrest.admin.get("/config")
         print(response.text)
         assert response.status_code == 200
@@ -1596,3 +1605,105 @@ def test_schema_cache_startup_load_with_in_db_config(defaultenv, metapostgrest):
     response = metapostgrest.session.post("/rpc/reset_db_schemas_config")
     assert response.text == ""
     assert response.status_code == 204
+
+
+def test_jwt_cache_purges_expired_entries(defaultenv):
+    "test expired cache entries are purged on cache miss"
+
+    # The verification of actual cache size reduction is done manually, see https://github.com/PostgREST/postgrest/pull/3801#issuecomment-2620776041
+    # This test is written for code coverage of purgeExpired function
+
+    relativeSeconds = lambda sec: int(
+        (datetime.now(timezone.utc) + timedelta(seconds=sec)).timestamp()
+    )
+
+    headers = lambda sec: jwtauthheader(
+        {"role": "postgrest_test_author", "exp": relativeSeconds(sec)},
+        SECRET,
+    )
+
+    env = {
+        **defaultenv,
+        "PGRST_JWT_CACHE_MAX_LIFETIME": "86400",
+        "PGRST_JWT_SECRET": SECRET,
+        "PGRST_DB_CONFIG": "false",
+    }
+
+    with run(env=env) as postgrest:
+
+        # Generate two unique JWT tokens
+        # The 1 second sleep is needed for it generate a unique token
+        hdrs1 = headers(5)
+        postgrest.session.get("/authors_only", headers=hdrs1)
+
+        time.sleep(1)
+
+        hdrs2 = headers(5)
+        postgrest.session.get("/authors_only", headers=hdrs2)
+
+        # Wait 5 seconds for the tokens to expire
+        time.sleep(5)
+
+        hdrs3 = headers(5)
+
+        # Make another request which should cause a cache miss and so
+        # the purgeExpired function will be triggered.
+        #
+        # This should remove the 2 expired tokens but adds another to cache
+        response = postgrest.session.get("/authors_only", headers=hdrs3)
+
+        assert response.status_code == 200
+
+
+def test_pgrst_log_503_client_error_to_stderr(defaultenv):
+    "PostgREST should log 503 errors to stderr"
+
+    env = {
+        **defaultenv,
+        "PGAPPNAME": "test-io",
+    }
+
+    with run(env=env) as postgrest:
+
+        postgrest.session.get("/rpc/terminate_pgrst?appname=test-io")
+
+        output = postgrest.read_stdout(nlines=6)
+
+        log_message = '{"code":"PGRST001","details":"no connection to the server\\n","hint":null,"message":"Database client error. Retrying the connection."}\n'
+
+        assert any(log_message in line for line in output)
+
+
+def test_invalidate_jwt_cache_when_secret_changes(tmp_path, defaultenv):
+    "JWT cache should be emptied after jwt-secret is changed in a config reload"
+
+    headers = jwtauthheader({"role": "postgrest_test_author"}, SECRET)
+
+    external_secret_file = tmp_path / "jwt-secret-config"
+    external_secret_file.write_text(SECRET)
+
+    env = {
+        **defaultenv,
+        "PGRST_JWT_SECRET": f"@{external_secret_file}",
+        "PGRST_DB_CHANNEL_ENABLED": "true",
+        "PGRST_JWT_CACHE_MAX_LIFETIME": "86400",  # enable cache
+        "PGRST_DB_ANON_ROLE": "postgrest_test_anonymous",  # required for NOTIFY
+    }
+
+    with run(env=env) as postgrest:
+        response = postgrest.session.get("/authors_only", headers=headers)
+        assert response.status_code == 200  # jwt gets cached
+
+        # change external file
+        external_secret_file.write_text("invalid" * 5)
+
+        # reload config and external file with NOTIFY
+        # jwt-cache should get empty
+        response = postgrest.session.post("/rpc/reload_pgrst_config")
+        assert response.text == ""
+        assert response.status_code == 204
+        sleep_until_postgrest_config_reload()
+
+        # now the request should fail because the cached token is removed
+        response = postgrest.session.get("/authors_only", headers=headers)
+        assert response.status_code == 401

test/memory/memory-tests.sh

@@ -103,8 +103,8 @@ postJsonArrayTest(){
 echo "Running memory usage tests.."
 
 jsonKeyTest "1M" "POST" "/rpc/leak?columns=blob" "27M"
-jsonKeyTest "1M" "POST" "/leak?columns=blob" "20M"
-jsonKeyTest "1M" "PATCH" "/leak?id=eq.1&columns=blob" "20M"
+jsonKeyTest "1M" "POST" "/leak?columns=blob" "21M"
+jsonKeyTest "1M" "PATCH" "/leak?id=eq.1&columns=blob" "21M"
 
 jsonKeyTest "10M" "POST" "/rpc/leak?columns=blob" "32M"
 jsonKeyTest "10M" "POST" "/leak?columns=blob" "32M"

test/spec/Feature/Query/CustomMediaSpec.hs

@@ -375,3 +375,31 @@ spec = describe "custom media types" $ do
           { matchStatus  = 200
           , matchHeaders = ["Content-Type" <:> "application/octet-stream"]
           }
+
+  context "media type parser fails" $ do
+    it "sends media type as is" $
+      request methodGet "/items" (acceptHdrs "undefined") ""
+      `shouldRespondWith`
+      [json| {"code":"PGRST107","details":null,"hint":null,"message":"None of these media types are available: undefined"} |]
+      { matchStatus = 406 }
+
+  context "media type parser allowed characters" $ do
+    it "regression test allowing charset=utf-8" $
+      request methodPost "/rpc/overloaded_default"
+        [("Content-Type", "application/json; charset=utf-8")]
+        [json|{"must_param":1}|]
+        `shouldRespondWith`
+        [json|{"val":1}|]
+        { matchStatus = 200
+        , matchHeaders = ["Content-Type" <:> "application/json; charset=utf-8"]
+        }
+
+    it "handle unrecognized parameters leniently" $ do
+      request methodPost "/rpc/overloaded_default"
+        [("Content-Type", "application/json; $$ unrecognized-chars=ignored $$")]
+        [json|{"must_param":1}|]
+        `shouldRespondWith`
+        [json|{"val":1}|]
+        { matchStatus = 200
+        , matchHeaders = ["Content-Type" <:> "application/json; charset=utf-8"]
+        }

test/spec/SpecHelper.hs

@@ -151,6 +151,7 @@ baseCfg = let secret = Just $ encodeUtf8 "reallyreallyreallyreallyverysafe" in
   , configDbTxAllowOverride         = True
   , configDbTxRollbackAll           = True
   , configAdminServerPort           = Nothing
+  , configAdminServerConfigEnabled  = False
   , configRoleSettings              = mempty
   , configRoleIsoLvl                = mempty
   , configInternalSCSleep           = Nothing