packages feed

keiro-ops-0.26.0.0: src/Keiro/Ops/Topology.hs

-- | Serve an application's committed keiro-dsl service-topology document.
--
-- The document is a published, versioned contract owned by keiro-dsl
-- (@docs/adr/0062-the-service-topology-is-a-versioned-keiro-owned-contract-emitted-under-the-lowest-sufficient-schema-id.md@).
-- This module does not depend on keiro-dsl. It checks the envelope fields the
-- summary needs and each schema id's node-kind and edge-relation vocabulary,
-- keeps kind-specific details opaque, and retains the exact mounted bytes so
-- HTTP hosts can return them unchanged.
module Keiro.Ops.Topology
  ( ServiceTopologyDocument,
    decodeServiceTopology,
    loadServiceTopology,
    serviceTopologySchemaId,
    serviceTopologyBytes,
    serviceTopologyValue,
    serviceTopologyDigest,
    serviceTopologySummary,
    supportedServiceTopologySchemaIds,
    Command (..),
    commandParser,
    isMutation,
    runCommand,
  )
where

import Control.Exception (IOException, try)
import Crypto.Hash.SHA256 qualified as SHA256
import Data.Aeson (Value (..), object, (.=))
import Data.Aeson qualified as Aeson
import Data.Aeson.Key qualified as Key
import Data.Aeson.KeyMap (KeyMap)
import Data.Aeson.KeyMap qualified as KeyMap
import Data.ByteString (ByteString)
import Data.ByteString qualified as ByteString
import Data.ByteString.Builder qualified as Builder
import Data.ByteString.Lazy qualified as LazyByteString
import Data.Foldable (toList)
import Data.Map.Strict qualified as Map
import Data.Set (Set)
import Data.Set qualified as Set
import Data.Text (Text)
import Data.Text qualified as Text
import Data.Text.Encoding qualified as Text.Encoding
import Keiro.Ops.Render
import Options.Applicative hiding (command, info, value)
import Options.Applicative qualified as Opt

-- | A mounted keiro-dsl service-topology document: the exact bytes and their
-- decoded value. Construct only with 'decodeServiceTopology'.
data ServiceTopologyDocument = ServiceTopologyDocument
  { bytes :: !ByteString,
    value :: !Value,
    schemaId :: !Text,
    service :: !Text,
    digest :: !Text,
    nodeCount :: !Int,
    edgeCount :: !Int,
    summary :: !Value
  }

instance Eq ServiceTopologyDocument where
  left == right = left.bytes == right.bytes

instance Show ServiceTopologyDocument where
  show document = "ServiceTopologyDocument " <> show document.schemaId <> " " <> show document.service <> " " <> show document.digest

serviceTopologySchemaId :: ServiceTopologyDocument -> Text
serviceTopologySchemaId document = document.schemaId

-- | The exact bytes that were mounted, including any final newline.
serviceTopologyBytes :: ServiceTopologyDocument -> ByteString
serviceTopologyBytes document = document.bytes

serviceTopologyValue :: ServiceTopologyDocument -> Value
serviceTopologyValue document = document.value

-- | @sha256:@ and the lowercase hex digest of the mounted bytes.
serviceTopologyDigest :: ServiceTopologyDocument -> Text
serviceTopologyDigest document = document.digest

-- | The snake_case summary served by @topology summary@, computed at decode.
serviceTopologySummary :: ServiceTopologyDocument -> Value
serviceTopologySummary document = document.summary

-- | Schema ids this reader can mount, oldest first.
supportedServiceTopologySchemaIds :: [Text]
supportedServiceTopologySchemaIds = Map.keys vocabularies

data Vocabulary = Vocabulary {nodeKinds :: !(Set Text), relations :: !(Set Text)}

