reanimator/bee
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
main
bee/bible-local/architecture/api-surface.md
Michael Chus 7d2e904d14 Bring codebase into compliance with bible contracts (A–E) 
A (hardware-ingest-json v2.8-2.9): remove sensor location fields from schema
and collector; tag HardwareMemory.Location as json:"-"; add PlatformConfig to
HardwareSnapshot.

B (no-hardcoded-vendors): consolidate PCI vendor IDs into collector/pci_vendors.go;
replace all vendor-name string checks in isGPUDevice, isNVIDIADevice, isMellanoxDevice,
isAMDGPUDevice, matchesGPUVendor (sat_overlay), and validateIsVendorGPU (page_validate)
with numeric vendor_id comparisons.

C (module-structure): split app/app.go (1413 lines) into app.go + app_format.go,
app_network.go, app_services.go, app_packs.go, app_install.go — no logic changes.

D (go-code-style): wrap bare return err in interfaceAdminState and
interfaceIPv4Addrs (platform/network.go) with fmt.Errorf context including
the interface name.

E (go-project-bible): add bible-local/architecture/data-model.md and
bible-local/architecture/api-surface.md.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-13 14:32:08 +03:00

10 KiB
Raw Permalink Blame History

API Surface

HTTP endpoints exposed by bee web (binds 0.0.0.0:80). Handler registration: audit/internal/webui/server.go → NewHandler().

Health & readiness

Method Path Description
GET /healthz Always 200. Used by load balancers / boot scripts.
GET /api/ready 200 when audit JSON exists and is readable.
GET /loading HTML loading page shown before first audit.

Audit

Method Path Description
GET /audit.json Latest audit JSON with SAT overlay applied.
GET /runtime-health.json Latest runtime preflight JSON.
POST /api/audit/run Enqueue a full bee audit run. Returns task ID.
GET /api/audit/stream SSE: audit run log lines (data: + newline per line).
GET /api/preflight Run runtime preflight check (synchronous, returns JSON).
GET /api/hardware-summary Hardware health summary (status counts + failures).
GET /api/components/{type} HTML fragment for component detail dialog (e.g. cpu, memory, storage, pcie).

SAT (System Acceptance Testing)

All SAT run endpoints enqueue an async task. Response: {"task_id": "..."}.

Method Path Description
POST /api/sat/nvidia/run NVIDIA DCGM SAT
POST /api/sat/nvidia-targeted-stress/run NVIDIA targeted stress validate
POST /api/sat/nvidia-compute/run NVIDIA max compute load
POST /api/sat/nvidia-targeted-power/run NVIDIA targeted power
POST /api/sat/nvidia-pulse/run NVIDIA pulse test
POST /api/sat/nvidia-interconnect/run NCCL all_reduce_perf
POST /api/sat/nvidia-bandwidth/run NVBandwidth test
POST /api/sat/nvidia-stress/run NVIDIA stress pack
POST /api/sat/memory/run Memory acceptance
POST /api/sat/storage/run Storage acceptance (smartctl)
POST /api/sat/cpu/run CPU acceptance (stress-ng)
POST /api/sat/amd/run AMD GPU SAT (ROCm)
POST /api/sat/amd-mem/run AMD memory integrity + bandwidth
POST /api/sat/amd-bandwidth/run AMD memory bandwidth
POST /api/sat/amd-stress/run AMD GPU stress
POST /api/sat/memory-stress/run Memory stress
POST /api/sat/sat-stress/run Combined storage+memory stress
POST /api/sat/platform-stress/run Fan + thermal stress
GET /api/sat/stream SSE: live SAT log stream
POST /api/sat/abort Abort the running SAT task

Benchmarks

Method Path Description
POST /api/bee-bench/nvidia/perf/run NVIDIA performance benchmark
POST /api/bee-bench/nvidia/power/run NVIDIA power benchmark
POST /api/bee-bench/nvidia/autotune/run Power source autotune (prerequisite for benchmarks)
GET /api/bee-bench/nvidia/autotune/status Current autotune result / status
GET /api/benchmark/results List completed benchmark result archives

Tasks (async job queue)

Method Path Description
GET /api/tasks List all tasks with status
POST /api/tasks/cancel-all Cancel all pending/running tasks
POST /api/tasks/kill-workers Force-kill worker goroutines
POST /api/tasks/{id}/cancel Cancel a specific task
POST /api/tasks/{id}/priority Elevate task priority
GET /api/tasks/{id}/stream SSE: live log stream for a task
GET /api/tasks/{id}/charts List chart names for a task
GET /api/tasks/{id}/chart/ SVG chart for a task result
GET /tasks/{id} HTML task detail page

Services

Method Path Description
GET /api/services List bee-* systemd services and their states
POST /api/services/action start/stop/restart a service

Network

Method Path Description
GET /api/network List interfaces with state and IPv4 addresses
POST /api/network/dhcp Run dhclient on one or all interfaces
POST /api/network/static Set static IPv4 address
POST /api/network/toggle Bring interface up or down
POST /api/network/confirm Confirm pending network change (clears rollback)
POST /api/network/rollback Restore pre-change network snapshot

Export

Method Path Description
GET /export/support.tar.gz Download support bundle (live-generated)
GET /export/file Download a file from the export dir by path param
GET /export/ Browse export dir (HTML index)
GET /api/export/list JSON list of files in export dir
GET /api/export/usb List removable USB targets available for export

GPU

Method Path Description
GET /api/gpu/presence {"nvidia": bool, "amd": bool}
GET /api/gpu/nvidia List NVIDIA GPUs from nvidia-smi
GET /api/gpu/nvidia-status Per-GPU status (ECC, power, throttle)
POST /api/gpu/nvidia-reset GPU reset by index
GET /api/gpu/tools nvidia-smi / rocm-smi tool availability

System

Method Path Description
GET /api/system/ram-status toram boot state and ISO copy status
POST /api/system/install-to-ram Copy ISO to RAM (background task)
GET /api/install/disks List block devices suitable for disk installation
POST /api/install/run Install bee to disk (background task)

Tools & NVMe

Method Path Description
GET /api/tools/check Check availability of required CLI tools
GET /api/tools/nvme-formats List NVMe format options for a device
POST /api/tools/nvme-format/run Run nvme-format on a device

Live metrics

Method Path Description
GET /api/metrics/stream SSE: live metrics (GPU power, temp, utilization)
GET /api/metrics/latest Latest metrics snapshot (JSON)
GET /api/metrics/chart/ SVG chart for a metric over time
GET /api/metrics/export.csv Download metrics history as CSV

Blackbox logging

Method Path Description
GET /api/blackbox/status Blackbox log state (enabled, size, path)
POST /api/blackbox/enable Start recording blackbox log
POST /api/blackbox/disable Stop recording, flush to disk

UI pages

Method Path Description
GET / Main dashboard (serves all page routes)
GET /viewer Standalone JSON viewer for uploaded audit files

All pages are rendered server-side as HTML. The / route handles sub-paths such as /network, /services, /sat, /benchmark, /install, /validate, /export.

Reference in New Issue View Git Blame Copy Permalink