vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

docs: state current behaviour, drop change-log wording

Browse source 
Refs #3902
This commit is contained in:
atlas 2026-10-02 07:57:50 +02:00
commit 4498272276
2 changed files with 48 additions and 67 deletions
Download patch file Download diff file Expand all files Collapse all files

104
docs/integrations/matrix.md
View file

@ -62,12 +62,12 @@ room id, so adopting a new one does **not** rename the existing users and rooms
it strands them, because their ids still name a homeserver that no it strands them, because their ids still name a homeserver that no
longer answers. longer answers.
<details><summary>Upgrading a homeserver that already has ids</summary> <details><summary>Pinning <code>serverName</code> on a homeserver with existing ids</summary>
A homeserver that minted ids under an older `serverName` default must `serverName` defaults to the bare `services.hyperhive.swarm.domain`. A
**pin the value it actually minted them under**, not adopt the current homeserver must set `serverName` to the value that minted its existing
default — see above for why adopting a new one strands existing users ids — see above for why a different value strands existing users and
and rooms: rooms:
```nix ```nix
services.hyperhive.swarm.matrix = { services.hyperhive.swarm.matrix = {
@ -79,8 +79,8 @@ services.hyperhive.swarm.matrix = {
A rebuild on a host that already has a homeserver prints a A rebuild on a host that already has a homeserver prints a
`hive-matrix: WARNING — … serverName is unset` line when this is missing, `hive-matrix: WARNING — … serverName is unset` line when this is missing,
naming the value it's about to default to. It never fails the rebuild, so act on naming the value it's about to default to. It never fails the rebuild, so
it before the homeserver mints the ids. pin the value before the homeserver mints any ids under the default.
</details> </details>
@ -210,67 +210,55 @@ tuwunel only treats a message as a command when its sender is already an
admin. `@hive-<hive>:` has no admin sender to make that call with. Both are admin. `@hive-<hive>:` has no admin sender to make that call with. Both are
swarm-level operations. swarm-level operations.
<details><summary>Upgrading a hive that shared one sender account with every other hive</summary> <details><summary>Store precedence for a hive's sender account</summary>
Nothing to do, and no window where the hive is without an account. `swarm/services/matrix/sender-token` is a shared path `hive-c0re` and
`swarm-controller` both build from the same function; nothing reads it.
`ensure_hive_user` reads the per-hive path
`swarm/hives/<hive>/matrix/sender-token` **first, on every sweep**, not
just when that file is missing (`sender_source`'s decision), so a value
at the shared path never takes effect once the per-hive path has one.
`swarm-controller` mints a per-hive token within five minutes of a hive
appearing; the sweep then overwrites the per-hive file, no boot
required.
<!-- vale write-good.Passive = NO --> <!-- vale write-good.Passive = NO -->
- **The old shared value at `swarm/services/matrix/sender-token` is read by - **Room membership follows the account the sweep currently uses.**
nothing.** `hive-c0re` and `swarm-controller` both build the path from the `ensure_hive_space` takes the stored room id first: if a different
same function, and it now carries the hive's name — so the old object account than the room's member created that id, the sweep's invite
stays in the store, unread, until an operator deletes it. Delete it or comes back refused (a non-member can't invite), and the sweep logs it
leave it; the accounts it authenticates as keep their own standing either and carries on — degraded, not crashed. Two ways out, both
way, since an access token lives on the device that minted it. operator-chosen: invite `@hive-<hive>:` into the existing Space and
- **The hive switches on the next sweep.** `ensure_hive_user` reads the chat room from a client, which keeps the history; or delete the
per-hive store path **first, on every sweep**, not just when the file is hive's stored room-id files, after which the next sweep creates a
missing (`sender_source`'s decision). `swarm-controller` mints a token Space and chat room owned by the current account and invites every
there for every hive within five minutes; the sweep takes it and agent into them. Leaving it unresolved gives a hive that provisions
overwrites the file, so the shared token stops being served as soon as no rooms.
one exists in the store, no boot required. While the store has nothing
yet, the file is left untouched (still the shared token, right after the
upgrade), so nothing breaks mid-sweep.
- **The rooms the shared account created don't follow the new account, and
this is the one step that needs a decision.** Membership is per account.
`ensure_hive_space` takes the stored room id first, so the sweep hands the
new account the old Space's id, the invite it then sends comes back
refused (a non-member can't invite), and the sweep logs it and carries
on — degraded, not crashed. Two ways out, both operator-chosen. Either invite
`@hive-<hive>:` into the existing Space and chat room from a client, which
keeps the history; or delete the hive's stored room-id files, after which
the next sweep creates a Space and chat room owned by the new account and
invites every agent into them. Do one of the two; leaving it gives a hive
that provisions no rooms.
<!-- vale write-good.Passive = YES --> <!-- vale write-good.Passive = YES -->
</details> </details>
<details><summary>Upgrading a hive that used the registration token</summary> <details><summary>Appservice identity, not the registration token</summary>
Nothing to do, and nothing to time. The activation script mints the The activation script mints the appservice token and renders the
appservice token and renders the registration before the homeserver registration before the homeserver restarts, so every boot has both
restarts, so the first boot after the switch already has both halves. halves. `registrationTokenFile` is a removed option: a config that
still sets it fails to evaluate with a message naming the appservice.
<!-- vale write-good.Passive = NO --> <!-- vale write-good.Passive = NO -->
- **Existing accounts keep working.** An access token lives on the - **Access tokens are independent of the registration token.** An
device that minted it; removing the registration token touches no access token lives on the device that minted it, so accounts and
device, no account and no session. `login_with_password` stays on, so sessions are unaffected by the registration token's presence.
the password fallback is still there too. `login_with_password` stays on, so the password fallback works
- **The sender account may already be an admin** on such a hive (it won the too.
first-user grant when the hive was new). Nothing here demotes it; the - **The homeserver's `admin_execute` promotes only `@swarm` at boot**
homeserver no longer promotes it, so a hive built fresh has an (above); a hive's sender account is never promoted, regardless of
ordinary account and an older one keeps whatever standing it acquired. when it was created.
- **`/var/lib/hyperhive/matrix-register-token` stays on disk**, read by - **The value that matters lives at `matrix/appservice-token`.**
nothing. Delete it or leave it; neither does any harm. `swarm-secret-publish` on the authelia host mints and `put`s it
- **`registrationTokenFile` is a removed option.** A config that still there; the hive uses its locally minted token only until the first
sets it fails to evaluate with a message naming the appservice — a hive successful read. See [`../swarm/secrets.md`](../swarm/secrets.md)
that never set it (the default) is unaffected. for how that mint stays idempotent across runs.
- **A swarm store holding the old `matrix/registration-token` path** is
no longer read at all. The value that matters now lives at
`matrix/appservice-token`, and `swarm-secret-publish` on the authelia
host mints and `put`s it there — the hive uses its locally minted
token only until the first successful read. See
[`../swarm/secrets.md`](../swarm/secrets.md) for how that mint stays
idempotent across runs.
<!-- vale write-good.Passive = YES --> <!-- vale write-good.Passive = YES -->
</details> </details>

11
docs/networking/network.md
View file

@ -8,15 +8,8 @@ the hive collector, and the gateway's resolver, which every swarm service
turns on. Configured via `services.hyperhive.network.*`. turns on. Configured via `services.hyperhive.network.*`.
Isolation is the only mode; agent containers never share the host netns. Isolation is the only mode; agent containers never share the host netns.
`services.hyperhive.network.isolateContainers` and
<details><summary>Upgrading a config that sets isolateContainers or upstreamDns</summary> `services.hyperhive.network.upstreamDns` don't exist.
Neither option exists. A config that still sets
`services.hyperhive.network.isolateContainers` or
`services.hyperhive.network.upstreamDns` fails eval with a removal
message; drop the line.
</details>
## Network map ## Network map