Development

Layout

Cargo workspace:

Crate	Role
fd-domain	entities, invariants, domain events, problem codes (no I/O)
fd-ports	port traits (engine, repos, blobs, probe, bus, auth, devices, sync, sources, scenarios, enhance, …)
fd-app	use cases: venues, calibration, content, shows, playback, cues / triggers, parameters, devices, system, scenarios, sync / cluster, video I/O
fd-adapters	engine gRPC client + mock, SQLite + blob store, ffprobe, brokers (inproc / Redis / NATS), auth, devices (projector agents, PJLink, Art-Net / sACN, serial), sync (linuxptp pmc, SNTP, OS readers), sources (URL probe, NDI), outbound OSC / HTTP, MIDI
fd-transport	REST, GraphQL, WebSocket, socket.io, legacy profile, OSC, gRPC, mDNS — all calling the same operations
fd-dome, freedome-contract	.dome codec (reference-codec port) and generated contract types
fd-config, fd-observability	configuration (schema, validation, reload) and logging / health / metrics
freedome-scenario-api, fd-scenario-host, freedome_scenarios	scenario plugin API, host, built-in scenarios
freedome_ai	AI enhancement (ffmpeg backends; Core ML planned) consumed through EnhancePort
bins/freedome-mediaserver, bins/freedome-dome	server (composition root) and the .dome CLI
legacy/freedome_core	the old crate, quarantined until each module’s port gate passes (not built)

Build and test

The host needs only Docker; every tool runs in the toolchain image freedome/tc-rust via scripts/rs:

scripts/rs cargo build --workspace
scripts/rs cargo test --workspace
scripts/rs cargo clippy --workspace --all-targets -- -D warnings
scripts/rs python3 scripts/check-layers.py
scripts/rs cargo deny --locked check

Contract pin: scripts/sync-contract.sh --copy --bundle (host) then scripts/rs scripts/sync-contract.sh --gen. Integration scripts: scripts/bench.sh, scripts/test-brokers.sh, scripts/test-sync.sh, scripts/test-sources.sh, scripts/test-devices-live.sh, scripts/test-osc-interop.sh, scripts/test-transports-conformance.sh, scripts/test-packages.sh. Contract conformance: make conformance-full CONTRACT_TOKEN=fdk_ci… in freedome_contract with MS_IMAGE=freedome/mediaserver:dev.

Fuzz, security and load

• Fuzz targets (fuzz/): osc_decode, ws_envelope, dome_unpack, json_bodies; cp Cargo.lock fuzz/Cargo.lock && scripts/rs env RUSTC_BOOTSTRAP=1 cargo fuzz run <target> --fuzz-dir fuzz -- -max_total_time=3600.
• Security suite: tests/security/run.sh against a running image (auth matrix, allow-lists, redaction, traversal, token policy, rate limits).
• Load: load/run.sh (k6 HTTP / WS / socket.io / GraphQL WS + the OSC flooder) against a running image; targets in

Packaging and CI

scripts/package.sh deb|rpm|power|lint|all [--target <triple>] (cargo-deb, cargo-generate-rpm, lintian); scripts/test-packages.sh target/packages (install / upgrade / purge in debian:12). Docker: docker build -f packaging/docker/Dockerfile -t freedome/mediaserver:dev .. .gitlab-ci.yml runs lint, tests, cross builds (arm64; loongarch64 when the toolchain has a cross gcc), packages, native jobs for dedicated runners (Elbrus, Baikal, Loongson, Astra, BOSS, Kylin, Vega, Shakti, Windows, macOS) and nightly fuzz / load jobs.