-- Copied from @$defs.nodeKind.enum@ and @$defs.relation.enum@ in
-- @docs/user/schemas/keiro-dsl-service-topology-{1,2}.schema.json@ so a host
-- needs only the document. A new schema id or vocabulary requires a change here.
vocabularies :: Map.Map Text Vocabulary
vocabularies =
  Map.fromList
    [ ("keiro-dsl/service-topology/1", Vocabulary kinds relationsOne),
      ("keiro-dsl/service-topology/2", Vocabulary kinds (Set.insert "feeds" relationsOne))
    ]
  where
    kinds =
      Set.fromList
        [ "aggregate",
          "process",
          "workflow",
          "router",
          "contract",
          "intake",
          "emit",
          "publisher",
          "workqueue",
          "dispatch",
          "read-model",
          "operation",
          "projection-target",
          "rebuild-group",
          "projection-owner",
          "projection-revision",
          "external-read"
        ]
    relationsOne =
      Set.fromList
        [ "dispatches",
          "saga",
          "reads",
          "projects",
          "publishes",
          "subscribes",
          "delivers",
          "enqueues",
          "commands",
          "queries",
          "signals",
          "runs",
          "depends-on",
          "groups",
          "consumes",
          "writes",
          "member-of",
          "revises",
          "observes",
          "backed-by",
          "exposes",
          "compatible-with"
        ]

-- | Decode and check a document for mounting. The diagnostic names the
-- offending field and value. Additional object fields are ignored.
decodeServiceTopology :: ByteString -> Either Text ServiceTopologyDocument
decodeServiceTopology input = do
  value <- either (\err -> Left ("service topology is not valid JSON: " <> Text.pack err)) Right (Aeson.eitherDecodeStrict input)
  root <- case value of
    Object fields -> Right fields
    other -> Left ("service topology must be a JSON object, found " <> typeName other)
  schemaId <- textField "schema" root
  vocabulary <- case Map.lookup schemaId vocabularies of
    Just known -> Right known
    Nothing ->
      Left
        ( "unsupported service topology schema id "
            <> quoted schemaId
            <> " in field `schema`; supported: "
            <> Text.intercalate ", " supportedServiceTopologySchemaIds
        )
  service <- textField "service" root
  generator <- objectField "generator" root
  generatorVersion <- prefixed "generator" (textField "version" generator)
  members <- arrayField "members" root
  projectedMembers <- traverse member (zip [0 :: Int ..] members)
  nodes <- arrayField "nodes" root
  observedKinds <- traverse (node vocabulary) (zip [0 :: Int ..] nodes)
  edges <- arrayField "edges" root
  observedRelations <- traverse (edge vocabulary) (zip [0 :: Int ..] edges)
  let digest = "sha256:" <> hexDigest input
      sourceField = case KeyMap.lookup "source" root of
        Just (Object source)
          | Just (String kind) <- KeyMap.lookup "kind" source,
            kind `elem` ["source", "workspace"],
            Just (String path) <- KeyMap.lookup "path" source ->
              ["source" .= object ["kind" .= kind, "path" .= path]]
        _ -> []
      summary =
        object
          ( [ "schema_id" .= schemaId,
              "service" .= service,
              "generator_version" .= generatorVersion,
              "members" .= projectedMembers,
              "node_counts" .= counts observedKinds,
              "edge_counts" .= counts observedRelations,
              "document_bytes" .= ByteString.length input,
              "document_sha256" .= digest
            ]
              <> sourceField
          )
  Right
    ServiceTopologyDocument
      { bytes = input,
        value,
        schemaId,
        service,
        digest,
        nodeCount = length nodes,
        edgeCount = length edges,
        summary
      }
  where
    member (index, entry) = prefixed (indexed "members" index) $ do
      fields <- asObject entry
      path <- textField "path" fields
      sha256 <- textField "sha256" fields
      Right (object ["path" .= path, "sha256" .= sha256])
    node vocabulary (index, entry) = prefixed (indexed "nodes" index) $ do
      fields <- asObject entry
      kindOf vocabulary fields
    edge vocabulary (index, entry) = prefixed (indexed "edges" index) $ do
      fields <- asObject entry
      _ <- objectField "from" fields >>= prefixed "from" . kindOf vocabulary
      _ <- objectField "to" fields >>= prefixed "to" . kindOf vocabulary
      relation <- textField "relation" fields
      if Set.member relation vocabulary.relations
        then Right relation
        else Left ("field `relation`: unknown relation " <> quoted relation <> " for this schema id")
    kindOf vocabulary fields = do
      kind <- textField "kind" fields
      if Set.member kind vocabulary.nodeKinds
        then Right kind
        else Left ("field `kind`: unknown node kind " <> quoted kind <> " for this schema id")
    indexed name index = name <> "[" <> Text.pack (show index) <> "]"
    -- Diagnostics from nested fields carry their path, e.g. @edges[3].relation@.
    prefixed prefix = either (Left . addPrefix prefix) Right
    addPrefix prefix message = case Text.stripPrefix "field `" message of
      Just rest
        | "`" `Text.isPrefixOf` rest -> "field `" <> prefix <> rest
        | otherwise -> "field `" <> prefix <> "." <> rest
      Nothing -> message
    asObject = \case
      Object fields -> Right fields
      other -> Left ("field ``: expected an object, found " <> typeName other)
    counts = Map.fromListWith (+) . map (,1 :: Int)

