add: support running admin server on unix socket

This is useful when multiple instances run on the same machine, for
example behind a proxy. Unix sockets for web and admin servers can then
be put in the same folder for each instance.

Can be helpful when writing tests as well.

CHANGELOG.md

@@ -14,6 +14,7 @@ All notable changes to this project will be documented in this file. From versio
 - Add config `db-timezone-enabled` for optional querying of timezones by @taimoorzaeem in #4751
 - Log schema cache queries timings on `log-level=debug` by @steve-chavez in #4805
 - Add GHC runtime metrics to the metrics endpoint by @mkleczek in #4862
+- Support running the admin server on a unix socket by @wolfgangwalther in #5003
 
 ### Fixed
 

docs/references/admin_server.rst

@@ -3,7 +3,7 @@
 Admin Server
 ############
 
-PostgREST provides an admin server that can be enabled by setting :ref:`admin-server-port`.
+PostgREST provides an admin server that can be enabled by setting :ref:`admin-server-port` or `:ref:`admin-server-unix-socket`.
 
 .. _health_check:
 

docs/references/configuration.rst

@@ -176,6 +176,46 @@ admin-server-port
 
   Specifies the port for the :ref:`admin_server`. Cannot be equal to :ref:`server-port`.
 
+.. _admin-server-unix-socket:
+
+admin-server-unix-socket
+------------------------
+
+  =============== =================================
+  **Type**        String
+  **Default**     `n/a`
+  **Reloadable**  N
+  **Environment** PGRST_ADMIN_SERVER_UNIX_SOCKET
+  **In-Database** `n/a`
+  =============== =================================
+
+  `Unix domain socket <https://en.wikipedia.org/wiki/Unix_domain_socket>`_ where to bind the :ref:`admin_server`.
+  If specified, this takes precedence over :ref:`admin-server-port`. Example:
+
+  .. code:: bash
+
+    admin-server-unix-socket = "/tmp/pgrst-admin.sock"
+
+.. _admin-server-unix-socket-mode:
+
+admin-server-unix-socket-mode
+-----------------------------
+
+  =============== ===================================
+  **Type**        String
+  **Default**     660
+  **Reloadable**  N
+  **Environment** PGRST_ADMIN_SERVER_UNIX_SOCKET_MODE
+  **In-Database** `n/a`
+  =============== ===================================
+
+  `Unix file mode <https://en.wikipedia.org/wiki/File_system_permissions>`_ to be set for the socket specified in :ref:`admin-server-unix-socket`
+  Needs to be a valid octal between 600 and 777.
+
+  .. code:: bash
+
+    admin-server-unix-socket-mode = "660"
+
 .. _app.settings.*:
 
 app.settings.*

src/PostgREST/App.hs

@@ -265,10 +265,14 @@ initSockets AppConfig{..} = do
     Just path -> createAndBindDomainSocket path configServerUnixSocketMode
     Nothing -> bindPortTCP configServerPort (fromString $ T.unpack configServerHost)
 
-  adminSock <- case configAdminServerPort of
+  adminSock <- case configAdminServerUnixSocket of
-    Just adminPort -> do
+    Just path -> do
-      adminSock <- bindPortTCP adminPort (fromString $ T.unpack configAdminServerHost)
+      adminSock <- createAndBindDomainSocket path configAdminServerUnixSocketMode
       pure $ Just adminSock
-    Nothing -> pure Nothing
+    Nothing -> case configAdminServerPort of
+      Just adminPort -> do
+        adminSock <- bindPortTCP adminPort (fromString $ T.unpack configAdminServerHost)
+        pure $ Just adminSock
+      Nothing -> pure Nothing
 
   pure (sock, adminSock)

src/PostgREST/Config.hs

@@ -78,55 +78,57 @@ audMatchesCfg :: AppConfig -> Text -> Bool
 audMatchesCfg =  maybe (const True) (==) . configJwtAudience
 
 data AppConfig = AppConfig
