bunny-lab/Borealis-Github-Replica
1
0
Fork 0
mirror of https://github.com/bunny-lab-io/Borealis.git synced 2026-02-05 23:50:30 -07:00
Code Issues Packages Projects Releases Wiki Activity

Documentation Overhaul

Browse Source
This commit is contained in:
Nicole Rappe
2026-01-27 01:09:20 -07:00
parent e23daf69b5
commit 287d3b1cf7
26 changed files with 2062 additions and 801 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
Docs/assemblies.md
View File

@@ -1,20 +1,97 @@
# Assemblies Runtime Reference
# Assemblies and Quick Jobs
[Back to Docs Index](index.md) | [Index (HTML)](index.html)
## Database Layout
- Three SQLite databases live under `Data/Engine/Assemblies` (`official.db`, `community.db`, `user_created.db`) and mirror to `Engine/Assemblies` at runtime.
- Automatic JSON → SQLite imports for the official domain have been retired; the staged `official.db` now serves as the authoritative store unless you invoke a manual sync.
- Payload binaries/json store under `Payloads/<payload-guid>` in both staging and runtime directories; the AssemblyCache references payload GUIDs instead of embedding large blobs.
- WAL mode with shared-cache is enabled on every connection; queue flushes copy the refreshed `.db`, `-wal`, and `-shm` files into the runtime mirror.
- `AssemblyCache.describe()` reveals dirty/clean state per assembly, helping operators spot pending writes before shutdown or sync operations.
## Purpose
Explain Borealis assemblies (script definitions), how they are stored, and how quick jobs execute them.
## Dev Mode Controls
- User-created domain mutations remain open to authenticated operators; community/official writes require an administrator with Dev Mode enabled.
- Toggle Dev Mode via `POST /api/assemblies/dev-mode/switch` or the Assemblies admin controls; state expires automatically based on the server-side TTL.
- Privileged actions (create/update/delete, cross-domain clone, queue flush, official sync, import into protected domains) emit audit entries under `Engine/Logs/assemblies.log`.
- When Dev Mode is disabled, API responses return `dev_mode_required` to prompt admins to enable overrides before retrying protected mutations.
## Assemblies at a Glance
- Assemblies are script definitions stored in SQLite domains.
- Domains include: `official`, `community`, and `user_created`.
- Payload artifacts live under `Payloads/<payload-guid>`.
- Assemblies are cached at runtime by the Engine and served via API.
## Backup Guidance
- Regularly snapshot `Data/Engine/Assemblies` and `Data/Engine/Assemblies/Payloads` alongside the mirrored runtime copies to preserve both metadata and payload artifacts.
- Include the queue inspection endpoint (`GET /api/assemblies`) in maintenance scripts to verify no dirty entries remain before capturing backups.
- Maintain the staged databases directly; to publish new official assemblies copy the curated `official.db` into `Data/Engine/Assemblies` before restarting the Engine.
- Future automation will extend to scheduled backups and staged restore helpers; until then, ensure filesystem backups capture both SQLite databases and payload directories atomically.
## Quick Jobs
- Quick jobs are immediate executions of a script assembly.
- The Engine resolves the script, signs it, and emits a Socket.IO `quick_job_run` event.
- Agents execute the payload and return `quick_job_result` for status and output.
## Activity History
- Quick job executions are tracked in `activity_history`.
- Operators can view or delete device activity history via API.
## Ansible Status (Current)
- Ansible quick-run exists as an endpoint but is not implemented.
- Agent and Engine scaffolding exist but are unstable; treat as disabled.
## API Endpoints
- `GET /api/assemblies` (Token Authenticated) - list assemblies.
- `GET /api/assemblies/<assembly_guid>` (Token Authenticated) - assembly details.
- `POST /api/assemblies` (Token Authenticated) - create assembly.
- `PUT /api/assemblies/<assembly_guid>` (Token Authenticated) - update assembly.
- `DELETE /api/assemblies/<assembly_guid>` (Token Authenticated) - delete assembly.
- `POST /api/assemblies/<assembly_guid>/clone` (Admin + Dev Mode for protected domains) - clone assembly.
- `POST /api/assemblies/dev-mode/switch` (Admin) - toggle dev mode.
- `POST /api/assemblies/dev-mode/write` (Admin + Dev Mode) - flush queued writes.
- `POST /api/assemblies/import` (Domain write permissions) - import legacy JSON.
- `GET /api/assemblies/<assembly_guid>/export` (Token Authenticated) - export legacy JSON.
- `POST /api/scripts/quick_run` (Token Authenticated) - quick PowerShell job.
- `POST /api/ansible/quick_run` (Token Authenticated) - placeholder (not implemented).
- `GET /api/device/activity/<hostname>` (Token Authenticated) - device activity history.
- `DELETE /api/device/activity/<hostname>` (Token Authenticated) - clear history.
- `GET /api/device/activity/job/<int:job_id>` (Token Authenticated) - activity record.
## Related Documentation
- [Flow Editor and Nodes](flow-editor-and-nodes.md)
- [Scheduled Jobs](scheduled-jobs.md)
- [Security and Trust](security-and-trust.md)
- [API Reference](api-reference.md)
## Codex Agent (Detailed)
### Storage layout and caching
- Staging assemblies live under `Data/Engine/Assemblies/`:
- `official.db`
- `community.db`
- `user_created.db`
- `Payloads/` for large script assets
- Runtime mirror lives under `Engine/Assemblies/` and is refreshed at launch.
- The Engine loads and caches assemblies via `Data/Engine/assembly_management` and `AssemblyRuntimeService`.
### Dev Mode behavior
- User-created domain writes are allowed for authenticated operators.
- Official/community domains require Admin + Dev Mode enabled.
- Dev Mode state is tracked per session and expires after a TTL.
- Use `/api/assemblies/dev-mode/switch` to toggle and `/api/assemblies/dev-mode/write` to flush.
### Quick job execution path
1) Operator calls `/api/scripts/quick_run` with `script_path` and `hostnames`.
2) Engine resolves the assembly document (DB-backed or filesystem).
3) Engine rewrites variable placeholders and signs the script with Ed25519.
4) Engine creates `activity_history` rows and emits `quick_job_run` over Socket.IO.
5) Agent role executes the script (SYSTEM or CURRENTUSER) and returns `quick_job_result`.
6) Engine updates `activity_history` and emits `device_activity_changed`.
### Script variables and environment injection
- Assembly variables are stored with name, type, default, and description.
- Engine builds an environment map and also rewrites `$env:VAR` occurrences.
- Variables are included in the payload so agents can log context.
### Code signing
- Script bytes are signed in `Data/Engine/services/API/assemblies/execution.py`.
- Agents verify signatures using `signature_utils` before execution.
### Activity history
- `activity_history` stores script metadata, timestamps, status, stdout, stderr.
- Use `/api/device/activity/<hostname>` to query or clear entries.
### Backup guidance
- Back up `Data/Engine/Assemblies/` and `Data/Engine/Assemblies/Payloads/` together.
- Also back up `Engine/Assemblies/` if you need runtime snapshots.
### Known limitations
- Ansible quick-run is not implemented in the Engine runtime.
- Linux agent support is incomplete; PowerShell scripts are Windows-first.
### Touch points to remember
- API routes: `Data/Engine/services/API/assemblies/`.
- Assembly runtime: `Data/Engine/services/assemblies/service.py` and `Data/Engine/assembly_management/`.
- UI editors: `Data/Engine/web-interface/src/Assemblies/`.