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 +22/−0
- keiro-ops.cabal +13/−7
- src/Keiro/Ops.hs +31/−0
- src/Keiro/Ops/Embed.hs +7/−2
- src/Keiro/Ops/Topology.hs +320/−0
- test/Main.hs +4/−1
- test/TopologySpec.hs +245/−0
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)