Documentation
¶
Overview ¶
Package peers serves the one versioned peers read model peer-connectivity#req:peers-api requires, mounted identically in three places: the local daemon API (`GET /api/v1/peers`), the hub dashboard reads (`GET /v0/workbench/peers`), and — later, behind admin-requires-owner-credential — the admin write routes. This package owns only the reads; Task 1's CLI writes go through the owner RPC instead.
Index ¶
Constants ¶
const SchemaVersion = 1
SchemaVersion is the one version every response names, so a consumer can tell the shape it is decoding.
Variables ¶
This section is empty.
Functions ¶
func NewHandler ¶
NewHandler serves prefix (list) and prefix+"/{id}" (detail) as GET-only JSON routes. prefix is exactly what the mount point is (no trailing slash), so the same handler factory produces byte-identical JSON at /api/v1/peers and at /v0/workbench/peers. authorize may be nil, which disables the check (no current production caller does this).
Types ¶
type Authorize ¶
Authorize is the viewer check NewHandler runs before ListPeers/GetPeer, so this read route carries the same discipline as every sibling dashboard read route instead of being the one exception. A nil error admits the request; every current caller wires one equivalent to the always-true loopback-operator viewer the sibling read APIs already use, so nothing behaves differently today — the hook exists so a future non-trivial viewer (a hosted deployment, or Task 7's admin session) has a real gate to plug into rather than this route staying structurally ungated.
type Counters ¶
type Counters struct {
RXPayloadBytes uint64 `json:"rx_payload_bytes"`
TXPayloadBytes uint64 `json:"tx_payload_bytes"`
RXMessages uint64 `json:"rx_messages"`
TXMessages uint64 `json:"tx_messages"`
RXEvents uint64 `json:"rx_events"`
TXEvents uint64 `json:"tx_events"`
}
Counters is the traffic-and-event-counters shape, all zero until Task 6.
type Detail ¶
type Detail struct {
Record
Session *Session `json:"session"`
Counters Counters `json:"counters"`
AdminAvailable bool `json:"admin_available"`
}
Detail is the full `GET .../{id}` response: the record, the current session (nil for now), the counters (empty for now), and whether an admin session (Task 7) can act on this peer from wherever this response is read.
type ListResponse ¶
type ListResponse struct {
SchemaVersion int `json:"schema_version"`
Peers []Record `json:"peers"`
}
ListResponse is the `GET .../peers` shape.
type Record ¶
type Record struct {
SchemaVersion int `json:"schema_version"`
ID string `json:"id"`
Name string `json:"name"`
Role string `json:"role"`
Status string `json:"status"`
NodeID string `json:"node_id,omitempty"`
CreatedAt time.Time `json:"created_at"`
LastSeenAt *time.Time `json:"last_seen_at,omitempty"`
LastConnectedAt *time.Time `json:"last_connected_at,omitempty"`
ResetPending bool `json:"reset_pending,omitempty"`
// Lag is the peer's queued-work count (pieces of sync work, after
// coalescing, not yet acknowledged) — `wb peers list`'s LAG column. nil
// until Task 3/4 start writing it (no queue-state document exists yet,
// or this peer has never had one), rendered as "-"; ResetPending takes
// priority over it in the rendered CLI table, since a pending reset
// makes the count stale.
Lag *int64 `json:"lag,omitempty"`
WBVersion string `json:"wb_version,omitempty"`
OS string `json:"os,omitempty"`
Arch string `json:"arch,omitempty"`
Protocol int `json:"protocol,omitempty"`
}
Record is one peer as every mount reports it: the trust record, its derived status, and nothing that Task 2 or later tasks have not filled in yet. Node IDs are shown truncated to 8 characters; they are not secret.
type Session ¶
type Session struct {
ConnectedAt time.Time `json:"connected_at"`
LastHeartbeat time.Time `json:"last_heartbeat"`
RemoteAddress string `json:"remote_address,omitempty"`
Protocol int `json:"protocol,omitempty"`
}
Session is the live session a peer detail response carries. It is always nil until Task 2 adds sessions.
type Source ¶
type Source interface {
ListPeers(context.Context) ([]Record, error)
GetPeer(ctx context.Context, idOrName string) (Detail, bool, error)
}
Source is what NewHandler needs from its host. The hub side and (in a later task) the laptop's upstream side each implement it, so the same handler serves identical JSON everywhere it is mounted.
Source Files