packages feed

kenshou-synthetic (empty) → 0.1.0.0

raw patch · 15 files changed

+1416/−0 lines, 15 filesdep +aesondep +basedep +bytestring

Dependencies added: aeson, base, bytestring, containers, file-embed, hasql, kenshou-check, kenshou-cli, kenshou-core, kenshou-diagnose, kenshou-measure, kenshou-synthetic, network, pg-migrate, scientific, stm, text, time

Files

+ CHANGELOG.md view
@@ -0,0 +1,13 @@+# Changelog++## 0.1.0.0 - 2026-10-28++### New Features++- First public release of the synthetic reference suite, a layer built only on the generic packages that exercises every extension point: migration sets, worker roles, a registered oracle, advisory labels, pool methodology, routing rules, and a named resource.+- Five scenarios cover correctness under kill and restart, disjoint lease ownership, an open-loop benchmark, a soak for leak diagnosis, and a resource round trip.+- Provides the standalone `kenshou` executable.++### Other Changes++- New in this repository; the suite it verifies is the harness itself.
+ LICENSE view
@@ -0,0 +1,28 @@+BSD 3-Clause License++Copyright (c) 2026, Nadeem Bitar++Redistribution and use in source and binary forms, with or without+modification, are permitted provided that the following conditions are met:++1. Redistributions of source code must retain the above copyright notice, this+   list of conditions and the following disclaimer.++2. Redistributions in binary form must reproduce the above copyright notice,+   this list of conditions and the following disclaimer in the documentation+   and/or other materials provided with the distribution.++3. Neither the name of the copyright holder nor the names of its contributors+   may be used to endorse or promote products derived from this software without+   specific prior written permission.++THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ app/Main.hs view
@@ -0,0 +1,7 @@+module Main (main) where++import Kenshou.Cli (mainWith)+import Kenshou.Suite.Synthetic (syntheticProgram)++main :: IO ()+main = mainWith syntheticProgram
+ data/components.json view
@@ -0,0 +1,385 @@+{+  "schema": "kenshou.component-graph/v1",+  "ignoredPackages": [+    "pg-migrate-test-support"+  ],+  "components": [+    {+      "id": "postgresql",+      "kind": "service",+      "uri": null,+      "repository": "postgresql",+      "sourceRoots": [],+      "packages": [],+      "selectors": [],+      "verifiedAgainst": "PostgreSQL 17 and 18",+      "dependsOn": []+    },+    {+      "id": "pg-migrate",+      "kind": "library",+      "uri": "mori://shinzui/pg-migrate",+      "repository": "pg-migrate",+      "sourceRoots": [+        "src/",+        "pg-migrate.cabal"+      ],+      "packages": [+        "pg-migrate"+      ],+      "selectors": [],+      "verifiedAgainst": "pg-migrate 1.1.0.0",+      "dependsOn": [+        {+          "to": "postgresql",+          "kind": "runtime"+        }+      ]+    },+    {+      "id": "ephemeral-pg",+      "kind": "harness",+      "uri": "mori://shinzui/ephemeral-pg",+      "repository": "ephemeral-pg",+      "sourceRoots": [+        "src/",+        "ephemeral-pg.cabal"+      ],+      "packages": [+        "ephemeral-pg"+      ],+      "selectors": [+        "selftest/kernel/**"+      ],+      "verifiedAgainst": "ephemeral-pg 0.3.1.0",+      "dependsOn": [+        {+          "to": "postgresql",+          "kind": "runtime"+        }+      ]+    },+    {+      "id": "hs-opentelemetry",+      "kind": "library",+      "uri": "mori://iand675/hs-opentelemetry",+      "repository": "hs-opentelemetry",+      "sourceRoots": [],+      "packages": [+        "hs-opentelemetry-api",+        "hs-opentelemetry-sdk",+        "hs-opentelemetry-exporter-otlp",+        "hs-opentelemetry-propagator-w3c",+        "hs-opentelemetry-semantic-conventions"+      ],+      "selectors": [+        "selftest/telemetry/**"+      ],+      "changeImplies": {+        "minDimensionPolicy": "telemetry-corners"+      },+      "verifiedAgainst": "hs-opentelemetry 1.0 family",+      "dependsOn": []+    },+    {+      "id": "kenshou-harness",+      "kind": "harness",+      "uri": "mori://shinzui/kenshou/packages/kenshou-core",+      "repository": "kenshou",+      "sourceRoots": [+        "kenshou-core/"+      ],+      "packages": [+        "kenshou-core"+      ],+      "selectors": [+        "selftest/**"+      ],+      "verifiedAgainst": "kenshou-core 0.1.0.0",+      "subcomponents": [+        {+          "id": "kernel",+          "pathPrefixes": [],+          "selectors": [+            "selftest/kernel/**"+          ],+          "uses": []+        }+      ],+      "dependsOn": [+        {+          "to": "pg-migrate",+          "kind": "build"+        },+        {+          "to": "ephemeral-pg",+          "kind": "build"+        }+      ]+    },+    {+      "id": "synthetic-table",+      "kind": "harness",+      "uri": "mori://shinzui/kenshou/packages/kenshou-synthetic",+      "repository": "kenshou",+      "sourceRoots": [+        "kenshou-synthetic/src/Kenshou/Suite/Synthetic/Table.hs",+        "kenshou-synthetic/src/Kenshou/Suite/Synthetic/Roles.hs",+        "kenshou-synthetic/src/Kenshou/Suite/Synthetic/Schema.hs",+        "kenshou-synthetic/src/Kenshou/Suite/Synthetic/Correctness.hs",+        "kenshou-synthetic/src/Kenshou/Suite/Synthetic/Concurrency.hs",+        "kenshou-synthetic/src/Kenshou/Suite/Synthetic/Bench.hs",+        "kenshou-synthetic/src/Kenshou/Suite/Synthetic/Oracle.hs"+      ],+      "packages": [+        "kenshou-synthetic"+      ],+      "selectors": [+        "synthetic/table/**"+      ],+      "verifiedAgainst": "kenshou-synthetic 0.1.0.0",+      "dependsOn": [+        {+          "to": "pg-migrate",+          "kind": "build"+        },+        {+          "to": "kenshou-harness",+          "kind": "build"+        },+        {+          "to": "postgresql",+          "kind": "runtime"+        }+      ]+    },+    {+      "id": "synthetic-echo",+      "kind": "harness",+      "uri": "mori://shinzui/kenshou/packages/kenshou-synthetic",+      "repository": "kenshou",+      "sourceRoots": [+        "kenshou-synthetic/src/Kenshou/Suite/Synthetic/Echo.hs"+      ],+      "packages": [],+      "selectors": [+        "synthetic/echo/**"+      ],+      "verifiedAgainst": "kenshou-synthetic 0.1.0.0",+      "dependsOn": []+    }+  ],+  "repositoryPaths": [+    {+      "prefix": "kenshou-core/src/Kenshou/Plan/",+      "effect": {+        "kind": "selectors",+        "selectors": [+          "selftest/**"+        ]+      }+    },+    {+      "prefix": "kenshou-core/data/",+      "effect": {+        "kind": "selectors",+        "selectors": [+          "selftest/**"+        ]+      }+    },+    {+      "prefix": "kenshou-cli/",+      "effect": {+        "kind": "selectors",+        "selectors": [+          "selftest/**"+        ]+      }+    },+    {+      "prefix": "kenshou-remote/",+      "effect": {+        "kind": "selectors",+        "selectors": [+          "selftest/**"+        ]+      }+    },+    {+      "prefix": "kenshou-evidence/",+      "effect": {+        "kind": "selectors",+        "selectors": [+          "selftest/**"+        ]+      }+    },+    {+      "prefix": "schemas/",+      "effect": {+        "kind": "selectors",+        "selectors": [+          "selftest/**"+        ]+      }+    },+    {+      "prefix": "suites/",+      "effect": {+        "kind": "selectors",+        "selectors": [+          "selftest/**"+        ]+      }+    },+    {+      "prefix": "policies/",+      "effect": {+        "kind": "selectors",+        "selectors": [+          "selftest/**"+        ]+      }+    },+    {+      "prefix": "cohort/",+      "effect": {+        "kind": "cohort"+      }+    },+    {+      "prefix": "kenshou-core/",+      "effect": {+        "kind": "all"+      }+    },+    {+      "prefix": "kenshou-measure/",+      "effect": {+        "kind": "all"+      }+    },+    {+      "prefix": "kenshou-check/",+      "effect": {+        "kind": "all"+      }+    },+    {+      "prefix": "kenshou-diagnose/",+      "effect": {+        "kind": "all"+      }+    },+    {+      "prefix": "kenshou-telemetry/",+      "effect": {+        "kind": "all"+      }+    },+    {+      "prefix": "cabal.project",+      "effect": {+        "kind": "all"+      }+    },+    {+      "prefix": "flake.",+      "effect": {+        "kind": "all"+      }+    },+    {+      "prefix": "nix/",+      "effect": {+        "kind": "all"+      }+    },+    {+      "prefix": "docs/",+      "effect": {+        "kind": "nothing"+      }+    },+    {+      "prefix": "agents/",+      "effect": {+        "kind": "nothing"+      }+    },+    {+      "prefix": ".seihou/",+      "effect": {+        "kind": "nothing"+      }+    },+    {+      "prefix": ".github/",+      "effect": {+        "kind": "nothing"+      }+    },+    {+      "prefix": ".claude/",+      "effect": {+        "kind": "nothing"+      }+    },+    {+      "prefix": ".agents/",+      "effect": {+        "kind": "nothing"+      }+    },+    {+      "prefix": "README.md",+      "effect": {+        "kind": "nothing"+      }+    },+    {+      "prefix": "mori.dhall",+      "effect": {+        "kind": "nothing"+      }+    },+    {+      "prefix": "mina.kdl",+      "effect": {+        "kind": "nothing"+      }+    },+    {+      "prefix": "justfile",+      "effect": {+        "kind": "nothing"+      }+    },+    {+      "prefix": "process-compose.yaml",+      "effect": {+        "kind": "nothing"+      }+    },+    {+      "prefix": "kenshou-synthetic/",+      "effect": {+        "kind": "selectors",+        "selectors": [+          "selftest/**",+          "synthetic/**"+        ]+      }+    },+    {+      "prefix": "fixtures/",+      "effect": {+        "kind": "selectors",+        "selectors": [+          "selftest/**"+        ]+      }+    }+  ]+}
+ kenshou-synthetic.cabal view
@@ -0,0 +1,93 @@+cabal-version: 3.0+name: kenshou-synthetic+version: 0.1.0.0+synopsis: Synthetic reference suite and the standalone kenshou executable+description:+  The kenshou executable assembled from the generic operator commands and the+  harness's own self-test bundles.++license: BSD-3-Clause+license-file: LICENSE+author: Nadeem Bitar+maintainer: nadeem@gmail.com+homepage: https://github.com/shinzui/kenshou+bug-reports: https://github.com/shinzui/kenshou/issues+category: Testing+build-type: Simple+extra-doc-files: CHANGELOG.md+extra-source-files: data/components.json+tested-with: ghc >=9.12 && <9.13++common warnings+  ghc-options:+    -Wall+    -Wcompat+    -Widentities+    -Wincomplete-record-updates+    -Wincomplete-uni-patterns+    -Wpartial-fields+    -Wredundant-constraints++  default-language: GHC2024+  default-extensions:+    BlockArguments+    DuplicateRecordFields+    ImportQualifiedPost+    LambdaCase+    NoFieldSelectors+    OverloadedLabels+    OverloadedRecordDot+    OverloadedStrings++library+  import: warnings+  hs-source-dirs: src+  exposed-modules:+    Kenshou.Suite.Synthetic+    Kenshou.Suite.Synthetic.Bench+    Kenshou.Suite.Synthetic.Concurrency+    Kenshou.Suite.Synthetic.Correctness+    Kenshou.Suite.Synthetic.Echo+    Kenshou.Suite.Synthetic.Knobs+    Kenshou.Suite.Synthetic.Oracle+    Kenshou.Suite.Synthetic.Roles+    Kenshou.Suite.Synthetic.Schema+    Kenshou.Suite.Synthetic.Table++  build-depends:+    aeson >=2.2 && <2.3,+    base >=4.21 && <4.22,+    bytestring >=0.12 && <0.13,+    containers >=0.7 && <0.8,+    file-embed >=0.0.16 && <0.1,+    hasql >=1.10 && <1.11,+    kenshou-check ^>=0.1.0.0,+    kenshou-cli ^>=0.1.0.0,+    kenshou-core ^>=0.1.0.0,+    kenshou-diagnose ^>=0.1.0.0,+    kenshou-measure ^>=0.1.0.0,+    network >=3.2 && <3.3,+    pg-migrate >=1.1 && <1.2,+    scientific >=0.3 && <0.4,+    stm >=2.5 && <2.6,+    text >=2.1 && <2.2,+    time >=1.14 && <1.15,++executable kenshou+  import: warnings+  hs-source-dirs: app+  main-is: Main.hs+  ghc-options:+    -threaded+    -rtsopts+    -with-rtsopts=-N+    -with-rtsopts=-T++  build-depends:+    base >=4.21 && <4.22,+    kenshou-cli ^>=0.1.0.0,+    kenshou-synthetic,++source-repository head+  type: git+  location: https://github.com/shinzui/kenshou.git
+ src/Kenshou/Suite/Synthetic.hs view
@@ -0,0 +1,56 @@+{-# LANGUAGE TemplateHaskell #-}++-- | The synthetic reference suite: a layer named @synthetic@ that exercises every+-- extension point a consuming suite uses, built only on the generic packages. It is+-- both the proof that the harness boundary holds and the worked example of a suite.+module Kenshou.Suite.Synthetic+  ( syntheticLayer,+    syntheticBundle,+    syntheticProgram,+    syntheticGraphBytes,+  )+where++import Data.ByteString (ByteString)+import Data.FileEmbed (embedFile)+import Data.List.NonEmpty (NonEmpty (..))+import Data.Text qualified as Text+import Kenshou.Cli (Program (..), selfTestAssembly)+import Kenshou.Core.Bundle (LayerBundle (..), mkBundle, requirePgVersionsFor)+import Kenshou.Core.Contribution (PoolMethodology (..), RoutingRule (..), RuleCondition (..))+import Kenshou.Core.Dimension (PgVersion (..))+import Kenshou.Core.Id (LayerId, mkLayerId)+import Kenshou.Suite.Synthetic.Bench (appendThroughput, steadyAppend)+import Kenshou.Suite.Synthetic.Concurrency (competingWriters, contenderRole, leaseLabel)+import Kenshou.Suite.Synthetic.Correctness (appendSurvivesKillRestart)+import Kenshou.Suite.Synthetic.Echo (echoClientRole, echoProvider, resourceRoundtrip)+import Kenshou.Suite.Synthetic.Oracle (itemsOracle)+import Kenshou.Suite.Synthetic.Roles (readerRole, writerRole)+import Kenshou.Suite.Synthetic.Schema (syntheticMigrationSet, syntheticSchema)++syntheticLayer :: LayerId+syntheticLayer = either (error . show) id (mkLayerId "synthetic")++syntheticBundle :: LayerBundle+syntheticBundle =+  (mkBundle syntheticLayer [appendSurvivesKillRestart, competingWriters, appendThroughput, steadyAppend, resourceRoundtrip] [writerRole, readerRole, contenderRole, echoClientRole])+    { migrations = [syntheticMigrationSet],+      rules = [requirePgVersionsFor syntheticSchema (Pg18 :| [Pg17])],+      resources = [echoProvider],+      oracles = [itemsOracle],+      advisoryLabels = [leaseLabel ("lease-" <> Text.pack (show key)) | key <- [0 .. 9 :: Int]],+      methodology = Just (PoolMethodology 8 (4, 16)),+      evidenceSubject = Just "mori://shinzui/kenshou",+      -- An example rule: a run that asks for unlogged item tables needs a cell whose+      -- PostgreSQL allows them.+      routingRules = [RoutingRule (KnobEquals "writer.storage" "unlogged") "postgres.unlogged-tables" "Unlogged item tables need a cell PostgreSQL that allows them."]+    }++-- | The @kenshou@ executable's program: the self-test assembly plus the synthetic+-- bundle, with a component graph that also covers the synthetic layer.+syntheticProgram :: Program+syntheticProgram = selfTestAssembly {bundles = selfTestAssembly.bundles <> [syntheticBundle], componentGraph = syntheticGraphBytes}++-- | The self-test component graph plus the synthetic suite's components.+syntheticGraphBytes :: ByteString+syntheticGraphBytes = $(embedFile "data/components.json")
+ src/Kenshou/Suite/Synthetic/Bench.hs view
@@ -0,0 +1,119 @@+-- | Measured appends to @synthetic.items@: a benchmark whose paired comparisons+-- exercise the measurement toolkit, and a soak whose runtime series feed the leak+-- diagnosis.+module Kenshou.Suite.Synthetic.Bench+  ( appendThroughput,+    steadyAppend,+  )+where++import Control.Exception (bracket)+import Data.List.NonEmpty (NonEmpty (..))+import Data.Map.Strict qualified as Map+import Data.Text (Text)+import Data.Text qualified as Text+import Data.Word (Word64)+import Hasql.Connection qualified as Connection+import Hasql.Connection.Settings qualified as Settings+import Hasql.Session qualified as Session+import Kenshou.Core.Context (RunContext (..), requirePostgres)+import Kenshou.Core.Dimension+import Kenshou.Core.Env (PostgresRequirement (..), noEnvironment)+import Kenshou.Core.Env qualified as Env+import Kenshou.Core.Env.Postgres (PostgresEnv (..))+import Kenshou.Core.Id (Kind (..), ScenarioId (..), parseScenarioId)+import Kenshou.Core.Knob (knobInt)+import Kenshou.Core.Phase qualified as Core+import Kenshou.Core.Scenario+import Kenshou.Diagnose.Leak.MajorGcProbe (withMajorGcProbe)+import Kenshou.Measure.Knobs+import Kenshou.Measure.Load+import Kenshou.Measure.Recorder+import Kenshou.Measure.Sampler.Postgres (PgSamplerConfig (..))+import Kenshou.Measure.Session+import Kenshou.Suite.Synthetic.Knobs (intKnob, knob)+import Kenshou.Suite.Synthetic.Schema (syntheticSchema)+import Kenshou.Suite.Synthetic.Table (appendItem, countItems)++appendThroughput :: Scenario+appendThroughput =+  (appendScenario "synthetic/table/benchmark/append-throughput" "Measures single-row appends to the synthetic items table." Benchmark (Core.PhasePlan 2 10 1))+    { tier = TierStandard+    }++steadyAppend :: Scenario+steadyAppend =+  let soak = appendScenario "synthetic/table/soak/steady-append" "Appends at a steady rate long enough for a leak diagnosis." Soak (Core.PhasePlan 5 30 0)+   in soak+        { tier = TierSoak,+          knobs = soak.knobs <> [intKnob "diagnose.major-gc-interval-ms" "Forced major-GC interval, or zero to disable" 1000 0 60000]+        }++appendScenario :: Text -> Text -> Kind -> Core.PhasePlan -> Scenario+appendScenario identifier summary kind phases =+  Scenario+    { id = either (error . show) id (parseScenarioId identifier),+      revision = 1,+      summary,+      tier = TierSmoke,+      placement = PlaceEither,+      -- An open loop at a modest rate measures append latency without saturating+      -- the load driver, which the measurement health checks would flag.+      knobs = loadKnobs (defaultLoadDefaults {model = "open-constant", ratePerSecond = 200, executors = 8}) <> measureKnobs kind,+      dimensions = postgresDimensions (PgDurable :| []) (Pg18 :| [Pg17]) telemetryOff,+      phases,+      requires = noEnvironment {Env.postgres = Just (PostgresRequirement [syntheticSchema] [("shared_preload_libraries", "'pg_stat_statements'")] False)},+      knownDefect = Nothing,+      run = runAppendLoad+    }++runAppendLoad :: RunContext -> IO ScenarioReport+runAppendLoad context = case (loadModelFromKnobs context.knobs, measureConfigFromKnobs context (phasePlanFromCore context.phases)) of+  (Left message, _) -> pure (failedWith ["invalid-load-config"] message)+  (_, Left message) -> pure (failedWith ["invalid-measure-config"] message)+  (Right loadModel, Right baseConfig) -> do+    let environment = requirePostgres context+        config = watchItems baseConfig+        -- A soak forces major collections so the heap has points to judge; a+        -- benchmark must not perturb its own measurements that way.+        majorGcMs = if context.scenario.kind == Soak then fromIntegral (knobInt context.knobs (knob "diagnose.major-gc-interval-ms")) else 0+        workers = case loadModel of ClosedLoop closed -> closed.workers; OpenLoop open -> open.executors+        settings = Settings.connectionString environment.connectionString <> Settings.applicationName "synthetic-append"+    bracket (traverse (const (Connection.acquire settings)) [1 .. max 1 workers]) (mapM_ Connection.release . concatMap (either (const []) pure)) \acquired ->+      case sequence acquired of+        Left problem -> pure (infrastructureFailureBecause (Text.pack (show problem)))+        Right [] -> pure (infrastructureFailureBecause "no PostgreSQL connection")+        Right connections@(first : _) -> do+          let operation = Operation (OpName "append") (appendOne connections)+          (_, report) <- withMajorGcProbe context majorGcMs (withMeasurement context config (\measurement -> runLoad measurement loadModel operation))+          counted <- Connection.use first (Session.statement () countItems)+          let successful = case report.recorder.operations of+                recorded : _ -> sum [successes | (successes, _, _) <- Map.elems recorded.phaseCounts]+                [] -> 0+              scenarioReport = case counted of+                Right rows | fromIntegral rows == successful -> passed+                _ -> failedWith ["row-count"] ("rows " <> Text.pack (show counted) <> ", recorded successes " <> Text.pack (show successful))+          pure scenarioReport {outcome = measuredOutcome report scenarioReport.outcome}++appendOne :: [Connection.Connection] -> Int -> Word64 -> IO OpResult+appendOne connections worker sequenceNumber = do+  let connection = connections !! (worker `mod` length connections)+      key = "load-" <> Text.pack (show worker)+      number = fromIntegral sequenceNumber+  result <- Connection.use connection (Session.statement (key, number, key <> "/" <> Text.pack (show number), "load") appendItem)+  pure case result of+    Right True -> OpOk 1+    _ -> OpFailed (ErrorCause "postgres")++-- | Sample the items table's size and dead tuples alongside the database series.+watchItems :: MeasureConfig -> MeasureConfig+watchItems (MeasureConfig phases histogram rawSamples sampleInterval intervalSeconds postgres extraSamplers healthConfig) =+  MeasureConfig phases histogram rawSamples sampleInterval intervalSeconds (fmap (\pg -> pg {relations = ["synthetic.items"]}) postgres) extraSamplers healthConfig++telemetryOff :: DimensionSupport+telemetryOff =+  DimensionSupport+    (Supported (Support (TracingOff :| []) TracingOff))+    (Supported (Support (MetricsOff :| []) MetricsOff))+    NotApplicable+    NotApplicable
+ src/Kenshou/Suite/Synthetic/Concurrency.hs view
@@ -0,0 +1,184 @@+-- | @synthetic/table/concurrency/competing-writers-hold-disjoint-leases@: contender+-- processes repeatedly take a lease on a key under a transaction-scoped advisory+-- lock, append one item while they hold it, and release it. Their facts, ordered by+-- the database clock, must show that no owner acted on a key another owner held.+module Kenshou.Suite.Synthetic.Concurrency+  ( contenderRole,+    competingWriters,+    leaseLabel,+  )+where++import Control.Concurrent (threadDelay)+import Control.Concurrent.STM (atomically)+import Control.Monad (forM, forM_, when)+import Data.Aeson (FromJSON (..), object, withObject, (.:), (.=))+import Data.Aeson.Types (parseMaybe)+import Data.Functor.Contravariant ((>$<))+import Data.Int (Int64)+import Data.List (sortOn)+import Data.List.NonEmpty (NonEmpty (..))+import Data.Text (Text)+import Data.Text qualified as Text+import Data.Time (getCurrentTime)+import Hasql.Decoders qualified as Decoders+import Hasql.Encoders qualified as Encoders+import Hasql.Statement qualified as Statement+import Kenshou.Check.Fact (FactKind (..), ProcId (..))+import Kenshou.Check.Invariant+import Kenshou.Check.Ledger (LedgerConfig, LedgerWriter, defaultLedgerConfig, record, sealLedger, withLedger)+import Kenshou.Check.Ledger.Read (discoverLedgers)+import Kenshou.Check.Process+import Kenshou.Check.Scenario+import Kenshou.Check.Verdict (InvariantClass (..))+import Kenshou.Core.Context (RunContext (..))+import Kenshou.Core.Contribution (AdvisoryKeySpec (..), AdvisoryLabel (..))+import Kenshou.Core.Dimension+import Kenshou.Core.Env (PostgresRequirement (..), noEnvironment)+import Kenshou.Core.Env qualified as Env+import Kenshou.Core.Id (parseScenarioId, renderRunId)+import Kenshou.Core.Knob+import Kenshou.Core.Phase (zeroPhases)+import Kenshou.Core.Role+import Kenshou.Core.Scenario+import Kenshou.Suite.Synthetic.Knobs (intKnob, knob)+import Kenshou.Suite.Synthetic.Roles (awaitStart, awaitStop, intArg, roleName)+import Kenshou.Suite.Synthetic.Schema (syntheticSchema)+import Kenshou.Suite.Synthetic.Table (run, withConnection)++-- | A lease step a contender reports, at a database clock time in microseconds.+data Step = Step {kind :: !Text, key :: !Text, at :: !Int64}++instance FromJSON Step where+  parseJSON = withObject "lease step" \value -> Step <$> value .: "kind" <*> value .: "key" <*> value .: "at"++-- | The label a stall capture gives the advisory lock a contender takes on a key.+leaseLabel :: Text -> AdvisoryLabel+leaseLabel key = AdvisoryLabel ("synthetic lease " <> key) (HashText ("synthetic/lease/" <> key))++-- | Takes the lease on each of @keys@ keys in turn, @iterations@ times, appending one+-- item under each lease; every step reports the database clock time.+contenderRole :: WorkerRole+contenderRole = WorkerRole (roleName "synthetic/contender") "Takes leases on keys and appends an item while holding each." \context -> do+  connection <- maybe (fail "the contender requires PostgreSQL") (pure . (.connectionString)) context.init.postgres+  let iterations = intArg context "iterations"+      keys = intArg context "keys"+      owner = context.init.instanceName+      step kind key at = object ["kind" .= (kind :: Text), "key" .= key, "at" .= at]+  withConnection connection ("synthetic-contender-" <> owner) \database -> do+    context.send WrkReady+    started <- awaitStart context+    when started do+      forM_ [1 .. iterations] \iteration -> do+        let key = "lease-" <> Text.pack (show (iteration `mod` keys))+        run database () (unit "begin")+        run database key takeLock+        acquiredAt <- run database (key, owner) acquireLease+        actedAt <- run database key appendUnderLease+        releasedAt <- run database (key, owner) releaseLease+        run database () (unit "commit")+        context.send (WrkFacts [step "acquired" key acquiredAt, step "acted" key actedAt, step "released" key releasedAt])+        now <- getCurrentTime+        context.send (WrkProgress iteration now)+      awaitStop context++competingWriters :: Scenario+competingWriters =+  Scenario+    { id = either (error . show) id (parseScenarioId "synthetic/table/concurrency/competing-writers-hold-disjoint-leases"),+      revision = 1,+      summary = "Runs contending writers that take per-key leases and checks no owner acts on another's lease.",+      tier = TierSmoke,+      placement = PlaceEither,+      knobs =+        [ intKnob "contention.contenders" "Contending writer processes" 4 2 32,+          intKnob "contender.iterations" "Leases each contender takes" 100 1 100000,+          intKnob "lease.keys" "Keys the contenders share" 3 1 100+        ],+      dimensions = postgresDimensions (PgFsyncOff :| [PgDurable]) (Pg18 :| [Pg17]) noDimensions,+      phases = zeroPhases,+      requires = noEnvironment {Env.postgres = Just (PostgresRequirement [syntheticSchema] [] False)},+      knownDefect = Nothing,+      run = runContention+    }++runContention :: RunContext -> IO ScenarioReport+runContention context = withCheck context \environment -> withSupervisor environment \supervisor -> do+  let contenders = fromIntegral (knobInt context.knobs (knob "contention.contenders")) :: Int+      iterations = knobInt context.knobs (knob "contender.iterations")+      keys = knobInt context.knobs (knob "lease.keys")+  children <- forM [0 .. contenders - 1] \index -> do+    spec <- roleProcess environment "synthetic/contender" index (object ["iterations" .= iterations, "keys" .= keys])+    child <- spawn supervisor spec+    awaitReady child 10000+    pure child+  forM_ children \child -> sendCommand child CtlStart+  finished <- and <$> traverse (\child -> waitFor 60000 (atomically ((>= iterations) . (.count) <$> progress child))) children+  forM_ children \child -> stopGracefully supervisor child 2000+  steps <- forM (zip [0 ..] children) \(index, child) -> do+    messages <- readChildMessages child+    pure [(index, step) | WrkFacts values <- messages, Just step <- fmap (parseMaybe parseJSON) values :: [Maybe Step]]+  -- Each contender records its own steps in its own ledger scope, in the order the+  -- database clock put them, so wall-clock order across owners is the real order.+  withLedgers [defaultLedgerConfig environment.ledgerDirectory (ProcId "synthetic-contender" index 0) (renderRunId context.runId) | index <- [0 .. contenders - 1]] \writers -> do+    forM_ (sortOn ((.at) . snd) (concat steps)) \(index, step) ->+      record (writers !! index) (stepKind step.kind) step.key step.at step.key mempty+    mapM_ sealLedger writers+  sealLedger environment.ledger+  ledgerSet <- discoverLedgers environment.ledgerDirectory+  verdicts <- runCheckers environment ledgerSet [disjointOwnership "disjoint-ownership" Contract]+  if finished && length (concat steps) == contenders * fromIntegral iterations * 3+    then finishWithVerdicts environment verdicts+    else pure (failedWith ["contenders-incomplete"] "not every contender finished its leases")+  where+    stepKind :: Text -> FactKind+    stepKind = \case+      "acquired" -> Acquired+      "acted" -> Acted+      _ -> Released++withLedgers :: [LedgerConfig] -> ([LedgerWriter] -> IO a) -> IO a+withLedgers configs action = go configs []+  where+    go [] opened = action (reverse opened)+    go (config : rest) opened = withLedger config \writer -> go rest (writer : opened)++waitFor :: Int -> IO Bool -> IO Bool+waitFor millis condition = loop millis+  where+    loop left = do+      satisfied <- condition+      if satisfied || left <= 0 then pure satisfied else threadDelay 20000 >> loop (left - 20)++unit :: Text -> Statement.Statement () ()+unit sql = Statement.unpreparable sql Encoders.noParams Decoders.noResult++clockMicros :: Decoders.Result Int64+clockMicros = Decoders.singleRow (Decoders.column (Decoders.nonNullable Decoders.int8))++takeLock :: Statement.Statement Text ()+takeLock = Statement.unpreparable "select pg_advisory_xact_lock(hashtext('synthetic/lease/' || $1))" (Encoders.param (Encoders.nonNullable Encoders.text)) Decoders.noResult++acquireLease :: Statement.Statement (Text, Text) Int64+acquireLease =+  Statement.unpreparable+    "insert into synthetic.leases (key, owner, acquired_at, expires_at) values ($1, $2, clock_timestamp(), clock_timestamp() + interval '5 seconds') on conflict (key) do update set owner = excluded.owner, acquired_at = excluded.acquired_at, expires_at = excluded.expires_at returning (extract(epoch from clock_timestamp()) * 1000000)::bigint"+    pairParams+    clockMicros++appendUnderLease :: Statement.Statement Text Int64+appendUnderLease =+  Statement.unpreparable+    "insert into synthetic.items (key, seq, item, writer) select $1, coalesce(max(seq), 0) + 1, $1 || '/' || (coalesce(max(seq), 0) + 1), 'contender' from synthetic.items where key = $1 returning (extract(epoch from clock_timestamp()) * 1000000)::bigint"+    (Encoders.param (Encoders.nonNullable Encoders.text))+    clockMicros++releaseLease :: Statement.Statement (Text, Text) Int64+releaseLease =+  Statement.unpreparable+    "with released as (delete from synthetic.leases where key = $1 and owner = $2) select (extract(epoch from clock_timestamp()) * 1000000)::bigint"+    pairParams+    clockMicros++pairParams :: Encoders.Params (Text, Text)+pairParams = (fst >$< Encoders.param (Encoders.nonNullable Encoders.text)) <> (snd >$< Encoders.param (Encoders.nonNullable Encoders.text))
+ src/Kenshou/Suite/Synthetic/Correctness.hs view
@@ -0,0 +1,136 @@+-- | @synthetic/table/correctness/append-survives-kill-restart@: a writer process+-- appends items while it is killed and restarted, a reader process observes them,+-- and the run's ledger must show no loss, per-key order, duplicates only within the+-- crash windows, quiescence, and agreement with the table.+module Kenshou.Suite.Synthetic.Correctness (appendSurvivesKillRestart) where++import Control.Concurrent (threadDelay)+import Control.Concurrent.STM (atomically)+import Control.Monad (forM_)+import Data.Aeson (object, (.=))+import Data.Int (Int64)+import Data.List.NonEmpty (NonEmpty (..))+import Data.Text (Text)+import Kenshou.Check.Fact (FactKind (..), ProcId (..))+import Kenshou.Check.Invariant+import Kenshou.Check.Ledger (defaultLedgerConfig, record, recordDurable, sealLedger, withLedger)+import Kenshou.Check.Ledger.Read (discoverLedgers)+import Kenshou.Check.Oracle (OracleResult (..), reconcile, runOracle)+import Kenshou.Check.Process+import Kenshou.Check.Scenario+import Kenshou.Check.Verdict (InvariantClass (..))+import Kenshou.Core.Context (ArtifactDir (..), RunContext (..), artifactPath, requirePostgres)+import Kenshou.Core.Dimension+import Kenshou.Core.Env (PostgresRequirement (..), noEnvironment)+import Kenshou.Core.Env qualified as Env+import Kenshou.Core.Id (parseScenarioId, renderRunId)+import Kenshou.Core.Knob+import Kenshou.Core.Phase (zeroPhases)+import Kenshou.Core.Role (ControlMessage (..))+import Kenshou.Core.Scenario+import Kenshou.Suite.Synthetic.Knobs (intKnob, knob)+import Kenshou.Suite.Synthetic.Oracle (itemsQuery)+import Kenshou.Suite.Synthetic.Roles (Fact (..), decodeFacts)+import Kenshou.Suite.Synthetic.Schema (syntheticSchema)++appendSurvivesKillRestart :: Scenario+appendSurvivesKillRestart =+  Scenario+    { id = either (error . show) id (parseScenarioId "synthetic/table/correctness/append-survives-kill-restart"),+      revision = 1,+      summary = "Appends items through a writer that is killed and restarted, and checks a reader sees each exactly once.",+      tier = TierSmoke,+      placement = PlaceEither,+      knobs =+        [ intKnob "writer.count" "Items per key" 500 1 100000,+          intKnob "writer.keys" "Keys written in turn" 8 1 1000,+          intKnob "kill.count" "Times the writer is killed and restarted" 2 0 20+        ],+      dimensions = postgresDimensions (PgFsyncOff :| [PgDurable]) (Pg18 :| [Pg17]) noDimensions,+      phases = zeroPhases,+      requires = noEnvironment {Env.postgres = Just (PostgresRequirement [syntheticSchema] [] False)},+      knownDefect = Nothing,+      run = runAppend+    }++runAppend :: RunContext -> IO ScenarioReport+runAppend context = withCheck context \environment -> withSupervisor environment \supervisor -> do+  let count = knobInt context.knobs (knob "writer.count")+      keys = knobInt context.knobs (knob "writer.keys")+      kills = fromIntegral (knobInt context.knobs (knob "kill.count")) :: Int+      total = count * keys+  readerSpec <- roleProcess environment "synthetic/reader" 0 (object ["total" .= total])+  writerSpec <- roleProcess environment "synthetic/writer" 0 (object ["count" .= count, "keys" .= keys])+  reader <- start supervisor readerSpec+  firstWriter <- start supervisor writerSpec+  -- Kill the writer after it has written a share of its items, then restart it.+  writers <- killAndRestart supervisor (max 1 (total `div` fromIntegral (kills + 1))) kills firstWriter+  finished <- waitFor 120000 (atomically ((>= total) . (.count) <$> progress reader))+  _ <- traverse (\writer -> stopGracefully supervisor writer 2000) (lastOf writers)+  _ <- stopGracefully supervisor reader 2000+  writerFacts <- decodeFacts . concat <$> traverse readChildMessages writers+  readerFacts <- decodeFacts <$> readChildMessages reader+  forM_ writerFacts \fact -> case fact.kind of+    "intent" -> record environment.ledger Intent fact.key fact.seq fact.item mempty+    "produced" -> recordDurable environment.ledger Produced fact.key fact.seq fact.item mempty+    _ -> pure ()+  -- The reader's observations go in their own ledger scope, as a consumer process+  -- would write them, so per-key order is judged over the consumer's arrivals.+  withLedger (defaultLedgerConfig environment.ledgerDirectory (ProcId "synthetic-reader" 0 0) (renderRunId context.runId)) \readerLedger -> do+    forM_ readerFacts \fact -> do+      recordDurable readerLedger Observed fact.key fact.seq fact.item mempty+      record readerLedger Terminal fact.key fact.seq fact.item mempty+    sealLedger readerLedger+  sealLedger environment.ledger+  ledgerSet <- discoverLedgers environment.ledgerDirectory+  windows <- crashWindows supervisor+  verdictDirectory <- artifactPath context VerdictsDir ""+  durable <- runOracle verdictDirectory (requirePostgres context) itemsQuery >>= either (fail . show) pure+  verdicts <-+    runCheckers+      environment+      ledgerSet+      [ noLoss "no-loss" Contract readerScope,+        perKeyOrder "per-key-order" Contract readerScope,+        duplicatesWithin "duplicates-within-windows" Contract readerScope (DuplicateBudget (Just 0) Nothing) windows,+        eventualQuiescence "eventual-quiescence" Contract (Deadline 120000000),+        reconcile "ledger-versus-oracle" Contract durable.rows+      ]+  if finished && fromIntegral (length readerFacts) == total+    then finishWithVerdicts environment verdicts+    else pure (failedWith ["reader-incomplete"] "the reader did not observe every item before the deadline")+  where+    lastOf values = case reverse values of+      final : _ -> [final]+      [] -> []++readerScope :: Text+readerScope = "synthetic-reader/0"++start :: Supervisor -> ProcessSpec -> IO Child+start supervisor spec = do+  child <- spawn supervisor spec+  awaitReady child 10000+  sendCommand child CtlStart+  pure child++-- | Kill the writer each time it has written another @step@ items, restarting it,+-- and return every incarnation in order.+killAndRestart :: Supervisor -> Int64 -> Int -> Child -> IO [Child]+killAndRestart supervisor step remaining child+  | remaining <= 0 = pure [child]+  | otherwise = do+      _ <- waitFor 60000 (atomically ((>= step) . (.count) <$> progress child))+      killChild supervisor child+      replacement <- restartChild supervisor child+      awaitReady replacement 10000+      sendCommand replacement CtlStart+      (child :) <$> killAndRestart supervisor step (remaining - 1) replacement++-- | Poll a condition every 20 ms for at most the given milliseconds.+waitFor :: Int -> IO Bool -> IO Bool+waitFor millis condition = loop millis+  where+    loop left = do+      satisfied <- condition+      if satisfied || left <= 0 then pure satisfied else threadDelay 20000 >> loop (left - 20)
+ src/Kenshou/Suite/Synthetic/Echo.hs view
@@ -0,0 +1,133 @@+-- | A named resource the synthetic suite provisions itself: a loopback TCP echo+-- server. The provider starts it around a local run, workers find its address in the+-- @resources@ block of their initialization document, and+-- @synthetic/echo/correctness/resource-roundtrip@ checks every message comes back.+module Kenshou.Suite.Synthetic.Echo+  ( echoResource,+    echoProvider,+    echoClientRole,+    resourceRoundtrip,+  )+where++import Control.Concurrent (forkIO, killThread)+import Control.Exception (bracket, finally)+import Control.Monad (forM, forever, void)+import Data.Aeson (Value (..), object, (.=))+import Data.Aeson.Key qualified as Key+import Data.Aeson.KeyMap qualified as KeyMap+import Data.ByteString qualified as ByteString+import Data.Map.Strict qualified as Map+import Data.Maybe (fromMaybe)+import Data.Scientific (toBoundedInteger)+import Data.Text (Text)+import Data.Text qualified as Text+import Data.Text.Encoding qualified as Text+import Kenshou.Core.Context (RunContext (..))+import Kenshou.Core.Dimension (noDimensions)+import Kenshou.Core.Env (requiresResource)+import Kenshou.Core.Id (parseScenarioId)+import Kenshou.Core.Knob+import Kenshou.Core.Phase (zeroPhases)+import Kenshou.Core.Resource (ProvisionedResource (..), ResourceName, ResourceProvider (..), mkResourceName)+import Kenshou.Core.Role+import Kenshou.Core.Role.Spawn (WorkerHandle (..), withWorker)+import Kenshou.Core.Scenario+import Kenshou.Suite.Synthetic.Knobs (intKnob, knob)+import Kenshou.Suite.Synthetic.Roles (roleName)+import Network.Socket+import Network.Socket.ByteString (recv, sendAll)++echoResource :: ResourceName+echoResource = either (error . Text.unpack) id (mkResourceName "echo")++-- | Starts the echo server for one local run. It has no cell binding, so a scenario+-- that requires it cannot be placed on a cell.+echoProvider :: ResourceProvider+echoProvider =+  ResourceProvider+    { name = echoResource,+      summary = "Loopback TCP echo server",+      normalize = Right . fromMaybe (object []),+      withLocal = \_ _ action -> withEchoServer \port ->+        action (ProvisionedResource (object ["host" .= ("127.0.0.1" :: Text), "port" .= port]) (object ["kind" .= ("loopback-echo" :: Text)])),+      cell = Nothing+    }++withEchoServer :: (Int -> IO a) -> IO a+withEchoServer action = do+  address : _ <- getAddrInfo (Just defaultHints {addrFlags = [AI_PASSIVE], addrSocketType = Stream}) (Just "127.0.0.1") (Just "0")+  bracket (openSocket address) close \listener -> do+    setSocketOption listener ReuseAddr 1+    bind listener (addrAddress address)+    listen listener 16+    port <- fromIntegral <$> socketPort listener+    acceptor <- forkIO (forever (accept listener >>= \(connection, _) -> void (forkIO (echo connection `finally` close connection))))+    action port `finally` killThread acceptor+  where+    echo connection = do+      bytes <- recv connection 4096+      if ByteString.null bytes then pure () else sendAll connection bytes >> echo connection++-- | Sends @messages@ lines to the echo server in its initialization document and+-- reports how many came back unchanged.+echoClientRole :: WorkerRole+echoClientRole = WorkerRole (roleName "synthetic/echo-client") "Round-trips messages through the echo resource." \context -> do+  context.send WrkReady+  context.receive >>= \case+    Just (CtlCustom "echo" (Object request)) -> do+      let messages = fromMaybe 0 (KeyMap.lookup "messages" request >>= number)+      (host, port) <- maybe (fail "the worker has no echo resource") pure (Map.lookup echoResource context.init.resources >>= endpoint)+      address : _ <- getAddrInfo (Just defaultHints {addrSocketType = Stream}) (Just (Text.unpack host)) (Just (show port))+      matched <- bracket (openSocket address) close \connection -> do+        connect connection (addrAddress address)+        results <- forM [1 .. messages] \index -> do+          let line = Text.encodeUtf8 ("message-" <> Text.pack (show index) <> "\n")+          sendAll connection line+          received <- receiveExactly connection (ByteString.length line)+          pure (received == line)+        pure (length (filter id results))+      context.send (WrkCustom "echoed" (object ["sent" .= messages, "matched" .= matched]))+    _ -> pure ()+  where+    number (Number value) = toBoundedInteger value :: Maybe Int+    number _ = Nothing+    endpoint (Object fields) = case (KeyMap.lookup (Key.fromText "host") fields, KeyMap.lookup (Key.fromText "port") fields >>= number) of+      (Just (String host), Just port) -> Just (host, port)+      _ -> Nothing+    endpoint _ = Nothing+    receiveExactly connection size = go ByteString.empty+      where+        go acquired+          | ByteString.length acquired >= size = pure acquired+          | otherwise = do+              chunk <- recv connection (size - ByteString.length acquired)+              if ByteString.null chunk then pure acquired else go (acquired <> chunk)++resourceRoundtrip :: Scenario+resourceRoundtrip =+  Scenario+    { id = either (error . show) id (parseScenarioId "synthetic/echo/correctness/resource-roundtrip"),+      revision = 1,+      summary = "Provisions the suite's echo resource and round-trips messages through it from a worker.",+      tier = TierSmoke,+      placement = PlaceLocal,+      knobs = [intKnob "echo.messages" "Messages to round-trip" 100 1 100000],+      dimensions = noDimensions,+      phases = zeroPhases,+      requires = requiresResource echoResource,+      knownDefect = Nothing,+      run = \context -> withWorker context (roleName "synthetic/echo-client") "echo-1" (object []) \worker -> do+        let messages = knobInt context.knobs (knob "echo.messages")+        ready <- worker.receive 10000+        case ready of+          Just WrkReady -> do+            worker.send (CtlCustom "echo" (object ["messages" .= messages]))+            reply <- worker.receive 30000+            pure case reply of+              Just (WrkCustom "echoed" (Object result))+                | KeyMap.lookup "matched" result == Just (Number (fromIntegral messages)) -> passed+                | otherwise -> failedWith ["echo-mismatch"] "some echoes differed from what was sent"+              _ -> failedWith ["echo-timeout"] "the echo client did not report"+          _ -> pure (failedWith ["echo-not-ready"] "the echo client did not become ready")+    }
+ src/Kenshou/Suite/Synthetic/Knobs.hs view
@@ -0,0 +1,17 @@+-- | Knob helpers shared by the synthetic suite's scenarios.+module Kenshou.Suite.Synthetic.Knobs+  ( knob,+    intKnob,+  )+where++import Data.Int (Int64)+import Data.Text (Text)+import Data.Text qualified as Text+import Kenshou.Core.Knob++knob :: Text -> KnobName+knob = either (error . Text.unpack) id . mkKnobName++intKnob :: Text -> Text -> Int64 -> Int64 -> Int64 -> KnobSpec+intKnob name summary def low high = KnobSpec (knob name) summary KnobInt (VInt def) (IntRange low high) []
+ src/Kenshou/Suite/Synthetic/Oracle.hs view
@@ -0,0 +1,24 @@+-- | The synthetic suite's SQL oracle, registered on its bundle so the correctness+-- scenario and attestation recompute the same durable rows.+module Kenshou.Suite.Synthetic.Oracle+  ( itemsOracle,+    itemsQuery,+  )+where++import Data.Text (Text)+import Data.Text qualified as Text+import Kenshou.Check.Oracle (ItemRef (..), OracleQuery, OracleSpec (..), fromSpec)+import Text.Read (readMaybe)++itemsOracle :: OracleSpec+itemsOracle = OracleSpec "synthetic-items" "select key || '|' || seq || '|' || item from synthetic.items order by key, seq"++-- | The registered oracle with its row decoder: one @key|seq|item@ line per row.+itemsQuery :: OracleQuery [ItemRef]+itemsQuery = fromSpec itemsOracle (traverse row . filter (not . Text.null) . Text.lines)+  where+    row :: Text -> Either Text ItemRef+    row line = case Text.splitOn "|" line of+      [key, sequence, item] | Just number <- readMaybe (Text.unpack sequence) -> Right (ItemRef key number item)+      _ -> Left ("unreadable oracle row: " <> line)
+ src/Kenshou/Suite/Synthetic/Roles.hs view
@@ -0,0 +1,119 @@+-- | Worker roles of the synthetic suite. Each runs in its own process, receives a+-- @kenshou.worker-init/v1@ document, and reports facts as JSON objects with a+-- @kind@, @key@, @seq@, and @item@ that the scenario turns into ledger facts.+module Kenshou.Suite.Synthetic.Roles+  ( writerRole,+    readerRole,+    Fact (..),+    decodeFacts,+    roleName,+    awaitStart,+    awaitStop,+    intArg,+  )+where++import Control.Concurrent (threadDelay)+import Control.Monad (forM_, unless, when)+import Data.Aeson (FromJSON (..), Value (..), object, withObject, (.:), (.=))+import Data.Aeson.Key qualified as Key+import Data.Aeson.KeyMap qualified as KeyMap+import Data.Aeson.Types (parseMaybe)+import Data.Int (Int64)+import Data.Maybe (mapMaybe)+import Data.Scientific (toBoundedInteger)+import Data.Set qualified as Set+import Data.Text (Text)+import Data.Text qualified as Text+import Data.Time (getCurrentTime)+import Kenshou.Core.Role+import Kenshou.Suite.Synthetic.Table++-- | A fact a worker reports.+data Fact = Fact {kind :: !Text, key :: !Text, seq :: !Int64, item :: !Text}+  deriving stock (Eq, Show)++instance FromJSON Fact where+  parseJSON = withObject "synthetic fact" \value -> Fact <$> value .: "kind" <*> value .: "key" <*> value .: "seq" <*> value .: "item"++factValue :: Text -> Row -> Value+factValue kind row = object ["kind" .= kind, "key" .= row.key, "seq" .= row.seq, "item" .= row.item]++-- | The facts in a worker's messages.+decodeFacts :: [WorkerMessage] -> [Fact]+decodeFacts messages = mapMaybe (parseMaybe parseJSON) [value | WrkFacts values <- messages, value <- values]++-- | Appends @count@ items to each of @keys@ keys, one transaction per item, in+-- sequence-major order. It reports an @intent@ fact before each insert and a+-- @produced@ fact after the insert commits, and after a restart resumes from the+-- highest sequence already committed for each key.+writerRole :: WorkerRole+writerRole = WorkerRole (roleName "synthetic/writer") "Appends items to synthetic.items, resuming after a restart." \context -> do+  connection <- requireConnection context+  let count = intArg context "count"+      keys = [keyName number | number <- [0 .. intArg context "keys" - 1]]+      writer = context.init.instanceName+  withConnection connection ("synthetic-writer-" <> writer) \database -> do+    context.send WrkReady+    started <- awaitStart context+    when started do+      resumed <- traverse (\key -> (key,) <$> run database key highestSeq) keys+      let pending = [Row key sequence (key <> "/" <> Text.pack (show sequence)) | sequence <- [1 .. count], (key, written) <- resumed, sequence > written]+      forM_ (zip [1 :: Int64 ..] pending) \(number, row) -> do+        context.send (WrkFacts [factValue "intent" row])+        inserted <- run database (row.key, row.seq, row.item, writer) appendItem+        when inserted (context.send (WrkFacts [factValue "produced" row]))+        now <- getCurrentTime+        context.send (WrkProgress number now)+      context.send (WrkCustom "written" (object ["items" .= length pending]))+      awaitStop context++-- | Polls @synthetic.items@ and reports an @observed@ fact for every row it has not+-- reported before, until it has seen @total@ rows.+readerRole :: WorkerRole+readerRole = WorkerRole (roleName "synthetic/reader") "Observes every row of synthetic.items exactly once." \context -> do+  connection <- requireConnection context+  let total = intArg context "total"+  withConnection connection "synthetic-reader" \database -> do+    context.send WrkReady+    started <- awaitStart context+    when started do+      let loop seen = do+            rows <- run database () allRows+            let fresh = filter (`Set.notMember` seen) rows+                seen' = foldr Set.insert seen fresh+            unless (null fresh) (context.send (WrkFacts (fmap (factValue "observed") fresh)))+            now <- getCurrentTime+            context.send (WrkProgress (fromIntegral (Set.size seen')) now)+            if fromIntegral (Set.size seen') >= total then pure () else threadDelay 20000 >> loop seen'+      loop Set.empty+      awaitStop context++requireConnection :: RoleContext -> IO Text+requireConnection context = maybe (fail "the synthetic roles require PostgreSQL") (pure . (.connectionString)) context.init.postgres++awaitStart :: RoleContext -> IO Bool+awaitStart context =+  context.receive >>= \case+    Just CtlStart -> pure True+    Just (CtlStop _) -> pure False+    Nothing -> pure False+    Just _ -> awaitStart context++awaitStop :: RoleContext -> IO ()+awaitStop context =+  context.receive >>= \case+    Just (CtlStop _) -> pure ()+    Nothing -> pure ()+    Just _ -> awaitStop context++intArg :: RoleContext -> Text -> Int64+intArg context name = case context.init.args of+  Object fields | Just (Number value) <- KeyMap.lookup (Key.fromText name) fields, Just number <- toBoundedInteger value -> number+  _ -> error ("synthetic worker argument " <> Text.unpack name <> " is missing")++keyName :: Int64 -> Text+keyName number = "key-" <> Text.pack (show number)++roleName :: Text -> RoleName+roleName = either (error . Text.unpack) id . mkRoleName
+ src/Kenshou/Suite/Synthetic/Schema.hs view
@@ -0,0 +1,32 @@+-- | The synthetic suite's migration set: one schema holding an append-only items+-- table and a leases table, composed into the run's one pg-migrate ledger by the+-- kernel like any suite's migrations.+module Kenshou.Suite.Synthetic.Schema+  ( syntheticSchema,+    syntheticMigrationSet,+  )+where++import Data.List.NonEmpty (NonEmpty (..))+import Data.Set qualified as Set+import Data.Text qualified as Text+import Database.PostgreSQL.Migrate (migrationComponent, sqlMigration)+import Kenshou.Core.Env (MigrationSet (..), MigrationSetName (..))++syntheticSchema :: MigrationSetName+syntheticSchema = MigrationSetName "synthetic"++syntheticMigrationSet :: MigrationSet+syntheticMigrationSet =+  MigrationSet+    { name = syntheticSchema,+      requires = [],+      component = either (Left . Text.pack . show) Right do+        tables <-+          sqlMigration+            "create-tables"+            "create schema synthetic;\n\+            \create table synthetic.items (key text not null, seq bigint not null, item text not null, writer text not null, written_at timestamptz not null default now(), primary key (key, seq));\n\+            \create table synthetic.leases (key text primary key, owner text not null, acquired_at timestamptz not null, expires_at timestamptz not null);\n"+        migrationComponent "synthetic" Set.empty (tables :| [])+    }
+ src/Kenshou/Suite/Synthetic/Table.hs view
@@ -0,0 +1,70 @@+-- | Statements against the synthetic suite's tables, shared by its workers and+-- scenarios.+module Kenshou.Suite.Synthetic.Table+  ( Row (..),+    withConnection,+    appendItem,+    highestSeq,+    allRows,+    countItems,+    run,+  )+where++import Control.Exception (bracket)+import Data.Functor.Contravariant ((>$<))+import Data.Int (Int64)+import Data.Text (Text)+import Hasql.Connection qualified as Connection+import Hasql.Connection.Settings qualified as Settings+import Hasql.Decoders qualified as Decoders+import Hasql.Encoders qualified as Encoders+import Hasql.Session qualified as Session+import Hasql.Statement qualified as Statement++-- | One row of @synthetic.items@.+data Row = Row {key :: !Text, seq :: !Int64, item :: !Text}+  deriving stock (Eq, Ord, Show)++-- | Open one connection with an application name, so a stall capture or a backend+-- fault can select it.+withConnection :: Text -> Text -> (Connection.Connection -> IO a) -> IO a+withConnection connectionString application action =+  bracket (Connection.acquire settings >>= either (fail . show) pure) Connection.release action+  where+    settings = Settings.connectionString connectionString <> Settings.applicationName application++-- | Run one statement, failing loudly on a database error.+run :: Connection.Connection -> params -> Statement.Statement params result -> IO result+run connection params statement = Connection.use connection (Session.statement params statement) >>= either (fail . show) pure++-- | Insert an item; 'False' when the row already exists.+appendItem :: Statement.Statement (Text, Int64, Text, Text) Bool+appendItem =+  Statement.unpreparable+    "insert into synthetic.items (key, seq, item, writer) values ($1, $2, $3, $4) on conflict do nothing"+    ( ((\(key, _, _, _) -> key) >$< Encoders.param (Encoders.nonNullable Encoders.text))+        <> ((\(_, sequence, _, _) -> sequence) >$< Encoders.param (Encoders.nonNullable Encoders.int8))+        <> ((\(_, _, item, _) -> item) >$< Encoders.param (Encoders.nonNullable Encoders.text))+        <> ((\(_, _, _, writer) -> writer) >$< Encoders.param (Encoders.nonNullable Encoders.text))+    )+    ((> 0) <$> Decoders.rowsAffected)++-- | The highest sequence number already written for a key, or 0.+highestSeq :: Statement.Statement Text Int64+highestSeq =+  Statement.unpreparable+    "select coalesce(max(seq), 0)::bigint from synthetic.items where key = $1"+    (Encoders.param (Encoders.nonNullable Encoders.text))+    (Decoders.singleRow (Decoders.column (Decoders.nonNullable Decoders.int8)))++-- | Every row, in key and sequence order.+allRows :: Statement.Statement () [Row]+allRows =+  Statement.unpreparable+    "select key, seq, item from synthetic.items order by key, seq"+    Encoders.noParams+    (Decoders.rowList (Row <$> Decoders.column (Decoders.nonNullable Decoders.text) <*> Decoders.column (Decoders.nonNullable Decoders.int8) <*> Decoders.column (Decoders.nonNullable Decoders.text)))++countItems :: Statement.Statement () Int64+countItems = Statement.unpreparable "select count(*)::bigint from synthetic.items" Encoders.noParams (Decoders.singleRow (Decoders.column (Decoders.nonNullable Decoders.int8)))