[dev] Refactoring roadmap

[monacoremo]

With #1793, we've started the process of streamlining the codebase. This is a purely internal concern that will yield no additional features. It will, however:

• ease maintenance
• help with the onboarding of new contributors
• enable quicker implementation of new features
• further increase confidence on correctness

Next steps include (in no particular order and to be completed - please feel free to edit)

• Split CLI and Config modules (Carve CLI out of Config #1806)
• Streamline main/Main.hs, minimizing code under CPP conditional compilation (refactor: carve out modules from Main.hs #1814)
• Split steps in request processing, e.g. along the pipeline: (finished on refactor: remove SchemaCache from ApiRequest #2695)
  • Request: purely parse request, at most taking config into account. `parseRequest :: Wai.Request -> Either RequestError Request
  • Plan: Use db structure to validate and plan the request, including embeds. plan :: DbStructure -> Request -> Either PlanError QueryPlan
  • Query: Run the planned query. `query :: QueryPlan -> Transaction (Either QueryError QueryResult)
  • Response: Create a HTTP response out of the result. reponse :: Plan -> QueryResult -> Wai.Response
• Single entrypoint for Plan/Query/Respones based on GADTs refactor: Split Request, Query and Response interfaces from App #1831 (review)
• Encapsulate the Request modules behind one API (refactor: Split Request, Query and Response interfaces from App #1831)
• Encapsulate the Query modules behind on API (refactor: Split Request, Query and Response interfaces from App #1831, refactor: add Query.hs module #2488)
• Carve-out Response concerns from App, i.a. (refactor: Split Request, Query and Response interfaces from App #1831, refactor: add Response.hs module #2484)
• Split Error type along Request, Query and Response
• Stop using GHC.Show instances for string conversion (Refactor: Remove (mis)uses of GHC.Show instances #2016)
• Stop using partial functions (ones from Protolude.Conv, unsafeHead etc.)
  • Protolude.Conv.toS (Refactor: Remove uses of Protolude.Conv.toS #2017)
  • decodeUtf8 et. al
  • unsafeHead
  • ...
• Improve string handling in Query generation for additional safety and performance
• Use doctest for unit testing within modules where needed (Add doctests #2019)
• Add an ARCHITECTURE.md or similar to guide newcomers to the codebase, explaining how the major modules fit together
• Add io test for parsing the example config file Carve CLI out of Config #1806 (comment)
• Clean up how Config is loaded from different sources and parsed
• Use AppState as a monad (tbd)
• Make readPGRSTEnv redundant in Main, e.g. by making all opts optional and failing in the parser
• Sort out loading of DB schema and settings on startup
• Make imports and import aliases consistent, check them in CI using hsie (Refactor: Make import aliases consistent #2008)
• Add documentation to modules and exposed functions/types
• Represent the AppState as a sum type
• ...

Other:

• Add a postgrest-install-git-hooks script

[steve-chavez]

Putting another pending refactor here.

We had an issue where Content-Type was being considered for GET - invalid since it has no body. This happened mostly because a typing deficiency(still present). More details at #2168 (comment).

[steve-chavez]

unsafeHead went away on #2254