-  { configAppSettings              :: [(Text, Text)]
+  { configAppSettings               :: [(Text, Text)]
-  , configClientErrorVerbosity     :: Verbosity
+  , configClientErrorVerbosity      :: Verbosity
-  , configDbAggregates             :: Bool
+  , configDbAggregates              :: Bool
-  , configDbAnonRole               :: Maybe BS.ByteString
+  , configDbAnonRole                :: Maybe BS.ByteString
-  , configDbChannel                :: Text
+  , configDbChannel                 :: Text
-  , configDbChannelEnabled         :: Bool
+  , configDbChannelEnabled          :: Bool
-  , configDbExtraSearchPath        :: [Text]
+  , configDbExtraSearchPath         :: [Text]
-  , configDbHoistedTxSettings      :: [Text]
+  , configDbHoistedTxSettings       :: [Text]
-  , configDbMaxRows                :: Maybe Integer
+  , configDbMaxRows                 :: Maybe Integer
-  , configDbPlanEnabled            :: Bool
+  , configDbPlanEnabled             :: Bool
-  , configDbPoolSize               :: Int
+  , configDbPoolSize                :: Int
-  , configDbPoolAcquisitionTimeout :: Int
+  , configDbPoolAcquisitionTimeout  :: Int
-  , configDbPoolMaxLifetime        :: Int
+  , configDbPoolMaxLifetime         :: Int
-  , configDbPoolMaxIdletime        :: Int
+  , configDbPoolMaxIdletime         :: Int
-  , configDbPoolAutomaticRecovery  :: Bool
+  , configDbPoolAutomaticRecovery   :: Bool
-  , configDbPreRequest             :: Maybe QualifiedIdentifier
+  , configDbPreRequest              :: Maybe QualifiedIdentifier
-  , configDbPreparedStatements     :: Bool
+  , configDbPreparedStatements      :: Bool
-  , configDbRootSpec               :: Maybe QualifiedIdentifier
+  , configDbRootSpec                :: Maybe QualifiedIdentifier
-  , configDbSchemas                :: NonEmpty Text
+  , configDbSchemas                 :: NonEmpty Text
-  , configDbConfig                 :: Bool
+  , configDbConfig                  :: Bool
-  , configDbPreConfig              :: Maybe QualifiedIdentifier
+  , configDbPreConfig               :: Maybe QualifiedIdentifier
-  , configDbTimezoneEnabled        :: Bool
+  , configDbTimezoneEnabled         :: Bool
-  , configDbTxAllowOverride        :: Bool
+  , configDbTxAllowOverride         :: Bool
-  , configDbTxRollbackAll          :: Bool
+  , configDbTxRollbackAll           :: Bool
-  , configDbUri                    :: Text
+  , configDbUri                     :: Text
-  , configFilePath                 :: Maybe FilePath
+  , configFilePath                  :: Maybe FilePath
-  , configJWKS                     :: Maybe JwkSet
+  , configJWKS                      :: Maybe JwkSet
-  , configJwtAudience              :: Maybe Text
+  , configJwtAudience               :: Maybe Text
-  , configJwtRoleClaimKey          :: JSPath
+  , configJwtRoleClaimKey           :: JSPath
-  , configJwtSecret                :: Maybe BS.ByteString
+  , configJwtSecret                 :: Maybe BS.ByteString
-  , configJwtSecretIsBase64        :: Bool
+  , configJwtSecretIsBase64         :: Bool
-  , configJwtCacheMaxEntries       :: Int
+  , configJwtCacheMaxEntries        :: Int
-  , configLogLevel                 :: LogLevel
+  , configLogLevel                  :: LogLevel
-  , configLogQuery                 :: Bool
+  , configLogQuery                  :: Bool
-  , configOpenApiMode              :: OpenAPIMode
+  , configOpenApiMode               :: OpenAPIMode
-  , configOpenApiSecurityActive    :: Bool
+  , configOpenApiSecurityActive     :: Bool
-  , configOpenApiServerProxyUri    :: Maybe Text
+  , configOpenApiServerProxyUri     :: Maybe Text
-  , configServerCorsAllowedOrigins :: [Text]
+  , configServerCorsAllowedOrigins  :: [Text]
-  , configServerHost               :: Text
+  , configServerHost                :: Text
-  , configServerPort               :: Int
+  , configServerPort                :: Int
-  , configServerTraceHeader        :: Maybe (CI.CI BS.ByteString)
+  , configServerTraceHeader         :: Maybe (CI.CI BS.ByteString)
-  , configServerTimingEnabled      :: Bool
+  , configServerTimingEnabled       :: Bool
-  , configServerUnixSocket         :: Maybe FilePath
+  , configServerUnixSocket          :: Maybe FilePath
-  , configServerUnixSocketMode     :: FileMode
+  , configServerUnixSocketMode      :: FileMode
-  , configAdminServerHost          :: Text
+  , configAdminServerHost           :: Text
-  , configAdminServerPort          :: Maybe Int
+  , configAdminServerPort           :: Maybe Int
-  , configRoleSettings             :: RoleSettings
+  , configAdminServerUnixSocket     :: Maybe FilePath
-  , configRoleIsoLvl               :: RoleIsolationLvl
+  , configAdminServerUnixSocketMode :: FileMode
-  , configInternalSCQuerySleep     :: Maybe Int32
+  , configRoleSettings              :: RoleSettings
+  , configRoleIsoLvl                :: RoleIsolationLvl
+  , configInternalSCQuerySleep      :: Maybe Int32
   }
 
 data LogLevel = LogCrit | LogError | LogWarn | LogInfo | LogDebug
@@ -207,6 +209,8 @@ toText conf =
       ,("server-unix-socket-mode",   q . T.pack . showSocketMode)
       ,("admin-server-host",         q . configAdminServerHost)
       ,("admin-server-port",             maybe "\"\"" show . configAdminServerPort)
+      ,("admin-server-unix-socket",  q . maybe mempty T.pack . configAdminServerUnixSocket)
+      ,("admin-server-unix-socket-mode", q . T.pack . showAdminSocketMode)
       ]
 
     -- quote all app.settings
