graphql-engine/server/src-lib/Data/HashMap/Strict/Extended.hs
Antoine Leblanc 3a400fab3d Rewrite OpenAPI
### Description

This PR rewrites OpenAPI to be more idiomatic. Some noteworthy changes:
- we accumulate all required information during the Analyze phase, to avoid having to do a single lookup in the schema cache during the OpenAPI generation phase (we now only need the schema cache as input to run the analysis)
- we no longer build intermediary endpoint information and aggregate it, we directly build the the `PathItem` for each endpoint; additionally, that means we no longer have to assume that different methods have the same metadata
- we no longer have to first declare types, then craft references: we do everything in one step
- we now properly deal with nullability by treating "typeName" and "typeName!" as different
- we add a bunch of additional fields in the generated "schema", such as title
- we do now support enum values in both input and output positions
- checking whether the request body is required is now performed on the fly rather than by introspecting the generated schema
- the methods in the file are sorted by topic

### Controversial point

However, this PR creates some additional complexity, that we might not want to keep. The main complexity is _knot-tying_: to avoid lookups when generating the OpenAPI, it builds an actual graph of input types, which means that we need something similar to (but simpler than) `MonadSchema`, to avoid infinite recursions when analyzing the input types of a query. To do this, this PR introduces `CircularT`, a lesser `SchemaT` that aims at avoiding ever having to reinvent this particular wheel ever again.

### Remaining work

- [x] fix existing tests (they are all failing due to some of the schema changes)
- [ ] add tests to cover the new features:
  - [x] tests for `CircularT`
  - [ ] tests for enums in output schemas
- [x] extract / document `CircularT` if we wish to keep it
- [x] add more comments to `OpenAPI`
- [x] have a second look at `buildVariableSchema`
- [x] fix all missing diagnostics in `Analyze`
- [x] add a Changelog entry?

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/4654
Co-authored-by: David Overton <7734777+dmoverton@users.noreply.github.com>
GitOrigin-RevId: f4a9191f22dfcc1dccefd6a52f5c586b6ad17172
2022-06-30 12:57:09 +00:00

118 lines
3.7 KiB
Haskell

module Data.HashMap.Strict.Extended
( module M,
catMaybes,
fromListOn,
groupOn,
groupOnNE,
differenceOn,
insertWithM,
isInverseOf,
unionWithM,
unionsAll,
homogenise,
)
where
import Control.Monad (foldM)
import Data.Foldable qualified as F
import Data.Function (on)
import Data.HashMap.Strict as M
import Data.HashSet (HashSet)
import Data.HashSet qualified as S
import Data.Hashable (Hashable)
import Data.List qualified as L
import Data.List.NonEmpty (NonEmpty (..))
import Prelude
catMaybes :: HashMap k (Maybe v) -> HashMap k v
catMaybes = M.mapMaybe id
fromListOn :: (Eq k, Hashable k) => (v -> k) -> [v] -> HashMap k v
fromListOn f = fromList . Prelude.map (\v -> (f v, v))
-- | Given a 'Foldable' sequence of values and a function that extracts a key from each value,
-- returns a 'HashMap' that maps each key to a list of all values in the sequence for which the
-- given function produced it.
--
-- >>> groupOn (take 1) ["foo", "bar", "baz"]
-- fromList [("f", ["foo"]), ("b", ["bar", "baz"])]
groupOn :: (Eq k, Hashable k, Foldable t) => (v -> k) -> t v -> HashMap k [v]
groupOn f = fmap F.toList . groupOnNE f
groupOnNE ::
(Eq k, Hashable k, Foldable t) => (v -> k) -> t v -> HashMap k (NonEmpty v)
groupOnNE f =
Prelude.foldr
(\v -> M.alter (Just . (v :|) . maybe [] F.toList) (f v))
M.empty
differenceOn ::
(Eq k, Hashable k, Foldable t) => (v -> k) -> t v -> t v -> HashMap k v
differenceOn f = M.difference `on` (fromListOn f . F.toList)
-- | Monadic version of https://hackage.haskell.org/package/unordered-containers-0.2.18.0/docs/Data-HashMap-Internal.html#v:insertWith
insertWithM :: (Monad m, Hashable k, Eq k) => (v -> v -> m v) -> k -> v -> HashMap k v -> m (HashMap k v)
insertWithM f k v m =
sequence $
M.insertWith
( \a b -> do
x <- a
y <- b
f x y
)
k
(return v)
(return <$> m)
-- | Determines whether the left-hand-side and the right-hand-side are inverses of each other.
--
-- More specifically, for two maps @A@ and @B@, 'isInverseOf' is satisfied when both of the
-- following are true:
-- 1. @∀ key ∈ A. A[key] ∈ B ∧ B[A[key]] == key@
-- 2. @∀ key ∈ B. B[key] ∈ A ∧ A[B[key]] == key@
isInverseOf ::
(Eq k, Hashable k, Eq v, Hashable v) => HashMap k v -> HashMap v k -> Bool
lhs `isInverseOf` rhs = lhs `invertedBy` rhs && rhs `invertedBy` lhs
where
invertedBy ::
forall s t.
(Eq s, Eq t, Hashable t) =>
HashMap s t ->
HashMap t s ->
Bool
a `invertedBy` b = and $ do
(k, v) <- M.toList a
pure $ M.lookup v b == Just k
-- | The union of two maps.
--
-- If a key occurs in both maps, the provided function (first argument) will be
-- used to compute the result. Unlike 'unionWith', 'unionWithM' performs the
-- computation in an arbitratry monad.
unionWithM ::
(Monad m, Eq k, Hashable k) =>
(k -> v -> v -> m v) ->
HashMap k v ->
HashMap k v ->
m (HashMap k v)
unionWithM f m1 m2 = foldM step m1 (toList m2)
where
step m (k, new) = case M.lookup k m of
Nothing -> pure $ insert k new m
Just old -> do
combined <- f k new old
pure $ insert k combined m
-- | Like 'M.unions', but keeping all elements in the result.
unionsAll ::
(Eq k, Hashable k, Foldable t) => t (HashMap k v) -> HashMap k (NonEmpty v)
unionsAll = F.foldl' (\a b -> unionWith (<>) a (fmap (:| []) b)) M.empty
-- | Homogenise maps, such that all maps range over the full set of
-- keys, inserting a default value as needed.
homogenise :: (Hashable a, Eq a) => b -> [HashMap a b] -> (HashSet a, [HashMap a b])
homogenise defaultValue maps =
let ks = S.unions $ L.map keysSet maps
defaults = fromList [(k, defaultValue) | k <- S.toList ks]
in (ks, L.map (<> defaults) maps)