2021-11-10 03:37:42 +03:00
|
|
|
-- | This module defines the type class 'BackendSchema' and auxiliary types.
|
|
|
|
--
|
|
|
|
-- 'BackendSchema' represents the part of the interface that a backend driver
|
|
|
|
-- presents to the GraphQL Engine core that is responsible for generating
|
|
|
|
-- the backend's Schema Parsers.
|
|
|
|
--
|
|
|
|
-- The Schema Parsers recognise (and reflect) the schema that a backend exposes.
|
|
|
|
--
|
|
|
|
-- The 'BackendSchema' methods are used by
|
|
|
|
-- 'Hasura.GraphQL.Schema.buildGQLContext', which is the core's entrypoint to
|
|
|
|
-- schema generation.
|
|
|
|
--
|
|
|
|
-- Many of the 'BackendSchema' methods will have default implementations that a
|
|
|
|
-- backend driver may use. These may be found (chiefly) in the modules:
|
|
|
|
--
|
|
|
|
-- * The module "Hasura.GraphQL.Schema.Build", commonly qualified @GSB@
|
|
|
|
-- * "Hasura.GraphQL.Schema.Select", commonly qualified @GSS@
|
|
|
|
-- * "Hasura.GraphQL.Schema.BoolExp"
|
|
|
|
--
|
|
|
|
-- For more information see:
|
|
|
|
--
|
|
|
|
-- * <https://github.com/hasura/graphql-engine/blob/master/server/documentation/schema.md Technical overview of Schema Generation >
|
|
|
|
-- * The type 'Hasura.GraphQL.Parser.Parser', and associated source code notes
|
|
|
|
-- in the same folder (not exposed with Haddock unfortunately)
|
2021-11-04 19:08:33 +03:00
|
|
|
module Hasura.GraphQL.Schema.Backend
|
2021-11-08 21:11:44 +03:00
|
|
|
( -- * Main Types
|
|
|
|
BackendSchema (..),
|
2022-06-30 18:22:19 +03:00
|
|
|
BackendTableSelectSchema (..),
|
2023-04-04 15:45:20 +03:00
|
|
|
BackendCustomReturnTypeSelectSchema (..),
|
2023-01-10 04:54:40 +03:00
|
|
|
BackendUpdateOperatorsSchema (..),
|
2021-11-04 19:08:33 +03:00
|
|
|
MonadBuildSchema,
|
2021-11-08 21:11:44 +03:00
|
|
|
|
|
|
|
-- * Auxiliary Types
|
|
|
|
ComparisonExp,
|
2021-11-10 03:37:42 +03:00
|
|
|
|
|
|
|
-- * Note: @BackendSchema@ modelling principles
|
|
|
|
-- $modelling
|
2021-11-04 19:08:33 +03:00
|
|
|
)
|
|
|
|
where
|
2020-12-01 18:50:18 +03:00
|
|
|
|
2023-01-10 04:54:40 +03:00
|
|
|
import Data.Kind (Type)
|
2022-05-26 14:54:30 +03:00
|
|
|
import Data.Text.Casing (GQLNameIdentifier)
|
2023-03-31 18:33:32 +03:00
|
|
|
import Hasura.CustomReturnType.Cache (CustomReturnTypeInfo)
|
2023-04-03 13:18:54 +03:00
|
|
|
import Hasura.Function.Cache
|
2022-07-25 18:53:25 +03:00
|
|
|
import Hasura.GraphQL.ApolloFederation (ApolloFederationParserFunction)
|
2021-09-24 01:56:37 +03:00
|
|
|
import Hasura.GraphQL.Schema.Common
|
2022-07-12 17:00:15 +03:00
|
|
|
import Hasura.GraphQL.Schema.NamingCase
|
server: Metadata origin for definitions (type parameter version v2)
The code that builds the GraphQL schema, and `buildGQLContext` in particular, is partial: not every value of `(ServerConfigCtx, GraphQLQueryType, SourceCache, HashMap RemoteSchemaName (RemoteSchemaCtx, MetadataObject), ActionCache, AnnotatedCustomTypes)` results in a valid GraphQL schema. When it fails, we want to be able to return better error messages than we currently do.
The key thing that is missing is a way to trace back GraphQL type information to their origin from the Hasura metadata. Currently, we have a number of correctness checks of our GraphQL schema. But these correctness checks only have access to pure GraphQL type information, and hence can only report errors in terms of that. Possibly the worst is the "conflicting definitions" error, which, in practice, can only be debugged by Hasura engineers. This is terrible DX for customers.
This PR allows us to print better error messages, by adding a field to the `Definition` type that traces the GraphQL type to its origin in the metadata. So the idea is simple: just add `MetadataObjId`, or `Maybe` that, or some other sum type of that, to `Definition`.
However, we want to avoid having to import a `Hasura.RQL` module from `Hasura.GraphQL.Parser`. So we instead define this additional field of `Definition` through a new type parameter, which is threaded through in `Hasura.GraphQL.Parser`. We then define type synonyms in `Hasura.GraphQL.Schema.Parser` that fill in this type parameter, so that it is not visible for the majority of the codebase.
The idea of associating metadata information to `Definition`s really comes to fruition when combined with hasura/graphql-engine-mono#4517. Their combination would allow us to use the API of fatal errors (just like the current `MonadError QErr`) to report _inconsistencies_ in the metadata. Such inconsistencies are then _automatically_ ignored. So no ad-hoc decisions need to be made on how to cut out inconsistent metadata from the GraphQL schema. This will allow us to report much better errors, as well as improve the likelihood of a successful HGE startup.
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/4770
Co-authored-by: Samir Talwar <47582+SamirTalwar@users.noreply.github.com>
GitOrigin-RevId: 728402b0cae83ae8e83463a826ceeb609001acae
2022-06-28 18:52:26 +03:00
|
|
|
import Hasura.GraphQL.Schema.Parser hiding (Type)
|
2023-03-02 19:02:27 +03:00
|
|
|
import Hasura.LogicalModel.Cache (LogicalModelInfo)
|
2021-09-24 01:56:37 +03:00
|
|
|
import Hasura.Prelude
|
|
|
|
import Hasura.RQL.IR
|
2021-10-01 15:52:19 +03:00
|
|
|
import Hasura.RQL.IR.Insert qualified as IR
|
2021-09-24 01:56:37 +03:00
|
|
|
import Hasura.RQL.IR.Select qualified as IR
|
2022-04-27 16:57:28 +03:00
|
|
|
import Hasura.RQL.Types.Backend
|
|
|
|
import Hasura.RQL.Types.Column hiding (EnumValueInfo)
|
2022-09-14 00:21:07 +03:00
|
|
|
import Hasura.RQL.Types.Column qualified as Column
|
2022-04-27 16:57:28 +03:00
|
|
|
import Hasura.RQL.Types.ComputedField
|
|
|
|
import Hasura.RQL.Types.Relationships.Local
|
|
|
|
import Hasura.RQL.Types.SchemaCache
|
Remove circular dependency in schema building code
### Description
The main goal of this PR is, as stated, to remove the circular dependency in the schema building code. This cycle arises from the existence of remote relationships: when we build the schema for a source A, a remote relationship might force us to jump to the schema of a source B, or some remote schema. As a result, we end up having to do a dispatch from a "leaf" of the schema, similar to the one done at the root. In turn, this forces us to carry along in the schema a lot of information required for that dispatch, AND it forces us to import the instances in scope, creating an import loop.
As discussed in #4489, this PR implements the "dependency injection" solution: we pass to the schema a function to call to do the dispatch, and to get a generated field for a remote relationship. That way, this function can be chosen at the root level, and the leaves need not be aware of the overall context.
This PR grew a bit bigger than that, however; in an attempt to try and remove the `SourceCache` from the schema altogether, it changed a lot of functions across the schema building code, to thread along the `SourceInfo b` of the source being built. This avoids having to do cache lookups within a given source. A few cases remain, such as relay, that we might try to tackle in a subsequent PR.
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/4557
GitOrigin-RevId: 9388e48372877520a72a9fd1677005df9f7b2d72
2022-05-27 20:21:22 +03:00
|
|
|
import Hasura.RQL.Types.Source
|
2022-08-03 22:08:34 +03:00
|
|
|
import Hasura.RQL.Types.SourceCustomization (MkRootFieldName)
|
2022-04-27 16:57:28 +03:00
|
|
|
import Hasura.SQL.Backend
|
2021-09-24 01:56:37 +03:00
|
|
|
import Language.GraphQL.Draft.Syntax qualified as G
|
2020-12-01 18:50:18 +03:00
|
|
|
|
2021-11-10 03:37:42 +03:00
|
|
|
-- | Bag of constraints available to the methods of @BackendSchema@.
|
|
|
|
--
|
|
|
|
-- Note that @BackendSchema b@ is itself part of this, so a methods may also
|
|
|
|
-- call other methods. This might seem trivial, but it can be easy to miss when
|
|
|
|
-- the functions used to implement a class instance are defined in multiple
|
|
|
|
-- modules.
|
2021-02-03 19:17:20 +03:00
|
|
|
type MonadBuildSchema b r m n =
|
2021-12-22 02:14:56 +03:00
|
|
|
( BackendSchema b,
|
server: reduce schema contexts to the bare minimum
### Description
This monster of a PR took way too long. As the title suggests, it reduces the schema context carried in the readers to the very strict minimum. In practice, that means that to build a source, we only require:
- the global `SchemaContext`
- the global `SchemaOptions` (soon to be renamed `SchemaSourceOptions`)
- that source's `SourceInfo`
Furthermore, _we no longer carry "default" customization options throughout the schema_. All customization information is extracted from the `SourceInfo`, when required. This prevents an entire category of bugs we had previously encountered, such as parts of the code using uninitialized / unupdated customization info.
In turn, this meant that we could remove the explicit threading of the `SourceInfo` throughout the schema, since it is now always available through the reader context.
Finally, this meant making a few adjustments to relay and actions as well, such as the introduction of a new separate "context" for actions, and a change to how we create some of the action-specific postgres scalar parsers.
I'll highlight with review comments the areas of interest.
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/6709
GitOrigin-RevId: ea80fddcb24e2513779dd04b0b700a55f0028dd1
2022-11-17 13:34:05 +03:00
|
|
|
MonadBuildSourceSchema b r m n
|
2021-02-03 19:17:20 +03:00
|
|
|
)
|
|
|
|
|
2021-11-10 03:37:42 +03:00
|
|
|
-- | This type class is responsible for generating the schema of a backend.
|
|
|
|
-- Its methods are called by the common core that orchestrates the various
|
|
|
|
-- backend drivers.
|
|
|
|
--
|
|
|
|
-- Its purpose in life is to make it convenient to express the GraphQL schema we
|
|
|
|
-- want to expose for the backends that we support. This means balancing the
|
|
|
|
-- desire to have consistency with the desire to differentiate the schema of a
|
|
|
|
-- backend.
|
|
|
|
--
|
|
|
|
-- This means that it is expected to evolve over time as we add new backends,
|
|
|
|
-- and that you have the license to change it: Whatever form it currently takes
|
|
|
|
-- only reflects status quo current implementation.
|
|
|
|
--
|
|
|
|
-- The module "Hasura.GraphQL.Schema.Build" (commonly qualified as @GSB@)
|
|
|
|
-- provides standard building blocks for implementing many methods of this
|
|
|
|
-- class. And as such, these two modules are very much expected to evolve in
|
|
|
|
-- tandem.
|
|
|
|
--
|
|
|
|
-- See <#modelling Note BackendSchema modelling principles>.
|
2022-02-03 19:13:50 +03:00
|
|
|
class
|
2022-06-30 18:22:19 +03:00
|
|
|
Backend b =>
|
2022-02-03 19:13:50 +03:00
|
|
|
BackendSchema (b :: BackendType)
|
|
|
|
where
|
2021-02-03 19:17:20 +03:00
|
|
|
-- top level parsers
|
2022-06-07 08:32:08 +03:00
|
|
|
buildTableQueryAndSubscriptionFields ::
|
2021-09-24 01:56:37 +03:00
|
|
|
MonadBuildSchema b r m n =>
|
2022-08-03 22:08:34 +03:00
|
|
|
MkRootFieldName ->
|
2021-09-24 01:56:37 +03:00
|
|
|
TableName b ->
|
|
|
|
TableInfo b ->
|
2022-05-26 14:54:30 +03:00
|
|
|
GQLNameIdentifier ->
|
2022-09-06 19:48:04 +03:00
|
|
|
SchemaT
|
|
|
|
r
|
|
|
|
m
|
2022-06-07 08:32:08 +03:00
|
|
|
( [FieldParser n (QueryDB b (RemoteRelationshipField UnpreparedValue) (UnpreparedValue b))],
|
2022-07-25 18:53:25 +03:00
|
|
|
[FieldParser n (QueryDB b (RemoteRelationshipField UnpreparedValue) (UnpreparedValue b))],
|
|
|
|
Maybe (G.Name, Parser 'Output n (ApolloFederationParserFunction n))
|
2022-06-07 08:32:08 +03:00
|
|
|
)
|
2022-04-22 22:53:12 +03:00
|
|
|
buildTableStreamingSubscriptionFields ::
|
|
|
|
MonadBuildSchema b r m n =>
|
2022-08-03 22:08:34 +03:00
|
|
|
MkRootFieldName ->
|
2022-04-22 22:53:12 +03:00
|
|
|
TableName b ->
|
|
|
|
TableInfo b ->
|
2022-05-26 14:54:30 +03:00
|
|
|
GQLNameIdentifier ->
|
2022-09-06 19:48:04 +03:00
|
|
|
SchemaT r m [FieldParser n (QueryDB b (RemoteRelationshipField UnpreparedValue) (UnpreparedValue b))]
|
2021-09-24 01:56:37 +03:00
|
|
|
buildTableRelayQueryFields ::
|
|
|
|
MonadBuildSchema b r m n =>
|
2022-08-03 22:08:34 +03:00
|
|
|
MkRootFieldName ->
|
2021-09-24 01:56:37 +03:00
|
|
|
TableName b ->
|
|
|
|
TableInfo b ->
|
2022-05-26 14:54:30 +03:00
|
|
|
GQLNameIdentifier ->
|
2021-09-24 01:56:37 +03:00
|
|
|
NESeq (ColumnInfo b) ->
|
2022-09-06 19:48:04 +03:00
|
|
|
SchemaT r m [FieldParser n (QueryDB b (RemoteRelationshipField UnpreparedValue) (UnpreparedValue b))]
|
2021-09-24 01:56:37 +03:00
|
|
|
buildTableInsertMutationFields ::
|
|
|
|
MonadBuildSchema b r m n =>
|
2022-08-03 22:08:34 +03:00
|
|
|
MkRootFieldName ->
|
Role-invariant schema constructors
We build the GraphQL schema by combining building blocks such as `tableSelectionSet` and `columnParser`. These building blocks individually build `{InputFields,Field,}Parser` objects. Those object specify the valid GraphQL schema.
Since the GraphQL schema is role-dependent, at some point we need to know what fragment of the GraphQL schema a specific role is allowed to access, and this is stored in `{Sel,Upd,Ins,Del}PermInfo` objects.
We have passed around these permission objects as function arguments to the schema building blocks since we first started dealing with permissions during the PDV refactor - see hasura/graphql-engine@5168b99e463199b1934d8645bd6cd37eddb64ae1 in hasura/graphql-engine#4111. This means that, for instance, `tableSelectionSet` has as its type:
```haskell
tableSelectionSet ::
forall b r m n.
MonadBuildSchema b r m n =>
SourceName ->
TableInfo b ->
SelPermInfo b ->
m (Parser 'Output n (AnnotatedFields b))
```
There are three reasons to change this.
1. We often pass a `Maybe (xPermInfo b)` instead of a proper `xPermInfo b`, and it's not clear what the intended semantics of this is. Some potential improvements on the data types involved are discussed in issue hasura/graphql-engine-mono#3125.
2. In most cases we also already pass a `TableInfo b`, and together with the `MonadRole` that is usually also in scope, this means that we could look up the required permissions regardless: so passing the permissions explicitly undermines the "single source of truth" principle. Breaking this principle also makes the code more difficult to read.
3. We are working towards role-based parsers (see hasura/graphql-engine-mono#2711), where the `{InputFields,Field,}Parser` objects are constructed in a role-invariant way, so that we have a single object that can be used for all roles. In particular, this means that the schema building blocks _need_ to be constructed in a role-invariant way. While this PR doesn't accomplish that, it does reduce the amount of role-specific arguments being passed, thus fixing hasura/graphql-engine-mono#3068.
Concretely, this PR simply drops the `xPermInfo b` argument from almost all schema building blocks. Instead these objects are looked up from the `TableInfo b` as-needed. The resulting code is considerably simpler and shorter.
One way to interpret this change is as follows. Before this PR, we figured out permissions at the top-level in `Hasura.GraphQL.Schema`, passing down the obtained `xPermInfo` objects as required. After this PR, we have a bottom-up approach where the schema building blocks themselves decide whether they want to be included for a particular role.
So this moves some permission logic out of `Hasura.GraphQL.Schema`, which is very complex.
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/3608
GitOrigin-RevId: 51a744f34ec7d57bc8077667ae7f9cb9c4f6c962
2022-02-17 11:16:20 +03:00
|
|
|
Scenario ->
|
2021-09-24 01:56:37 +03:00
|
|
|
TableName b ->
|
|
|
|
TableInfo b ->
|
2022-05-26 14:54:30 +03:00
|
|
|
GQLNameIdentifier ->
|
2022-09-06 19:48:04 +03:00
|
|
|
SchemaT r m [FieldParser n (AnnotatedInsert b (RemoteRelationshipField UnpreparedValue) (UnpreparedValue b))]
|
2021-11-10 03:37:42 +03:00
|
|
|
|
|
|
|
-- | This method is responsible for building the GraphQL Schema for mutations
|
|
|
|
-- backed by @UPDATE@ statements on some table, as described in
|
|
|
|
-- @https://hasura.io/docs/latest/graphql/core/databases/postgres/mutations/update.html@.
|
|
|
|
--
|
|
|
|
-- The suggested way to implement this is using building blocks in GSB, c.f.
|
|
|
|
-- its namesake @GSB.@'Hasura.GraphQL.Schema.Build.buildTableUpdateMutationFields'.
|
2021-09-24 01:56:37 +03:00
|
|
|
buildTableUpdateMutationFields ::
|
|
|
|
MonadBuildSchema b r m n =>
|
2022-05-31 17:41:09 +03:00
|
|
|
Scenario ->
|
2021-11-10 03:37:42 +03:00
|
|
|
-- | table info
|
2021-09-24 01:56:37 +03:00
|
|
|
TableInfo b ->
|
2021-11-10 03:37:42 +03:00
|
|
|
-- | field display name
|
2022-05-26 14:54:30 +03:00
|
|
|
GQLNameIdentifier ->
|
2022-09-06 19:48:04 +03:00
|
|
|
SchemaT r m [FieldParser n (AnnotatedUpdateG b (RemoteRelationshipField UnpreparedValue) (UnpreparedValue b))]
|
2021-11-10 03:37:42 +03:00
|
|
|
|
2021-09-24 01:56:37 +03:00
|
|
|
buildTableDeleteMutationFields ::
|
|
|
|
MonadBuildSchema b r m n =>
|
2022-08-03 22:08:34 +03:00
|
|
|
MkRootFieldName ->
|
2022-05-31 17:41:09 +03:00
|
|
|
Scenario ->
|
2021-09-24 01:56:37 +03:00
|
|
|
TableName b ->
|
|
|
|
TableInfo b ->
|
2022-05-26 14:54:30 +03:00
|
|
|
GQLNameIdentifier ->
|
2022-09-06 19:48:04 +03:00
|
|
|
SchemaT r m [FieldParser n (AnnDelG b (RemoteRelationshipField UnpreparedValue) (UnpreparedValue b))]
|
2021-11-26 00:07:53 +03:00
|
|
|
|
2021-09-24 01:56:37 +03:00
|
|
|
buildFunctionQueryFields ::
|
|
|
|
MonadBuildSchema b r m n =>
|
2022-08-03 22:08:34 +03:00
|
|
|
MkRootFieldName ->
|
2021-09-24 01:56:37 +03:00
|
|
|
FunctionName b ->
|
|
|
|
FunctionInfo b ->
|
|
|
|
TableName b ->
|
2022-09-06 19:48:04 +03:00
|
|
|
SchemaT r m [FieldParser n (QueryDB b (RemoteRelationshipField UnpreparedValue) (UnpreparedValue b))]
|
2021-11-26 00:07:53 +03:00
|
|
|
|
2021-09-24 01:56:37 +03:00
|
|
|
buildFunctionRelayQueryFields ::
|
|
|
|
MonadBuildSchema b r m n =>
|
2022-08-03 22:08:34 +03:00
|
|
|
MkRootFieldName ->
|
2021-09-24 01:56:37 +03:00
|
|
|
FunctionName b ->
|
|
|
|
FunctionInfo b ->
|
|
|
|
TableName b ->
|
|
|
|
NESeq (ColumnInfo b) ->
|
2022-09-06 19:48:04 +03:00
|
|
|
SchemaT r m [FieldParser n (QueryDB b (RemoteRelationshipField UnpreparedValue) (UnpreparedValue b))]
|
2021-11-26 00:07:53 +03:00
|
|
|
|
2021-09-24 01:56:37 +03:00
|
|
|
buildFunctionMutationFields ::
|
|
|
|
MonadBuildSchema b r m n =>
|
2022-08-03 22:08:34 +03:00
|
|
|
MkRootFieldName ->
|
2021-09-24 01:56:37 +03:00
|
|
|
FunctionName b ->
|
|
|
|
FunctionInfo b ->
|
|
|
|
TableName b ->
|
2022-09-06 19:48:04 +03:00
|
|
|
SchemaT r m [FieldParser n (MutationDB b (RemoteRelationshipField UnpreparedValue) (UnpreparedValue b))]
|
2021-02-03 19:17:20 +03:00
|
|
|
|
2023-02-21 16:45:12 +03:00
|
|
|
buildLogicalModelRootFields ::
|
2023-01-19 14:25:52 +03:00
|
|
|
MonadBuildSchema b r m n =>
|
2023-02-22 16:45:27 +03:00
|
|
|
LogicalModelInfo b ->
|
2023-01-19 14:25:52 +03:00
|
|
|
SchemaT
|
|
|
|
r
|
|
|
|
m
|
|
|
|
(Maybe (FieldParser n (QueryDB b (RemoteRelationshipField UnpreparedValue) (UnpreparedValue b))))
|
2023-02-21 16:45:12 +03:00
|
|
|
buildLogicalModelRootFields _ = pure Nothing
|
2023-01-19 14:25:52 +03:00
|
|
|
|
2021-10-01 15:52:19 +03:00
|
|
|
-- | Make a parser for relationships. Default implementaton elides
|
|
|
|
-- relationships altogether.
|
|
|
|
mkRelationshipParser ::
|
|
|
|
MonadBuildSchema b r m n =>
|
|
|
|
RelInfo b ->
|
2022-09-06 19:48:04 +03:00
|
|
|
SchemaT r m (Maybe (InputFieldsParser n (Maybe (IR.AnnotatedInsertField b (UnpreparedValue b)))))
|
server: reduce schema contexts to the bare minimum
### Description
This monster of a PR took way too long. As the title suggests, it reduces the schema context carried in the readers to the very strict minimum. In practice, that means that to build a source, we only require:
- the global `SchemaContext`
- the global `SchemaOptions` (soon to be renamed `SchemaSourceOptions`)
- that source's `SourceInfo`
Furthermore, _we no longer carry "default" customization options throughout the schema_. All customization information is extracted from the `SourceInfo`, when required. This prevents an entire category of bugs we had previously encountered, such as parts of the code using uninitialized / unupdated customization info.
In turn, this meant that we could remove the explicit threading of the `SourceInfo` throughout the schema, since it is now always available through the reader context.
Finally, this meant making a few adjustments to relay and actions as well, such as the introduction of a new separate "context" for actions, and a change to how we create some of the action-specific postgres scalar parsers.
I'll highlight with review comments the areas of interest.
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/6709
GitOrigin-RevId: ea80fddcb24e2513779dd04b0b700a55f0028dd1
2022-11-17 13:34:05 +03:00
|
|
|
mkRelationshipParser _ = pure Nothing
|
2021-10-01 15:52:19 +03:00
|
|
|
|
2021-02-03 19:17:20 +03:00
|
|
|
-- backend extensions
|
2021-09-24 01:56:37 +03:00
|
|
|
relayExtension :: Maybe (XRelay b)
|
2021-06-09 16:02:15 +03:00
|
|
|
nodesAggExtension :: Maybe (XNodesAgg b)
|
2022-04-22 22:53:12 +03:00
|
|
|
streamSubscriptionExtension :: Maybe (XStreamingSubscription b)
|
2021-02-03 19:17:20 +03:00
|
|
|
|
|
|
|
-- individual components
|
2021-09-24 01:56:37 +03:00
|
|
|
columnParser ::
|
2022-09-06 19:48:04 +03:00
|
|
|
MonadBuildSchema b r m n =>
|
2021-09-24 01:56:37 +03:00
|
|
|
ColumnType b ->
|
2021-12-20 20:02:32 +03:00
|
|
|
G.Nullability -> -- TODO maybe use Hasura.GraphQL.Parser.Schema.Nullability instead?
|
2022-09-06 19:48:04 +03:00
|
|
|
SchemaT r m (Parser 'Both n (ValueWithOrigin (ColumnValue b)))
|
2022-09-14 00:21:07 +03:00
|
|
|
enumParser ::
|
|
|
|
MonadBuildSchema b r m n =>
|
|
|
|
TableName b ->
|
|
|
|
NonEmpty (EnumValue, Column.EnumValueInfo) ->
|
|
|
|
Maybe G.Name ->
|
|
|
|
G.Nullability ->
|
|
|
|
SchemaT r m (Parser 'Both n (ScalarValue b))
|
|
|
|
possiblyNullable ::
|
|
|
|
MonadParse m =>
|
|
|
|
ScalarType b ->
|
|
|
|
G.Nullability ->
|
|
|
|
Parser 'Both m (ScalarValue b) ->
|
|
|
|
Parser 'Both m (ScalarValue b)
|
2021-09-24 01:56:37 +03:00
|
|
|
|
2022-05-03 11:58:56 +03:00
|
|
|
-- | Parser for arguments on scalar fields in a selection set
|
|
|
|
scalarSelectionArgumentsParser ::
|
2021-09-24 01:56:37 +03:00
|
|
|
MonadParse n =>
|
|
|
|
ColumnType b ->
|
2022-05-03 11:58:56 +03:00
|
|
|
InputFieldsParser n (Maybe (ScalarSelectionArguments b))
|
2021-09-24 01:56:37 +03:00
|
|
|
|
|
|
|
orderByOperators ::
|
2022-06-10 06:59:00 +03:00
|
|
|
SourceInfo b ->
|
2022-05-26 14:54:30 +03:00
|
|
|
NamingCase ->
|
2022-06-10 06:59:00 +03:00
|
|
|
(G.Name, NonEmpty (Definition EnumValueInfo, (BasicOrderType b, NullsOrderType b)))
|
|
|
|
|
2021-09-24 01:56:37 +03:00
|
|
|
comparisonExps ::
|
|
|
|
MonadBuildSchema b r m n =>
|
|
|
|
ColumnType b ->
|
2022-09-06 19:48:04 +03:00
|
|
|
SchemaT r m (Parser 'Input n [ComparisonExp b])
|
2021-11-08 21:11:44 +03:00
|
|
|
|
2022-01-18 17:53:44 +03:00
|
|
|
-- | The input fields parser, for "count" aggregate field, yielding a function
|
|
|
|
-- which generates @'CountType b' from optional "distinct" field value
|
|
|
|
countTypeInput ::
|
|
|
|
MonadParse n =>
|
|
|
|
Maybe (Parser 'Both n (Column b)) ->
|
|
|
|
InputFieldsParser n (CountDistinct -> CountType b)
|
2021-11-08 21:11:44 +03:00
|
|
|
|
2020-12-01 18:50:18 +03:00
|
|
|
aggregateOrderByCountType :: ScalarType b
|
2021-09-24 01:56:37 +03:00
|
|
|
|
2020-12-01 18:50:18 +03:00
|
|
|
-- | Computed field parser
|
2021-09-24 01:56:37 +03:00
|
|
|
computedField ::
|
|
|
|
MonadBuildSchema b r m n =>
|
|
|
|
ComputedFieldInfo b ->
|
|
|
|
TableName b ->
|
Role-invariant schema constructors
We build the GraphQL schema by combining building blocks such as `tableSelectionSet` and `columnParser`. These building blocks individually build `{InputFields,Field,}Parser` objects. Those object specify the valid GraphQL schema.
Since the GraphQL schema is role-dependent, at some point we need to know what fragment of the GraphQL schema a specific role is allowed to access, and this is stored in `{Sel,Upd,Ins,Del}PermInfo` objects.
We have passed around these permission objects as function arguments to the schema building blocks since we first started dealing with permissions during the PDV refactor - see hasura/graphql-engine@5168b99e463199b1934d8645bd6cd37eddb64ae1 in hasura/graphql-engine#4111. This means that, for instance, `tableSelectionSet` has as its type:
```haskell
tableSelectionSet ::
forall b r m n.
MonadBuildSchema b r m n =>
SourceName ->
TableInfo b ->
SelPermInfo b ->
m (Parser 'Output n (AnnotatedFields b))
```
There are three reasons to change this.
1. We often pass a `Maybe (xPermInfo b)` instead of a proper `xPermInfo b`, and it's not clear what the intended semantics of this is. Some potential improvements on the data types involved are discussed in issue hasura/graphql-engine-mono#3125.
2. In most cases we also already pass a `TableInfo b`, and together with the `MonadRole` that is usually also in scope, this means that we could look up the required permissions regardless: so passing the permissions explicitly undermines the "single source of truth" principle. Breaking this principle also makes the code more difficult to read.
3. We are working towards role-based parsers (see hasura/graphql-engine-mono#2711), where the `{InputFields,Field,}Parser` objects are constructed in a role-invariant way, so that we have a single object that can be used for all roles. In particular, this means that the schema building blocks _need_ to be constructed in a role-invariant way. While this PR doesn't accomplish that, it does reduce the amount of role-specific arguments being passed, thus fixing hasura/graphql-engine-mono#3068.
Concretely, this PR simply drops the `xPermInfo b` argument from almost all schema building blocks. Instead these objects are looked up from the `TableInfo b` as-needed. The resulting code is considerably simpler and shorter.
One way to interpret this change is as follows. Before this PR, we figured out permissions at the top-level in `Hasura.GraphQL.Schema`, passing down the obtained `xPermInfo` objects as required. After this PR, we have a bottom-up approach where the schema building blocks themselves decide whether they want to be included for a particular role.
So this moves some permission logic out of `Hasura.GraphQL.Schema`, which is very complex.
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/3608
GitOrigin-RevId: 51a744f34ec7d57bc8077667ae7f9cb9c4f6c962
2022-02-17 11:16:20 +03:00
|
|
|
TableInfo b ->
|
2022-09-06 19:48:04 +03:00
|
|
|
SchemaT r m (Maybe (FieldParser n (AnnotatedField b)))
|
2021-09-24 01:56:37 +03:00
|
|
|
|
2022-06-30 18:22:19 +03:00
|
|
|
-- | The public interface for the schema of table queries exposed by a backend.
|
|
|
|
--
|
|
|
|
-- Remote Schemas and the Relay schema are the chief backend-agnostic clients of
|
|
|
|
-- this typeclass.
|
|
|
|
--
|
|
|
|
-- Some of schema building components in the "Hasura.GraphQL.Schema" namespace
|
|
|
|
-- also make use of these methods, ensuring backends expose a consistent schema
|
|
|
|
-- regardless of the mode it's referenced.
|
|
|
|
--
|
|
|
|
-- Default implementations exist for all of these in
|
|
|
|
-- 'Hasura.GraphQL.Schema.Select'.
|
|
|
|
class Backend b => BackendTableSelectSchema (b :: BackendType) where
|
|
|
|
tableArguments ::
|
server: reduce schema contexts to the bare minimum
### Description
This monster of a PR took way too long. As the title suggests, it reduces the schema context carried in the readers to the very strict minimum. In practice, that means that to build a source, we only require:
- the global `SchemaContext`
- the global `SchemaOptions` (soon to be renamed `SchemaSourceOptions`)
- that source's `SourceInfo`
Furthermore, _we no longer carry "default" customization options throughout the schema_. All customization information is extracted from the `SourceInfo`, when required. This prevents an entire category of bugs we had previously encountered, such as parts of the code using uninitialized / unupdated customization info.
In turn, this meant that we could remove the explicit threading of the `SourceInfo` throughout the schema, since it is now always available through the reader context.
Finally, this meant making a few adjustments to relay and actions as well, such as the introduction of a new separate "context" for actions, and a change to how we create some of the action-specific postgres scalar parsers.
I'll highlight with review comments the areas of interest.
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/6709
GitOrigin-RevId: ea80fddcb24e2513779dd04b0b700a55f0028dd1
2022-11-17 13:34:05 +03:00
|
|
|
MonadBuildSourceSchema b r m n =>
|
2022-06-30 18:22:19 +03:00
|
|
|
TableInfo b ->
|
2022-09-06 19:48:04 +03:00
|
|
|
SchemaT r m (InputFieldsParser n (IR.SelectArgsG b (UnpreparedValue b)))
|
2022-06-30 18:22:19 +03:00
|
|
|
|
|
|
|
tableSelectionSet ::
|
server: reduce schema contexts to the bare minimum
### Description
This monster of a PR took way too long. As the title suggests, it reduces the schema context carried in the readers to the very strict minimum. In practice, that means that to build a source, we only require:
- the global `SchemaContext`
- the global `SchemaOptions` (soon to be renamed `SchemaSourceOptions`)
- that source's `SourceInfo`
Furthermore, _we no longer carry "default" customization options throughout the schema_. All customization information is extracted from the `SourceInfo`, when required. This prevents an entire category of bugs we had previously encountered, such as parts of the code using uninitialized / unupdated customization info.
In turn, this meant that we could remove the explicit threading of the `SourceInfo` throughout the schema, since it is now always available through the reader context.
Finally, this meant making a few adjustments to relay and actions as well, such as the introduction of a new separate "context" for actions, and a change to how we create some of the action-specific postgres scalar parsers.
I'll highlight with review comments the areas of interest.
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/6709
GitOrigin-RevId: ea80fddcb24e2513779dd04b0b700a55f0028dd1
2022-11-17 13:34:05 +03:00
|
|
|
MonadBuildSourceSchema b r m n =>
|
2022-06-30 18:22:19 +03:00
|
|
|
TableInfo b ->
|
2022-09-06 19:48:04 +03:00
|
|
|
SchemaT r m (Maybe (Parser 'Output n (AnnotatedFields b)))
|
2022-06-30 18:22:19 +03:00
|
|
|
|
|
|
|
selectTable ::
|
server: reduce schema contexts to the bare minimum
### Description
This monster of a PR took way too long. As the title suggests, it reduces the schema context carried in the readers to the very strict minimum. In practice, that means that to build a source, we only require:
- the global `SchemaContext`
- the global `SchemaOptions` (soon to be renamed `SchemaSourceOptions`)
- that source's `SourceInfo`
Furthermore, _we no longer carry "default" customization options throughout the schema_. All customization information is extracted from the `SourceInfo`, when required. This prevents an entire category of bugs we had previously encountered, such as parts of the code using uninitialized / unupdated customization info.
In turn, this meant that we could remove the explicit threading of the `SourceInfo` throughout the schema, since it is now always available through the reader context.
Finally, this meant making a few adjustments to relay and actions as well, such as the introduction of a new separate "context" for actions, and a change to how we create some of the action-specific postgres scalar parsers.
I'll highlight with review comments the areas of interest.
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/6709
GitOrigin-RevId: ea80fddcb24e2513779dd04b0b700a55f0028dd1
2022-11-17 13:34:05 +03:00
|
|
|
MonadBuildSourceSchema b r m n =>
|
2022-06-30 18:22:19 +03:00
|
|
|
-- | table info
|
|
|
|
TableInfo b ->
|
|
|
|
-- | field display name
|
|
|
|
G.Name ->
|
|
|
|
-- | field description, if any
|
|
|
|
Maybe G.Description ->
|
2022-09-06 19:48:04 +03:00
|
|
|
SchemaT r m (Maybe (FieldParser n (SelectExp b)))
|
2022-06-30 18:22:19 +03:00
|
|
|
|
|
|
|
selectTableAggregate ::
|
server: reduce schema contexts to the bare minimum
### Description
This monster of a PR took way too long. As the title suggests, it reduces the schema context carried in the readers to the very strict minimum. In practice, that means that to build a source, we only require:
- the global `SchemaContext`
- the global `SchemaOptions` (soon to be renamed `SchemaSourceOptions`)
- that source's `SourceInfo`
Furthermore, _we no longer carry "default" customization options throughout the schema_. All customization information is extracted from the `SourceInfo`, when required. This prevents an entire category of bugs we had previously encountered, such as parts of the code using uninitialized / unupdated customization info.
In turn, this meant that we could remove the explicit threading of the `SourceInfo` throughout the schema, since it is now always available through the reader context.
Finally, this meant making a few adjustments to relay and actions as well, such as the introduction of a new separate "context" for actions, and a change to how we create some of the action-specific postgres scalar parsers.
I'll highlight with review comments the areas of interest.
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/6709
GitOrigin-RevId: ea80fddcb24e2513779dd04b0b700a55f0028dd1
2022-11-17 13:34:05 +03:00
|
|
|
MonadBuildSourceSchema b r m n =>
|
2022-06-30 18:22:19 +03:00
|
|
|
-- | table info
|
|
|
|
TableInfo b ->
|
|
|
|
-- | field display name
|
|
|
|
G.Name ->
|
|
|
|
-- | field description, if any
|
|
|
|
Maybe G.Description ->
|
2022-09-06 19:48:04 +03:00
|
|
|
SchemaT r m (Maybe (FieldParser n (AggSelectExp b)))
|
2022-06-30 18:22:19 +03:00
|
|
|
|
2020-12-01 18:50:18 +03:00
|
|
|
type ComparisonExp b = OpExpG b (UnpreparedValue b)
|
2021-11-10 03:37:42 +03:00
|
|
|
|
2023-04-04 15:45:20 +03:00
|
|
|
class Backend b => BackendCustomReturnTypeSelectSchema (b :: BackendType) where
|
|
|
|
customReturnTypeArguments ::
|
2023-02-15 20:55:06 +03:00
|
|
|
MonadBuildSourceSchema b r m n =>
|
|
|
|
G.Name ->
|
2023-03-31 18:33:32 +03:00
|
|
|
CustomReturnTypeInfo b ->
|
2023-02-15 20:55:06 +03:00
|
|
|
SchemaT r m (InputFieldsParser n (IR.SelectArgsG b (UnpreparedValue b)))
|
|
|
|
|
2023-04-04 15:45:20 +03:00
|
|
|
customReturnTypeSelectionSet ::
|
2023-02-15 20:55:06 +03:00
|
|
|
MonadBuildSourceSchema b r m n =>
|
|
|
|
G.Name ->
|
2023-04-04 15:45:20 +03:00
|
|
|
CustomReturnTypeInfo b ->
|
2023-02-15 20:55:06 +03:00
|
|
|
SchemaT r m (Maybe (Parser 'Output n (AnnotatedFields b)))
|
|
|
|
|
2023-01-10 04:54:40 +03:00
|
|
|
class Backend b => BackendUpdateOperatorsSchema (b :: BackendType) where
|
|
|
|
-- | Intermediate Representation of the set of update operators that act
|
|
|
|
-- upon table fields during an update mutation. (For example, _set and _inc)
|
|
|
|
--
|
|
|
|
-- It is parameterised over the type of fields, which changes during the IR
|
|
|
|
-- translation phases.
|
|
|
|
type UpdateOperators b :: Type -> Type
|
|
|
|
|
|
|
|
parseUpdateOperators ::
|
|
|
|
forall m n r.
|
|
|
|
MonadBuildSchema b r m n =>
|
|
|
|
TableInfo b ->
|
|
|
|
UpdPermInfo b ->
|
|
|
|
SchemaT r m (InputFieldsParser n (HashMap (Column b) (UpdateOperators b (UnpreparedValue b))))
|
|
|
|
|
2021-11-10 03:37:42 +03:00
|
|
|
-- $modelling
|
|
|
|
-- #modelling#
|
|
|
|
--
|
|
|
|
-- In its current form, we model every component, from the top level (query,
|
|
|
|
-- insert mutation, etc.) of the schema down to its leaf values, as a type class
|
|
|
|
-- method of @BackendSchema@.
|
|
|
|
--
|
|
|
|
-- Consider, for example, the following query for a given table "author":
|
|
|
|
--
|
|
|
|
-- > query {
|
|
|
|
-- > author(where: {id: {_eq: 2}}) {
|
|
|
|
-- > name
|
|
|
|
-- > }
|
|
|
|
-- > }
|
|
|
|
--
|
|
|
|
-- The chain of functions leading to a parser for this RootField will be along
|
|
|
|
-- the lines of:
|
|
|
|
--
|
2022-06-07 08:32:08 +03:00
|
|
|
-- > > BackendSchema.buildTableQueryAndSubscriptionFields (Suggested default its GSB namesake)
|
2021-11-10 03:37:42 +03:00
|
|
|
-- > > GSS.selectTable
|
|
|
|
-- > > BackendSchema.tableArguments (Suggested default implementation being
|
|
|
|
-- > GSS.defaultTableArgs)
|
|
|
|
-- > > GSS.tableWhereArg
|
|
|
|
-- > > GSBE.boolExp
|
|
|
|
-- > > BackendSchema.comparisonExps
|
|
|
|
-- > > BackendSchema.columnParser
|
|
|
|
-- >
|
|
|
|
-- > > tableSelectionSet (...)
|
|
|
|
-- > > fieldSelection
|
|
|
|
--
|
|
|
|
-- (where the abbreviation @GSB@ refers to "Hasura.GraphQL.Schema.Build" and @GSS@
|
|
|
|
-- refers to "Hasura.GraphQL.Schema.Select", and @GSBE@ refers to
|
|
|
|
-- "Hasura.GraphQL.Schema.BoolExp".)
|
|
|
|
--
|
|
|
|
-- Several of those steps are part of the class, meaning that a backend can
|
|
|
|
-- customize part of this tree without having to reimplement all of it. For
|
|
|
|
-- instance, a backend that supports a different set ot table arguments can
|
|
|
|
-- choose to reimplement 'tableArguments', but can still use
|
|
|
|
-- 'Hasura.GraphQL.Schema.Select.tableWhereArg' in its custom implementation.
|
|
|
|
--
|
|
|
|
-- Applying the above modelling guidelines has pros and cons:
|
|
|
|
--
|
|
|
|
-- * Pro: You can specify both shared and diverging behavior.
|
|
|
|
-- * Pro: You can specify a lot of behavior implicitly, i.e. it's easy to write.
|
2022-08-22 18:57:46 +03:00
|
|
|
-- * Con: You can specify a lot of behavior implicitly, i.e. it's hard to
|
2021-11-10 03:37:42 +03:00
|
|
|
-- understand without tracing through implementations.
|
|
|
|
-- * Con: You get a proliferation of type class methods and it's difficult to
|
|
|
|
-- understand how they fit together.
|
|
|
|
--
|
|
|
|
-- == Going forward, we want to follow some different modelling guidelines:
|
|
|
|
--
|
|
|
|
-- We should break up / refactor the building blocks (in
|
|
|
|
-- "Hasura.GraphQL.Schema.Build" etc.) which are used to implement the top-level
|
2022-06-07 08:32:08 +03:00
|
|
|
-- type class methods (e.g. @BackendSchema@.'buildTableQueryAndSubscriptionFields', c.f.
|
|
|
|
-- @GSB.@'Hasura.GraphQL.Schema.Build.buildTableQueryAndSubscriptionFields', etc.) and have them
|
2021-11-10 03:37:42 +03:00
|
|
|
-- invoke the backend-specific behaviors they rely on via /function arguments/
|
|
|
|
-- instead of other type class methods.
|
|
|
|
--
|
|
|
|
-- When we do this, the function call sites (which will often be in @instance
|
2022-08-22 18:57:46 +03:00
|
|
|
-- BackendSchema ...@) become the centralised places where we decide which behavior
|
2021-11-10 03:37:42 +03:00
|
|
|
-- variation to follow.
|
|
|
|
--
|
|
|
|
-- When faced with answering the question of "what does this method do, and how does
|
|
|
|
-- it do it?", at least you will have listed the other components it depends on
|
|
|
|
-- front and center without having to trace through its implementation.
|
|
|
|
--
|
|
|
|
-- That is of course, if we refactor our building blocks mindfully into
|
|
|
|
-- conceptually meaningful units. Otherwise we'll just end up with an
|
|
|
|
-- incomprehensible mass of poorly shaped pieces. And we will still have a hard
|
|
|
|
-- time explaining what they do.
|
|
|
|
--
|
|
|
|
-- In other words, It is still the case that if you don't clean your room
|
|
|
|
-- you'll be living in a mess.
|