@@ -230,6 +234,7 @@ toText conf =
       where
         secret = fromMaybe mempty $ configJwtSecret c
     showSocketMode c = showOct (configServerUnixSocketMode c) mempty
+    showAdminSocketMode c = showOct (configAdminServerUnixSocketMode c) mempty
 
 -- This class is needed for the polymorphism of overrideFromDbOrEnvironment
 -- because C.required and C.optional have different signatures
@@ -323,6 +328,8 @@ parser optPath env dbSettings roleSettings roleIsolationLvl =
     <*> (defaultServerHost <$> optWithAlias (optString "admin-server-host")
                                             (optString "server-host"))
     <*> parseAdminServerPort "admin-server-port"
+    <*> (fmap T.unpack <$> optString "admin-server-unix-socket")
+    <*> parseSocketFileMode "admin-server-unix-socket-mode"
     <*> pure roleSettings
     <*> pure roleIsolationLvl
     <*> optInt "internal-schema-cache-query-sleep"
@@ -372,10 +379,10 @@ parser optPath env dbSettings roleSettings roleIsolationLvl =
         Just fileModeText ->
           case readOct $ T.unpack fileModeText of
             []              ->
-              fail "Invalid server-unix-socket-mode: not an octal"
+              fail $ "Invalid " <> T.unpack k <> ": not an octal"
             (fileMode, _):_ ->
               if fileMode < 384 || fileMode > 511
-                then fail "Invalid server-unix-socket-mode: needs to be between 600 and 777"
+                then fail $ "Invalid " <> T.unpack k <> ": needs to be between 600 and 777"
                 else pure fileMode
 
     parseOpenAPIMode :: C.Key -> C.Parser C.Config OpenAPIMode

test/io/configs/expected/aliases.config

