docs: sync README + AGENTS + config.example with supervisor + current config schema#1
Draft
Sbussiso wants to merge 1 commit into
Draft
docs: sync README + AGENTS + config.example with supervisor + current config schema#1Sbussiso wants to merge 1 commit into
Sbussiso wants to merge 1 commit into
Conversation
… config schema
Three pieces of drift:
- AGENTS.md "Outbound API surface" table listed `X-API-Key` for
`/api/nodes/register` and `/api/nodes/heartbeat`. Code has always sent
`X-Node-API-Key` on every outbound call (src/api/client.rs). Fixed
the table and noted that heartbeats now carry per-camera
`CameraStatus { camera_id, status, last_error }` with real pipeline
state.
- The new FFmpeg supervisor (streaming/supervisor.rs) wasn't reflected
anywhere in the docs. Added it to the project structure in both
README and AGENTS, and documented its behaviour (2s poll, 1s→30s
exponential backoff, 5-crashes-in-60s trips to `Failed`) plus the
fact that every heartbeat now reports real pipeline state instead of
the old hardcoded "streaming".
- config.example.yaml was missing `streaming.encoder`, the entire
`streaming.hls:` subsection (enabled / segment_duration /
playlist_size / bitrate), and the entire `motion:` section (enabled /
threshold 0.02 / cooldown_secs). All three are real, required-shaped
config structs in src/config/settings.rs.
No code changes.
Sbussiso
added a commit
that referenced
this pull request
Apr 27, 2026
🔴 #1 from yesterday's code review. Previously: if init_file_logging failed (ACL denial on %ProgramData%\OpenSentry\logs\, disk full, etc), service_main would call tracing::error! + eprintln! and return. Both targets are unobservable in a service context — tracing wasn't initialised yet, eprintln has no console — so the service silently exited with services.msc reporting "started and immediately stopped" and nothing in any log to explain why. Adds write_fatal_startup_error which: 1. Tries %ProgramData%\OpenSentry\fatal-startup-error.txt first (the canonical place; any operator looking at the data dir will find it). 2. Falls back to %TEMP%\opensentry-cloudnode-fatal-startup-error.txt if step 1 fails (which is exactly when init_file_logging would have failed too — same dir). 3. Best-effort, append-only — chronological audit trail across multiple failed starts; failure to write either location is swallowed silently because at that point we're out of reporting options. Synchronous std::fs write — no tracing dependency, no Tokio runtime, no third-party crates. Works even if everything else in the service initialisation is wedged. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documentation drift audit — code is the source of truth; docs brought back into line.
X-API-Keyfor/api/nodes/registerand/api/nodes/heartbeat. All six outbound call sites insrc/api/client.rshave always usedX-Node-API-Key. Fixed, and noted that heartbeats now carry per-cameraCameraStatus { camera_id, status, last_error }.src/streaming/supervisor.rs(2s poll, 1s→30s exponential backoff, trips toFailedafter 5 crashes in 60s, reports real pipeline state into the Dashboard) wasn't reflected in either README or AGENTS. Added to project structure and architecture in both, and noted that heartbeats now report real pipeline state (starting/streaming/restarting/failed/error) instead of the legacy hardcoded"streaming".streaming.encoder, the entirestreaming.hls:subsection, and the entiremotion:section — all of which are real config structs insrc/config/settings.rswith defaults that matter (notablymotion.threshold: 0.02,hls.segment_duration: 1,hls.playlist_size: 15).No code changes — docs only.
Test plan
src/api/client.rs,src/streaming/supervisor.rs,src/config/settings.rsto confirm parityconfig.example.yamlparses cleanly intoConfig(should be a no-op — every field matches a serde-named struct field)