117 lines
5.1 KiB
Plaintext
Executable File
117 lines
5.1 KiB
Plaintext
Executable File
# Fester — Development Notes
|
|
|
|
## Overview
|
|
|
|
Fester is a distributed, DAG-driven build execution system with real-time
|
|
scheduling, thermal/load awareness, cache-aware execution, and deterministic
|
|
replay. It turns a cluster of heterogeneous machines into a single observable
|
|
build brain.
|
|
|
|
## Architecture Principles
|
|
|
|
### EventBus-Centric Design
|
|
|
|
Every state change in Fester flows through the singleton EventBus. Subscribers
|
|
index, journal, and broadcast events. This strict separation means:
|
|
|
|
- Routers (FastAPI APIRouters under `backend/api/`) never mutate state directly.
|
|
- The timeline store, cause graph, failure propagator, and WebSocket broadcaster
|
|
are all passive bus subscribers.
|
|
- Adding a new feature means emitting events and subscribing to them — not
|
|
wiring ad-hoc callbacks.
|
|
|
|
### Storage Layer
|
|
|
|
Fester uses SQLite in WAL mode for builds, sessions, events, and node states.
|
|
Optional storage backends activate automatically when their prerequisites are
|
|
installed:
|
|
|
|
- **Btrfs CoW** — reflink-based snapshots for zero-copy artifact storage.
|
|
- **QCOW2** — workspace freezing via real mount + rsync for KVM environments.
|
|
- **tmpfs** — workspace acceleration for fast in-memory builds.
|
|
- **MinIO** — distributed cache for multi-node artifact sharing.
|
|
|
|
### Scheduler Modes
|
|
|
|
The scheduler picks the best node for each build action using a weighted
|
|
scoring model. Available modes:
|
|
|
|
| Mode | Behavior |
|
|
|--------------------|---------------------------------------------------------|
|
|
| unified (default) | Weighted scoring: CPU, temperature, policy, history |
|
|
| weighted | Thermal-aware: throttles above 85 C per-node |
|
|
| cache-first | Prioritizes nodes with cached artifacts |
|
|
| target-isolated | Each target arch runs on designated nodes only |
|
|
| intelligence | Experimental: ML-driven scheduling (future) |
|
|
|
|
## BTC.sh Integration
|
|
|
|
Fester integrates with BTC.sh (Build Tool Chain) cross-compilation forges
|
|
via `backend/toolchain/btc.py`. The integration layer:
|
|
|
|
1. **Probes** `/opt/BTC/` for golden image tarballs and manifest JSON sidecars.
|
|
2. **Parses** the SYS_LABEL format: `DCOSNET-{FAMILY}-{TARGET_ID}-{ISA}-CROSS`.
|
|
3. **Configures** build environment variables (CC, CXX, CFLAGS, LDFLAGS) using
|
|
the target's microarchitecture, ISA tier, and cross-compiler triple from
|
|
the manifest.
|
|
4. **Verifies** `.note.BTC` ELF stamps and `user.btc.stamp` xattr on build
|
|
outputs to confirm they were produced by a BTC-forged toolchain.
|
|
|
|
### Supported ISA Tiers
|
|
|
|
| ISA Tier | Flags |
|
|
|----------|-----------------------------------------------------|
|
|
| AVX512 | `-mavx512f -mavx512dq -mavx512vl -mavx512bw` |
|
|
| AVX2 | `-mavx2` |
|
|
| SSE4_2 | `-msse4.2` |
|
|
| NEON | `-mfpu=neon -mfloat-abi=hard` |
|
|
| MIPS32 | (per-target architecture) |
|
|
| TILE | (per-target architecture) |
|
|
|
|
### Supported BTC Targets (19 total)
|
|
|
|
**Intel HEDT/Server:** haswell, haswell-ep, skylake, skylake-x, skylake-server
|
|
**AMD Ryzen/EPYC:** znver1, znver2, znver3, znver4
|
|
**AMD APU:** apu-zn1, apu-zn2, apu-zn3, apu-zn4
|
|
**Intel Atom:** atom-silvermont, atom-goldmont, atom-tremont, atom-sierraforest
|
|
**Embedded:** mipselr2, armv7, tilegx
|
|
|
|
### CAS (Content-Addressable Store)
|
|
|
|
Fester exposes a shared CAS API for cross-project artifact caching:
|
|
|
|
- `PUT /api/cas/{sha256}` — store an artifact (SHA-256 verified server-side)
|
|
- `GET /api/cas/{sha256}` — retrieve an artifact
|
|
- `HEAD /api/cas/{sha256}` — check existence
|
|
- `DELETE /api/cas/{sha256}` — remove an artifact
|
|
- `GET /api/cas/` — list all artifacts (paginated, filterable by target)
|
|
- `GET /api/cas/stats` — cache statistics
|
|
|
|
## Security Model
|
|
|
|
Fester is designed to run behind existing network controls (OPNsense, IPFire,
|
|
or any firewall appliance). There is no built-in authentication layer — the
|
|
network is assumed to be trusted. For public exposure, use a reverse proxy with
|
|
authentication (nginx + OAuth2 Proxy, Traefik + Authelia, etc.).
|
|
|
|
## Port Assignment
|
|
|
|
- **8181** — Fester backend (FastAPI + WebSocket + UI)
|
|
- **8787** — Node agent probe port (HTTP health + metrics endpoint)
|
|
|
|
## Coding Standards
|
|
|
|
- Python 3.12+ with type hints and modern syntax.
|
|
- All imports use the `backend.X.Y` prefix (no bare imports).
|
|
- Events are emitted via `bus.emit()` — never mutate state from request handlers.
|
|
- UI is vanilla HTML/CSS/JS with no build step and no framework dependencies.
|
|
- CSS uses design tokens defined in `style.css` (dark theme only).
|
|
|
|
## Version History
|
|
|
|
| Version | Date | Summary |
|
|
|---------|------------|----------------------------------------------|
|
|
| 0.1.0 | 2026-06-25 | Initial project structure, stubbed modules |
|
|
| 0.2.0 | 2026-06-27 | Real FastAPI backend, 7-page UI, WebSocket |
|
|
| 0.3.0 | 2026-06-28 | Storage layer, tmux, cause graph, debugger |
|
|
| Unreleased | — | BTC 0.4.0 integration, CAS API, SSE4_2 ISA | |