steve
6d295bc9f6
Foundational for the restore wizard's tree browser. The wizard needs to lazy-load directory contents from a snapshot as the operator drills down; this lands the transport. - internal/api adds MsgTreeList (server → agent) + MsgTreeListResult (agent → server) with TreeListRequestPayload / TreeListEntry / TreeListResultPayload types. Reply correlates by Envelope.ID. - internal/restic.ListTreeChildren wraps 'restic ls --json' and filters its recursive output to direct children of the requested path. Parser + path-normalisation + isDirectChild are unit-tested. - internal/server/ws/rpc.go introduces a generic SendRPC helper on Hub: register a buffered channel keyed by ULID, send the request, block on ctx.Done()/timeout/reply. Reply routing piggybacks on the existing dispatchAgentMessage by adding a MsgTreeListResult case that forwards to the registered waiter; if no waiter is registered (caller already gave up) the stray reply is dropped quietly. - cmd/agent gains a tree.list handler that runs ListTreeChildren on a fresh per-call context (60s ceiling) and ships the matching tree.list.result envelope. Errors surface in result.Error rather than as transport failures so the server-side waiter can render a sensible UI message. - internal/server/http/tree_cache.go is the per-wizard-session cache layer (~30min TTL, sweep-on-access) that fetchTreeWithCache uses before falling through to SendRPC. Cached on success only; agent errors aren't cached so a transient failure doesn't poison the session. Tests: - internal/restic/ls_test.go covers parseLsChildren at root / mid-tree / leaf, plus normalizeTreePath and isDirectChild edge cases. - internal/server/ws/rpc_test.go unit-tests the registry: round-trip, release semantics, concurrent waiters, ctx-cancel. - internal/server/http/tree_rpc_test.go is the full round-trip: server SendRPC → fake-agent over a real WS → reply → server gets the payload. Plus a timeout test that confirms ~300ms timeouts terminate in ~300ms rather than waiting forever. The cache is plumbed but no UI handler hits fetchTreeWithCache yet — that lands with P3-01 (wizard backend). The unused-linter is suppressed via nolint until the wizard wires it in.
92 lines
3.1 KiB
Go
92 lines
3.1 KiB
Go
package api
|
|
|
|
import (
|
|
"encoding/json"
|
|
"fmt"
|
|
)
|
|
|
|
// MessageType enumerates every kind of envelope that can flow over
|
|
// the agent ↔ server WebSocket. Keeping these as string constants
|
|
// (not iota ints) makes traffic readable in logs and packet captures.
|
|
type MessageType string
|
|
|
|
// Agent → server message types.
|
|
const (
|
|
MsgHello MessageType = "hello"
|
|
MsgHeartbeat MessageType = "heartbeat"
|
|
MsgJobStarted MessageType = "job.started"
|
|
MsgJobProgress MessageType = "job.progress"
|
|
MsgJobFinished MessageType = "job.finished"
|
|
MsgSnapshotsRpt MessageType = "snapshots.report"
|
|
MsgRepoStats MessageType = "repo.stats"
|
|
MsgLogStream MessageType = "log.stream"
|
|
MsgScheduleAck MessageType = "schedule.ack"
|
|
MsgScheduleFire MessageType = "schedule.fire" // agent: a local cron entry fired, please dispatch a job
|
|
MsgCommandResult MessageType = "command.result" // ack for command.run
|
|
MsgTreeListResult MessageType = "tree.list.result" // reply to a server-driven tree.list
|
|
MsgError MessageType = "error"
|
|
)
|
|
|
|
// Server → agent message types.
|
|
const (
|
|
MsgCommandRun MessageType = "command.run"
|
|
MsgCommandCancel MessageType = "command.cancel"
|
|
MsgScheduleSet MessageType = "schedule.set"
|
|
MsgConfigUpdate MessageType = "config.update"
|
|
MsgAgentUpdateAvail MessageType = "agent.update.available"
|
|
MsgTreeList MessageType = "tree.list" // sync RPC: list a snapshot's children
|
|
)
|
|
|
|
// Envelope is the framing for every WS message in either direction.
|
|
// Payload is parsed into the concrete struct chosen by Type.
|
|
//
|
|
// ID is set on RPC-style messages (command.run / command.result) so
|
|
// responses can be correlated. For one-shot pushes (heartbeat,
|
|
// job.progress) it is empty.
|
|
type Envelope struct {
|
|
Type MessageType `json:"type"`
|
|
ID string `json:"id,omitempty"`
|
|
Payload json.RawMessage `json:"payload,omitempty"`
|
|
}
|
|
|
|
// Marshal builds an envelope from a concrete payload struct.
|
|
func Marshal(t MessageType, id string, payload any) (Envelope, error) {
|
|
if payload == nil {
|
|
return Envelope{Type: t, ID: id}, nil
|
|
}
|
|
raw, err := json.Marshal(payload)
|
|
if err != nil {
|
|
return Envelope{}, fmt.Errorf("marshal %s payload: %w", t, err)
|
|
}
|
|
return Envelope{Type: t, ID: id, Payload: raw}, nil
|
|
}
|
|
|
|
// UnmarshalPayload decodes the envelope's payload into v.
|
|
func (e Envelope) UnmarshalPayload(v any) error {
|
|
if len(e.Payload) == 0 {
|
|
return nil
|
|
}
|
|
return json.Unmarshal(e.Payload, v)
|
|
}
|
|
|
|
// ErrorCode enumerates error reasons surfaced over the wire.
|
|
// These are stable identifiers; client code may switch on them.
|
|
type ErrorCode string
|
|
|
|
// Stable ErrorCode values surfaced over the wire. Clients switch on
|
|
// these; renaming requires a wire-version bump.
|
|
const (
|
|
ErrProtocolTooOld ErrorCode = "protocol_too_old"
|
|
ErrProtocolTooNew ErrorCode = "protocol_too_new"
|
|
ErrUnauthorized ErrorCode = "unauthorized"
|
|
ErrBadRequest ErrorCode = "bad_request"
|
|
ErrInternal ErrorCode = "internal"
|
|
)
|
|
|
|
// ErrorPayload is the body of an `error` envelope.
|
|
type ErrorPayload struct {
|
|
Code ErrorCode `json:"code"`
|
|
Message string `json:"message"`
|
|
HelpURL string `json:"help_url,omitempty"`
|
|
}
|