From cdb9caf8372916dc74469d2316e4bac724db96f8 Mon Sep 17 00:00:00 2001
From: Robert Vollmert <rob@vllmrt.net>
Date: Tue, 2 Aug 2022 17:50:11 +0200
Subject: [PATCH] refactor: rename releasePool to flushPool and document its
 intended behaviour

Also fix documentation of AppState pool field.
---
 src/PostgREST/AppState.hs | 18 +++++++++++++-----
 src/PostgREST/Workers.hs  |  2 +-
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/src/PostgREST/AppState.hs b/src/PostgREST/AppState.hs
index 72ad8ad3cf..a45f69d0cf 100644
--- a/src/PostgREST/AppState.hs
+++ b/src/PostgREST/AppState.hs
@@ -3,6 +3,7 @@
 module PostgREST.AppState
   ( AppState
   , destroy
+  , flushPool
   , getConfig
   , getDbStructure
   , getIsListenerOn
@@ -21,7 +22,6 @@ module PostgREST.AppState
   , putJsonDbS
   , putPgVersion
   , putRetryNextIn
-  , releasePool
   , signalListener
   , usePool
   , waitListener
@@ -46,7 +46,9 @@ import Protolude
 
 
 data AppState = AppState
-  { statePool         :: SQL.Pool -- | Connection pool, either a 'Connection' or a 'ConnectionError'
+  -- | Database connection pool
+  { statePool         :: SQL.Pool
+  -- | Database server version, will be updated by the connectionWorker
   , statePgVersion    :: IORef PgVersion
   -- | No schema cache at the start. Will be filled in by the connectionWorker
   , stateDbStructure  :: IORef (Maybe DbStructure)
@@ -91,7 +93,7 @@ initWithPool newPool conf =
     <*> newIORef 0
 
 destroy :: AppState -> IO ()
-destroy = releasePool
+destroy AppState{..} = SQL.release statePool
 
 initPool :: AppConfig -> IO SQL.Pool
 initPool AppConfig{..} =
@@ -100,8 +102,14 @@ initPool AppConfig{..} =
 usePool :: AppState -> SQL.Session a -> IO (Either SQL.UsageError a)
 usePool AppState{..} = SQL.use statePool
 
-releasePool :: AppState -> IO ()
-releasePool AppState{..} = SQL.release statePool
+-- | Flush the connection pool so that any future use of the pool will
+-- use connections freshly established after this call.
+--
+-- FIXME: #2401 Connections that are in-use during the call to flushPool
+-- will currently be returned to the pool and reused afterwards, in
+-- conflict with the intention.
+flushPool :: AppState -> IO ()
+flushPool AppState{..} = SQL.release statePool
 
 getPgVersion :: AppState -> IO PgVersion
 getPgVersion = readIORef . statePgVersion
diff --git a/src/PostgREST/Workers.hs b/src/PostgREST/Workers.hs
index 9deae36ea6..69c7c55244 100644
--- a/src/PostgREST/Workers.hs
+++ b/src/PostgREST/Workers.hs
@@ -109,7 +109,7 @@ connectionWorker appState = do
 connectionStatus :: AppState -> IO ConnectionStatus
 connectionStatus appState =
   retrying retrySettings shouldRetry $
-    const $ AppState.releasePool appState >> getConnectionStatus
+    const $ AppState.flushPool appState >> getConnectionStatus
   where
     retrySettings = capDelay delayMicroseconds $ exponentialBackoff backoffMicroseconds
     delayMicroseconds = 32000000 -- 32 seconds