Documentation
¶
Overview ¶
Package activityhandlers serves the activity log, the alert list, and the SSE event stream with its digest and presence-acknowledgement routes: the HTTP surface over the in-memory registries that record what the server is doing and what went wrong.
It exists because every other data package under internal/server acquired a handlers sibling — coverage has coveragehandlers, config has confighandlers — while activity and events did not, so six handlers over four fields stayed on Server. They were the narrowest cluster on that type: no live state, no store, no metrics, no config, and all four dependencies were already sub-package types. The package's own extraction criterion is that a concern moves out once it can be handed its dependencies rather than reaching for a snapshot, and this one never needed the snapshot at all.
Index ¶
- type Deps
- type Handler
- func (h *Handler) HandleCancelActivity(w http.ResponseWriter, r *http.Request)
- func (h *Handler) HandleDismissActivity(w http.ResponseWriter, r *http.Request)
- func (h *Handler) HandleDismissAlert(w http.ResponseWriter, r *http.Request)
- func (h *Handler) HandleEvents(w http.ResponseWriter, r *http.Request)
- func (h *Handler) HandleEventsAlive(w http.ResponseWriter, r *http.Request)
- func (h *Handler) HandleEventsSync(w http.ResponseWriter, r *http.Request)
- func (h *Handler) HandleGetActivity(w http.ResponseWriter, _ *http.Request)
- func (h *Handler) HandleGetAlerts(w http.ResponseWriter, _ *http.Request)
- type SyncJobCanceller
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Deps ¶
type Deps struct {
// Activity is the running/completed activity log this surface pages over.
Activity *activity.Log
// Alerts is the persistent-alert list the UI banner reads.
Alerts *activity.AlertLog
// Stops is the live stop-callback registry: it supplies the cancellable flag
// on a running entry and receives the explicit stop request.
Stops *activity.StopRegistry
// Events is the SSE hub. The client cap lives on the hub itself, set at
// construction and re-applied by hot reload, so no per-request config read
// happens here.
Events *events.EventBus
// SyncJobs cancels queued sync jobs addressed by activity id (D1). A
// queued DELETE releases the admission slot immediately; one that lost
// the race to admission converts to a running-cancel.
SyncJobs SyncJobCanceller
}
Deps is what this surface needs, and it is the whole of it: three registries and the event hub, each already owned by a sibling package.
Stops is a pointer because Server holds the registry by value and the scan and scheduler packages register into that same one — the registry's zero value is ready to use, so it lives as a field and is shared by address, the way a sync.WaitGroup is.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler serves the activity, alert and event routes.
func (*Handler) HandleCancelActivity ¶
func (h *Handler) HandleCancelActivity(w http.ResponseWriter, r *http.Request)
HandleCancelActivity handles POST /api/activity/{id}/cancel — the explicit graceful stop for running background scans. The scan ends after the item in flight completes (a stop SIGNAL, never a context hard-kill).
Two idioms now address activity entries and must not be confused: DELETE /api/activity?id= (dismiss) removes a completed row or cancels a QUEUED one and never stops running work; this endpoint stops RUNNING work and nothing else.
Authorization is object-level against the entry's required role: per-item scans are cancellable by any configured user (single-household policy), full scans — manual and scheduled both run through the same path — by admins only. Responses: 204 stopped or already stopping (idempotent), 403 role too low, 404 unknown id, 409 not cancellable (completed, queued dismiss-cancelled, or not a stoppable activity). Every attempt is logged.
func (*Handler) HandleDismissActivity ¶
func (h *Handler) HandleDismissActivity(w http.ResponseWriter, r *http.Request)
HandleDismissActivity removes a completed activity or cancels a queued one. DELETE /api/activity?id={id}
A QUEUED sync job routes through the dispatcher BEFORE the legacy scan path: its slot releases immediately (the next 202 enters), and a delete that lost the lock race to admission converts to a running-cancel through the just-registered stop entry — 204 either way, with the job settling done(cancelled) on worker exit. A TERMINAL sync row's dismissal never touches the registry: it falls through to the plain activity dismiss.
func (*Handler) HandleDismissAlert ¶
func (h *Handler) HandleDismissAlert(w http.ResponseWriter, r *http.Request)
HandleDismissAlert handles DELETE /api/alerts?id=N.
func (*Handler) HandleEvents ¶
func (h *Handler) HandleEvents(w http.ResponseWriter, r *http.Request)
HandleEvents serves the SSE stream.
func (*Handler) HandleEventsAlive ¶ added in v0.5.39
func (h *Handler) HandleEventsAlive(w http.ResponseWriter, r *http.Request)
HandleEventsAlive serves POST /api/events/alive: the client's receipt for one keepalive, keyed by the SSE-Client tag it also streams under. A tag outside the hub's grammar is a 400; a tag no stream has presented records nothing, because only the hub's connected event mints a presence row.
func (*Handler) HandleEventsSync ¶ added in v0.5.39
func (h *Handler) HandleEventsSync(w http.ResponseWriter, r *http.Request)
HandleEventsSync serves POST /api/events/sync, the library's state digest over the bus's subject versions, under the route timeout.
func (*Handler) HandleGetActivity ¶
func (h *Handler) HandleGetActivity(w http.ResponseWriter, _ *http.Request)
HandleGetActivity returns the most recent activity entries. Running entries survive the page cap unconditionally — a busy system must never hide a live cancellable scan, because UI restoration depends on seeing it — and each running entry carries the serialization-time cancellable flag merged from the stop registry. Retention is NOT this handler's job: the server's prune ticker is the one owner of PruneCompleted, so a read never mutates the log.
func (*Handler) HandleGetAlerts ¶
func (h *Handler) HandleGetAlerts(w http.ResponseWriter, _ *http.Request)
HandleGetAlerts handles GET /api/alerts. Method dispatch lives in routes.go (GET here, DELETE on HandleDismissAlert) like every other route.
type SyncJobCanceller ¶ added in v0.5.0
type SyncJobCanceller interface {
Cancel(activityID string) syncjobs.CancelOutcome
}
SyncJobCanceller routes an activity-id cancellation into the sync-job dispatcher: the activity-id→dispatcher lookup this surface consults BEFORE the legacy scan path on DELETE. *syncjobs.Dispatcher satisfies it.