System Activity

[elusiveshiba]

Dogebox system activity

Implementations

Frontend - Dogebox-WG/dpanel#156
Backend - Dogebox-WG/dogeboxd#152

Problem

Some critical jobs running on Dogebox can be 'lost' through a page refresh or otherwise. It can be unclear to a user that something important is in progress.

Solution

Display system jobs and other activity that's occurring in the background.

What should be included

The scope of this activity section is anything that triggers a nix rebuild, displayed in its contextual task format. For example:

• System upgrades
• Pup tasks - install, rebuild, uninstall etc.
• SSH enabling/disabling
• Backup operations (when feature is implemented)

Features

Role

This feature is a presenter for jobs that are already managed by the existing backend. It has no responsibility for job queue management or controlling what can run when.

Job Indicator (Navigation)

• Lightweight component in navigation footer
• Shows count of active (in-progress) jobs
• Spinning gear icon when jobs are active
• Clicking navigates to activity page

Activity Page

• Organised into sections: Active Jobs, Pending Jobs, Recently Completed Jobs
• Search and filter capabilities (status, date)
• "Show more" pagination for each section
• Expandable job cards showing logs and error details

Mockups

Lightweight component in nav bar:

Activity page:

APIs

Endpoints

• GET /jobs - Get all jobs
• GET /jobs/active - Get active jobs (queued or in progress)
• GET /jobs/recent - Get recent completed/failed jobs
• GET /jobs/{jobID} - Get a specific job
• GET /jobs/stats - Get job statistics
• POST /jobs/clear-completed - Clear completed jobs older than X days
• POST /jobs/clear-all - Clear all jobs (development/cleanup)

WebSocket

• /ws/jobs - Real-time job updates
  • Bootstrap: Sends all jobs on connection
  • Events: job:created, job:updated, job:completed, job:failed, job:cancelled
• /ws/log/job/{JobID} - Stream logs for a specific job
• /ws/log/pup/{PupID} - Update the pup log stream web socket location so it's clearly differentiated from job logs

Job object

Property	Type	Description
id	String	Unique identifier
started	String	ISO timestamp when job was started
finished	String	ISO timestamp when job was finished (null if not finished)
displayName	String	Job name
progress	Number	Progress percentage 0-100
status	String (enum)	Current status: queued, in_progress, completed, failed, or cancelled
summaryMessage	String	One line that explains the current high level task at hand
errorMessage	String	Error details if status is failed
logs	Array	Array of log entries
pupID	String	Associated pup if applicable (optional)

Flow

sequenceDiagram
  participant DP as dpanel client
  participant DBX as dogeboxd server
  participant JM as JobManager
  participant WS as WebSocket
  participant DB as SQLite

  Note over DP,DBX: user initiates SSH enable
  DP->>DBX: EnableSSH request
  
  Note over DBX,JM: job creation
  DBX->>JM: Create job for SSH enable
  JM->>JM: assign unique jobId
  JM->>DB: persist job to storage
  JM->>WS: Emit job:created event
  WS-->>DP: notify new job via websocket
  
  Note over DBX,DB: perform SSH configuration
  DBX->>JM: Update job progress
  JM->>JM: update job record
  JM->>DB: persist job update
  JM->>WS: Emit job:updated event
  WS-->>DP: notify status changed via websocket
  
  DBX->>DBX: update nixos configuration enable SSH
  DBX->>DBX: trigger rebuild
  
  alt rebuild success
    DBX-->>DBX: rebuild success
    DBX->>JM: Complete job (success)
    JM->>JM: update job status to completed
    JM->>DB: persist job completion
    JM->>WS: Emit job:completed event
    WS-->>DP: notify completion via websocket
  else rebuild error
    DBX-->>DBX: rebuild failed with error
    DBX->>JM: Complete job (failed)
    JM->>JM: update job status to failed with error message
    JM->>DB: persist job failure
    JM->>WS: Emit job:failed event
    WS-->>DP: notify failure via websocket
  end

Loading

Down the track

• Pups could expose their jobs to this system, and query it to see what other activities are happening
• Job type flag to distinguish between system jobs and pup jobs if needed

[elusiveshiba]

Chatting through with @SomeoneWeird and @patowens the consensus was to adjust as follows:

• Remove the concept of 'critical' jobs, a flag to distinguish between things like system jobs and pup jobs may be useful later but not needed now.
• The scope of this new activity section for now will be anything that triggers a nix rebuild, but displayed as its contextual task for eg. 'pup installing', 'ssh enabling' etc.
• This new feature will have no say in job queue management or what can run when, it's a presenter for jobs that are already managed by the existing backend.
• Required endpoints remain unchanged, need to 'Create job', 'Update job', 'Get job' and 'Get jobs'.
• Logs are also to be managed by the existing log manager - currently logs for a specific pupID can be retrieved through "/ws/log/{PupID}" but this should be expanded to have both /ws/log/pup/{PupID} and /ws/log/job/{JobID}
• The job object can therefore be simplified as follows:

Property	Type	Description
id	Number	Unique identifier
started	Datetime	Timestamp when job was started
finished	Datetime	Timestamp when job was finished
displayName	String	Job name
progress	Number	Progress percentage 0-100
status	String (enum)	Current status queued, in progress, completed, or failed
summaryMessage	String	One line that explains the current high level task at hand
errorMessage	String	Error details if status is failed

[elusiveshiba]

Removing the notifications side of this, can be implemented later as part of a larger notification system.
I've also updated above Features and APIs sections to be aligned with the current implementation.

FYI @SomeoneWeird @patowens

[elusiveshiba]

Frontend - Dogebox-WG/dpanel#156
Backend - Dogebox-WG/dogeboxd#152