Files
pipelines/internal/buildinfo/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

93 lines
3.0 KiB
Go

package buildinfo
import "fmt"
// Severity classifies how a client build relates to the server it is talking to.
// The zero value is the in-sync case so callers can treat "no relationship" as
// no output.
type Severity int
const (
// InSync means both peers report the same build and the same protocol.
InSync Severity = iota
// Warn means the builds differ or the server could not be identified, but the
// exchange is still safe: the client keeps working and reports once.
Warn
// Refuse means the server speaks a protocol newer than this client can
// interpret; continuing would silently misread frames, so the caller must
// fail rather than proceed.
Refuse
)
// Relationship is the outcome of comparing a client build with a server build.
type Relationship struct {
Severity Severity
Message string
}
// Describe names a build for humans. A missing build is reported as
// "unavailable" rather than guessed.
func Describe(info *Info) string {
if info == nil {
return "unavailable"
}
return fmt.Sprintf("%s (commit %s)", info.Version, info.Commit)
}
// Compare classifies the client/server build relationship in O(1). Ordering uses
// the integer protocol only; build strings are used for naming, never parsed or
// ordered. server may be nil when the server omitted its build identity.
func Compare(client Info, clientProtocol int, serverProtocol int, server *Info) Relationship {
if serverProtocol > clientProtocol {
return Relationship{
Severity: Refuse,
Message: fmt.Sprintf(
"server build %s speaks protocol %d, newer than this client's supported protocol %d; "+
"update the pipelines CLI (client build %s) before connecting",
Describe(server), serverProtocol, clientProtocol, Describe(&client)),
}
}
if server != nil && serverProtocol == clientProtocol && sameBuild(client, *server) {
return Relationship{}
}
switch {
case server == nil:
return Relationship{
Severity: Warn,
Message: fmt.Sprintf(
"the connected server did not report its build identity (older or incompatible server); "+
"client build %s", Describe(&client)),
}
case serverProtocol == 0:
return Relationship{
Severity: Warn,
Message: fmt.Sprintf(
"the connected server did not report a protocol version (legacy server); "+
"client build %s, server build %s", Describe(&client), Describe(server)),
}
default:
return Relationship{
Severity: Warn,
Message: fmt.Sprintf(
"client build %s does not match server build %s; rebuild or reinstall the CLI so it "+
"matches the connected server", Describe(&client), Describe(server)),
}
}
}
// sameBuild reports whether two identities name the same compiled artifact. A
// missing Dirty pointer is distinct from an explicit value.
func sameBuild(a, b Info) bool {
if a.Version != b.Version || a.Commit != b.Commit {
return false
}
switch {
case a.Dirty == nil && b.Dirty == nil:
return true
case a.Dirty == nil || b.Dirty == nil:
return false
default:
return *a.Dirty == *b.Dirty
}
}