@@ -1,5 +1,7 @@
 admin-server-host = "!4"
 admin-server-port = ""
+admin-server-unix-socket = ""
+admin-server-unix-socket-mode = "660"
 client-error-verbosity = "verbose"
 db-aggregates-enabled = false
 db-anon-role = ""

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

@@ -1,5 +1,7 @@
 admin-server-host = "!4"
 admin-server-port = ""
+admin-server-unix-socket = ""
+admin-server-unix-socket-mode = "660"
 client-error-verbosity = "verbose"
 db-aggregates-enabled = false
 db-anon-role = ""

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

@@ -1,5 +1,7 @@
 admin-server-host = "!4"
 admin-server-port = ""
+admin-server-unix-socket = ""
+admin-server-unix-socket-mode = "660"
 client-error-verbosity = "verbose"
 db-aggregates-enabled = false
 db-anon-role = ""

test/io/configs/expected/defaults.config

@@ -1,5 +1,7 @@
 admin-server-host = "!4"
 admin-server-port = ""
+admin-server-unix-socket = ""
+admin-server-unix-socket-mode = "660"
 client-error-verbosity = "verbose"
 db-aggregates-enabled = false
 db-anon-role = ""

test/io/configs/expected/jspath-str-op-dump1.config

@@ -1,5 +1,7 @@
 admin-server-host = "!4"
 admin-server-port = ""
+admin-server-unix-socket = ""
+admin-server-unix-socket-mode = "660"
 client-error-verbosity = "verbose"
 db-aggregates-enabled = false
 db-anon-role = ""

test/io/configs/expected/jspath-str-op-dump2.config

@@ -1,5 +1,7 @@
 admin-server-host = "!4"
 admin-server-port = ""
+admin-server-unix-socket = ""
+admin-server-unix-socket-mode = "660"
 client-error-verbosity = "verbose"
 db-aggregates-enabled = false
 db-anon-role = ""

test/io/configs/expected/jspath-str-op-dump3.config

@@ -1,5 +1,7 @@
 admin-server-host = "!4"
 admin-server-port = ""
+admin-server-unix-socket = ""
+admin-server-unix-socket-mode = "660"
 client-error-verbosity = "verbose"
 db-aggregates-enabled = false
 db-anon-role = ""

test/io/configs/expected/jspath-str-op-dump4.config

@@ -1,5 +1,7 @@
 admin-server-host = "!4"
 admin-server-port = ""
+admin-server-unix-socket = ""
+admin-server-unix-socket-mode = "660"
 client-error-verbosity = "verbose"
 db-aggregates-enabled = false
 db-anon-role = ""

test/io/configs/expected/jspath-str-op-dump5.config

@@ -1,5 +1,7 @@
 admin-server-host = "!4"
 admin-server-port = ""
+admin-server-unix-socket = ""
+admin-server-unix-socket-mode = "660"
 client-error-verbosity = "verbose"
 db-aggregates-enabled = false
 db-anon-role = ""

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

@@ -1,5 +1,7 @@
 admin-server-host = "127.0.0.1"
 admin-server-port = 3001
+admin-server-unix-socket = "/tmp/admin_io_test.sock"
+admin-server-unix-socket-mode = "666"
 app.settings.test = "test"
 app.settings.test2 = "test"
 client-error-verbosity = "minimal"

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

@@ -1,5 +1,7 @@
 admin-server-host = "127.0.0.1"
 admin-server-port = 3001
+admin-server-unix-socket = "/tmp/admin_io_test.sock"
+admin-server-unix-socket-mode = "666"
 app.settings.test = "test"
 app.settings.test2 = "test"
 client-error-verbosity = "minimal"

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

@@ -1,5 +1,7 @@
 admin-server-host = "127.0.0.1"
 admin-server-port = 3001
+admin-server-unix-socket = "/tmp/admin_io_test.sock"
+admin-server-unix-socket-mode = "666"
 app.settings.test = "test"
 app.settings.test2 = "test"
 client-error-verbosity = "minimal"

