Skip to content

[Feature]: Typed param registry with schema validation #188

Description

@mrhillsman

Problem Statement

Per-workload params are currently implemented as ad-hoc getter methods scattered across each workload file. Each getter independently reads from WorkloadConfig.Params map[string]string, hardcodes its own default, and performs no validation. This pattern was established in the chaos workloads and extended to all nine workloads in #184, but it has limitations:

  • No validation: unknown param keys are silently ignored, typos produce default behavior with no warning
  • No type safety: all values are raw strings — a param that expects an integer accepts "banana" without complaint
  • No discoverability: the only way to know what params a workload accepts is to read the source code or docs
  • Scattered declarations: defaults and param metadata are spread across nine files in private getter methods
  • Manual doc maintenance: the params table in configuration.md must be updated by hand and can drift from the code

Proposed Solution

Introduce a centralized param registry where each workload declares its accepted params with types, defaults, and descriptions:

type ParamType int

const (
    ParamString ParamType = iota
    ParamInt
    ParamBool
    ParamList
)

type ParamDef struct {
    Key     string
    Type    ParamType
    Default string
    Desc    string
}

Each workload registers its param schema alongside its constructor in the workload registry. A shared GetParam(key) method on BaseWorkload replaces the per-workload getters, looking up the key in the schema for validation and type coercion.

At config load time, the registry validates all workloads.<name>.params entries:

  • Unknown workload name → error
  • Unknown param key for that workload → error
  • Value doesn't match declared type → error

This also enables:

  • CLI --params flag ([Feature]: CLI flag for per-workload params #187) with input validation and clear error messages
  • Tab completion / --help listing available params per workload
  • Doc generation from the schema (single source of truth for the params table in configuration.md)
  • Range/constraint validation (e.g., cpu-load-percent must be 1–100)

Alternatives Considered

  • Status quo (per-workload getters): Works ([Feature]: Configurable params for built-in workloads #184 proves it), but doesn't scale well — every new param means a new private method, manual doc update, and no validation. Acceptable as a stepping stone, not as a long-term pattern.
  • Map-of-defaults on BaseWorkload: Lighter than a full registry but still no type safety or validation. Doesn't solve discoverability.
  • External schema file (JSON/YAML): Over-engineered for the current codebase size. The Go struct approach keeps schema and code co-located.

Area

CLI / Configuration, Workloads

Architecture Layer

Layer 3 - Workload Definitions (workloads, registry)

Additional Context

This is a refactor of the param infrastructure established by #184. The per-workload getter pattern from #184 should merge first — it proves that all nine workloads support params and provides full test coverage. This issue replaces the scattered getters with a centralized, validated registry. Issue #187 (CLI --params flag) depends on this registry existing to validate input.

Metadata

Metadata

Assignees

Labels

kind/featureCategorizes issue or PR as related to a new feature.priority/backlogHigher priority than priority/awaiting-more-evidence.size/XLDenotes a PR that changes 500-999 lines, ignoring generated files.tech-debtTechnical debt, code quality, or maintenance concerntriage/acceptedIndicates an issue or PR is ready to be actively worked on.

Type

No type

Fields

No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions