Skip to content

feat!: regroup the parameter surface into concern structs#28

Merged
jcardozo-eth merged 4 commits into
mainfrom
feat/struct-parameter-surface
Jul 22, 2026
Merged

feat!: regroup the parameter surface into concern structs#28
jcardozo-eth merged 4 commits into
mainfrom
feat/struct-parameter-surface

Conversation

@jcardozo-eth

@jcardozo-eth jcardozo-eth commented Jul 22, 2026

Copy link
Copy Markdown
Member

Closes #13.

Changes

The parameter surface regroups into five flat keys (concurrent, runners, runner_defaults, runner_tokens, secret_store_path) and six parameter groups, one hash per concern (configuration_file, runner_account, packages, rootless_docker, runner_service, and standalone with self_update nested inside), declared in a deliberate order that the generated REFERENCE.md and the example node files preserve: the config.toml content first, then the host concerns.

Every default now lives in the module data layer and each group carries a deep-merge lookup rule, so consumer data holds only deviations: a node file setting rootless_docker.manage: true inherits the rest of the group, hierarchy layers can own different subkeys of one group, array subkeys union across layers with a ---prefixed element removing the matching element a lower layer contributed (the knockout_prefix of the deep merge), and a mistyped subkey fails the compile instead of being silently ignored. The class signature is types-only; a resource-style declaration bypasses Hiera merging and must pass complete hashes, as documented.

The apply script now installs on any declared-standalone host (standalone.manage: true), not only with the self-update loop, and enabling standalone.self_update.manage on a host not declared standalone fails at compile time. healthcheck_interval lives on the standalone group.

The data check's advisory no longer calls subkeys under a disabled manage toggle inert: it reports them as not enforced, since the module may still read some of them as shared inputs (the runner account's identity keys are read by every concern regardless of the toggle).

The README, examples/data/, CONTRIBUTING, and REFERENCE.md are reworked to the new surface, and the unreleased CHANGELOG entries are consolidated into one coherent description of it.

Verification

  • Full gate green: validate, lint, 112 spec examples, docs-check.
  • Deep merge exercised through a real two-layer Hiera hierarchy: a partial consumer hash fills its unset subkeys from the module defaults, a scalar subkey set in the node layer overrides the common layer, array subkeys union across layers with a ---prefixed element removing the matching lower-layer element, and a plain-YAML token store is wrapped Sensitive by the convert_to lookup rule.
  • Unknown subkeys (top-level and nested) and the standalone containment check demonstrated failing the compile with the offending key named.
  • Mutation-checked, each failing its test when reverted: the containment fail() in manifests/init.pp, the default values in data/common.yaml, the knockout_prefix: '--' entry in the lookup_options, the Struct type rejecting unknown subkeys, and the advisory wording in scripts/check_hiera_data.rb.
  • The shipped data check run against pre-restructure consumer keys reports each as failing loud; a subkey under a disabled manage toggle gets the non-failing advisory.

Five flat keys (concurrent, runners, runner_defaults, runner_tokens,
secret_store_path) and six concern structs (configuration_file,
runner_account, packages, rootless_docker, runner_service, standalone
with self_update nested inside), declared in the order the generated
documentation and the example node files preserve.

Every default moves to the module data layer behind a deep-merge lookup
rule with the '--' knockout prefix, so consumer data holds only
deviations; the class signature is types-only and Struct types reject
unknown subkeys at compile time. The apply script installs on any
declared-standalone host, enabling the self-update loop on a host not
declared standalone fails the compile, and healthcheck_interval lives
on the standalone struct.

BREAKING CHANGE: the flat 1.x parameter names are gone; consumer data
must move to the struct keys.
The runner account's identity keys are read by every concern even when
its manage is false (socket derivation, file ownership, the service
ExecStart), so the advisory's claim that subkeys under an effective
manage: false are inert was wrong for shared-input keys. The advisory
now says the module does not enforce resources from them and, staying
module-neutral, that the module may still read some of them as shared
inputs; the unit spec pins the wording and rejects the inert phrasing.
One coherent description of the new surface: separate entries for the
regrouping, the module-data defaults with deep merge, and the tokens
rename; the Removed bullets read in struct-era key names and the
data-check and apt-fix entries reference the new toggle paths.
The directory-tree annotations, the dependency note, and the spec-suite
description now name the struct-era toggles (packages.sources.manage,
the manage subkeys) instead of the flat manage_* parameters.
@jcardozo-eth jcardozo-eth self-assigned this Jul 22, 2026
@jcardozo-eth
jcardozo-eth merged commit 27f4ee4 into main Jul 22, 2026
3 checks passed
@jcardozo-eth
jcardozo-eth deleted the feat/struct-parameter-surface branch July 22, 2026 21:37
@jcardozo-eth jcardozo-eth added this to the 2.0.0 milestone Jul 24, 2026
@jcardozo-eth jcardozo-eth added breaking Breaking change: lands only in a major release enhancement New feature or request labels Jul 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking Breaking change: lands only in a major release enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Restructure the parameter surface into per-concern structs

1 participant