Files
pipelines/internal/protocol/identity.go
T
alan 8c1eea53a9 Report a stale client and refuse an unreadable newer server
Exchange a build/protocol identity so an older CLI can no longer talk to a
newer native server silently:

- protocol carries ProtocolVersion and every server frame (including the
  unsolicited welcome) is stamped with the server build and protocol, so a
  client that never pings still learns the server identity.
- buildinfo.Compare classifies the relationship as InSync/Warn/Refuse and
  names both builds; the client Watch reports one warning per connection and
  returns a hard error when the server speaks a newer, uninterpretable
  protocol so the caller never acts on the frame.
- client.ReceiveNotice decodes the raw frame so an unmodeled top-level field
  produces a one-time "unrecognized field(s)" notice instead of being dropped
  silently (the case that hid the artifacts field).
- CLI routes warnings to stderr, keeps machine JSON stdout clean and fails
  non-zero on a refused mismatch; ping/connection print the client/server
  relationship. The TUI surfaces the same notices through the shared log.
- scripts/setup-native.py now warns when an older `pipelines` earlier on PATH
  shadows prefix/bin/pipelines, naming both paths and versions, without
  installing or modifying anything else.
- Docs, the packaged debugging skill reference and README no longer imply the
  installed CLI always matches the server.

Tests cover the comparison table, unknown-field detection and caching, the
server identity stamping on pong and welcome, the CLI/TUI reporting paths and
the installer PATH shadowing warning.
2026-10-16 18:37:01 +01:00

61 lines
1.7 KiB
Go

package protocol
import (
"encoding/json"
"reflect"
"sort"
"strings"
"sync"
)
// ProtocolVersion is the integer wire protocol this build speaks. Ordering
// between peers compares this integer; build strings are for naming only and are
// never parsed or sorted to infer ordering.
const ProtocolVersion = 1
// MaxSupportedProtocol is the newest server protocol this client can interpret.
// A server reporting a higher value is refused rather than silently misread.
const MaxSupportedProtocol = ProtocolVersion
var (
knownFieldsOnce sync.Once
knownFields map[string]struct{}
)
// KnownFields returns the set of top-level JSON keys protocol.Message models,
// derived once from the struct tags and cached. The map is read-only.
func KnownFields() map[string]struct{} {
knownFieldsOnce.Do(func() {
knownFields = map[string]struct{}{}
message := reflect.TypeOf(Message{})
for index := 0; index < message.NumField(); index++ {
name := strings.Split(message.Field(index).Tag.Get("json"), ",")[0]
if name == "" || name == "-" {
continue
}
knownFields[name] = struct{}{}
}
})
return knownFields
}
// UnknownFields returns the sorted top-level JSON keys in data that protocol.Message
// does not model. It performs one bounded map decode plus O(1) set lookups, so a
// forward-compatible frame is never a per-frame reflection walk. A frame that is
// not a JSON object (or cannot be parsed) reports no unknown fields.
func UnknownFields(data []byte) []string {
var raw map[string]json.RawMessage
if err := json.Unmarshal(data, &raw); err != nil {
return nil
}
known := KnownFields()
var unknown []string
for key := range raw {
if _, ok := known[key]; !ok {
unknown = append(unknown, key)
}
}
sort.Strings(unknown)
return unknown
}