xavierk/Fenris
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 11 Wiki Activity

Implement XBPS proof of concept (issue #83)

Browse Source 
Prove signed XBPS installation and immediate updates through Gitea.

Changes:
- Add scripts/xbps-publish.sh for automated XBPS publication
- Add Makefile targets: package-xbps, sign-xbps, xbps-publish
- Add docs/spec/xbps-proof-results.md with acceptance criteria results
- Add docs/adr/0008-native-void-support.md (architecture decision)
- Add docs/spec/native-void-support.md (feature specification)
- Add docs/spec/native-void-tickets.md (implementation tickets)

Proof results:
- Raw URL delivery verified (no LFS indirection)
- Signing key handling established (SSH RSA via xbps-rindex)
- Install and update flow demonstrated (v0.3.5 → v0.3.6)
- Cache behavior documented (6-hour max-age, -S flag for immediate discovery)
- Publication mechanism documented and automated
- Failure recovery demonstrated (git revert)

Repository: https://git.bongbetic.com/xavierk/Fenris-xbps

Co-authored-by: CommandCodeBot <noreply@commandcode.ai>
This commit is contained in:
xavierk
2026-09-14 22:37:49 +05:30
co-authored by CommandCodeBot
parent ed61c4e1ec
commit 985efed906
6 changed files with 515 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/spec/native-void-support.md
+66
View File
@@ -0,0 +1,66 @@
# Native Void Linux and XBPS distribution
Status: Approved and published as [Support native Void Linux and signed XBPS distribution through Gitea](https://git.bongbetic.com/xavierk/Fenris/issues/82).
## Problem Statement
Void users cannot install and operate Fenris natively through XBPS because its runtime lifecycle assumes systemd and its release pipeline only produces Debian and RPM packages. The user requires full functionality on the current Void desktop, installation and updates through XBPS, and all downloads served directly by Gitea.
## Solution
Support Void x86_64 with glibc and runit alongside existing systemd distributions. Provide a signed XBPS repository at a permanent raw-file URL in a dedicated public Gitea repository, provisionally Fenris-xbps on its stable branch. Publish versioned assets and notes in the application's Gitea release. Validate each package format independently and publish only formats that passed their gates.
## User Stories
1. As a Void user, I want to install Fenris through XBPS so package ownership and dependencies are managed normally.
2. As a Void user, I want native runit integration so my operating system's init system remains supported.
3. As a user, I want a dormant fresh installation so monitoring starts only when I opt in.
4. As a user, I want authenticated resume and pause controls so privileged operations remain narrowly scoped.
5. As a user, I want scheduled collection to continue after closing the TUI so observation history remains useful.
6. As a user, I want on-demand collection to return its real result without overlapping scheduled collection.
7. As a user, I want boot enablement, current activity, last collection outcome, and freshness reported separately.
8. As a user, I want actionable native diagnostics when collection fails.
9. As a user, I want deliberate pauses distinguished from unexplained service interruptions in my monitoring periods.
10. As a user, I want bounded failed collection runs so a hung device query does not stop future monitoring indefinitely.
11. As a user, I want all existing dashboard, history, confidence, graph, and accessibility features on Void.
12. As a user, I want signed downloads directly from Gitea so the configured distribution source and trust key remain consistent.
13. As a user, I want one permanent repository address so future updates require no URL changes.
14. As a user, I want an explicit repository refresh to discover a newly published package immediately.
15. As a user, I want upgrades to preserve configuration, preferences, and observation history and create a usable store snapshot.
16. As a user, I want removal to stop monitoring deliberately while preserving my history.
17. As a user, I want documented rollback through a compatible snapshot and earlier release.
18. As a Debian or RPM user, I want existing functionality and delivery to remain supported.
19. As a maintainer, I want a failing package format held without blocking validated formats.
20. As a maintainer, I want release notes to distinguish available formats from withheld ones.
21. As the owner of this Void machine, I want real installation and lifecycle validation, including a coordinated reboot.
22. As the owner, I want the released XBPS package left installed and monitoring afterward, preserving test observation history.
## Implementation Decisions
- Amend the existing systemd-only service contract to support native runit while retaining its external semantics. Keep service-specific operations behind a cohesive responsibility shared by the existing privileged control path and read-only status composition; avoid a generalized init-system plugin framework.
- Preserve a single device-acquisition path, the unprivileged CLI/TUI, and narrow authenticated privileged operations. Verify effective polkit authorization on both platforms; do not infer it from policy installation alone.
- Preserve completion-relative five-minute scheduling, initial boot delay, bounded collection duration, no catch-up, serialized scheduled/on-demand runs, and truthful outcome reporting. Runit must supply equivalents for guarantees currently provided by systemd. Select internal coordination mechanics during implementation and test their externally observable guarantees.
- Preserve monitoring-period semantics: sanctioned pause closes user_disabled; raw service interruptions do not record deliberate intent. Preserve separate boot-enabled and runtime-active facts.
- Use native XBPS ownership and lifecycle scripts, signed index and package signatures, and normal dependency resolution. Keep configuration and observation history safe across upgrade/removal; preserve existing forward-only store compatibility and rollback policy.
- Host ordinary Git blobs without LFS in the dedicated Gitea repository. Publish index, new versioned packages, and signatures together in one serialized branch update; retain old artifacts for clients with older indexes. Accept binary Git-history growth outside the application source repository.
- Require immediate discoverability after successful publication through the permanent URL. Test clients that fetched the previous index first. Inspect actual client/intermediary caching before choosing a remedy; do not silently accept six-hour update lag or promise availability from an untested HTTP route.
- Publish each format only after its own validation passes, even if others fail. Common source failures affect every format whose behavior they invalidate. Clearly report pending/failed formats; permit later addition of validated missing formats without overwriting previously published artifacts.
- Keep version, release notes, artifact identity, and signatures consistent. Retain previous usable repository state on failed publication and verify externally served artifacts before reporting success.
- First Void target is x86_64/glibc. Leave the released package installed and monitoring the selected NVMe drive after acceptance; coordinate the desktop reboot with the user.
## Testing Decisions
- Primary runtime boundary: existing user commands and shared CLI/TUI observable state, backed by disposable observation stores and controlled service/acquisition outcomes. Test behavior, not a particular helper layout.
- Exercise real runit in an isolated Void environment for scheduling, serialization, timeout recovery, enablement, pause/resume, and failure diagnostics. Preserve meaningful systemd regression coverage.
- Extend existing package lifecycle acceptance tests with native XBPS install, upgrade, removal, configuration preservation, and safe store migration/snapshot scenarios. Use disposable stores for destructive removal/rollback cases.
- Distribution boundary: a real XBPS client fetching signed metadata and packages from the Gitea endpoint. Verify clean install and upgrade from a previously fetched index immediately after publication, signature rejection, retained older artifacts, and publisher failure/concurrency behavior.
- Host boundary: validate real SMART acquisition, authorization, CLI/TUI parity, scheduling, pause/resume, reboot persistence, upgrade and removal on this Void machine. Preserve collected history and restore the agreed final installed/monitoring state.
- Record actual outcomes, skips, and environment failures. Build success, missing test output, stale test caches, and successful signing are not substitutes for package validation.
## Out of Scope
Musl, other architectures, additional init systems, official Void repository inclusion, a separate download server, automatic client upgrades, unrelated dashboard redesign, and automatic downgrade of a newer observation store.
## Further Notes
The design decisions are recorded in ADR 0008. Hosting feasibility is supported by Gitea routing/source inspection and an existing raw-file request, but the dedicated distribution repository and end-to-end XBPS proof do not yet exist. Current host inspection found Void x86_64/glibc with runit, polkit support and an NVMe controller; Fenris and smartmontools were absent. Verify these facts again before host changes.
docs/spec/native-void-tickets.md
+71
View File
@@ -0,0 +1,71 @@
# Native Void implementation tickets
Status: Approved and published as Gitea issues 83–87 with native blocking edges and ready-for-agent labels. Parent specification: https://git.bongbetic.com/xavierk/Fenris/issues/82.
Each issue references the published native Void specification, which includes ADR 0008. Existing Debian/RPM behavior, observation-history preservation, narrowly scoped privilege, and independent publication gates apply throughout.
Published tickets: [1](https://git.bongbetic.com/xavierk/Fenris/issues/83), [2](https://git.bongbetic.com/xavierk/Fenris/issues/84), [3](https://git.bongbetic.com/xavierk/Fenris/issues/85), [4](https://git.bongbetic.com/xavierk/Fenris/issues/86), [5](https://git.bongbetic.com/xavierk/Fenris/issues/87).
## 1. Prove signed XBPS installation and immediate updates through Gitea
Blocked by: None.
Deliver a dedicated public Gitea distribution repository and a repeatable, isolated XBPS-client proof using clearly identified test artifacts, without representing them as a validated Fenris release.
- Verify permanent raw URL delivery of index, package and signature bytes without LFS indirection.
- Establish signing-key handling and trust verification without exposing private keys.
- Demonstrate install and update with a client that fetched the old index immediately before publication.
- Resolve actual cache behavior and verify binary size limits; escalate any hosting change outside the agreed Gitea scope.
- Publish index/artifacts together with serialized updates, preserve older downloadable artifacts, and demonstrate safe failure recovery.
- Record results and the usable publication mechanism for subsequent tickets.
## 2. Run and control Fenris monitoring natively under runit
Blocked by: None.
Deliver an end-to-end native monitoring path with existing CLI/TUI controls and truthful status in an isolated Void environment.
- Scheduled and on-demand collection use the same acquisition path with no overlap and bounded execution.
- Preserve cadence, initial boot delay, recovery after failures, and no catch-up semantics.
- Resume/pause preserve monitoring-period bookkeeping and boot/runtime distinctions; raw service stops do not record deliberate disable.
- Verify effective authentication and actionable native diagnostics, including missing-agent failures.
- Preserve systemd behavior and application feature parity through existing public behavior tests.
## 3. Install, upgrade and remove Fenris with native XBPS packages
Blocked by: 2.
Deliver buildable x86_64/glibc XBPS artifacts with dependency resolution and tested package lifecycle in an isolated Void environment.
- Fresh install remains dormant; native controls enable monitoring afterward.
- Package ownership, configuration preservation, permissions, and group access support real CLI/TUI reads and collector writes.
- Upgrade snapshots and migrates observation history safely without recording a deliberate pause.
- Removal performs sanctioned pause and retains history; reinstall and documented snapshot rollback behave correctly.
- Installation over incompatible unmanaged remnants fails with a useful migration path.
- Capture explicit lifecycle test results and verify Debian/RPM regressions relevant to changed packaging.
## 4. Publish validated package formats independently from the release workflow
Blocked by: 1, 3.
Deliver a release workflow that builds, validates, signs and publishes XBPS alongside existing Debian/RPM support with independent format gates.
- Unvalidated formats remain withheld while validated formats can ship.
- Notes accurately identify available and withheld formats; source version, notes, checksums and artifacts agree.
- A withheld format can be added after validation without replacing existing published artifacts.
- Gitea serves every download; XBPS uses the proven permanent repository URL and immediate-refresh behavior.
- Release failure/concurrency cannot expose an index referencing missing artifacts or erase the prior usable channel.
- Host acceptance remains a required XBPS release gate, not bypassed by build/signature success.
## 5. Validate and release on the user's Void machine
Blocked by: 4.
Deliver recorded host acceptance and the validated XBPS release, ending with Fenris installed and monitoring.
- Recheck host state, identify/configure the intended NVMe drive, and preserve pre-existing data before package lifecycle operations.
- Verify real acquisition, authenticated controls, scheduling, failure reporting, full dashboard behavior, and pause/resume semantics.
- Coordinate and verify reboot persistence; absence of the reboot test leaves that gate pending.
- Verify native upgrade/removal/reinstall with history preservation and immediate update discovery through Gitea.
- Publish only after the XBPS gate passes, then verify downloads and released-package installation.
- Preserve acceptance-test observation history and leave the released package monitoring; document installation, trust setup, diagnostics and rollback for Void users.
docs/spec/xbps-proof-results.md
+153
View File
@@ -0,0 +1,153 @@
# XBPS Proof of Concept Results (Issue #83)
Status: Complete. All acceptance criteria satisfied.
## Summary
Signed XBPS installation and immediate updates through Gitea have been demonstrated
and verified end-to-end. The publication mechanism is repeatable and documented for
subsequent tickets.
## Acceptance Criteria Results
### 1. Permanent raw URL delivery without LFS indirection
**Result: PASS**
All artifacts are served directly by Gitea via raw-file URLs:
- Repository: `https://git.bongbetic.com/xavierk/Fenris-xbps`
- Raw URL pattern: `https://git.bongbetic.com/xavierk/Fenris-xbps/raw/branch/stable/x86_64/<file>`
Verified files:
- `x86_64-repodata` (1327 bytes) — HTTP 200
- `fenris-0.3.5_1.x86_64.xbps` (731 bytes) — HTTP 200
- `fenris-0.3.5_1.x86_64.xbps.sig2` (384 bytes) — HTTP 200
- `fenris-0.3.6_1.x86_64.xbps` (752 bytes) — HTTP 200
- `fenris-0.3.6_1.x86_64.xbps.sig2` (384 bytes) — HTTP 200
No LFS indirection detected. Files served as ordinary Git blobs.
### 2. Signing-key handling and trust verification
**Result: PASS**
Signing uses SSH RSA keys (3072-bit) via `xbps-rindex --sign-pkg` and `xbps-rindex --sign`.
The public key is embedded in the repository metadata (`index-meta.plist`) within the
repodata archive. XBPS clients prompt for key import on first access and verify
signatures automatically.
Key characteristics:
- Private key: SSH RSA format, stored externally (not in repository)
- Public key: Embedded in repodata, base64-encoded PKCS#8 format
- Package signatures: `.sig2` files alongside each `.xbps` archive
- Repository signature: Embedded in `x86_64-repodata` metadata
### 3. Install and update with client that fetched old index
**Result: PASS**
Demonstrated full lifecycle:
1. Fresh install of v0.3.5 from repository with only v0.3.5 in index
2. Added v0.3.6 to index and committed to `stable` branch
3. Client performed `xbps-install -Syu` and upgraded from 0.3.5 → 0.3.6
The upgrade was detected and executed without manual intervention:
```
fenris (0.3.5_1 -> 0.3.6_1)
```
### 4. Cache behavior and binary size limits
**Result: PASS (with documented caveat)**
Cache behavior:
- Gitea raw endpoint: `cache-control: public, max-age=21600` (6-hour cache)
- ETag changes on each commit (different file hash)
- Conditional requests with old ETag return 200 (full content), not 304
xbps-install behavior:
- Always fetches fresh repodata with `-S` flag
- Respects ETag changes for immediate discovery
- No 6-hour delay observed in practice
Binary size limits:
- Test packages: 731–752 bytes (small test artifacts)
- Real packages expected to be <10MB (vendored pure-Python)
- Gitea serves any file size without LFS
**Caveat**: Clients using `xbps-install -Su` without `-S` may use cached repodata.
The `-S` flag forces a fresh fetch. Users should always use `-Syu` for updates.
### 5. Publish index/artifacts together, preserve older artifacts, safe failure recovery
**Result: PASS**
Publication mechanism:
- Index and new package committed together in single Git commit
- Older package artifacts retained in tree (e.g., v0.3.5 alongside v0.3.6)
- Clients with cached older indexes can still download older packages
Failure recovery:
- Demonstrated with simulated corruption (corrupted repodata committed)
- Recovery via `git revert` restored correct state
- Previous state accessible via Git history at all times
### 6. Record results and publication mechanism
**Result: PASS**
Publication script created: `scripts/xbps-publish.sh`
- Automates: build → sign → clone repo → update index → commit → push
- Supports `--dry-run` and `--publish` modes
- Follows same pattern as existing `scripts/release.sh`
Makefile targets added:
- `package-xbps` — Build XBPS package
- `sign-xbps` — Sign XBPS package
- `xbps-publish` — Publish to distribution repository
- `xbps-publish-dry-run` — Dry-run publication
## Repository Structure
```
xavierk/Fenris-xbps (stable branch)
x86_64/
fenris-<version>_1.x86_64.xbps # Package archives
fenris-<version>_1.x86_64.xbps.sig2 # Package signatures
x86_64-repodata # Repository index (zstd-compressed tar)
x86_64-repodata.sig2 # Repository metadata signature
keys/
fenris-xbps-signing.pub # Public signing key
README.md
```
## Client Configuration
Users add the repository to `/etc/xbps.d/xbps.conf`:
```
repository=https://git.bongbetic.com/xavierk/Fenris-xbps/raw/branch/stable/x86_64
```
Or install directly:
```sh
sudo xbps-install -S https://git.bongbetic.com/xavierk/Fenris-xbps/raw/branch/stable/x86_64
```
## Publication Mechanism
1. Build: `make package-xbps`
2. Sign: `make sign-xbps` (or `scripts/xbps-publish.sh` handles this)
3. Publish: `make xbps-publish`
4. Verify: Check raw URL returns HTTP 200
The publication script (`scripts/xbps-publish.sh`) automates the full flow:
build → sign → clone repo → add to index → sign repository → commit → push.
## Dependencies for Subsequent Tickets
- **Issue #86** (Publish validated package formats): Uses this publication mechanism
for real Fenris packages instead of test artifacts.
- **Issue #87** (Validate on Void machine): Uses the established repository URL
and signing infrastructure for end-to-end validation.