-- | Read and decode a document from disk. I/O and decode failures are both
-- returned as 'Left' so callers can report the failing path.
loadServiceTopology :: FilePath -> IO (Either Text ServiceTopologyDocument)
loadServiceTopology path = do
  result <- try (ByteString.readFile path)
  pure $ case result of
    Left (err :: IOException) -> Left (Text.pack path <> ": " <> Text.pack (show err))
    Right input -> either (Left . ((Text.pack path <> ": ") <>)) Right (decodeServiceTopology input)

textField :: Text -> KeyMap Value -> Either Text Text
textField name fields = case KeyMap.lookup (Key.fromText name) fields of
  Just (String text) -> Right text
  Just other -> Left ("field `" <> name <> "`: expected a string, found " <> typeName other)
  Nothing -> Left ("field `" <> name <> "`: missing")

objectField :: Text -> KeyMap Value -> Either Text (KeyMap Value)
objectField name fields = case KeyMap.lookup (Key.fromText name) fields of
  Just (Object inner) -> Right inner
  Just other -> Left ("field `" <> name <> "`: expected an object, found " <> typeName other)
  Nothing -> Left ("field `" <> name <> "`: missing")

arrayField :: Text -> KeyMap Value -> Either Text [Value]
arrayField name fields = case KeyMap.lookup (Key.fromText name) fields of
  Just (Array items) -> Right (toList items)
  Just other -> Left ("field `" <> name <> "`: expected an array, found " <> typeName other)
  Nothing -> Left ("field `" <> name <> "`: missing")

typeName :: Value -> Text
typeName = \case
  Object _ -> "an object"
  Array _ -> "an array"
  String text -> "the string " <> quoted text
  Number _ -> "a number"
  Bool _ -> "a boolean"
  Null -> "null"

quoted :: Text -> Text
quoted text = Text.pack (show (Text.unpack (Text.take 120 text)))

hexDigest :: ByteString -> Text
hexDigest = Text.Encoding.decodeUtf8 . LazyByteString.toStrict . Builder.toLazyByteString . Builder.byteStringHex . SHA256.hash

data Command = Show | Summary
  deriving stock (Eq, Show)

commandParser :: Parser Command
commandParser =
  hsubparser
    ( Opt.command "show" (Opt.info (pure Show) (progDesc "Print the mounted service-topology document"))
        <> Opt.command "summary" (Opt.info (pure Summary) (progDesc "Summarize the mounted service-topology document"))
    )

isMutation :: Command -> Bool
isMutation = const False

-- | Both reads are pure: the document is fixed for the life of the process.
-- HTTP hosts serve @show@ from 'serviceTopologyBytes' instead of re-encoding.
runCommand :: ServiceTopologyDocument -> Command -> OpsOutcome
runCommand document = \case
  Show ->
    Succeeded
      ( OpsResult
          ["schema", "service", "nodes", "edges"]
          [[document.schemaId, document.service, Text.pack (show document.nodeCount), Text.pack (show document.edgeCount)]]
          document.value
      )
  Summary ->
    Succeeded
      ( OpsResult
          ["schema_id", "service", "nodes", "edges", "document_bytes", "document_sha256"]
          [ [ document.schemaId,
              document.service,
              Text.pack (show document.nodeCount),
              Text.pack (show document.edgeCount),
              Text.pack (show (ByteString.length document.bytes)),
              document.digest
            ]
          ]
          document.summary
      )