LastState Relay

Offline-first gateway between devices running Latch and one or more Trace backends. Relay accepts LEP envelopes (serial, TCP, HTTP, MQTT, adapters, or files), validates them, stores them on disk, ACKs the device only after the write, optionally analyzes crashes locally, and forwards events with retries and idempotency.

Guarantees

• Persist before ACK — LSAK ACK_STORED only after object write + SQLite commit
• At-least-once delivery — duplicates possible after a lost response; stable IDs make retries safe
• Works offline — outages do not block collection
• Raw kept locally — original LEP bytes stay exportable and checksummed
• No cloud lock-in — talks only to the Trace HTTP contract

Note

At-least-once means downstream systems must tolerate duplicates. They can: every envelope carries a stable event id, and Trace dedupes on it.

Features

• LEP v1/v2 validation/encode (v2 is the current wire version; v1 accepted), CRC-32/IEEE, optional HMAC + ChaCha20-Poly1305, zstd payloads
• Latch stream and COBS framing with resync
• Sources: serial, TCP/TLS, UDP, HTTP/TLS, directory, MQTT, subprocess adapters
• Delivery: mirror / priority / route / local-only, JSON or binary batch, zstd
• Privacy filters per destination (local raw untouched)
• ELF catalog, build-id match, DWARF + external symbolizers, Cortex-M and multi-arch basics
• CLI/TUI, Prometheus, Grafana dashboard template, backup/restore
• Packaging: Docker, systemd, deb/rpm templates, Windows service, launchd, Homebrew

Build

go test ./...
go build -trimpath -ldflags "-s -w \
  -X main.cliVersion=v0.4.0 \
  -X main.gitCommit=$(git rev-parse --short HEAD) \
  -X main.buildDate=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -o bin/laststate-relay ./cmd/laststate-relay

Needs Go 1.26.1+.

Quick start

The fastest path is the full stack:

git clone --recurse-submodules https://github.com/laststate/laststate.git
cd laststate
docker compose up -d
# admin → http://localhost:8383

Standalone, from this repo:

cp relay.yaml.example relay.yaml
laststate-relay config validate relay.yaml
laststate-relay run --config relay.yaml

Serial collect:

laststate-relay collect \
  --serial COM5 \
  --baud 115200 \
  --framing latch-stream \
  --ack lsak-v1 \
  --data-dir ./data

Offline analysis (explicit ELF or auto-match from the artifact catalog):

laststate-relay analyze crash.lep --elf build/firmware.elf
laststate-relay analyze crash.lep --data-dir ./data

Tip

laststate-relay doctor --config relay.yaml checks tokens, spool health and destination reachability before you start. Run it after every config change.

APIs

Admin and ingest are separate listeners with separate tokens.

Warning

Never expose the admin listener publicly without TLS and a strong token. Admin can replay, prune and reconcile the spool. Bind it to loopback (or a private interface) unless a reverse proxy with TLS terminates in front.

Admin

GET  /v1/status | /v1/health | /v1/ready
GET  /v1/events | /v1/events/{id}
GET  /v1/destinations
POST /v1/events/{id}/replay
POST /v1/destinations/{id}/pause|resume
POST /v1/spool/prune|reconcile

Ingest

GET  /v1/ingest/capabilities
GET  /v1/relay/capabilities
POST /v1/ingest
POST /v1/events:batch

Trace (as destination)

GET  /v1/relay/capabilities
POST /v1/ingest
POST /v1/events:batch

Batching is per destination. Relay discovers limits, sends JSON or binary batches (optionally zstd), retries only failed items, and falls back to single-event POST for older servers.

CLI

run · collect · info · inspect · analyze
import · export · replay · status · doctor
artifacts · destinations · bundle · spool
backup · restore · config · version

Docs

Doc	Topic
docs/architecture.md	How the pieces fit
docs/durability.md	ACK / write path
docs/production.md	Deploy checklist
docs/v1-release-gate.md	v1.0.0 tagging gate
docs/hil-matrix.md	CAN/BLE/LoRa/Probe HIL evidence
docs/compatibility-matrix.md	What is ready vs draft
spec/	Wire drafts (crypto, batch, TLVs, …)
ROADMAP.md	What is left

Status

Native CAN (SocketCAN/CAN FD/USB-CAN/TCP), BLE GATT, and LoRa/LoRaWAN sources are implemented (internal/source/can.go, ble.go, lorawan.go) with unit coverage (go test ./internal/source/).

Caution

CAN/BLE/LoRa sources are not tagged v1.0.0. That waits on the executable gate in docs/v1-release-gate.md: protocol freeze, durability soak, Latch+Trace E2E, the HIL matrix, and an external security review. Do not plan production around them yet.

Community and security

• Contributing guide
• Security policy
• Code of conduct
• Support

License

Apache-2.0 — LICENSE.md