packages feed

keiro-ops 0.25.1.0 → 0.26.0.0

raw patch · 7 files changed

+642/−10 lines, 7 filesdep +cryptohash-sha256dep +directorydep +filepathdep ~keirodep ~keiro-migrationsdep ~keiro-pgmqPVP ok

version bump matches the API change (PVP)

Dependencies added: cryptohash-sha256, directory, filepath

Dependency ranges changed: keiro, keiro-migrations, keiro-pgmq, keiro-test-support

API changes (from Hackage documentation)

+ Keiro.Ops: Topology :: Command -> Command
+ Keiro.Ops: [serviceTopology] :: AppHooks -> !Maybe ServiceTopologyDocument
+ Keiro.Ops: data ServiceTopologyDocument
+ Keiro.Ops: decodeServiceTopology :: ByteString -> Either Text ServiceTopologyDocument
+ Keiro.Ops: loadServiceTopology :: FilePath -> IO (Either Text ServiceTopologyDocument)
+ Keiro.Ops: serviceTopologyBytes :: ServiceTopologyDocument -> ByteString
+ Keiro.Ops: serviceTopologyDigest :: ServiceTopologyDocument -> Text
+ Keiro.Ops: serviceTopologySchemaId :: ServiceTopologyDocument -> Text
+ Keiro.Ops: serviceTopologySummary :: ServiceTopologyDocument -> Value
+ Keiro.Ops: serviceTopologyValue :: ServiceTopologyDocument -> Value
+ Keiro.Ops.Embed: [serviceTopology] :: AppHooks -> !Maybe ServiceTopologyDocument
+ Keiro.Ops.Topology: Show :: Command
+ Keiro.Ops.Topology: Summary :: Command
+ Keiro.Ops.Topology: commandParser :: Parser Command
+ Keiro.Ops.Topology: data Command
+ Keiro.Ops.Topology: data ServiceTopologyDocument
+ Keiro.Ops.Topology: decodeServiceTopology :: ByteString -> Either Text ServiceTopologyDocument
+ Keiro.Ops.Topology: instance GHC.Classes.Eq Keiro.Ops.Topology.Command
+ Keiro.Ops.Topology: instance GHC.Classes.Eq Keiro.Ops.Topology.ServiceTopologyDocument
+ Keiro.Ops.Topology: instance GHC.Internal.Show.Show Keiro.Ops.Topology.Command
+ Keiro.Ops.Topology: instance GHC.Internal.Show.Show Keiro.Ops.Topology.ServiceTopologyDocument
+ Keiro.Ops.Topology: isMutation :: Command -> Bool
+ Keiro.Ops.Topology: loadServiceTopology :: FilePath -> IO (Either Text ServiceTopologyDocument)
+ Keiro.Ops.Topology: runCommand :: ServiceTopologyDocument -> Command -> OpsOutcome
+ Keiro.Ops.Topology: serviceTopologyBytes :: ServiceTopologyDocument -> ByteString
+ Keiro.Ops.Topology: serviceTopologyDigest :: ServiceTopologyDocument -> Text
+ Keiro.Ops.Topology: serviceTopologySchemaId :: ServiceTopologyDocument -> Text
+ Keiro.Ops.Topology: serviceTopologySummary :: ServiceTopologyDocument -> Value
+ Keiro.Ops.Topology: serviceTopologyValue :: ServiceTopologyDocument -> Value
+ Keiro.Ops.Topology: supportedServiceTopologySchemaIds :: [Text]
- Keiro.Ops: AppHooks :: !Maybe ResumeHook -> !Maybe TimerFire -> !Maybe OpsAuditConfig -> !Maybe ProjectionCatalogOperations -> !Maybe AggregateInspectors -> !Maybe DurableConsumerRegistry -> !Maybe ProcessManagerInspectors -> AppHooks
+ Keiro.Ops: AppHooks :: !Maybe ResumeHook -> !Maybe TimerFire -> !Maybe OpsAuditConfig -> !Maybe ProjectionCatalogOperations -> !Maybe AggregateInspectors -> !Maybe DurableConsumerRegistry -> !Maybe ProcessManagerInspectors -> !Maybe ServiceTopologyDocument -> AppHooks
- Keiro.Ops.Embed: AppHooks :: !Maybe ResumeHook -> !Maybe TimerFire -> !Maybe OpsAuditConfig -> !Maybe ProjectionCatalogOperations -> !Maybe AggregateInspectors -> !Maybe DurableConsumerRegistry -> !Maybe ProcessManagerInspectors -> AppHooks
+ Keiro.Ops.Embed: AppHooks :: !Maybe ResumeHook -> !Maybe TimerFire -> !Maybe OpsAuditConfig -> !Maybe ProjectionCatalogOperations -> !Maybe AggregateInspectors -> !Maybe DurableConsumerRegistry -> !Maybe ProcessManagerInspectors -> !Maybe ServiceTopologyDocument -> AppHooks

