2022-01-25 16:17:26 +03:00
|
|
|
# Server engineering documentation
|
|
|
|
|
|
|
|
|
|
This page documents the structure and the internal architecture of the [GraphQL
|
|
|
|
|
Engine Server](https://github.com/hasura/graphql-engine/tree/master/server). To
|
|
|
|
|
get started, you can read the [overview](overview.md). We also maintain a
|
|
|
|
|
[glossary](glossary.md) of all the terms we use throughout the code and the
|
|
|
|
|
documentation.
|
|
|
|
|
|
|
|
|
|
You can also get started with a list of [tips and tricks](tips.md).
|
|
|
|
|
|
|
|
|
|
## Haddock documentation
|
|
|
|
|
|
|
|
|
|
You can browse the generated [haddock documentation](haddock/) for the engine's
|
|
|
|
|
code; we automatically update it on every push to a branch of interest:
|
|
|
|
|
|
|
|
|
|
* [stable branch](haddock/stable)
|
|
|
|
|
* [alpha branch](haddock/alpha)
|
|
|
|
|
* [beta branch](haddock/beta)
|
|
|
|
|
* [main branch](haddock/main)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Architecture deep-dive
|
|
|
|
|
|
|
|
|
|
* how to understand our [GraphQL schema](schema.md)
|
|
|
|
|
* how to perform [database migrations](migration-guidelines.md)
|
Enable remote joins from remote schemas in the execution engine.
### Description
This PR adds the ability to perform remote joins from remote schemas in the engine. To do so, we alter the definition of an `ExecutionStep` targeting a remote schema: the `ExecStepRemote` constructor now expects a `Maybe RemoteJoins`. This new argument is used when processing the execution step, in the transport layer (either `Transport.HTTP` or `Transport.WebSocket`).
For this `Maybe RemoteJoins` to be extracted from a parsed query, this PR also extends the `Execute.RemoteJoin.Collect` module, to implement "collection" from a selection set. Not only do those new functions extract the remote joins, but they also apply all necessary transformations to the selection sets (such as inserting the necessary "phantom" fields used as join keys).
Finally in `Execute.RemoteJoin.Join`, we make two changes. First, we now always look for nested remote joins, regardless of whether the join we just performed went to a source or a remote schema; and second we adapt our join tree logic according to the special cases that were added to deal with remote server edge cases.
Additionally, this PR refactors / cleans / documents `Execute.RemoteJoin.RemoteServer`. This is not required as part of this change and could be moved to a separate PR if needed (a similar cleanup of `Join` is done independently in #3894). It also introduces a draft of a new documentation page for this project, that will be refined in the release PR that ships the feature (either #3069 or a copy of it).
While this PR extends the engine, it doesn't plug such relationships in the schema, meaning that, as of this PR, the new code paths in `Join` are technically unreachable. Adding the corresponding schema code and, ultimately, enabling the metadata API will be done in subsequent PRs.
### Keeping track of concrete type names
The main change this PR makes to the existing `Join` code is to handle a new reserved field we sometimes use when targeting remote servers: the `__hasura_internal_typename` field. In short, a GraphQL selection set can sometimes "branch" based on the concrete "runtime type" of the object on which the selection happens:
```graphql
query {
author(id: 53478) {
... on Writer {
name
articles {
title
}
}
... on Artist {
name
articles {
title
}
}
}
}
```
If both of those `articles` are remote joins, we need to be able, when we get the answer, to differentiate between the two different cases. We do this by asking for `__typename`, to be able to decide if we're in the `Writer` or the `Artist` branch of the query.
To avoid further processing / customization of results, we only insert this `__hasura_internal_typename: __typename` field in the query in the case of unions of interfaces AND if we have the guarantee that we will processing the request as part of the remote joins "folding": that is, if there's any remote join in this branch in the tree. Otherwise, we don't insert the field, and we leave that part of the response untouched.
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/3810
GitOrigin-RevId: 89aaf16274d68e26ad3730b80c2d2fdc2896b96c
2022-03-09 06:17:28 +03:00
|
|
|
* how the [execution of remote joins](remote_joins_execution.md) works
|
2022-01-25 16:17:26 +03:00
|
|
|
|
|
|
|
|
TODO: we can either list individual topics here, or point to architecture/ and have a README file there.
|
|
|
|
|
|
|
|
|
|
## Notes
|
|
|
|
|
|
|
|
|
|
In our Haskell codebase, we use [GHC-style
|
|
|
|
|
notes](https://www.stackbuilders.com/news/the-notes-of-ghc) for long-form
|
|
|
|
|
comments detailing a specific aspect of the codebase. We gather all of them, as
|
|
|
|
|
of the `main` branch, in the [notes subfolder](notes/).
|
|
|
|
|
|
|
|
|
|
## Updating this documentation
|
|
|
|
|
|
|
|
|
|
All markdown files in this folder are either copied *verbatim* from
|
|
|
|
|
[`server/documentation`](https://github.com/hasura/graphql-engine/tree/master/server/documentation)
|
|
|
|
|
or generated as part of our CI; do not open a PR to modify files in
|
|
|
|
|
the `gh-pages` branch, and instead modify their source directly. Notes
|
|
|
|
|
are extracted using the `scripts/extract-nodes` bash script. The
|
|
|
|
|
haddock documentation is generated by running `cabal haddock
|
|
|
|
|
--haddock-internal --haddock-options="--ignore-all-exports"`.
|