crossbar/docs/plans/v2/03-wake.md

v2 task 03: wake-on-LAN

Branch: v2 (run git switch v2; git status --short must be empty, otherwise stop) Commit subject: Add the wake package: magic packets and a waiter

Goal

A pure package. wake.MagicPacket builds the 102-byte wake-on-LAN frame, wake.Send puts it on the wire as UDP, and wake.Waker wakes a named host at most once per wait window and waits for the health table to report it healthy. Task 05 uses it when a route has no healthy host.

Context

A magic packet is six 0xff bytes followed by the target MAC sixteen times, sent as a UDP datagram to the LAN broadcast address (port 9 by convention). The sleeping Mac (titan) has wake-on-magic-packet enabled; it takes 20–40 s to be reachable. Waking twice inside that window is harmless but pointless, so the waker remembers when it last sent.

Files

• Copy: internal/wake/wake_test.go
• Create: internal/wake/wake.go
• Modify: docs/implementer-log.md

Interfaces

package wake

type Target struct {
    MAC, Broadcast string   // "aa:bb:cc:dd:ee:ff" (also "-" separated, any case); "host:port"
    Wait           time.Duration
}
type Health interface{ Healthy(name string) bool }

func MagicPacket(mac string) ([]byte, error)     // net.ParseMAC; must be 6 bytes; 102-byte frame
func Send(mac, broadcast string) error           // one UDP datagram via net.DialUDP("udp4", …); errors from parse/resolve/write
type Waker struct { /* private: targets, health, mutex, last-sent per host, poll interval (default 1s) */ }
func New(targets map[string]Target, h Health) *Waker
func (w *Waker) PollEvery(d time.Duration)       // test hook; production keeps the 1 s default
// Wake returns true as soon as h.Healthy(host) is true, false if host is unknown, if Wait passes,
// or if ctx ends first. It sends the packet only if none was sent for host in the last Wait.
func (w *Waker) Wake(ctx context.Context, host string) bool

Rules the tests check: packet layout; separators; errors for bad MACs and unresolvable addresses; one packet per window; return within about Wait when the host never comes up; early return on a cancelled context; false for an unknown host without sending anything. Never panic; safe for concurrent Wake calls on different hosts.

Steps

• 1. git switch v2; mkdir -p internal/wake; copy the test.
• 2. See it fail (compile). 3. Write wake.go. gofmt -w internal/wake/.
• 4. go test -race -count=3 ./internal/wake/ → ok (timing tests; three runs).
• 5. make gate. 6. Row v2/03-wake; commit.

git add internal/wake docs/implementer-log.md
git commit

Done when

• -race -count=3 passes; gate ok; the copied test is byte-identical.