test/io/configs/expected/types.config

@@ -1,5 +1,7 @@
 admin-server-host = "!4"
 admin-server-port = ""
+admin-server-unix-socket = ""
+admin-server-unix-socket-mode = "660"
 app.settings.test = "Bool False"
 client-error-verbosity = "verbose"
 db-aggregates-enabled = false

test/io/configs/expected/utf-8.config

@@ -1,5 +1,7 @@
 admin-server-host = "!4"
 admin-server-port = ""
+admin-server-unix-socket = ""
+admin-server-unix-socket-mode = "660"
 client-error-verbosity = "verbose"
 db-aggregates-enabled = false
 db-anon-role = ""

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

@@ -43,3 +43,5 @@ PGRST_SERVER_UNIX_SOCKET: /tmp/pgrst_io_test.sock
 PGRST_SERVER_UNIX_SOCKET_MODE: 777
 PGRST_ADMIN_SERVER_HOST: 127.0.0.1
 PGRST_ADMIN_SERVER_PORT: 3001
+PGRST_ADMIN_SERVER_UNIX_SOCKET: /tmp/admin_io_test.sock
+PGRST_ADMIN_SERVER_UNIX_SOCKET_MODE: 666

test/io/configs/no-defaults.config

@@ -40,5 +40,7 @@ server-unix-socket = "/tmp/pgrst_io_test.sock"
 server-unix-socket-mode = "777"
 admin-server-port = 3001
 admin-server-host = "127.0.0.1"
+admin-server-unix-socket = "/tmp/admin_io_test.sock"
+admin-server-unix-socket-mode = "666"
 app.settings.test = "test"
 app.settings.test2 = "test"

test/io/fixtures/db_config.sql

@@ -39,6 +39,8 @@ ALTER ROLE db_config_authenticator IN DATABASE other SET pgrst.db_max_rows = '11
 -- non-reloadable configs
 ALTER ROLE db_config_authenticator SET pgrst.admin_server_host = 'ignored';
 ALTER ROLE db_config_authenticator SET pgrst.admin_server_port = 'ignored';
+ALTER ROLE db_config_authenticator SET pgrst.admin_server_unix_socket = 'ignored';
+ALTER ROLE db_config_authenticator SET pgrst.admin_server_unix_socket_mode = 'ignored';
 ALTER ROLE db_config_authenticator SET pgrst.db_channel = 'ignored';
 ALTER ROLE db_config_authenticator SET pgrst.db_channel_enabled = 'ignored';
 ALTER ROLE db_config_authenticator SET pgrst.db_config = 'true';

test/io/postgrest.py

