kenshou-core-0.1.0.0: src/Kenshou/Core/RunSpec.hs
module Kenshou.Core.RunSpec
( SpecPlacement (..),
ConnectionSource (..),
PostgresSpec (..),
EnvironmentSpec (..),
CohortExpectation (..),
ComparisonMembership (..),
RunSpec (..),
EffectiveRunSpec (..),
minimalRunSpec,
redactConnectionString,
withLegacyResource,
)
where
import Data.Aeson
import Data.Aeson.Key qualified as Key
import Data.Aeson.Types (Parser)
import Data.Map.Strict (Map)
import Data.Map.Strict qualified as Map
import Data.Text (Text)
import Data.Text qualified as Text
import Kenshou.Core.Dimension (Dimensions, renderDimensions)
import Kenshou.Core.Id (RunId, ScenarioId, Seed)
import Kenshou.Core.Knob (KnobName, RawKnob (..), ResolvedKnobs)
import Kenshou.Core.Knob qualified
import Kenshou.Core.Phase (PhasePlan)
import Kenshou.Core.Resource.Types (ResourceName, legacyKafkaName)
data SpecPlacement = RunLocal | RunOnCell deriving stock (Eq, Show)
data ConnectionSource = ConnLiteral Text | ConnFromEnv Text deriving stock (Eq, Show)
data PostgresSpec = PostgresEphemeral [(Text, Text)] | PostgresExternal ConnectionSource deriving stock (Eq, Show)
data EnvironmentSpec = EnvironmentSpec
{ placement :: SpecPlacement,
machineProfile :: Maybe Text,
postgres :: Maybe PostgresSpec,
extraPostgres :: Map Text PostgresSpec,
-- | Per-resource specification values, keyed by the resource name.
resources :: Map ResourceName Value,
telemetry :: Maybe Value
}
deriving stock (Eq, Show)
data CohortExpectation = CohortExpectation {name :: Maybe Text, planHash :: Text} deriving stock (Eq, Show)
data ComparisonMembership = ComparisonMembership {group :: Text, arm :: Text, trial :: Int, position :: Int} deriving stock (Eq, Show)
data RunSpec = RunSpec
{ runId :: Maybe RunId,
scenario :: ScenarioId,
scenarioRevision :: Maybe Int,
knobs :: [(KnobName, RawKnob)],
dimensions :: [(Text, Text)],
seed :: Maybe Seed,
phases :: Maybe PhasePlan,
timeoutSeconds :: Maybe Int,
environment :: EnvironmentSpec,
cohortExpectation :: Maybe CohortExpectation,
comparison :: Maybe ComparisonMembership,
labels :: Map Text Text
}
deriving stock (Eq, Show)
data EffectiveRunSpec = EffectiveRunSpec
{ runId :: RunId,
scenario :: ScenarioId,
scenarioRevision :: Int,
knobs :: ResolvedKnobs,
dimensions :: Dimensions,
seed :: Seed,
phases :: PhasePlan,
timeoutSeconds :: Int,
environment :: EnvironmentSpec,
cohortExpectation :: Maybe CohortExpectation,
comparison :: Maybe ComparisonMembership,
labels :: Map Text Text
}
deriving stock (Eq, Show)
minimalRunSpec :: ScenarioId -> RunSpec
minimalRunSpec scenario = RunSpec Nothing scenario Nothing [] [] Nothing Nothing Nothing (EnvironmentSpec RunLocal Nothing Nothing Map.empty Map.empty Nothing) Nothing Nothing Map.empty
redactConnectionString :: Text -> Text
redactConnectionString value = redactUri (Text.unwords (fmap redactWord (Text.words value)))
where
redactWord word
| "password=" `Text.isPrefixOf` Text.toCaseFold word = "password=<redacted>"
| otherwise = word
redactUri input = case Text.breakOn "://" input of
(scheme, rest)
| not (Text.null rest) ->
let afterScheme = Text.drop 3 rest
(authority, suffix) = Text.breakOn "/" afterScheme
in case Text.breakOnEnd "@" authority of
(credentials, host)
| not (Text.null credentials) ->
let (user, password) = Text.breakOn ":" (Text.dropEnd 1 credentials)
in if Text.null password then input else scheme <> "://" <> user <> ":<redacted>@" <> host <> suffix
_ -> input
_ -> input
instance FromJSON RunSpec where
parseJSON = withObject "RunSpec" \value -> do
schema <- value .: "schema"
if schema /= ("kenshou.run-spec/v1" :: Text) then fail "unsupported run-spec schema" else pure ()
runId <- value .:? "runId"
scenario <- value .: "scenario"
scenarioRevision <- value .:? "scenarioRevision"
rawKnobs <- value .:? "knobs" .!= Map.empty
knobs <- traverse parseKnob (Map.toList rawKnobs)
dimensions <- Map.toList <$> value .:? "dimensions" .!= Map.empty
seed <- value .:? "seed"
phases <- value .:? "phases"
timeoutSeconds <- value .:? "timeoutSeconds"
environment <- value .:? "environment" .!= EnvironmentSpec RunLocal Nothing Nothing Map.empty Map.empty Nothing
cohortExpectation <- value .:? "cohortExpectation"
comparison <- value .:? "comparison"
labels <- value .:? "labels" .!= Map.empty
pure RunSpec {runId, scenario, scenarioRevision, knobs, dimensions, seed, phases, timeoutSeconds, environment, cohortExpectation, comparison, labels}
where
parseKnob (name, raw) = case Kenshou.Core.Knob.mkKnobName name of
Left err -> fail (Text.unpack err)
Right parsed -> pure (parsed, RawJson raw)
instance ToJSON RunSpec where
toJSON spec =
object $
[ "schema" .= ("kenshou.run-spec/v1" :: Text),
"scenario" .= spec.scenario,
"knobs" .= Map.fromList [(Kenshou.Core.Knob.renderKnobName name, rawValue raw) | (name, raw) <- spec.knobs],
"dimensions" .= Map.fromList spec.dimensions,
"environment" .= spec.environment,
"cohortExpectation" .= spec.cohortExpectation,
"comparison" .= spec.comparison,
"labels" .= spec.labels
]
<> maybe [] (pure . ("runId" .=)) spec.runId
<> maybe [] (pure . ("scenarioRevision" .=)) spec.scenarioRevision
<> maybe [] (pure . ("seed" .=)) spec.seed
<> maybe [] (pure . ("phases" .=)) spec.phases
<> maybe [] (pure . ("timeoutSeconds" .=)) spec.timeoutSeconds
where
rawValue (RawText value) = String value
rawValue (RawJson value) = value
instance ToJSON EffectiveRunSpec where
toJSON spec =
object
[ "schema" .= ("kenshou.run-spec/v1" :: Text),
"runId" .= spec.runId,
"scenario" .= spec.scenario,
"scenarioRevision" .= spec.scenarioRevision,
"knobs" .= spec.knobs,
"dimensions" .= object [Key.fromText name .= value | (name, value) <- renderDimensions spec.dimensions],
"seed" .= spec.seed,
"phases" .= spec.phases,
"timeoutSeconds" .= spec.timeoutSeconds,
"environment" .= spec.environment,
"cohortExpectation" .= spec.cohortExpectation,
"comparison" .= spec.comparison,
"labels" .= spec.labels
]
instance ToJSON EnvironmentSpec where
toJSON environment =
object $
["placement" .= placementText environment.placement, "machineProfile" .= environment.machineProfile, "postgres" .= environment.postgres]
<> ["extraPostgres" .= environment.extraPostgres | not (Map.null environment.extraPostgres)]
<> ["resources" .= environment.resources | not (Map.null environment.resources)]
<> ["telemetry" .= environment.telemetry]
instance FromJSON EnvironmentSpec where
parseJSON = withObject "EnvironmentSpec" \value -> do
resources <- (value .:? "resources" .!= Map.empty) >>= withLegacyResource "environment" value
EnvironmentSpec <$> (value .:? "placement" .!= RunLocal) <*> value .:? "machineProfile" <*> value .:? "postgres" <*> (value .:? "extraPostgres" .!= Map.empty) <*> pure resources <*> value .:? "telemetry"
-- | Documents written before named resources carried the one resource they knew as a
-- top-level field; read a non-null one as that named resource.
withLegacyResource :: Text -> Object -> Map ResourceName Value -> Parser (Map ResourceName Value)
withLegacyResource label value resources = do
legacy <- value .:? "kafka"
case (legacy, Map.lookup legacyKafkaName resources) of
(Nothing, _) -> pure resources
(Just Null, _) -> pure resources
(Just found, Nothing) -> pure (Map.insert legacyKafkaName found resources)
(Just found, Just current)
| found == current -> pure resources
| otherwise -> fail (Text.unpack label <> ".kafka and " <> Text.unpack label <> ".resources.kafka disagree")
instance ToJSON SpecPlacement where toJSON = String . placementText
instance FromJSON SpecPlacement where parseJSON = withText "SpecPlacement" \case "local" -> pure RunLocal; "cell" -> pure RunOnCell; other -> fail ("unknown placement " <> Text.unpack other)
placementText :: SpecPlacement -> Text
placementText RunLocal = "local"
placementText RunOnCell = "cell"
instance ToJSON PostgresSpec where
toJSON (PostgresEphemeral settings) = object ["mode" .= ("ephemeral" :: Text), "settings" .= Map.fromList settings]
toJSON (PostgresExternal (ConnFromEnv name)) = object ["mode" .= ("external" :: Text), "connectionStringEnv" .= name]
toJSON (PostgresExternal (ConnLiteral value)) = object ["mode" .= ("external" :: Text), "connectionString" .= redactConnectionString value]
instance FromJSON PostgresSpec where
parseJSON = withObject "PostgresSpec" \value -> do
mode <- value .: "mode" :: Parser Text
case mode of
"ephemeral" -> PostgresEphemeral . Map.toList <$> value .:? "settings" .!= Map.empty
"external" -> do
env <- value .:? "connectionStringEnv"
literal <- value .:? "connectionString"
case (env, literal) of (Just name, Nothing) -> pure (PostgresExternal (ConnFromEnv name)); (Nothing, Just connection) -> pure (PostgresExternal (ConnLiteral connection)); _ -> fail "external PostgreSQL requires exactly one connection source"
_ -> fail "unknown PostgreSQL mode"
instance ToJSON CohortExpectation where toJSON value = object ["name" .= value.name, "planHash" .= value.planHash]
instance FromJSON CohortExpectation where parseJSON = withObject "CohortExpectation" \value -> CohortExpectation <$> value .:? "name" <*> value .: "planHash"
instance ToJSON ComparisonMembership where toJSON value = object ["group" .= value.group, "arm" .= value.arm, "trial" .= value.trial, "position" .= value.position]
instance FromJSON ComparisonMembership where parseJSON = withObject "ComparisonMembership" \value -> ComparisonMembership <$> value .: "group" <*> value .: "arm" <*> value .: "trial" <*> value .: "position"