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 +18/−0
- keiro-ops-http.cabal +21/−15
- src/Keiro/Ops/Http/Host.hs +64/−5
- test/Main.hs +2/−0
- test/Test/TopologySpec.hs +195/−0
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