@@ -124,10 +124,14 @@ def run(
             env["PGRST_SERVER_UNIX_SOCKET"] = str(socketfile)
             baseurl = "http+unix://" + urllib.parse.quote_plus(str(socketfile))
 
-        adminport = freeport(used_ports=[port]) if admin_port is None else admin_port
+        if admin_port:
-        env["PGRST_ADMIN_SERVER_PORT"] = str(adminport)
+            env["PGRST_ADMIN_SERVER_PORT"] = str(admin_port)
-        adminhost = f"[{host}]" if host and is_ipv6(host) else localhost
+            adminhost = f"[{host}]" if host and is_ipv6(host) else localhost
-        adminurl = f"http://{adminhost}:{adminport}"
+            adminurl = f"http://{adminhost}:{admin_port}"
+        else:
+            socketfile = pathlib.Path(tmpdir) / "admin.sock"
+            env["PGRST_ADMIN_SERVER_UNIX_SOCKET"] = str(socketfile)
+            adminurl = "http+unix://" + urllib.parse.quote_plus(str(socketfile))
 
         command = [POSTGREST_BIN]
         env["HPCTIXFILE"] = hpctixfile()

test/io/test_cli.py

@@ -305,8 +305,9 @@ def test_cli_ready_flag_success(host, defaultenv):
     "test PostgREST ready flag succeeds when ready"
 
     port = freeport()
+    admin_port = freeport(used_ports=[port])
 
-    with run(env=defaultenv, host=host, port=port) as postgrest:
+    with run(env=defaultenv, host=host, port=port, admin_port=admin_port) as postgrest:
         output = cli(["--ready"], env=postgrest.config)
 
         (admin_host, admin_port) = get_admin_host_and_port_from_config(postgrest.config)
@@ -330,8 +331,9 @@ def test_cli_ready_flag_fail_when_schema_cache_not_loaded(defaultenv, metapostgr
     }
 
     port = freeport()
+    admin_port = freeport(used_ports=[port])
 
-    with run(env=env, port=port) as postgrest:
+    with run(env=env, port=port, admin_port=admin_port) as postgrest:
         # The schema cache query takes at least 500ms, due to PGRST_INTERNAL_SCHEMA_CACHE_QUERY_SLEEP above.
         # Make it impossible to load the schema cache, by setting statement timeout to 400ms.
         set_statement_timeout(metapostgrest, role, 400)
@@ -351,11 +353,11 @@ def test_cli_ready_flag_fail_with_http_exception(defaultenv):
     "test PostgREST ready flag fail when http exception occurs"
 
     port = freeport()
+    admin_port = freeport(used_ports=[port])
 
     # when healthcheck process sends the request to a wrong endpoint
-    with run(env=defaultenv, port=port) as postgrest:
+    with run(env=defaultenv, port=port, admin_port=admin_port) as postgrest:
         # we set it to some freeport where server and admin server is not running
-        admin_port = int(postgrest.config["PGRST_ADMIN_SERVER_PORT"])
         used_ports = [port, admin_port]
 
         postgrest.config["PGRST_ADMIN_SERVER_PORT"] = str(freeport(used_ports))
@@ -368,7 +370,7 @@ def test_cli_ready_flag_fail_with_http_exception(defaultenv):
         )
 
     # When client sends the request to invalid URL
-    with run(env=defaultenv, port=port) as postgrest:
+    with run(env=defaultenv, port=port, admin_port=admin_port) as postgrest:
         postgrest.config["PGRST_ADMIN_SERVER_PORT"] = str(-1)
         output = cli(["--ready"], env=postgrest.config, expect_error=True)
         (admin_host, admin_port) = get_admin_host_and_port_from_config(postgrest.config)
@@ -382,7 +384,7 @@ def test_cli_ready_flag_fail_with_special_hostname(defaultenv):
     port = freeport()
     host = "*4"
 
-    with run(env=defaultenv, host=host, port=port) as postgrest:
+    with run(env=defaultenv, host=host, port=port, admin_port=freeport()) as postgrest:
         output = cli(["--ready"], env=postgrest.config, expect_error=True)
 
         assert (

test/observability/ObsHelper.hs

@@ -115,6 +115,8 @@ baseCfg = let secret = encodeUtf8 "reallyreallyreallyreallyverysafe" in
   , configDbTxRollbackAll           = True
   , configAdminServerHost           = "localhost"
   , configAdminServerPort           = Nothing
+  , configAdminServerUnixSocket     = Nothing
+  , configAdminServerUnixSocketMode = 432
   , configRoleSettings              = mempty
   , configRoleIsoLvl                = mempty
   , configInternalSCQuerySleep      = Nothing

test/spec/SpecHelper.hs

@@ -156,6 +156,8 @@ baseCfg = let secret = encodeUtf8 "reallyreallyreallyreallyverysafe" in
   , configDbTxRollbackAll           = True
   , configAdminServerHost           = "localhost"
   , configAdminServerPort           = Nothing
+  , configAdminServerUnixSocket     = Nothing
+  , configAdminServerUnixSocketMode = 432
   , configRoleSettings              = mempty
   , configRoleIsoLvl                = mempty
   , configInternalSCQuerySleep      = Nothing