packages feed

keiro-ops-http 0.25.1.0 → 0.26.0.0

raw patch · 5 files changed

+300/−20 lines, 5 filesdep +cryptohash-sha256dep ~keirodep ~keiro-migrationsdep ~keiro-opsPVP ok

version bump matches the API change (PVP)

Dependencies added: cryptohash-sha256

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

API changes (from Hackage documentation)

+ Keiro.Ops.Http.Host: HostStartupError :: Text -> HostStartupError
+ Keiro.Ops.Http.Host: [topology] :: HostOptions -> !Maybe FilePath
+ Keiro.Ops.Http.Host: instance GHC.Internal.Exception.Type.Exception Keiro.Ops.Http.Host.HostStartupError
+ Keiro.Ops.Http.Host: instance GHC.Internal.Show.Show Keiro.Ops.Http.Host.HostStartupError
+ Keiro.Ops.Http.Host: loadHostTopology :: Int -> FilePath -> IO (Either Text ServiceTopologyDocument)
+ Keiro.Ops.Http.Host: newtype HostStartupError
- Keiro.Ops.Http.Host: HostOptions :: !Maybe Text -> !OpsHttpConfig -> !OpsHttpServerConfig -> HostOptions
+ Keiro.Ops.Http.Host: HostOptions :: !Maybe Text -> !OpsHttpConfig -> !OpsHttpServerConfig -> !Maybe FilePath -> HostOptions

Files

