phase 1 foundations: api types, store, crypto, auth
Lands the bottom three layers of Phase 1: P1-08 internal/api: protocol_version + envelope + every WS message shape from spec.md §6.2 (Hello, Heartbeat, Job*, Schedule*, etc). Wire-format tests pin the JSON shape so a rename here breaks tests instead of silently breaking the agent. P1-02 + P1-03 internal/store: SQLite via modernc.org/sqlite, embed.FS + a tiny version table for hand-rolled migrations. 0001_initial.sql covers every table from spec.md §5 plus enrollment_tokens and host_schedule_version. Typed accessors for users / sessions / enrollment / audit. WAL + foreign_keys + busy_timeout on by default. P1-06 internal/crypto: XChaCha20-Poly1305 AEAD wrapper with per-message random nonce. Key file lifecycle (generate + refuse-to-overwrite, load with size validation). Optional additionalData binds ciphertext to the row that owns it. P1-04 internal/auth (partial — passwords + tokens; sessions middleware lands with the HTTP handlers): argon2id following RFC 9106 (64 MiB / t=3 / p=4 / 32B), constant-time verify. HashToken stores SHA-256 of session/agent/enrollment tokens so a stolen DB doesn't hand over credentials. Build floor moves to Go 1.25 (modernc.org/sqlite v1.50+ requires it); CI + Dockerfile + README updated. Markdown lint diagnostics on tasks.md cleared. All packages tested. ~70 new tests pass in <1s. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,213 @@
|
||||
package api
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"time"
|
||||
)
|
||||
|
||||
// HostOS / HostArch are constrained string types. The store stores them
|
||||
// raw, but agent metadata collection should populate them from these
|
||||
// constants so we don't end up with both "linux" and "Linux" rows.
|
||||
type HostOS string
|
||||
|
||||
const (
|
||||
OSLinux HostOS = "linux"
|
||||
OSWindows HostOS = "windows"
|
||||
)
|
||||
|
||||
type HostArch string
|
||||
|
||||
const (
|
||||
ArchAmd64 HostArch = "amd64"
|
||||
ArchArm64 HostArch = "arm64"
|
||||
)
|
||||
|
||||
// HelloPayload is the agent's first message after WS auth. The server
|
||||
// upserts a Host row, marks it online, and (if protocol_version is
|
||||
// acceptable) responds with a config.update + schedule.set burst.
|
||||
type HelloPayload struct {
|
||||
ProtocolVersion int `json:"protocol_version"`
|
||||
AgentVersion string `json:"agent_version"`
|
||||
ResticVersion string `json:"restic_version"`
|
||||
Hostname string `json:"hostname"`
|
||||
OS HostOS `json:"os"`
|
||||
Arch HostArch `json:"arch"`
|
||||
BootTime time.Time `json:"boot_time,omitempty"`
|
||||
}
|
||||
|
||||
// HeartbeatPayload is sent by the agent every 30s. It carries no data
|
||||
// today; presence is the signal. Future fields (load, free disk) can
|
||||
// land here without bumping protocol_version.
|
||||
type HeartbeatPayload struct {
|
||||
SentAt time.Time `json:"sent_at"`
|
||||
}
|
||||
|
||||
// JobKind is the operation an agent is being asked to run, or just ran.
|
||||
type JobKind string
|
||||
|
||||
const (
|
||||
JobBackup JobKind = "backup"
|
||||
JobForget JobKind = "forget"
|
||||
JobPrune JobKind = "prune"
|
||||
JobCheck JobKind = "check"
|
||||
JobUnlock JobKind = "unlock"
|
||||
)
|
||||
|
||||
// JobStatus is the lifecycle state of a job.
|
||||
type JobStatus string
|
||||
|
||||
const (
|
||||
JobQueued JobStatus = "queued"
|
||||
JobRunning JobStatus = "running"
|
||||
JobSucceeded JobStatus = "succeeded"
|
||||
JobFailed JobStatus = "failed"
|
||||
JobCancelled JobStatus = "cancelled"
|
||||
)
|
||||
|
||||
// CommandRunPayload is the server → agent dispatch for a run-now job.
|
||||
type CommandRunPayload struct {
|
||||
JobID string `json:"job_id"`
|
||||
Kind JobKind `json:"kind"`
|
||||
Args []string `json:"args,omitempty"`
|
||||
}
|
||||
|
||||
// CommandCancelPayload is the server → agent cancel signal.
|
||||
type CommandCancelPayload struct {
|
||||
JobID string `json:"job_id"`
|
||||
}
|
||||
|
||||
// CommandResultPayload acks a command.run dispatch (the agent has
|
||||
// accepted the job and persisted it locally) — this is *not* the job
|
||||
// completion. job.finished signals that.
|
||||
type CommandResultPayload struct {
|
||||
JobID string `json:"job_id"`
|
||||
Accepted bool `json:"accepted"`
|
||||
Error string `json:"error,omitempty"`
|
||||
}
|
||||
|
||||
// JobStartedPayload — agent has begun execution.
|
||||
type JobStartedPayload struct {
|
||||
JobID string `json:"job_id"`
|
||||
Kind JobKind `json:"kind"`
|
||||
StartedAt time.Time `json:"started_at"`
|
||||
}
|
||||
|
||||
// JobProgressPayload — agent's periodic status while a job is running.
|
||||
// Field set chosen to match what restic --json emits for `backup`;
|
||||
// other kinds populate the subset that makes sense.
|
||||
type JobProgressPayload struct {
|
||||
JobID string `json:"job_id"`
|
||||
PercentDone float64 `json:"percent_done"`
|
||||
FilesDone int64 `json:"files_done"`
|
||||
TotalFiles int64 `json:"total_files"`
|
||||
BytesDone int64 `json:"bytes_done"`
|
||||
TotalBytes int64 `json:"total_bytes"`
|
||||
ETASeconds int64 `json:"eta_seconds"`
|
||||
ThroughputBps int64 `json:"throughput_bps"`
|
||||
}
|
||||
|
||||
// JobFinishedPayload — agent reports terminal state.
|
||||
type JobFinishedPayload struct {
|
||||
JobID string `json:"job_id"`
|
||||
Status JobStatus `json:"status"`
|
||||
ExitCode int `json:"exit_code"`
|
||||
FinishedAt time.Time `json:"finished_at"`
|
||||
Stats json.RawMessage `json:"stats,omitempty"` // restic summary blob
|
||||
Error string `json:"error,omitempty"`
|
||||
}
|
||||
|
||||
// LogStreamLine is one entry of the live job log.
|
||||
type LogStreamLine struct {
|
||||
JobID string `json:"job_id"`
|
||||
Seq int64 `json:"seq"`
|
||||
TS time.Time `json:"ts"`
|
||||
Stream LogStream `json:"stream"`
|
||||
Payload string `json:"payload"`
|
||||
}
|
||||
|
||||
// LogStream identifies which channel a log line came from.
|
||||
type LogStream string
|
||||
|
||||
const (
|
||||
LogStdout LogStream = "stdout"
|
||||
LogStderr LogStream = "stderr"
|
||||
LogEvent LogStream = "event" // parsed restic --json event
|
||||
)
|
||||
|
||||
// SnapshotsReportPayload — agent dumps its full snapshot list after
|
||||
// each successful backup, so the server can refresh its projection.
|
||||
type SnapshotsReportPayload struct {
|
||||
Snapshots []Snapshot `json:"snapshots"`
|
||||
}
|
||||
|
||||
// Snapshot is the projection mirrored from `restic snapshots --json`.
|
||||
type Snapshot struct {
|
||||
ID string `json:"id"` // restic snapshot ID
|
||||
Time time.Time `json:"time"`
|
||||
Hostname string `json:"hostname"`
|
||||
Paths []string `json:"paths"`
|
||||
Tags []string `json:"tags,omitempty"`
|
||||
SizeBytes int64 `json:"size_bytes,omitempty"`
|
||||
FileCount int64 `json:"file_count,omitempty"`
|
||||
}
|
||||
|
||||
// RepoStatsPayload — agent reports periodic repo health facts derived
|
||||
// from `restic stats` and lock-file inspection.
|
||||
type RepoStatsPayload struct {
|
||||
SizeBytes int64 `json:"size_bytes"`
|
||||
SnapshotCount int `json:"snapshot_count"`
|
||||
DedupRatio float64 `json:"dedup_ratio"`
|
||||
LastCheckAt time.Time `json:"last_check_at,omitempty"`
|
||||
LastCheckStatus string `json:"last_check_status,omitempty"`
|
||||
LockState string `json:"lock_state"` // locked|unlocked
|
||||
}
|
||||
|
||||
// Schedule is the agent-facing view of a Schedule row. (Server-side
|
||||
// CRUD shapes live in the http handlers; this is what gets pushed.)
|
||||
type Schedule struct {
|
||||
ID string `json:"id"`
|
||||
Kind JobKind `json:"kind"`
|
||||
CronExpr string `json:"cron_expr"`
|
||||
Paths []string `json:"paths,omitempty"`
|
||||
Excludes []string `json:"excludes,omitempty"`
|
||||
Tags []string `json:"tags,omitempty"`
|
||||
RetentionPolicy json.RawMessage `json:"retention_policy,omitempty"`
|
||||
Options json.RawMessage `json:"options,omitempty"`
|
||||
PreHook string `json:"pre_hook,omitempty"`
|
||||
PostHook string `json:"post_hook,omitempty"`
|
||||
Enabled bool `json:"enabled"`
|
||||
}
|
||||
|
||||
// ScheduleSetPayload — server pushes the full canonical schedule list
|
||||
// for a host. Agent reconciles its local cron and replies with
|
||||
// ScheduleAckPayload carrying the same Version.
|
||||
type ScheduleSetPayload struct {
|
||||
Version int64 `json:"version"`
|
||||
Schedules []Schedule `json:"schedules"`
|
||||
}
|
||||
|
||||
// ScheduleAckPayload — agent confirms it has applied a given version.
|
||||
type ScheduleAckPayload struct {
|
||||
Version int64 `json:"version"`
|
||||
AppliedAt time.Time `json:"applied_at"`
|
||||
}
|
||||
|
||||
// ConfigUpdatePayload — server pushes per-host config (currently just
|
||||
// repo connection details). Empty fields mean "leave existing alone";
|
||||
// to clear something, send an explicit zero value.
|
||||
type ConfigUpdatePayload struct {
|
||||
RepoURL string `json:"repo_url,omitempty"`
|
||||
RepoPassword string `json:"repo_password,omitempty"` // sensitive
|
||||
RepoUsername string `json:"repo_username,omitempty"`
|
||||
RepoCredential string `json:"repo_credential,omitempty"` // sensitive (for rest server basic auth)
|
||||
HookShell string `json:"hook_shell,omitempty"`
|
||||
}
|
||||
|
||||
// AgentUpdateAvailablePayload — informational only; the agent does
|
||||
// NOT self-update. See spec.md §4.2 for the package-manager-based
|
||||
// update model.
|
||||
type AgentUpdateAvailablePayload struct {
|
||||
LatestVersion string `json:"latest_version"`
|
||||
PackageURL string `json:"package_url"` // apt repo / choco source
|
||||
Changelog string `json:"changelog,omitempty"`
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
package api
|
||||
|
||||
// CurrentProtocolVersion is the wire-format version this build speaks.
|
||||
//
|
||||
// Bump this only when an incompatible wire-format change lands —
|
||||
// adding a new optional field does NOT count, removing or repurposing
|
||||
// one does. The server enforces MinAgentProtocolVersion against this
|
||||
// value at hello time. See spec.md §6.2 ("Protocol versioning").
|
||||
const CurrentProtocolVersion = 1
|
||||
|
||||
// MinAgentProtocolVersion is the lowest agent protocol_version this
|
||||
// server accepts in a hello. Agents below this are disconnected with
|
||||
// a structured error pointing at the upgrade docs.
|
||||
const MinAgentProtocolVersion = 1
|
||||
@@ -0,0 +1,86 @@
|
||||
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"
|
||||
MsgCommandResult MessageType = "command.result" // ack for command.run
|
||||
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"
|
||||
)
|
||||
|
||||
// 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
|
||||
|
||||
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"`
|
||||
}
|
||||
@@ -0,0 +1,143 @@
|
||||
package api
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
func TestEnvelopeRoundTrip(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
hello := HelloPayload{
|
||||
ProtocolVersion: CurrentProtocolVersion,
|
||||
AgentVersion: "0.1.0",
|
||||
ResticVersion: "0.17.1",
|
||||
Hostname: "test-host",
|
||||
OS: OSLinux,
|
||||
Arch: ArchAmd64,
|
||||
}
|
||||
|
||||
env, err := Marshal(MsgHello, "", hello)
|
||||
if err != nil {
|
||||
t.Fatalf("marshal: %v", err)
|
||||
}
|
||||
|
||||
wire, err := json.Marshal(env)
|
||||
if err != nil {
|
||||
t.Fatalf("marshal envelope: %v", err)
|
||||
}
|
||||
|
||||
var decoded Envelope
|
||||
if err := json.Unmarshal(wire, &decoded); err != nil {
|
||||
t.Fatalf("unmarshal envelope: %v", err)
|
||||
}
|
||||
if decoded.Type != MsgHello {
|
||||
t.Errorf("type: got %q want %q", decoded.Type, MsgHello)
|
||||
}
|
||||
|
||||
var got HelloPayload
|
||||
if err := decoded.UnmarshalPayload(&got); err != nil {
|
||||
t.Fatalf("unmarshal payload: %v", err)
|
||||
}
|
||||
if got != hello {
|
||||
t.Errorf("round-trip mismatch: %+v != %+v", got, hello)
|
||||
}
|
||||
}
|
||||
|
||||
func TestEnvelopeNilPayload(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
env, err := Marshal(MsgHeartbeat, "", nil)
|
||||
if err != nil {
|
||||
t.Fatalf("marshal: %v", err)
|
||||
}
|
||||
if len(env.Payload) != 0 {
|
||||
t.Errorf("nil payload should encode as empty, got %q", env.Payload)
|
||||
}
|
||||
// Unmarshalling nothing into anything must not error.
|
||||
var hb HeartbeatPayload
|
||||
if err := env.UnmarshalPayload(&hb); err != nil {
|
||||
t.Errorf("unmarshal empty payload: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestEnvelopeRPCCorrelation(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
cmd := CommandRunPayload{JobID: "01HJ8K7", Kind: JobBackup}
|
||||
env, err := Marshal(MsgCommandRun, "req-1", cmd)
|
||||
if err != nil {
|
||||
t.Fatalf("marshal: %v", err)
|
||||
}
|
||||
if env.ID != "req-1" {
|
||||
t.Errorf("id not preserved: %q", env.ID)
|
||||
}
|
||||
|
||||
res := CommandResultPayload{JobID: "01HJ8K7", Accepted: true}
|
||||
resEnv, err := Marshal(MsgCommandResult, env.ID, res)
|
||||
if err != nil {
|
||||
t.Fatalf("marshal result: %v", err)
|
||||
}
|
||||
if resEnv.ID != env.ID {
|
||||
t.Errorf("rpc id mismatch: req=%q res=%q", env.ID, resEnv.ID)
|
||||
}
|
||||
}
|
||||
|
||||
func TestErrorPayload(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
ep := ErrorPayload{
|
||||
Code: ErrProtocolTooOld,
|
||||
Message: "agent protocol_version 0 below minimum 1",
|
||||
HelpURL: "https://example.com/upgrade",
|
||||
}
|
||||
env, err := Marshal(MsgError, "", ep)
|
||||
if err != nil {
|
||||
t.Fatalf("marshal: %v", err)
|
||||
}
|
||||
wire, _ := json.Marshal(env)
|
||||
|
||||
var decoded Envelope
|
||||
if err := json.Unmarshal(wire, &decoded); err != nil {
|
||||
t.Fatalf("unmarshal: %v", err)
|
||||
}
|
||||
var got ErrorPayload
|
||||
if err := decoded.UnmarshalPayload(&got); err != nil {
|
||||
t.Fatalf("unmarshal payload: %v", err)
|
||||
}
|
||||
if got.Code != ErrProtocolTooOld {
|
||||
t.Errorf("code: got %q want %q", got.Code, ErrProtocolTooOld)
|
||||
}
|
||||
}
|
||||
|
||||
func TestProtocolVersionConstants(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
if CurrentProtocolVersion < 1 {
|
||||
t.Errorf("CurrentProtocolVersion must be >= 1, got %d", CurrentProtocolVersion)
|
||||
}
|
||||
if MinAgentProtocolVersion > CurrentProtocolVersion {
|
||||
t.Errorf("min %d > current %d — server would refuse all agents",
|
||||
MinAgentProtocolVersion, CurrentProtocolVersion)
|
||||
}
|
||||
}
|
||||
|
||||
func TestJobProgressShapeStable(t *testing.T) {
|
||||
t.Parallel()
|
||||
// Locks the JSON field names from spec.md §6.2 so a rename here
|
||||
// breaks tests instead of silently breaking the agent.
|
||||
p := JobProgressPayload{
|
||||
JobID: "j", PercentDone: 0.5, FilesDone: 1, TotalFiles: 2,
|
||||
BytesDone: 100, TotalBytes: 200, ETASeconds: 30, ThroughputBps: 1000,
|
||||
}
|
||||
raw, _ := json.Marshal(p)
|
||||
want := `{"job_id":"j","percent_done":0.5,"files_done":1,"total_files":2,"bytes_done":100,"total_bytes":200,"eta_seconds":30,"throughput_bps":1000}`
|
||||
if string(raw) != want {
|
||||
t.Errorf("wire shape drifted:\n got %s\n want %s", raw, want)
|
||||
}
|
||||
}
|
||||
|
||||
// touch time so the import is used by other tests in this file when
|
||||
// they grow over time.
|
||||
var _ = time.Now
|
||||
Reference in New Issue
Block a user