diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 6d0490c3a..000000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,52 +0,0 @@ -# Architecture - -This document describes the high-level architecture of PostgREST. - -## Bird's Eye View - -![PostgREST Architecture](docs/_static/arch.png) - -On the highest level, PostgREST processes the user HTTP request, if it's accepted it generates a SQL query, executes it, and produces a response. - -## Code Map - -This section talks briefly about various important modules. - -The starting points of the program are `main/Main.hs` -> `src/PostgREST/CLI.hs` -> `src/PostgREST/App.hs`. - -`App.hs` is then in charge of composing the different modules. - -### Auth - -It authenticates the request using JWT. - -### ApiRequest - -PostgREST operates over two types of resources: database relations (tables or views) and database functions; providing different representations (depending on the media type) -for them. - -This module is in charge of representing the operation over an `ApiRequest` type. It parses the URL querystring following PostgREST syntax, the request headers, and the request body -(if possible it avoids parsing the body and sends it directly to the db). - -A request might be rejected at this level if it's invalid. For example when providing an unknown media type to PostgREST or using an unknown HTTP method. - -### Plan - -Using the Schema Cache, this module fills in SQL details that the user might have not specified (like an `ON CONFLICT (pk)` clause ). - -A request might be rejected at this level if it's invalid. For example when doing resource embedding on a nonexistent resource. - -### Query - -This module generates SQL queries that are parametrized and prepared. Only at this stage a connection from the pool might be used. - -A query might fail (and be rollbacked) at this level if it doesn't comply to certain conditions, e.g. by not returning a single row when a ``Accept: application/vnd.pgrst.object`` -header is specified. - -### SchemaCache - -This queries the PostgreSQL system catalogs and caches the results into a SchemaCache type, which then is used by the other modules. - -### Admin - -Admin server exposed in another port, it provides health checks. diff --git a/docs/explanations/architecture.rst b/docs/explanations/architecture.rst new file mode 100644 index 000000000..e926f2c19 --- /dev/null +++ b/docs/explanations/architecture.rst @@ -0,0 +1,63 @@ +Architecture +############ + +This page describes the architecture of PostgREST. + +Bird's Eye View +=============== + +.. image:: ../_static/arch.png + +Code Map +======== + +This section talks briefly about various important modules. + +The starting points of the program are: + +- `Main.hs `_ +- `CLI.hs `_ +- `App.hs `_ + +``App.hs`` is then in charge of composing the different modules. + +Auth +---- + +`Auth.hs `_ is in charge of :ref:`authn`. + +Api Request +----------- + +`ApiRequest.hs `_ is in charge of parsing the URL query string (following PostgREST syntax), the request headers, and the request body. + +A request might be rejected at this level if it's invalid. For example when providing an unknown media type to PostgREST or using an unknown HTTP method. + +Plan +---- + +Using the Schema Cache, `Plan.hs `_ fills in out-of-band SQL details (like an ``ON CONFLICT (pk)`` clause) required to complete the user request. + +A request might be rejected at this level if it's invalid. For example when doing resource embedding on a nonexistent resource. + +Query +----- + +`Query.hs `_ generates the SQL queries (parametrized and prepared) required to satisfy the user request. + +Only at this stage a connection from the pool might be used. + +Schema Cache +------------ + +`SchemaCache.hs `_ is in charge of :ref:`schema_cache`. + +Config +------ + +`Config.hs `_ is in charge of :ref:`configuration`. + +Admin +----- + +`Admin.hs `_ is in charge of the :ref:`admin_server`. diff --git a/docs/index.rst b/docs/index.rst index f2939acb8..6baa61aab 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -132,7 +132,7 @@ Technical references for PostgREST's functionality. references/errors.rst references/configuration.rst references/observability.rst - references/health_check.rst + references/* Explanations ------------ diff --git a/docs/postgrest.dict b/docs/postgrest.dict index 5688aa3e1..63d935ec6 100644 --- a/docs/postgrest.dict +++ b/docs/postgrest.dict @@ -98,6 +98,7 @@ OpenAPI openapi ORM ov +parametrized passphrase PBKDF PgBouncer