feat: expand MQTT contract and reliability lessons

internal/contracts/message.go

@@ -0,0 +1,180 @@
+package contracts
+
+import (
+	"fmt"
+	"strings"
+	"time"
+)
+
+const SchemaVersion = 1
+
+// Kind values match the final topic segment used to route each message.
+type Kind string
+
+const (
+	KindTelemetry Kind = "telemetry"
+	KindCommands  Kind = "commands"
+	KindResponses Kind = "responses"
+	KindSales     Kind = "sales"
+)
+
+// Topic is the parsed device scope and message kind from an MQTT topic.
+type Topic struct {
+	DeviceID string
+	Kind     Kind
+}
+
+// MQTTMessage is implemented by each versioned message contract.
+// Validation uses the parsed route and caller-supplied time for deterministic checks.
+type MQTTMessage interface {
+	Validate(topic Topic, now time.Time) error
+}
+
+// These types define the JSON fields shared by backend and simulator.
+type Heartbeat struct {
+	SchemaVersion int      `json:"schema_version"`
+	MessageID     string   `json:"message_id"`
+	DeviceID      string   `json:"device_id"`
+	OccurredAt    string   `json:"occurred_at"`
+	Temperature   *float64 `json:"temperature,omitempty"`
+}
+
+type Command struct {
+	SchemaVersion int    `json:"schema_version"`
+	MessageID     string `json:"message_id"`
+	DeviceID      string `json:"device_id"`
+	OccurredAt    string `json:"occurred_at"`
+	CommandID     string `json:"command_id"`
+	Command       string `json:"command"`
+}
+
+type CommandResult struct {
+	SchemaVersion int    `json:"schema_version"`
+	MessageID     string `json:"message_id"`
+	DeviceID      string `json:"device_id"`
+	OccurredAt    string `json:"occurred_at"`
+	CommandID     string `json:"command_id"`
+	Status        string `json:"status"`
+	Detail        string `json:"detail,omitempty"`
+}
+
+type SalesLine struct {
+	SKU         string `json:"sku"`
+	Quantity    int64  `json:"quantity"`
+	AmountMinor int64  `json:"amount_minor"`
+}
+
+type SalesReport struct {
+	SchemaVersion int         `json:"schema_version"`
+	ReportID      string      `json:"report_id"`
+	DeviceID      string      `json:"device_id"`
+	OccurredAt    string      `json:"occurred_at"`
+	Items         []SalesLine `json:"items"`
+}
+
+// validID limits identifiers to safe, single-segment topic values.
+func validID(value string) bool {
+	if value == "" || len(value) > 128 {
+		return false
+	}
+	for _, r := range value {
+		if !(r >= 'a' && r <= 'z' || r >= 'A' && r <= 'Z' || r >= '0' && r <= '9' || strings.ContainsRune("._-", r)) {
+			return false
+		}
+	}
+	return true
+}
+
+// validateEnvelope checks fields shared by every versioned message.
+func validateEnvelope(topic Topic, version int, messageID, deviceID, occurredAt string, now time.Time) error {
+	if version != SchemaVersion {
+		return fmt.Errorf("unsupported schema_version %d", version)
+	}
+	if !validID(messageID) || !validID(deviceID) {
+		return fmt.Errorf("message_id and device_id must be valid IDs")
+	}
+	if topic.DeviceID != deviceID {
+		return fmt.Errorf("topic device %q does not match payload device_id %q", topic.DeviceID, deviceID)
+	}
+	stamp, err := time.Parse(time.RFC3339, occurredAt)
+	if err != nil {
+		return fmt.Errorf("occurred_at must be RFC3339: %w", err)
+	}
+	if stamp.After(now.Add(30 * time.Second)) {
+		return fmt.Errorf("occurred_at is more than 30 seconds in the future")
+	}
+	return nil
+}
+
+// Each Validate method adds checks specific to one message kind.
+func (m Heartbeat) Validate(topic Topic, now time.Time) error {
+	if topic.Kind != KindTelemetry {
+		return fmt.Errorf("heartbeat requires telemetry topic")
+	}
+	if err := validateEnvelope(topic, m.SchemaVersion, m.MessageID, m.DeviceID, m.OccurredAt, now); err != nil {
+		return err
+	}
+	if m.Temperature != nil && (*m.Temperature < -50 || *m.Temperature > 100) {
+		return fmt.Errorf("temperature is outside the supported range")
+	}
+	return nil
+}
+
+func (m Command) Validate(topic Topic, now time.Time) error {
+	if topic.Kind != KindCommands {
+		return fmt.Errorf("command requires commands topic")
+	}
+	if err := validateEnvelope(topic, m.SchemaVersion, m.MessageID, m.DeviceID, m.OccurredAt, now); err != nil {
+		return err
+	}
+	if !validID(m.CommandID) || m.Command != "ping" {
+		return fmt.Errorf("command_id is invalid or command is unsupported")
+	}
+	return nil
+}
+
+func (m CommandResult) Validate(topic Topic, now time.Time) error {
+	if topic.Kind != KindResponses {
+		return fmt.Errorf("command result requires responses topic")
+	}
+	if err := validateEnvelope(topic, m.SchemaVersion, m.MessageID, m.DeviceID, m.OccurredAt, now); err != nil {
+		return err
+	}
+	if !validID(m.CommandID) || (m.Status != "accepted" && m.Status != "completed" && m.Status != "rejected") {
+		return fmt.Errorf("command result has invalid command_id or status")
+	}
+	return nil
+}
+
+func (m SalesReport) Validate(topic Topic, now time.Time) error {
+	if topic.Kind != KindSales {
+		return fmt.Errorf("sales report requires sales topic")
+	}
+	if err := validateEnvelope(topic, m.SchemaVersion, m.ReportID, m.DeviceID, m.OccurredAt, now); err != nil {
+		return err
+	}
+	if len(m.Items) == 0 || len(m.Items) > 100 {
+		return fmt.Errorf("sales report must contain 1 to 100 items")
+	}
+	for i, item := range m.Items {
+		if !validID(item.SKU) || item.Quantity <= 0 || item.AmountMinor < 0 {
+			return fmt.Errorf("item %d has invalid SKU, quantity, or amount_minor", i)
+		}
+	}
+	return nil
+}
+
+// ParseTopic turns broker routing metadata into values handlers can compare.
+func ParseTopic(value string) (Topic, error) {
+	parts := strings.Split(value, "/")
+	if len(parts) != 5 || parts[0] != "lab" || parts[1] != "v1" || parts[2] != "devices" || !validID(parts[3]) {
+		return Topic{}, fmt.Errorf("topic must be lab/v1/devices/{deviceID}/{kind}")
+	}
+	kind := Kind(parts[4])
+	switch kind {
+	case KindTelemetry, KindCommands, KindResponses, KindSales:
+		return Topic{DeviceID: parts[3], Kind: kind}, nil
+	default:
+		return Topic{}, fmt.Errorf("unsupported topic kind %q", kind)
+	}
+}