Files

CHANGELOG.md view
@@ -6,6 +6,28 @@  ## [Unreleased] +## 0.26.0.0 — 2026-11-18++### Breaking Changes++- `AppHooks` gains `serviceTopology :: Maybe ServiceTopologyDocument`; direct record+  constructors must supply it (`Nothing` keeps the previous behavior). Updating+  `emptyAppHooks` remains the preferred embedding pattern.+- `Keiro.Ops.Command` gains a `Topology` constructor; exhaustive matches must handle it.++### New Features++- `Keiro.Ops.Topology` mounts an application's committed keiro-dsl service-topology+  document. `decodeServiceTopology` and `loadServiceTopology` accept schema ids+  `keiro-dsl/service-topology/1` and `/2`, check the envelope and each id's node kinds+  and edge relations, and keep the exact bytes. The type, loader, decoder and accessors+  are re-exported from `Keiro.Ops`.+- With the hook mounted, `topology show` returns the document and `topology summary`+  returns a snake_case header with member digests, node and edge counts, and the+  document's size and SHA-256. Both are reads. HTTP hosts serve `show` as the mounted+  bytes; the CLI's `--json topology show` re-encodes the decoded value.+- Adds a direct dependency on `cryptohash-sha256`, already required by `keiro`.+ ## 0.25.1.0 — 2026-11-16  ### Other Changes
keiro-ops.cabal view
@@ -1,6 +1,6 @@ cabal-version: 3.0 name: keiro-ops-version: 0.25.1.0+version: 0.26.0.0 synopsis: Operational command-line interface for Keiro deployments description:   A standalone database-only console and embeddable command tree for inspecting@@ -65,6 +65,7 @@     Keiro.Ops.Snapshot     Keiro.Ops.Stream     Keiro.Ops.Timer+    Keiro.Ops.Topology     Keiro.Ops.Workflow     Keiro.Ops.WorkflowHeaderCache @@ -73,13 +74,14 @@     base >=4.21 && <5,     bytestring >=0.12 && <0.13,     containers >=0.6 && <0.8,+    cryptohash-sha256 >=0.11.102 && <0.12,     effectful >=2.6 && <2.8,     effectful-core >=2.6 && <2.7 || >=2.7.1.1 && <2.8,     hasql >=1.10 && <1.11,     hasql-pool >=1.4 && <1.5,-    keiro ^>=0.25.1.0,-    keiro-migrations ^>=0.25.1.0,-    keiro-pgmq ^>=0.25.1.0,+    keiro ^>=0.26.0.0,+    keiro-migrations ^>=0.26.0.0,+    keiro-pgmq ^>=0.26.0.0,     kiroku-store ^>=0.13.0.1,     optparse-applicative >=0.18 && <0.20,     text >=2.1 && <2.2,@@ -113,6 +115,7 @@   other-modules:     CategoryConsumersSpec     ReactionInspectionSpec+    TopologySpec    build-tool-depends: keiro-ops:keiro-ops   build-depends:@@ -120,16 +123,19 @@     base >=4.21 && <5,     bytestring >=0.12 && <0.13,     containers >=0.6 && <0.8,+    cryptohash-sha256 >=0.11.102 && <0.12,+    directory >=1.3 && <1.4,     effectful >=2.6 && <2.8,     effectful-core >=2.6 && <2.7 || >=2.7.1.1 && <2.8,+    filepath >=1.4 && <1.6,     hasql >=1.10 && <1.11,     hasql-transaction >=1.1 && <1.3,     hspec >=2.11,     keiki >=0.9.1 && <0.10,-    keiro ^>=0.25.1.0,+    keiro ^>=0.26.0.0,     keiro-ops,-    keiro-pgmq ^>=0.25.1.0,-    keiro-test-support ^>=0.25.1.0,+    keiro-pgmq ^>=0.26.0.0,+    keiro-test-support ^>=0.26.0.0,     kiroku-store ^>=0.13.0.1,     optparse-applicative >=0.18 && <0.20,     pgmq-migration >=0.7.0.0 && <0.8,
src/Keiro/Ops.hs view
@@ -4,6 +4,14 @@     AppHooks (..),     AggregateInspectors,     ProcessManagerInspectors,+    ServiceTopologyDocument,+    decodeServiceTopology,+    loadServiceTopology,+    serviceTopologySchemaId,+    serviceTopologyBytes,+    serviceTopologyValue,+    serviceTopologyDigest,+    serviceTopologySummary,     OpsAuditConfig (..),     emptyAppHooks,     OpsInvocation (..),@@ -43,6 +51,17 @@ import Keiro.Ops.Snapshot qualified as Snapshot import Keiro.Ops.Stream qualified as Stream import Keiro.Ops.Timer qualified as Timer+import Keiro.Ops.Topology+  ( ServiceTopologyDocument,+    decodeServiceTopology,+    loadServiceTopology,+    serviceTopologyBytes,+    serviceTopologyDigest,+    serviceTopologySchemaId,+    serviceTopologySummary,+    serviceTopologyValue,+  )+import Keiro.Ops.Topology qualified as Topology import Keiro.Ops.Workflow qualified as Workflow import Keiro.Ops.WorkflowHeaderCache (WorkflowHeaderCache, runHeaderCached) import Kiroku.Store.Connection (defaultConnectionSettings, withStore)@@ -90,6 +109,7 @@   | Stream Stream.Command   | ReplayAudit ReplayAudit.Command   | Rebuild Rebuild.Command+  | Topology Topology.Command  opsCommandTree :: AppHooks -> ParserInfo OpsInvocation opsCommandTree hooks =@@ -144,8 +164,12 @@         <> rebuildCommand         <> aggregateCommand         <> processManagerCommand+        <> topologyCommand     )   where+    topologyCommand = case hooks.serviceTopology of+      Nothing -> mempty+      Just _ -> command "topology" (info (Topology <$> Topology.commandParser) (progDesc "Read the mounted service-topology document"))     processManagerCommand = case hooks.processManagers of       Nothing -> mempty       Just _ -> command "pm" (info (ProcessManager <$> ProcessManager.commandParser) (progDesc "Inspect mounted process managers"))@@ -218,6 +242,7 @@   Stream streamCommand -> Stream.isMutation streamCommand   ReplayAudit _ -> False   Rebuild rebuildCommand -> Rebuild.isMutation rebuildCommand+  Topology topologyCommand -> Topology.isMutation topologyCommand  -- | Reuse only pure header presentation after an exact fresh database check. -- The optional bytes encode this outcome's successful read result. Other@@ -247,6 +272,10 @@       pure $ case encoded of         Nothing -> (InspectionFailed "inspection_result_too_large" "encoded result exceeds the host limit; narrow the read", Nothing)         Just body -> (Succeeded result, Just body)+  -- The committed bytes are the response; never re-encode the document.+  Topology Topology.Show | Just document <- hooks.serviceTopology -> do+    outcome <- runCommand hooks env command+    pure (outcome, Just (serviceTopologyBytes document))   _ -> runCommandWithHeaderCache cache hooks env command  -- | Execute a parsed command after schema verification. Front ends must use@@ -274,6 +303,8 @@       (pure (Failed "projection catalog hook is not mounted"))       (\operations -> Rebuild.runCommand env operations rebuildCommand)       hooks.projectionCatalog+  Topology topologyCommand ->+    pure (maybe (Failed "service topology hook is not mounted") (\document -> Topology.runCommand document topologyCommand) hooks.serviceTopology)  finishOutcome :: OpsEnv -> OpsOutcome -> IO Exit.ExitCode finishOutcome env = \case
src/Keiro/Ops/Embed.hs view
@@ -16,6 +16,7 @@ import Keiro.Inspection.Consumers (DurableConsumerRegistry) import Keiro.Ops.ReplayAudit (OpsAuditConfig (..)) import Keiro.Ops.Timer (TimerFire)+import Keiro.Ops.Topology (ServiceTopologyDocument) import Keiro.Ops.Workflow (ResumeHook) import Keiro.ProcessManager.Inspect (ProcessManagerInspectors) import Keiro.Projection.Catalog.Operations (ProjectionCatalogOperations)@@ -27,7 +28,10 @@     projectionCatalog :: !(Maybe ProjectionCatalogOperations),     aggregates :: !(Maybe AggregateInspectors),     durableConsumers :: !(Maybe DurableConsumerRegistry),-    processManagers :: !(Maybe ProcessManagerInspectors)+    processManagers :: !(Maybe ProcessManagerInspectors),+    -- | The application's committed keiro-dsl service topology. Mounts+    -- @topology show@ and @topology summary@.+    serviceTopology :: !(Maybe ServiceTopologyDocument)   }  emptyAppHooks :: AppHooks@@ -39,5 +43,6 @@       projectionCatalog = Nothing,       aggregates = Nothing,       durableConsumers = Nothing,-      processManagers = Nothing+      processManagers = Nothing,+      serviceTopology = Nothing     }
+ src/Keiro/Ops/Topology.hs view
@@ -0,0 +1,320 @@+-- | 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+      )
test/Main.hs view
@@ -82,6 +82,7 @@ import System.Exit (ExitCode (..)) import System.Process (readProcessWithExitCode) import Test.Hspec+import TopologySpec qualified  main :: IO () main = do@@ -97,7 +98,8 @@       projectionCatalog = Just emptyCatalogOperations,       aggregates = Just Map.empty,       durableConsumers = Nothing,-      processManagers = Just Map.empty+      processManagers = Just Map.empty,+      serviceTopology = Nothing     }  emptyCatalogOperations :: CatalogOperations.ProjectionCatalogOperations@@ -121,6 +123,7 @@ spec fixture = do   CategoryConsumersSpec.spec fixture   ReactionInspectionSpec.spec fixture+  TopologySpec.spec fixture   describe "embedded command tree" do     it "omits code-dependent commands from the standalone tree" do       isParseSuccess (parseOps Ops.emptyAppHooks ["pm", "show", "--name", "test", "--correlation", "one"]) `shouldBe` False
+ test/TopologySpec.hs view
@@ -0,0 +1,245 @@+{-# LANGUAGE MultilineStrings #-}++module TopologySpec (spec) where++import Control.Exception (bracket, finally)+import Control.Monad (forM_)+import Crypto.Hash.SHA256 qualified as SHA256+import Data.Aeson (Value (..), object, (.=))+import Data.Aeson qualified as Aeson+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.Char8 qualified as Char8+import Data.ByteString.Lazy qualified as LazyByteString+import Data.Foldable (toList)+import Data.Map.Strict qualified as Map+import Data.Maybe (isJust)+import Data.Text (Text)+import Data.Text qualified as Text+import Data.Text.Encoding qualified as Text.Encoding+import GHC.IO.Handle (hDuplicate, hDuplicateTo)+import Keiro.Ops qualified as Ops+import Keiro.Ops.Render+import Keiro.Ops.Topology qualified as Topology+import Keiro.Test.Postgres (Fixture, withFreshDatabase)+import Options.Applicative qualified as Opt+import System.Directory (getTemporaryDirectory, removeFile)+import System.Environment (lookupEnv)+import System.Exit (ExitCode (..))+import System.FilePath ((</>))+import System.IO+import Test.Hspec++spec :: Fixture -> Spec+spec fixture = describe "service topology" $ do+  describe "decodeServiceTopology" $ do+    it "accepts a /1 document whose aggregate predates the category field" $ do+      document <- decoded schemaOneDocument+      Topology.serviceTopologySchemaId document `shouldBe` "keiro-dsl/service-topology/1"+      Topology.serviceTopologyBytes document `shouldBe` schemaOneDocument+      Topology.serviceTopologyValue document `shouldBe` json schemaOneDocument+      Topology.serviceTopologySummary document+        `shouldBe` object+          [ "schema_id" .= ("keiro-dsl/service-topology/1" :: Text),+            "service" .= ("orders" :: Text),+            "generator_version" .= ("1.2.3" :: Text),+            "source" .= object ["kind" .= ("source" :: Text), "path" .= ("orders.keiro" :: Text)],+            "members" .= [object ["path" .= ("orders.keiro" :: Text), "sha256" .= ("sha256:00" :: Text)]],+            "node_counts" .= object ["aggregate" .= (1 :: Int), "read-model" .= (2 :: Int)],+            "edge_counts" .= object ["writes" .= (1 :: Int), "consumes" .= (1 :: Int)],+            "document_bytes" .= ByteString.length schemaOneDocument,+            "document_sha256" .= ("sha256:" <> hex schemaOneDocument)+          ]++    it "computes the digest as lowercase hex SHA-256 of the exact bytes" $ do+      -- The known answer from `printf '{"a":1}\n' | shasum -a 256` checks the+      -- test's own digest helper independently of the library under test.+      document <- decoded schemaOneDocument+      Topology.serviceTopologyDigest document `shouldBe` "sha256:" <> hex schemaOneDocument+      hex "{\"a\":1}\n" `shouldBe` "e346432021b04179518d9614f3560ccd71354a4ee101ddcb893d6959a9d6301c"++    it "accepts feeds under /2, additional object fields and omits an unknown source shape" $ do+      document <- decoded schemaTwoDocument+      Topology.serviceTopologySchemaId document `shouldBe` "keiro-dsl/service-topology/2"+      let summary = Topology.serviceTopologySummary document+      field "edge_counts" summary `shouldBe` object ["feeds" .= (1 :: Int)]+      field "node_counts" summary `shouldBe` object ["intake" .= (1 :: Int), "aggregate" .= (1 :: Int)]+      KeyMap.member "source" (objectOf summary) `shouldBe` False+      field "members" summary `shouldBe` Aeson.toJSON ([] :: [Value])++    it "refuses malformed envelopes, unknown ids and unknown vocabulary" $ do+      let refusals =+            [ ("{}", "`schema`"),+              ("[]", "JSON object"),+              ("{\"schema\":", "not valid JSON"),+              (withSchema "keiro-dsl/service-topology/9", "\"keiro-dsl/service-topology/9\""),+              (replaceIn "\"service\":\"orders\"" "\"service\":7" schemaOneDocument, "`service`"),+              (replaceIn "\"version\":\"1.2.3\"" "\"version\":null" schemaOneDocument, "`generator.version`"),+              (replaceIn ",\"sha256\":\"sha256:00\"" "" schemaOneDocument, "`members[0].sha256`"),+              (replaceIn "\"nodes\":[" "\"nodes\":{\"x\":[" (replaceIn "],\"schema\"" "]},\"schema\"" schemaOneDocument), "`nodes`"),+              (replaceIn "\"kind\":\"aggregate\",\"line\"" "\"kind\":\"saga\",\"line\"" schemaOneDocument, "`nodes[0].kind`: unknown node kind \"saga\""),+              (replaceIn "\"from\":{\"kind\":\"aggregate\"" "\"from\":{\"kind\":\"actor\"" schemaOneDocument, "`edges[0].from.kind`: unknown node kind \"actor\""),+              (replaceIn "\"relation\":\"writes\"" "\"relation\":\"pokes\"" schemaOneDocument, "`edges[0].relation`: unknown relation \"pokes\""),+              (replaceIn "\"keiro-dsl/service-topology/2\"" "\"keiro-dsl/service-topology/1\"" schemaTwoDocument, "unknown relation \"feeds\"")+            ]+      forM_ refusals $ \(input, expected) -> case Topology.decodeServiceTopology input of+        Right _ -> expectationFailure ("accepted " <> Char8.unpack input)+        Left message -> message `shouldSatisfy` Text.isInfixOf expected++    it "reports a missing file by path" $ do+      result <- Topology.loadServiceTopology "does/not/exist.topology.json"+      either (Text.isInfixOf "does/not/exist.topology.json") (const False) result `shouldBe` True++  describe "producer goldens" $ do+    it "decodes every committed keiro-dsl golden when KEIRO_TOPOLOGY_FIXTURES is set" $ do+      directory <- lookupEnv "KEIRO_TOPOLOGY_FIXTURES"+      case directory of+        Nothing -> pendingWith "set KEIRO_TOPOLOGY_FIXTURES to keiro-dsl/test/fixtures/topology"+        Just root -> do+          forM_ goldenFiles $ \relative -> do+            result <- Topology.loadServiceTopology (root </> relative)+            either (\err -> expectationFailure (relative <> ": " <> Text.unpack err)) (const (pure ())) result+          schemas <- traverse (fmap (fmap Topology.serviceTopologySchemaId) . Topology.loadServiceTopology . (root </>)) goldenFiles+          schemas `shouldSatisfy` elem (Right "keiro-dsl/service-topology/2")++    it "summarizes the hospital golden from independent counts, size and digest" $ do+      directory <- lookupEnv "KEIRO_TOPOLOGY_FIXTURES"+      case directory of+        Nothing -> pendingWith "set KEIRO_TOPOLOGY_FIXTURES to keiro-dsl/test/fixtures/topology"+        Just root -> do+          bytes <- ByteString.readFile (root </> "hospital-capacity.topology.golden.json")+          document <- decoded bytes+          let summary = Topology.serviceTopologySummary document+              value = json bytes+              countBy collection key = Aeson.toJSON (Map.fromListWith (+) [(textAt key item, 1 :: Int) | item <- arrayAt collection value])+          ByteString.last bytes `shouldBe` 10+          field "document_bytes" summary `shouldBe` Aeson.toJSON (ByteString.length bytes)+          field "document_sha256" summary `shouldBe` String ("sha256:" <> hex bytes)+          field "node_counts" summary `shouldBe` countBy "nodes" "kind"+          field "edge_counts" summary `shouldBe` countBy "edges" "relation"+          field "schema_id" summary `shouldBe` String "keiro-dsl/service-topology/1"+          field "service" summary `shouldBe` String "hospital-capacity"+          field "source" summary `shouldBe` object ["kind" .= ("source" :: Text), "path" .= ("hospital-capacity.keiro" :: Text)]++  describe "topology commands" $ do+    it "mounts show and summary only with the hook, as reads" $ do+      document <- decoded schemaOneDocument+      let mounted = Ops.emptyAppHooks {Ops.serviceTopology = Just document}+      forM_ ["show", "summary"] $ \word -> do+        isJust (parsedCommand Ops.emptyAppHooks ["topology", word]) `shouldBe` False+        fmap Ops.isMutation (parsedCommand mounted ["topology", word]) `shouldBe` Just False+        fmap (either (const False) (const True) . Ops.validateCommand) (parsedCommand mounted ["topology", word]) `shouldBe` Just True+      isJust (parsedCommand mounted ["topology"]) `shouldBe` False+      isJust (parsedCommand mounted ["topology", "graph"]) `shouldBe` False++    it "returns the document and summary as JSON results" $ do+      document <- decoded schemaOneDocument+      jsonOf (Topology.runCommand document Topology.Show) `shouldBe` Just (json schemaOneDocument)+      jsonOf (Topology.runCommand document Topology.Summary) `shouldBe` Just (Topology.serviceTopologySummary document)++    around (withFreshDatabase fixture) $+      it "prints the complete document and summary through the normal CLI runner" $ \connectionString -> do+        document <- decoded schemaOneDocument+        let mounted = Ops.emptyAppHooks {Ops.serviceTopology = Just document}+            run word = do+              invocation <- case Opt.execParserPure Opt.defaultPrefs (Ops.opsCommandTree mounted) ["--database-url", Text.unpack connectionString, "--json", "topology", word] of+                Opt.Success parsed -> pure parsed+                _ -> fail "topology command did not parse"+              captureStdout (Ops.runOpsInvocation mounted invocation)+        (showExit, shown) <- run "show"+        showExit `shouldBe` ExitSuccess+        Aeson.eitherDecodeStrict shown `shouldBe` Right (json schemaOneDocument)+        (summaryExit, summarized) <- run "summary"+        summaryExit `shouldBe` ExitSuccess+        Aeson.eitherDecodeStrict summarized `shouldBe` Right (Topology.serviceTopologySummary document)+  where+    decoded bytes = either (fail . Text.unpack) pure (Topology.decodeServiceTopology bytes)+    jsonOf = \case+      Succeeded result -> Just result.jsonValue+      _ -> Nothing+    parsedCommand hooks args = case Opt.execParserPure Opt.defaultPrefs (Opt.info (Ops.commandParser hooks) mempty) args of+      Opt.Success command -> Just command+      _ -> Nothing+    withSchema schema = replaceIn "\"keiro-dsl/service-topology/1\"" ("\"" <> schema <> "\"") schemaOneDocument++goldenFiles :: [FilePath]+goldenFiles =+  [ "hospital-capacity.topology.golden.json",+    "incident-command.topology.golden.json",+    "incident-command-sourced.topology.golden.json",+    "projection-catalog.topology.golden.json",+    "workspace" </> "service.topology.golden.json"+  ]++schemaOneDocument :: ByteString+schemaOneDocument =+  Char8.pack+    ( filter+        (/= '\n')+        """+        {"edges":[{"attributes":{},"from":{"kind":"aggregate","name":"Order"},"relation":"writes","to":{"kind":"read-model","name":"order_summary"}},+        {"attributes":{},"from":{"kind":"aggregate","name":"Order"},"relation":"consumes","to":{"kind":"read-model","name":"order_lines"}}],+        "effectiveSemanticContract":6,"futureField":{"anything":[1,2]},+        "generator":{"tool":"keiro-dsl","version":"1.2.3"},+        "members":[{"declaredLanguageVersion":6,"effectiveLanguageVersion":6,"path":"orders.keiro","sha256":"sha256:00"}],+        "nodes":[{"context":"orders","details":{"stream":"order"},"kind":"aggregate","line":3,"member":"orders.keiro","name":"Order"},+        {"context":"orders","details":{},"kind":"read-model","line":9,"member":"orders.keiro","name":"order_summary"},+        {"context":"orders","details":{},"kind":"read-model","line":12,"member":"orders.keiro","name":"order_lines"}],+        "schema":"keiro-dsl/service-topology/1","service":"orders","source":{"kind":"source","path":"orders.keiro"}}+        """+    )+    <> "\n"++schemaTwoDocument :: ByteString+schemaTwoDocument =+  Char8.pack+    ( filter+        (/= '\n')+        """+        {"edges":[{"attributes":{"x":1},"from":{"kind":"intake","name":"ingest"},"relation":"feeds","to":{"kind":"aggregate","name":"Order"}}],+        "effectiveSemanticContract":6,"generator":{"tool":"keiro-dsl","version":"<version>"},"members":[],+        "nodes":[{"kind":"intake","name":"ingest","details":{}},{"kind":"aggregate","name":"Order","details":{"category":"order"}}],+        "schema":"keiro-dsl/service-topology/2","service":"orders","source":{"kind":"archive","path":"x"}}+        """+    )++replaceIn :: Text -> Text -> ByteString -> ByteString+replaceIn needle replacement = Text.Encoding.encodeUtf8 . Text.replace needle replacement . Text.Encoding.decodeUtf8++hex :: ByteString -> Text+hex = Text.Encoding.decodeUtf8 . LazyByteString.toStrict . Builder.toLazyByteString . Builder.byteStringHex . SHA256.hash++json :: ByteString -> Value+json bytes = either error id (Aeson.eitherDecodeStrict bytes)++objectOf :: Value -> KeyMap.KeyMap Value+objectOf = \case+  Object fields -> fields+  _ -> KeyMap.empty++field :: KeyMap.Key -> Value -> Value+field key value = maybe Null id (KeyMap.lookup key (objectOf value))++arrayAt :: KeyMap.Key -> Value -> [Value]+arrayAt key value = case field key value of+  Array items -> toList items+  _ -> []++textAt :: KeyMap.Key -> Value -> Text+textAt key value = case field key value of+  String text -> text+  _ -> ""++-- | Run an action with stdout redirected to a temporary file and return it.+captureStdout :: IO a -> IO (a, ByteString)+captureStdout action = do+  directory <- getTemporaryDirectory+  bracket (openBinaryTempFile directory "keiro-ops-topology.out") (\(path, handle) -> hClose handle `finally` removeFile path) $ \(path, handle) -> do+    hFlush stdout+    saved <- hDuplicate stdout+    result <- (hDuplicateTo handle stdout >> action) `finally` (hFlush stdout >> hDuplicateTo saved stdout >> hClose saved)+    hClose handle+    output <- ByteString.readFile path+    pure (result, output)