add basic ARCHITECTURE.md (#2503)

* refactor: move ApiRequest a top-level module
* refactor: rename DbStructure to SchemaCache
* refactor: GucHeader inside Response
* refactor: admin app to Workers

src/PostgREST/App.hs

@@ -30,29 +30,28 @@ import qualified Hasql.Transaction.Sessions as SQL
 import qualified Network.Wai                as Wai
 import qualified Network.Wai.Handler.Warp   as Warp
 
-import qualified PostgREST.Admin              as Admin
-import qualified PostgREST.AppState           as AppState
-import qualified PostgREST.Auth               as Auth
-import qualified PostgREST.Cors               as Cors
-import qualified PostgREST.Error              as Error
-import qualified PostgREST.Logger             as Logger
-import qualified PostgREST.Plan               as Plan
-import qualified PostgREST.Query              as Query
-import qualified PostgREST.Request.ApiRequest as ApiRequest
-import qualified PostgREST.Request.Types      as ApiRequestTypes
-import qualified PostgREST.Response           as Response
+import qualified PostgREST.ApiRequest       as ApiRequest
+import qualified PostgREST.ApiRequest.Types as ApiRequestTypes
+import qualified PostgREST.AppState         as AppState
+import qualified PostgREST.Auth             as Auth
+import qualified PostgREST.Cors             as Cors
+import qualified PostgREST.Error            as Error
+import qualified PostgREST.Logger           as Logger
+import qualified PostgREST.Plan             as Plan
+import qualified PostgREST.Query            as Query
+import qualified PostgREST.Response         as Response
+import qualified PostgREST.Workers          as Workers
 
-import PostgREST.AppState           (AppState)
-import PostgREST.Auth               (AuthResult (..))
-import PostgREST.Config             (AppConfig (..), LogLevel (..))
-import PostgREST.Config.PgVersion   (PgVersion (..))
-import PostgREST.DbStructure        (DbStructure (..))
-import PostgREST.Error              (Error)
-import PostgREST.Query              (DbHandler)
-import PostgREST.Request.ApiRequest (Action (..), ApiRequest (..),
-                                     Mutation (..), Target (..))
-import PostgREST.Version            (prettyVersion)
-import PostgREST.Workers            (connectionWorker, listener)
+import PostgREST.ApiRequest       (Action (..), ApiRequest (..),
+                                   Mutation (..), Target (..))
+import PostgREST.AppState         (AppState)
+import PostgREST.Auth             (AuthResult (..))
+import PostgREST.Config           (AppConfig (..), LogLevel (..))
+import PostgREST.Config.PgVersion (PgVersion (..))
+import PostgREST.Error            (Error)
+import PostgREST.Query            (DbHandler)
+import PostgREST.SchemaCache      (SchemaCache (..))
+import PostgREST.Version          (prettyVersion)
 
 import Protolude hiding (Handler)
 
@@ -65,17 +64,14 @@ type SocketRunner = Warp.Settings -> Wai.Application -> FileMode -> FilePath ->
 run :: SignalHandlerInstaller -> Maybe SocketRunner -> AppState -> IO ()
 run installHandlers maybeRunWithSocket appState = do
   conf@AppConfig{..} <- AppState.getConfig appState
-  connectionWorker appState -- Loads the initial DbStructure
+  Workers.connectionWorker appState -- Loads the initial SchemaCache
   installHandlers appState
   -- reload schema cache + config on NOTIFY
-  when configDbChannelEnabled $ listener appState
+  Workers.runListener conf appState
 
-  let app = postgrest configLogLevel appState (connectionWorker appState)
-      adminApp = Admin.postgrestAdmin appState conf
+  Workers.runAdmin conf appState $ serverSettings conf
 
-  whenJust configAdminServerPort $ \adminPort -> do
-    AppState.logWithZTime appState $ "Admin server listening on port " <> show adminPort
-    void . forkIO $ Warp.runSettings (serverSettings conf & setPort adminPort) adminApp
+  let app = postgrest configLogLevel appState (Workers.connectionWorker appState)
 
   case configServerUnixSocket of
     Just socket ->
@@ -90,9 +86,6 @@ run installHandlers maybeRunWithSocket appState = do
       do
         AppState.logWithZTime appState $ "Listening on port " <> show configServerPort
         Warp.runSettings (serverSettings conf) app
-  where
-    whenJust :: Applicative m => Maybe a -> (a -> m ()) -> m ()
-    whenJust mg f = maybe (pure ()) f mg
 
 serverSettings :: AppConfig -> Warp.Settings
 serverSettings AppConfig{..} =
@@ -113,14 +106,14 @@ postgrest logLevel appState connWorker =
       Left err -> respond $ Error.errorResponseFor err
       Right authResult -> do
         conf <- AppState.getConfig appState
-        maybeDbStructure <- AppState.getDbStructure appState
+        maybeSchemaCache <- AppState.getSchemaCache appState
         pgVer <- AppState.getPgVersion appState
         jsonDbS <- AppState.getJsonDbS appState
 
         let
           eitherResponse :: IO (Either Error Wai.Response)
           eitherResponse =
-            runExceptT $ postgrestResponse appState conf maybeDbStructure jsonDbS pgVer authResult req
+            runExceptT $ postgrestResponse appState conf maybeSchemaCache jsonDbS pgVer authResult req
 
         response <- either Error.errorResponseFor identity <$> eitherResponse
         -- Launch the connWorker when the connection is down.  The postgrest
@@ -135,17 +128,17 @@ postgrest logLevel appState connWorker =
 postgrestResponse
   :: AppState.AppState
   -> AppConfig
-  -> Maybe DbStructure
+  -> Maybe SchemaCache
   -> ByteString
   -> PgVersion
   -> AuthResult
   -> Wai.Request
   -> Handler IO Wai.Response
-postgrestResponse appState conf@AppConfig{..} maybeDbStructure jsonDbS pgVer authResult@AuthResult{..} req = do
-  dbStructure <-
-    case maybeDbStructure of
-      Just dbStructure ->
-        return dbStructure
+postgrestResponse appState conf@AppConfig{..} maybeSchemaCache jsonDbS pgVer authResult@AuthResult{..} req = do
+  sCache <-
+    case maybeSchemaCache of
+      Just sCache ->
+        return sCache
       Nothing ->
         throwError Error.NoSchemaCacheError
 
@@ -153,10 +146,10 @@ postgrestResponse appState conf@AppConfig{..} maybeDbStructure jsonDbS pgVer aut
 
   apiRequest <-
     liftEither . mapLeft Error.ApiRequestError $
-      ApiRequest.userApiRequest conf dbStructure req body
+      ApiRequest.userApiRequest conf sCache req body
 
   Response.optionalRollback conf apiRequest $
-    handleRequest authResult conf appState (Query.txMode apiRequest) (Just authRole /= configDbAnonRole) configDbPreparedStatements jsonDbS pgVer apiRequest dbStructure
+    handleRequest authResult conf appState (Query.txMode apiRequest) (Just authRole /= configDbAnonRole) configDbPreparedStatements jsonDbS pgVer apiRequest sCache
 
 runDbHandler :: AppState.AppState -> SQL.Mode -> Bool -> Bool -> DbHandler b -> Handler IO b
 runDbHandler appState mode authenticated prepared handler = do
@@ -170,45 +163,45 @@ runDbHandler appState mode authenticated prepared handler = do
 
   liftEither resp
 
-handleRequest :: AuthResult -> AppConfig -> AppState.AppState -> SQL.Mode -> Bool -> Bool -> ByteString -> PgVersion -> ApiRequest -> DbStructure -> Handler IO Wai.Response
-handleRequest AuthResult{..} conf appState mode authenticated prepared jsonDbS pgVer apiReq@ApiRequest{..} dbStructure =
+handleRequest :: AuthResult -> AppConfig -> AppState.AppState -> SQL.Mode -> Bool -> Bool -> ByteString -> PgVersion -> ApiRequest -> SchemaCache -> Handler IO Wai.Response
+handleRequest AuthResult{..} conf appState mode authenticated prepared jsonDbS pgVer apiReq@ApiRequest{..} sCache =
   case (iAction, iTarget) of
     (ActionRead headersOnly, TargetIdent identifier) -> do
-      rPlan <- liftEither $ Plan.readPlan identifier conf dbStructure apiReq
+      rPlan <- liftEither $ Plan.readPlan identifier conf sCache apiReq
       resultSet <- runQuery $ Query.readQuery rPlan conf apiReq
       return $ Response.readResponse headersOnly identifier apiReq resultSet
 
     (ActionMutate MutationCreate, TargetIdent identifier) -> do
-      mrPlan <- liftEither $ Plan.mutateReadPlan MutationCreate apiReq identifier conf dbStructure
+      mrPlan <- liftEither $ Plan.mutateReadPlan MutationCreate apiReq identifier conf sCache
       resultSet <- runQuery $ Query.createQuery mrPlan apiReq conf
       return $ Response.createResponse identifier mrPlan apiReq resultSet
 
     (ActionMutate MutationUpdate, TargetIdent identifier) -> do
-      mrPlan <- liftEither $ Plan.mutateReadPlan MutationUpdate apiReq identifier conf dbStructure
+      mrPlan <- liftEither $ Plan.mutateReadPlan MutationUpdate apiReq identifier conf sCache
       resultSet <- runQuery $ Query.updateQuery mrPlan apiReq conf
       return $ Response.updateResponse apiReq resultSet
 
     (ActionMutate MutationSingleUpsert, TargetIdent identifier) -> do
-      mrPlan <- liftEither $ Plan.mutateReadPlan MutationSingleUpsert apiReq identifier conf dbStructure
+      mrPlan <- liftEither $ Plan.mutateReadPlan MutationSingleUpsert apiReq identifier conf sCache
       resultSet <- runQuery $ Query.singleUpsertQuery mrPlan apiReq conf
       return $ Response.singleUpsertResponse apiReq resultSet
 
     (ActionMutate MutationDelete, TargetIdent identifier) -> do
-      mrPlan <- liftEither $ Plan.mutateReadPlan MutationDelete apiReq identifier conf dbStructure
+      mrPlan <- liftEither $ Plan.mutateReadPlan MutationDelete apiReq identifier conf sCache
       resultSet <- runQuery $ Query.deleteQuery mrPlan apiReq conf
       return $ Response.deleteResponse apiReq resultSet
 
     (ActionInvoke invMethod, TargetProc proc _) -> do
-      cPlan <- liftEither $ Plan.callReadPlan proc conf dbStructure apiReq
+      cPlan <- liftEither $ Plan.callReadPlan proc conf sCache apiReq
       resultSet <- runQuery $ Query.invokeQuery proc cPlan apiReq conf
       return $ Response.invokeResponse invMethod proc apiReq resultSet
 
     (ActionInspect headersOnly, TargetDefaultSpec tSchema) -> do
-      oaiResult <- runQuery $ Query.openApiQuery dbStructure pgVer conf tSchema
-      return $ Response.openApiResponse headersOnly oaiResult conf dbStructure iSchema iNegotiatedByProfile
+      oaiResult <- runQuery $ Query.openApiQuery sCache pgVer conf tSchema
+      return $ Response.openApiResponse headersOnly oaiResult conf sCache iSchema iNegotiatedByProfile
 
     (ActionInfo, _) ->
-      return $ Response.infoResponse iTarget dbStructure
+      return $ Response.infoResponse iTarget sCache
 
     _ ->
       -- This is unreachable as the ApiRequest.hs rejects it before