CHANGELOG.md view
@@ -2,6 +2,24 @@  ## [Unreleased] +## 0.26.0.0 — 2026-11-18++### Breaking Changes++- `HostOptions` gains `topology :: Maybe FilePath`; code constructing `HostOptions`+  must set it to `Nothing` or `Just path`.++### New Features++- `GET /topology/show` and `GET /topology/summary` exist when a host mounts+  `AppHooks.serviceTopology`. `show` returns the committed bytes unchanged under the+  usual admission, deadline, schema-verification and response-size limits.+- `--topology FILE` on every `mainWithHooks` host mounts a topology file at startup,+  replacing any document mounted in code. `withHost` throws `HostStartupError` before+  opening the database when the file is unreadable, undecodable or larger than+  `maxResponseBytes`; the executable prints the diagnostic and exits 1.+  `loadHostTopology` exposes the same bounded reader.+ ## 0.25.1.0 — 2026-11-16  ### Other Changes
keiro-ops-http.cabal view
@@ -1,6 +1,6 @@ cabal-version: 3.0 name: keiro-ops-http-version: 0.25.1.0+version: 0.26.0.0 synopsis:   Bounded HTTP transport for the Keiro operational command tree @@ -79,9 +79,9 @@     hasql >=1.10 && <1.11,     hasql-pool >=1.2 && <1.5,     http-types >=0.12 && <0.13,-    keiro ^>=0.25.1.0,-    keiro-migrations ^>=0.25.1.0,-    keiro-ops ^>=0.25.1.0,+    keiro ^>=0.26.0.0,+    keiro-migrations ^>=0.26.0.0,+    keiro-ops ^>=0.26.0.0,     kiroku-store ^>=0.13.0.1,     network >=3.1 && <3.3,     network-uri >=2.6.4.2 && <2.7,@@ -106,7 +106,7 @@    build-depends:     base >=4.21 && <5,-    keiro-ops ^>=0.25.1.0,+    keiro-ops ^>=0.26.0.0,     keiro-ops-http,  flag compose-example@@ -128,7 +128,7 @@   build-depends:     async >=2.2 && <2.3,     base >=4.21 && <5,-    keiro-ops ^>=0.25.1.0,+    keiro-ops ^>=0.26.0.0,     keiro-ops-http,     kiroku-metrics ^>=0.4.0.1,     kiroku-store ^>=0.13.0.1,@@ -160,10 +160,10 @@     http-client >=0.7 && <0.8,     http-types >=0.12 && <0.13,     jitsurei,-    keiro ^>=0.25.1.0,-    keiro-ops ^>=0.25.1.0,+    keiro ^>=0.26.0.0,+    keiro-ops ^>=0.26.0.0,     keiro-ops-http,-    keiro-test-support ^>=0.25.1.0,+    keiro-test-support ^>=0.26.0.0,     kiroku-store ^>=0.13.0.1,     process >=1.6 && <1.7,     text >=2.1 && <2.2,@@ -184,15 +184,21 @@   other-modules:     Test.ComposeSpec     Test.FeedSpec+    Test.TopologySpec     Test.WebSocketSpec -  build-tool-depends: keiro-ops:keiro-ops+  build-tool-depends:+    keiro-ops:keiro-ops,+    keiro-ops-http:keiro-ops-http,+   build-depends:     aeson >=2.2.2 && <2.3,     async >=2.2 && <2.3,     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,     hasql >=1.10 && <1.11,     hasql-pool >=1.2 && <1.5,@@ -200,12 +206,12 @@     http-client >=0.7 && <0.8,     http-types >=0.12 && <0.13,     jitsurei,-    keiro ^>=0.25.1.0,-    keiro-migrations ^>=0.25.1.0,-    keiro-ops ^>=0.25.1.0,+    keiro ^>=0.26.0.0,+    keiro-migrations ^>=0.26.0.0,+    keiro-ops ^>=0.26.0.0,     keiro-ops-http,-    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-metrics ^>=0.4.0.1,     kiroku-store ^>=0.13.0.1,     network >=3.1 && <3.3,
src/Keiro/Ops/Http/Host.hs view
@@ -1,20 +1,24 @@ -- | Shared lifecycle and command-line options for standalone inspection hosts. module Keiro.Ops.Http.Host   ( HostOptions (..),+    HostStartupError (..),     hostOptionsParser,+    loadHostTopology,     withHost,     mainWithHooks,   ) where  import Control.Concurrent.Async (wait)+import Control.Exception (Exception (..), IOException, throwIO, try)+import Data.ByteString qualified as ByteString import Data.Foldable (traverse_) import Data.Text (Text) import Data.Text qualified as Text import Data.Text.IO qualified as Text import Hasql.Connection.Settings qualified as Settings import Keiro.Migrations.SchemaCheck-import Keiro.Ops (AppHooks)+import Keiro.Ops (AppHooks (..), ServiceTopologyDocument, decodeServiceTopology) import Keiro.Ops.Env (resolveConnectionString) import Keiro.Ops.Http.Config import Keiro.Ops.Http.Config qualified as Config@@ -25,15 +29,26 @@ import Kiroku.Store.Connection (ConnectionSettingsM (..), KirokuStore (..), defaultConnectionSettings, withStore) import Options.Applicative import System.Environment (getProgName)-import System.IO (stderr)+import System.Exit (ExitCode (..), exitWith)+import System.IO (IOMode (..), hFileSize, stderr, withBinaryFile)  -- | Database selection, request policy, and listener settings for one host. data HostOptions = HostOptions   { databaseUrl :: !(Maybe Text),     http :: !OpsHttpConfig,-    server :: !OpsHttpServerConfig+    server :: !OpsHttpServerConfig,+    -- | A committed keiro-dsl service-topology file to mount at startup.+    -- It replaces any 'serviceTopology' hook supplied in code.+    topology :: !(Maybe FilePath)   } +-- | A host refused to start. Raised by 'withHost' before its continuation runs.+newtype HostStartupError = HostStartupError Text+  deriving stock (Show)++instance Exception HostStartupError where+  displayException (HostStartupError message) = Text.unpack message+ -- | The common flag surface used by database-only and application hosts. hostOptionsParser :: Parser HostOptions hostOptionsParser =@@ -45,6 +60,7 @@             <*> many (textOption (long "allow-origin" <> metavar "ORIGIN"))         )     <*> (OpsHttpServerConfig <$> textOption (long "bind" <> value "127.0.0.1") <*> option auto (long "port" <> value 9092) <*> option auto (long "request-timeout" <> value 300))+    <*> optional (strOption (long "topology" <> metavar "FILE" <> help "Mount a committed keiro-dsl service-topology document at /topology/show and /topology/summary"))   where     textOption modifiers = Text.pack <$> strOption modifiers @@ -53,16 +69,31 @@ mainWithHooks hooks = do   opts <- execParser (info (hostOptionsParser <**> helper) (fullDesc <> progDesc "Serve Keiro inspection on a trusted network or behind an authenticating proxy"))   name <- Text.pack <$> getProgName-  withHost opts hooks $ \running -> do+  started <- try $ withHost opts hooks $ \running -> do     Text.hPutStrLn stderr (name <> ": listening on " <> opts.server.bindHost <> ":" <> Text.pack (show running.serverPort) <> " (mutations " <> (if opts.http.mutations == MutationsEnabled then "enabled" else "disabled") <> ")")     wait running.serverThread+  case started of+    Right () -> pure ()+    Left (HostStartupError message) -> do+      Text.hPutStrLn stderr (name <> ": " <> message)+      exitWith (ExitFailure 1)  -- | Allocate the inspection store, feeds, and listener for the continuation. -- All resources are released before returning, including on exceptions. -- Port zero selects a free port reported by 'OpsHttpServer'. withHost :: HostOptions -> AppHooks -> (OpsHttpServer -> IO a) -> IO a-withHost opts hooks action = do+withHost opts suppliedHooks action = do   let config = opts.http+  -- Resolve file-backed mounts before any database or listener work.+  hooks <- case opts.topology of+    Nothing -> pure suppliedHooks+    Just path -> do+      loaded <- loadHostTopology config.inspectionLimits.maxResponseBytes path+      document <- either (throwIO . HostStartupError) pure loaded+      case suppliedHooks.serviceTopology of+        Just _ -> Text.hPutStrLn stderr ("warning: --topology " <> Text.pack path <> " replaces the service topology mounted in code")+        Nothing -> pure ()+      pure suppliedHooks {serviceTopology = Just document}   connectionString <- resolveConnectionString opts.databaseUrl   verified <- verifyExpectedSchema (Settings.connectionString connectionString)   case verified of@@ -76,3 +107,31 @@     withFeedHandle config defaultFeedConfig store $ \feeds -> do       app <- opsApplicationWithFeeds config feeds hooks store       withOpsHttpServer opts.server app action++-- | Read and decode a topology file that must fit the response limit.+-- The size is checked before decoding, and the read is bounded even if the+-- file grows after the check. Diagnostics name the path.+loadHostTopology :: Int -> FilePath -> IO (Either Text ServiceTopologyDocument)+loadHostTopology limit path = do+  result <- try $ withBinaryFile path ReadMode $ \handle -> do+    size <- hFileSize handle+    if size > fromIntegral limit+      then pure (Left (oversized (Text.pack (show size))))+      else do+        bytes <- ByteString.hGet handle (limit + 1)+        pure $+          if ByteString.length bytes > limit+            then Left (oversized ("more than " <> Text.pack (show limit)))+            else Right bytes+  pure $ case result of+    Left (err :: IOException) -> Left (prefix ("cannot read service topology: " <> Text.pack (displayException err)))+    Right (Left message) -> Left (prefix message)+    Right (Right bytes) -> either (Left . prefix) Right (decodeServiceTopology bytes)+  where+    prefix message = "--topology " <> Text.pack path <> ": " <> message+    oversized size =+      "service topology is "+        <> size+        <> " bytes, larger than the response limit of "+        <> Text.pack (show limit)+        <> " bytes (inspectionLimits.maxResponseBytes); /topology/show could never be served"
test/Main.hs view
@@ -77,6 +77,7 @@ import Test.ComposeSpec qualified as ComposeSpec import Test.FeedSpec qualified as FeedSpec import Test.Hspec+import Test.TopologySpec qualified as TopologySpec import Test.WebSocketSpec qualified as WebSocketSpec  main :: IO ()@@ -88,6 +89,7 @@ spec fixture = do   ComposeSpec.spec fixture   FeedSpec.spec fixture+  TopologySpec.spec fixture   WebSocketSpec.spec fixture   describe "live view parameters" $ do     it "canonicalizes equivalent status sets and bounds subscription inputs" $ do
+ test/Test/TopologySpec.hs view
@@ -0,0 +1,195 @@+module Test.TopologySpec (spec) where++import Control.Exception (bracket, try)+import Control.Monad (forM_)+import Crypto.Hash.SHA256 qualified as SHA256+import Data.Aeson (Value (..))+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.IORef+import Data.Map.Strict qualified as Map+import Data.Text (Text)+import Data.Text qualified as Text+import Data.Text.Encoding qualified as Text.Encoding+import Keiro.Ops qualified as Ops+import Keiro.Ops.Http+import Keiro.Ops.Http.Config qualified as Config+import Keiro.Test.Postgres (Fixture, withFreshDatabase, withFreshStore)+import Network.HTTP.Client qualified as Client+import Network.HTTP.Types+import Network.Wai (Application, requestHeaders, requestMethod)+import Network.Wai.Test+import Options.Applicative qualified as Options+import System.Directory (getTemporaryDirectory, removeFile)+import System.Exit (ExitCode (..))+import System.IO (hClose, openBinaryTempFile)+import System.Process (readProcessWithExitCode)+import Test.Hspec++spec :: Fixture -> Spec+spec fixture = describe "service topology over HTTP" $ do+  around (withFreshStore fixture) $ do+    it "serves the mounted bytes, a matching summary and the response cap" $ \store -> do+      document <- decoded spacedDocument+      let mounted = Ops.emptyAppHooks {Ops.serviceTopology = Just document}+          limitedTo bytes = defaultOpsHttpConfig {inspectionLimits = defaultInspectionLimits {maxResponseBytes = bytes}}+      app <- opsApplication defaultOpsHttpConfig mounted store+      shown <- call app methodGet "/topology/show" []+      simpleStatus shown `shouldBe` status200+      lookup hContentType (simpleHeaders shown) `shouldBe` Just "application/json; charset=utf-8"+      LazyByteString.toStrict (simpleBody shown) `shouldBe` spacedDocument+      summary <- call app methodGet "/topology/summary" []+      simpleStatus summary `shouldBe` status200+      body summary `shouldBe` Ops.serviceTopologySummary document+      field "document_sha256" (body summary) `shouldBe` Just (String ("sha256:" <> hex (LazyByteString.toStrict (simpleBody shown))))+      field "document_bytes" (body summary) `shouldBe` Just (Aeson.toJSON (LazyByteString.length (simpleBody shown)))+      exact <- opsApplication (limitedTo (ByteString.length spacedDocument)) mounted store+      atLimit <- call exact methodGet "/topology/show" []+      simpleStatus atLimit `shouldBe` status200+      LazyByteString.toStrict (simpleBody atLimit) `shouldBe` spacedDocument+      small <- opsApplication (limitedTo (ByteString.length spacedDocument - 1)) mounted store+      oversized <- call small methodGet "/topology/show" []+      assertError oversized status413 "inspection_result_too_large"++    it "is a read, hook-gated, and carries CORS for an allowed origin" $ \store -> do+      document <- decoded spacedDocument+      let mounted = Ops.emptyAppHooks {Ops.serviceTopology = Just document}+      app <- opsApplication defaultOpsHttpConfig {Config.allowedOrigins = ["http://ui.example"]} mounted store+      forM_ ["/topology/show", "/topology/summary"] $ \path -> do+        refused <- call app methodPost path []+        assertError refused status405 "method_not_allowed"+        lookup hAllow (simpleHeaders refused) `shouldBe` Just "GET"+      cross <- call app methodGet "/topology/show" [("Origin", "http://ui.example")]+      simpleStatus cross `shouldBe` status200+      lookup "Access-Control-Allow-Origin" (simpleHeaders cross) `shouldBe` Just "http://ui.example"+      absent <- opsApplication defaultOpsHttpConfig Ops.emptyAppHooks store+      forM_ ["/topology/show", "/topology/summary", "/aggregate/types"] $ \path -> do+        response <- call absent methodGet path []+        assertError response status400 "invalid_request"++  describe "--topology" $ do+    it "parses as an optional file" $ do+      fmap (.topology) (parseHost ["--topology", "services/orders/topology.json"]) `shouldBe` Just (Just "services/orders/topology.json")+      fmap (.topology) (parseHost []) `shouldBe` Just Nothing++    it "refuses to start the executable on a missing file" $ do+      executable <- hostExecutable+      (exit, _, err) <- readProcessWithExitCode executable ["--topology", "does/not/exist.topology.json"] ""+      exit `shouldBe` ExitFailure 1+      Text.pack err `shouldSatisfy` Text.isInfixOf "--topology does/not/exist.topology.json"++    around (withFreshDatabase fixture) $ do+      it "mounts a file over an in-code document and keeps the other hooks" $ \url -> do+        inCode <- decoded otherDocument+        fromFile <- decoded spacedDocument+        withTopologyFile spacedDocument $ \path -> do+          let hooks = Ops.emptyAppHooks {Ops.serviceTopology = Just inCode, Ops.processManagers = Just Map.empty}+          withHost (options url defaultOpsHttpConfig (Just path)) hooks $ \host -> do+            manager <- Client.newManager Client.defaultManagerSettings+            (status, summary) <- get manager host "/topology/summary"+            status `shouldBe` status200+            Aeson.eitherDecodeStrict summary `shouldBe` Right (Ops.serviceTopologySummary fromFile)+            (_, shown) <- get manager host "/topology/show"+            shown `shouldBe` spacedDocument+            (pmStatus, _) <- get manager host "/pm/types"+            pmStatus `shouldBe` status200+          withHost (options url defaultOpsHttpConfig Nothing) hooks $ \host -> do+            manager <- Client.newManager Client.defaultManagerSettings+            (_, shown) <- get manager host "/topology/show"+            shown `shouldBe` otherDocument++      it "refuses an unusable file before the continuation runs" $ \url -> do+        let unknownSchema = replaceIn "keiro-dsl/service-topology/1" "keiro-dsl/service-topology/9" spacedDocument+            limit = ByteString.length spacedDocument - 1+            cases =+              [ (Nothing, defaultOpsHttpConfig, "does not exist"),+                (Just "{\"schema\":", defaultOpsHttpConfig, "not valid JSON"),+                (Just unknownSchema, defaultOpsHttpConfig, "keiro-dsl/service-topology/9"),+                (Just spacedDocument, defaultOpsHttpConfig {inspectionLimits = defaultInspectionLimits {maxResponseBytes = limit}}, "larger than the response limit of " <> Text.pack (show limit))+              ]+        forM_ cases $ \(contents, config, expected) -> do+          ran <- newIORef False+          let attempt path = withHost (options url config (Just path)) Ops.emptyAppHooks (\_ -> writeIORef ran True)+          result <- case contents of+            Nothing -> attemptStartup (attempt "does/not/exist.topology.json")+            Just bytes -> withTopologyFile bytes (attemptStartup . attempt)+          case result of+            Left (HostStartupError message) -> message `shouldSatisfy` Text.isInfixOf expected+            Right () -> expectationFailure ("host started for " <> Text.unpack expected)+          readIORef ran `shouldReturn` False+  where+    decoded bytes = either (fail . Text.unpack) pure (Ops.decodeServiceTopology bytes)+    parseHost args = case Options.execParserPure Options.defaultPrefs (Options.info hostOptionsParser mempty) args of+      Options.Success parsed -> Just parsed+      _ -> Nothing+    attemptStartup :: IO () -> IO (Either HostStartupError ())+    attemptStartup = try++options :: Text -> OpsHttpConfig -> Maybe FilePath -> HostOptions+options url config topology = HostOptions {databaseUrl = Just url, http = config, server = defaultOpsHttpServerConfig {port = 0}, topology}++-- Whitespace and key order that re-encoding would change, plus a final newline,+-- so byte identity proves the host does not re-encode the document.+spacedDocument :: ByteString+spacedDocument =+  Char8.pack+    ( unlines+        [ "{ \"schema\": \"keiro-dsl/service-topology/1\",",+          "  \"service\": \"orders\",",+          "  \"source\": {\"path\": \"orders.keiro\", \"kind\": \"source\"},",+          "  \"generator\": {\"version\": \"1.2.3\", \"tool\": \"keiro-dsl\"},",+          "  \"members\": [{\"sha256\": \"sha256:00\", \"path\": \"orders.keiro\"}],",+          "  \"nodes\": [{\"name\": \"Order\", \"kind\": \"aggregate\", \"details\": {\"category\": \"order\"}},",+          "            {\"name\": \"order_summary\", \"kind\": \"read-model\", \"details\": {}}],",+          "  \"edges\": [{\"relation\": \"writes\", \"from\": {\"name\": \"Order\", \"kind\": \"aggregate\"}, \"to\": {\"name\": \"order_summary\", \"kind\": \"read-model\"}, \"attributes\": {}}]",+          "}"+        ]+    )++otherDocument :: ByteString+otherDocument = "{\"edges\":[],\"generator\":{\"version\":\"0\"},\"members\":[],\"nodes\":[],\"schema\":\"keiro-dsl/service-topology/2\",\"service\":\"billing\"}\n"++withTopologyFile :: ByteString -> (FilePath -> IO a) -> IO a+withTopologyFile contents action = do+  directory <- getTemporaryDirectory+  bracket (openBinaryTempFile directory "service.topology.json") (\(path, _) -> removeFile path) $ \(path, handle) -> do+    ByteString.hPut handle contents+    hClose handle+    action path++get :: Client.Manager -> OpsHttpServer -> String -> IO (Status, ByteString)+get manager host path = do+  req <- Client.parseRequest ("http://127.0.0.1:" <> show host.serverPort <> path)+  response <- Client.httpLbs req manager+  pure (Client.responseStatus response, LazyByteString.toStrict (Client.responseBody response))++call :: Application -> Method -> Text -> RequestHeaders -> IO SResponse+call app method path headers = runSession (srequest (SRequest ((setPath defaultRequest (Text.Encoding.encodeUtf8 path)) {requestMethod = method, requestHeaders = headers}) "")) app++body :: SResponse -> Value+body response = either error id (Aeson.eitherDecode (simpleBody response))++field :: Aeson.Key -> Value -> Maybe Value+field key (Object value) = KeyMap.lookup key value+field _ _ = Nothing++assertError :: SResponse -> Status -> Text -> Expectation+assertError response expected code = do+  simpleStatus response `shouldBe` expected+  (field "error" (body response) >>= field "code") `shouldBe` Just (String code)++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++hostExecutable :: IO FilePath+hostExecutable = do+  (exit, out, err) <- readProcessWithExitCode "cabal" ["list-bin", "exe:keiro-ops-http"] ""+  if exit == ExitSuccess then pure (Text.unpack (Text.strip (Text.pack out))) else fail err