Gandalf/sofarr
Public Access
0
0
Fork 0
Code Issues 1 Pull Requests Actions 1 Packages Projects Releases 59 Wiki Activity

FEATURE: Togglable server-side (Docker) log streaming debug endpoint #45

New Issue
Closed
opened 2026-05-24 11:08:07 +01:00 by Gandalf · 3 comments
Gandalf commented 2026-05-24 11:08:07 +01:00
Owner
Copy Link
Copy Source

Title:
FEATURE: Togglable server-side (Docker) log streaming debug endpoint with dual-authentication

Problem / Requirement:
Administrators and developers need a lightweight, real-time method to stream application stdout/stderr logs (which correspond exactly to Docker container logs in standard setups) directly through the API. This enables easier live debugging without requiring full Docker daemon or terminal access.

Success Criteria:

  1. Lightweight Log Streaming: Streams process standard output/error (representing Docker logs) via Server-Sent Events (SSE). Keep a rolling buffer of the last 1000 lines in memory.
  2. Dual-Authentication with Webhook Secret Bypass:
    • Accepts existing session cookie (emby_user) with administrative credentials.
    • Accepts standard HTTP Basic Authentication (Authorization: Basic ) using Emby administrator username/password credentials.
    • Accepts X-Webhook-Secret header matching the SOFARR_WEBHOOK_SECRET environment variable for programmatic bypass.
  3. Runtime Configuration Toggle: Enableable using a runtime environment variable ENABLE_LOG_STREAM=true (defaulting to false/disabled). When disabled, returns a 403 Forbidden response.
  4. API Spec Documentation: Documented in server/openapi.yaml under the /api/debug/logs endpoint, including the query format and response schemas.
Title: FEATURE: Togglable server-side (Docker) log streaming debug endpoint with dual-authentication Problem / Requirement: Administrators and developers need a lightweight, real-time method to stream application stdout/stderr logs (which correspond exactly to Docker container logs in standard setups) directly through the API. This enables easier live debugging without requiring full Docker daemon or terminal access. Success Criteria: 1. Lightweight Log Streaming: Streams process standard output/error (representing Docker logs) via Server-Sent Events (SSE). Keep a rolling buffer of the last 1000 lines in memory. 2. Dual-Authentication with Webhook Secret Bypass: - Accepts existing session cookie (emby_user) with administrative credentials. - Accepts standard HTTP Basic Authentication (Authorization: Basic <base64>) using Emby administrator username/password credentials. - Accepts X-Webhook-Secret header matching the SOFARR_WEBHOOK_SECRET environment variable for programmatic bypass. 3. Runtime Configuration Toggle: Enableable using a runtime environment variable ENABLE_LOG_STREAM=true (defaulting to false/disabled). When disabled, returns a 403 Forbidden response. 4. API Spec Documentation: Documented in server/openapi.yaml under the /api/debug/logs endpoint, including the query format and response schemas.
Gandalf added the Kind/Feature
Priority
Medium
3
 labels 2026-05-24 11:08:07 +01:00
Gandalf commented 2026-05-24 11:12:36 +01:00
Author
Owner
Copy Link
Copy Source

Amended the plan to include a high-priority bypass using the X-Webhook-Secret request header:

  1. Webhook Secret Bypass: If the request contains the X-Webhook-Secret header, we verify if it matches the configured SOFARR_WEBHOOK_SECRET environment variable.
  2. Access Granted: If matching, the request is immediately authorized, completely bypassing session and Emby Basic Auth checks. This is ideal for curl scripts, server-to-server monitoring, or external debugging logs captures.

I have updated the implementation_plan.md artifact to reflect this amendment.

Amended the plan to include a high-priority bypass using the `X-Webhook-Secret` request header: 1. **Webhook Secret Bypass**: If the request contains the `X-Webhook-Secret` header, we verify if it matches the configured `SOFARR_WEBHOOK_SECRET` environment variable. 2. **Access Granted**: If matching, the request is immediately authorized, completely bypassing session and Emby Basic Auth checks. This is ideal for curl scripts, server-to-server monitoring, or external debugging logs captures. I have updated the `implementation_plan.md` artifact to reflect this amendment.
Gandalf commented 2026-05-24 11:19:10 +01:00
Author
Owner
Copy Link
Copy Source

Amended the plan to add client-side console log capturing and streaming options:

Proposed Client Logging Design:

  • Client-Side Capture (Frontend Interception): Hook into standard browser console methods (console.log, console.warn, console.error) at client-side startup.
  • Client-to-Server Transmission:
    • Option A (Recommended): Store captured logs in a local memory queue, and periodically perform a batched POST /api/debug/client-logs (every 2 seconds or when the queue hits 20 items) to minimize network overhead.
    • Option B (WebSocket Channel): Stream logs instantly via persistent WebSockets, which adds structural and connection management complexity.
  • Server Storage & SSE Streaming:
    • Store incoming client logs in a separate rolling 1000-line buffer clientLogBuffer.
    • Expose GET /api/debug/client-logs/stream (under the exact same dual-auth/webhook-secret constraints) to stream client-side logs in real-time via SSE to debugging tools.

The implementation_plan.md artifact has been successfully updated with these options.

Amended the plan to add client-side console log capturing and streaming options: ### Proposed Client Logging Design: - **Client-Side Capture (Frontend Interception)**: Hook into standard browser console methods (`console.log`, `console.warn`, `console.error`) at client-side startup. - **Client-to-Server Transmission**: - **Option A (Recommended)**: Store captured logs in a local memory queue, and periodically perform a batched `POST /api/debug/client-logs` (every 2 seconds or when the queue hits 20 items) to minimize network overhead. - **Option B (WebSocket Channel)**: Stream logs instantly via persistent WebSockets, which adds structural and connection management complexity. - **Server Storage & SSE Streaming**: - Store incoming client logs in a separate rolling 1000-line buffer `clientLogBuffer`. - Expose `GET /api/debug/client-logs/stream` (under the exact same dual-auth/webhook-secret constraints) to stream client-side logs in real-time via SSE to debugging tools. The `implementation_plan.md` artifact has been successfully updated with these options.
Gandalf changed title from FEATURE: Log streaming debug endpoint with dual-authentication and runtime configuration to FEATURE: Togglable server-side (Docker) log streaming debug endpoint 2026-05-24 11:21:12 +01:00
Gandalf commented 2026-05-24 11:31:50 +01:00
Author
Owner
Copy Link
Copy Source

Resolved in commit 3c6791658c.

Resolved in commit 3c6791658c8fb05f15b84cbdba1815eef40823d1.
Gandalf added the Area/Frontend label 2026-05-28 11:58:06 +01:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Area/Docker
Docker image and container packaging
 Area/Download Clients
Download client integrations
 Area/Frontend
Client-side UI and build tooling
 Area/History
History and completed downloads views
 Area/Logging
Log streaming, file handling, and debug infrastructure
 Area/Matching
Matching and correlation logic
 Area/Proxy
Upstream service proxy routes
 Area/SSE
Server-Sent Events and real-time streaming
 Area/Webhooks
Webhook processing and reliability
 Compat/Breaking
Breaking change that won't be backward compatible
 Compat/Non-Breaking
Non-breaking compatibility change
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Low
4
The priority is low
Priority
Medium
3
The priority is medium
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
No labels Area/Frontend Kind/Feature
Priority
Medium
3
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
Gandalf
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Gandalf/sofarr#45