227 lines
10 KiB
Nix
227 lines
10 KiB
Nix
# Top-level, cross-cutting hyperhive options: the hive's identity
|
|
# (domain + display names) and hive-wide feature toggles read by several
|
|
# subsystem modules. Imported by the ./default.nix aggregator.
|
|
{
|
|
lib,
|
|
config,
|
|
options,
|
|
...
|
|
}:
|
|
let
|
|
hiveCfg = config.services.hyperhive;
|
|
hiveName = hiveCfg.deploy.hive-controller.hiveName;
|
|
in
|
|
{
|
|
imports = [
|
|
(lib.mkRemovedOptionModule [ "services" "hyperhive" "ruthless" ] ''
|
|
hive-c0re no longer creates ruth at boot. Remove this definition, and create
|
|
ruth from the swarm dashboard like any other agent; a ruth container that
|
|
already exists keeps starting with the hive.
|
|
'')
|
|
(lib.mkRenamedOptionModule
|
|
[ "services" "hyperhive" "github" "enable" ]
|
|
[ "services" "hyperhive" "swarm" "github" "enable" ]
|
|
)
|
|
];
|
|
|
|
# Canonical hive DNS domain shared by every subsystem that needs a
|
|
# stable hostname. Typed nullOr (default null) so the option always
|
|
# exists, but it's REQUIRED wherever this host runs a hive — an
|
|
# assertion in hive-network.nix fails eval when it's unset, since
|
|
# matrix bakes it in on first boot and the gateway/forge/agent URLs all
|
|
# derive from it (no safe default). Full identity-surface
|
|
# context (HYPERHIVE_HIVE_DOMAIN / HIVE_NAME / SWARM_NAME env-var
|
|
# chain → identity.rs → claude prompt): docs/process/conventions.md::
|
|
# Hive identity (label + domain + display names).
|
|
options.services.hyperhive.domain = lib.mkOption {
|
|
type = lib.types.nullOr lib.types.str;
|
|
# Read out of the swarm directory rather than derived here. The
|
|
# directory is what every OTHER hive reads this hive's address from,
|
|
# so deriving it separately gave two homes for one value with
|
|
# nothing asserting they agreed — and a disagreement surfaces as
|
|
# "the other hives can't reach me", on a machine other than the
|
|
# misconfigured one.
|
|
#
|
|
# ⚠️ The `<hiveName>.<swarm.domain>` formula lives once, on
|
|
# `hives.<name>.domain`, which this reads. A direct fallback here
|
|
# would recreate the second path (and, since that default reads
|
|
# `swarm.domain` too, a value that can differ from the directory's).
|
|
default =
|
|
if hiveName != null && hiveCfg.swarm.hives ? ${hiveName} then
|
|
hiveCfg.swarm.hives.${hiveName}.domain
|
|
else
|
|
null;
|
|
defaultText = lib.literalExpression "services.hyperhive.swarm.hives.\${hiveName}.domain, or null when there is no entry for this hive";
|
|
example = "darkest.space";
|
|
description = ''
|
|
Canonical host domain for hyperhive subsystems that need a
|
|
stable name (currently: `services.hyperhive.swarm.matrix.serverName`
|
|
derives from this, defaulting to
|
|
`matrix.''${services.hyperhive.domain}` when `serverName` is
|
|
null). **Required** when
|
|
`services.hyperhive.deploy.hive-controller.enable` — eval fails
|
|
with a helpful message if it's unset (it's baked into matrix on
|
|
first boot and drives the gateway/forge/agent URLs, with no safe
|
|
default; changing it later is destructive). Exposed to agents as
|
|
`HYPERHIVE_HIVE_DOMAIN`; consumed by
|
|
`hive-agent::identity::hive_domain()` for `<name>@<domain>`
|
|
qualified labels.
|
|
|
|
**Deprecated as a place to write.** It is read from this hive's
|
|
own entry in `services.hyperhive.swarm.hives`, whose `domain`
|
|
defaults to `<hiveName>.<swarm.domain>` — so a conventional hive
|
|
states nothing at all, and a non-conventional one states its
|
|
address in the directory every other hive reads. Setting it here
|
|
still wins and still works, with a warning: the directory is
|
|
shared, this option is not, so a value written only here is
|
|
invisible to the rest of the swarm.
|
|
'';
|
|
};
|
|
|
|
# Deprecation warning for the shorthand above, fired on PRIORITY.
|
|
#
|
|
# ⚠️ Not `isDefined`, and not `files`: the module system injects an
|
|
# option's own `default` as a definition attributed to the declaring
|
|
# file, so both say "defined, in hyperhive.nix" for a config that set
|
|
# nothing — measured, after this warning fired on the conventional
|
|
# case. `mkOptionDefault` is priority 1500, so anything lower is a
|
|
# definition someone actually wrote (100 plain, 1000 mkDefault).
|
|
config.warnings = lib.optional (options.services.hyperhive.domain.highestPrio < 1500) ''
|
|
services.hyperhive.domain is set explicitly and is deprecated. This
|
|
hive's address belongs in the swarm directory, which every hive in
|
|
the swarm shares a copy of:
|
|
|
|
services.hyperhive.swarm.hives."${toString hiveName}".domain = "${toString hiveCfg.domain}";
|
|
|
|
(Or drop the value entirely if it is the conventional
|
|
`<hiveName>.<swarm.domain>` — that is the directory entry's own
|
|
default.)
|
|
|
|
Setting it here still wins, so nothing is broken right now. What it
|
|
does not do is tell the other hives: they read this hive's address
|
|
out of their copy of the directory, so a value written only here
|
|
leaves them pointing somewhere else with nothing detecting it.
|
|
'';
|
|
|
|
# Where the swarm lives. Declared beside the hive's own identity
|
|
# because it is what that identity is derived FROM — every hive in a
|
|
# swarm is a sub-domain of it. No alias: this option has no earlier
|
|
# spelling.
|
|
options.services.hyperhive.swarm.domain = lib.mkOption {
|
|
type = lib.types.nullOr lib.types.str;
|
|
default = null;
|
|
example = "darkest.space";
|
|
description = ''
|
|
DNS domain of the wider swarm this hive belongs to. Each hive
|
|
occupies its own sub-domain of it, which is why every entry in
|
|
`services.hyperhive.swarm.hives` defaults its `domain` to
|
|
`<name>.<swarm.domain>` — set this plus
|
|
`services.hyperhive.deploy.hive-controller.hiveName`, list the hives by name, and no
|
|
hive in the swarm states an address at all.
|
|
|
|
**Required** on every host that runs a hyperhive service (a
|
|
`services.hyperhive.deploy.*` service, the gateway, the bridge,
|
|
`otel` or the snapshot store), with the same value on every host
|
|
of the swarm, and deliberately not
|
|
defaulted. A guessed swarm domain is a wrong hostname that
|
|
evaluates cleanly and deploys, which is worse than an eval
|
|
failure telling an operator to write down the one address their
|
|
swarm answers to.
|
|
'';
|
|
};
|
|
|
|
# The hive's name is `deploy.hive-controller.hiveName`, declared in
|
|
# ./deploy.nix beside the switch that makes a host run a hive. The
|
|
# identity surfaces (label, domain, display names, env-var chain) are in
|
|
# docs/process/conventions.md::Hive identity.
|
|
#
|
|
# A hive turns the name into an identifier with no fallback: hive-c0re's
|
|
# OIDC client and matrix localpart, the CN of the hive's `client.pem`
|
|
# (./glue-bao-tls.nix), and the `hives/<name>` path of its secrets. A null
|
|
# there renders as an empty string that evaluates and deploys.
|
|
config.assertions = [
|
|
{
|
|
assertion = !hiveCfg.deploy.hive-controller.enable || hiveName != null;
|
|
message = ''
|
|
hyperhive requires services.hyperhive.deploy.hive-controller.hiveName
|
|
to be set on a host that runs a hive — it is this hive's label
|
|
within the swarm, and the leftmost part of the domain it is
|
|
addressed by (`<hiveName>.<swarm.domain>`), not only a display name.
|
|
Set it (`services.hyperhive.deploy.hive-controller.hiveName = "pr1ma";`).
|
|
'';
|
|
}
|
|
{
|
|
# An EMPTY `hives` fires this too, deliberately: since
|
|
# `swarm.domain` is required, every hive is in a swarm — a swarm of
|
|
# one is still a swarm — so a directory with no entry for this host
|
|
# is missing one either way. It also has to fire here, because this
|
|
# host's own domain is read out of the directory: without the entry
|
|
# `services.hyperhive.domain` is null and the generic required-domain
|
|
# assertion in ./hive-network.nix would fire instead, naming an
|
|
# option the operator should not be setting.
|
|
#
|
|
# Guarded on `hiveName != null` so the required-hiveName assertion
|
|
# above is what fires for that case — two assertions naming the same
|
|
# missing value is noise.
|
|
assertion =
|
|
!hiveCfg.deploy.hive-controller.enable || hiveName == null || hiveCfg.swarm.hives ? ${hiveName};
|
|
message = ''
|
|
services.hyperhive.swarm.hives has no entry for this hive
|
|
(services.hyperhive.deploy.hive-controller.hiveName = "${toString hiveName}").
|
|
|
|
`hives` describes every hive in the swarm including this one,
|
|
so that every host can share one identical attrset, and this
|
|
hive's own domain is derived from its entry. Add:
|
|
|
|
services.hyperhive.swarm.hives."${toString hiveName}" = { };
|
|
|
|
No fields are needed: `domain` defaults to
|
|
`<name>.<swarm.domain>`. Set it in the entry if this hive is
|
|
addressed by something else.
|
|
|
|
Declared hives: ${lib.concatStringsSep ", " (lib.attrNames hiveCfg.swarm.hives)}
|
|
'';
|
|
}
|
|
];
|
|
|
|
config.services.hyperhive.deploy.hive-controller.dashboardDomain =
|
|
if hiveName != null && hiveCfg.swarm.dashboardDomains ? ${hiveName} then
|
|
hiveCfg.swarm.dashboardDomains.${hiveName}
|
|
else
|
|
null;
|
|
|
|
# The one hive-level option that describes something ABOVE the hive,
|
|
# which is why it sits under `swarm` with the swarm-global services
|
|
# rather than beside the hive's name.
|
|
options.services.hyperhive.swarm.name = lib.mkOption {
|
|
type = lib.types.nullOr lib.types.str;
|
|
default = null;
|
|
example = "constellat1on";
|
|
description = ''
|
|
Human-readable name of the wider swarm this hive belongs to.
|
|
Hives at different DNS domains can share a swarm name when
|
|
they federate together. Exposed to agents as
|
|
`HYPERHIVE_SWARM_NAME`; surfaced in the dashboard chrome and
|
|
per-agent system prompt when set.
|
|
'';
|
|
};
|
|
|
|
# `singleHostSwarm` is declared in ./local-defaults.nix, with
|
|
# the values it asserts. It is a deployment mode rather than a setting
|
|
# this module's options read, so it lives with its consequences.
|
|
|
|
options.services.hyperhive.swarm.github.enable = lib.mkOption {
|
|
type = lib.types.bool;
|
|
default = true;
|
|
example = false;
|
|
description = ''
|
|
Swarm-wide switch for the per-agent GitHub integration (the `gh` CLI
|
|
wrapper + git credential helper, per `services.hyperhive.agent.github.enable`). On by
|
|
default: every agent gets the integration, inert until an operator links
|
|
a PAT for it in the swarm UI. Set `false` to turn it off for the whole swarm --- the
|
|
meta-flake renderer (`hive-c0re/src/meta.rs`) then injects
|
|
`services.hyperhive.agent.github.enable = false` into every agent. Exposed to hive-c0re
|
|
as `HYPERHIVE_GITHUB_DISABLED` (set only when the integration is off).
|
|
'';
|
|
};
|
|
}
|