Skip to content

Agent Mesh

client: identify node and router requests with build versions

Antonio Ojea0ba25eca9fde
diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml
index 0031316f..b6b40def 100644
--- a/.github/workflows/deploy.yaml
+++ b/.github/workflows/deploy.yaml
@@ -90,6 +90,7 @@ jobs:
with:
context: .
file: Dockerfile.sam-router
+ build-args: VERSION=${{ github.ref_type == 'tag' && github.ref_name || github.sha }}
platforms: ${{ github.ref_type == 'tag' && 'linux/amd64,linux/arm64' || 'linux/amd64' }}
push: true
tags: ${{ steps.meta-router.outputs.tags }}
@@ -112,6 +113,7 @@ jobs:
with:
context: .
file: Dockerfile.sam-node
+ build-args: VERSION=${{ github.ref_type == 'tag' && github.ref_name || github.sha }}
platforms: ${{ github.ref_type == 'tag' && 'linux/amd64,linux/arm64' || 'linux/amd64' }}
push: true
tags: ${{ steps.meta-node.outputs.tags }}
@@ -200,6 +202,7 @@ jobs:
with:
context: .
file: Dockerfile.sam-one
+ build-args: VERSION=${{ github.ref_type == 'tag' && github.ref_name || github.sha }}
platforms: ${{ github.ref_type == 'tag' && 'linux/amd64,linux/arm64' || 'linux/amd64' }}
push: true
tags: ${{ steps.meta-sam-one.outputs.tags }}
diff --git a/.goreleaser.yaml b/.goreleaser.yaml
index 9f60e4cc..db1cbeb3 100644
--- a/.goreleaser.yaml
+++ b/.goreleaser.yaml
@@ -17,7 +17,7 @@ builds:
- amd64
- arm64
ldflags:
- - -s -w
+ - -s -w -X github.com/google/sam/internal/version.Version={{ .Tag }}
- id: sam-control-plane
main: ./cmd/sam-control-plane
binary: sam-control-plane
@@ -45,7 +45,7 @@ builds:
- amd64
- arm64
ldflags:
- - -s -w
+ - -s -w -X github.com/google/sam/internal/version.Version={{ .Tag }}
- id: mcp-client
main: ./cmd/mcp-client
binary: mcp-client
@@ -101,7 +101,7 @@ builds:
- amd64
- arm64
ldflags:
- - -s -w
+ - -s -w -X github.com/google/sam/internal/version.Version={{ .Tag }}
- id: nano-init
main: .
# nano-init is its own module: it carries a userspace TCP stack, and that
diff --git a/Dockerfile.sam-node b/Dockerfile.sam-node
index e9f29b78..8b7fbfdf 100644
--- a/Dockerfile.sam-node
+++ b/Dockerfile.sam-node
@@ -4,7 +4,8 @@ WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
-RUN CGO_ENABLED=0 GOOS=linux go build -buildvcs=false -o sam-node ./cmd/sam-node
+ARG VERSION=devel
+RUN CGO_ENABLED=0 GOOS=linux go build -buildvcs=false -ldflags="-X github.com/google/sam/internal/version.Version=${VERSION}" -o sam-node ./cmd/sam-node
# Pre-create the default data dir owned by the nonroot UID so that a fresh
# named/anonymous volume mounted over it inherits writable ownership instead
# of defaulting to root.
diff --git a/Dockerfile.sam-one b/Dockerfile.sam-one
index ee520f57..ed701dd6 100644
--- a/Dockerfile.sam-one
+++ b/Dockerfile.sam-one
@@ -4,7 +4,8 @@ WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
-RUN CGO_ENABLED=0 GOOS=linux go build -buildvcs=false -o sam-one ./cmd/sam-one
+ARG VERSION=devel
+RUN CGO_ENABLED=0 GOOS=linux go build -buildvcs=false -ldflags="-X github.com/google/sam/internal/version.Version=${VERSION}" -o sam-one ./cmd/sam-one
# Pre-create the data dir owned by the nonroot UID so that a fresh
# named/anonymous volume mounted over it inherits writable ownership instead
# of defaulting to root.
diff --git a/Dockerfile.sam-router b/Dockerfile.sam-router
index 30c61801..fa30fd1d 100644
--- a/Dockerfile.sam-router
+++ b/Dockerfile.sam-router
@@ -4,7 +4,8 @@ WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
-RUN CGO_ENABLED=0 GOOS=linux go build -buildvcs=false -o sam-router ./cmd/sam-router
+ARG VERSION=devel
+RUN CGO_ENABLED=0 GOOS=linux go build -buildvcs=false -ldflags="-X github.com/google/sam/internal/version.Version=${VERSION}" -o sam-router ./cmd/sam-router
# Pre-create the keys/data dir owned by the nonroot UID so that a fresh
# named/anonymous volume mounted over it inherits writable ownership instead
# of defaulting to root.
diff --git a/Makefile b/Makefile
index d6c27b18..b39e2672 100644
--- a/Makefile
+++ b/Makefile
@@ -1,5 +1,7 @@
REPO_ROOT:=${CURDIR}
OUT_DIR=$(REPO_ROOT)/bin
+VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo devel)
+VERSION_LDFLAGS = -X github.com/google/sam/internal/version.Version=$(VERSION)
.DEFAULT_GOAL := build
@@ -23,10 +25,10 @@ ANDROID_CC_X86_64=$(ANDROID_NDK_TOOLCHAIN)/x86_64-linux-android30-clang
build:
- go build -v -o "$(OUT_DIR)/sam-node" ./cmd/sam-node
+ go build -v -ldflags "$(VERSION_LDFLAGS)" -o "$(OUT_DIR)/sam-node" ./cmd/sam-node
go build -v -o "$(OUT_DIR)/sam-control-plane" ./cmd/sam-control-plane
- go build -v -o "$(OUT_DIR)/sam-router" ./cmd/sam-router
- go build -v -o "$(OUT_DIR)/sam-one" ./cmd/sam-one
+ go build -v -ldflags "$(VERSION_LDFLAGS)" -o "$(OUT_DIR)/sam-router" ./cmd/sam-router
+ go build -v -ldflags "$(VERSION_LDFLAGS)" -o "$(OUT_DIR)/sam-one" ./cmd/sam-one
go build -v -o "$(OUT_DIR)/mcp-client" ./cmd/mcp-client
go build -v -o "$(OUT_DIR)/sam-box" ./cmd/sam-box
go build -v -o "$(OUT_DIR)/sam-bench" ./cmd/sam-bench
@@ -42,14 +44,14 @@ build:
.PHONY: mobile-ffi-host mobile-ffi-android mobile-ffi-android-x86_64 mobile-ffi-ios mobile-ffi mobile-app-apk mobile-app-apk-emulator mobile-app-bundle
mobile-ffi-host:
mkdir -p "$(OUT_DIR)"
- CGO_ENABLED=1 go build -v -buildmode=c-shared -o "$(OUT_DIR)/libsam.so" ./mobile/sam-node-ffi
+ CGO_ENABLED=1 go build -v -ldflags "$(VERSION_LDFLAGS)" -buildmode=c-shared -o "$(OUT_DIR)/libsam.so" ./mobile/sam-node-ffi
mobile-ffi-android:
@if [ -z "$(ANDROID_NDK_LATEST)" ]; then \
echo "Error: Android NDK not found under $(ANDROID_HOME_RESOLVED)/ndk/. Please install NDK (Side-by-side) via Android Studio or sdkmanager." >&2; \
exit 1; \
fi
- GOOS=android GOARCH=arm64 CGO_ENABLED=1 CC=$(ANDROID_CC_ARM64) go build -v -ldflags="-checklinkname=0" -buildmode=c-shared -o "$(OUT_DIR)/android/libsam.so" ./mobile/sam-node-ffi
+ GOOS=android GOARCH=arm64 CGO_ENABLED=1 CC=$(ANDROID_CC_ARM64) go build -v -ldflags="-checklinkname=0 $(VERSION_LDFLAGS)" -buildmode=c-shared -o "$(OUT_DIR)/android/libsam.so" ./mobile/sam-node-ffi
mobile-ffi-android-x86_64:
@if [ -z "$(ANDROID_NDK_LATEST)" ]; then \
@@ -57,11 +59,11 @@ mobile-ffi-android-x86_64:
exit 1; \
fi
mkdir -p "$(OUT_DIR)/android-x86_64"
- GOOS=android GOARCH=amd64 CGO_ENABLED=1 CC=$(ANDROID_CC_X86_64) go build -v -ldflags="-checklinkname=0" -buildmode=c-shared -o "$(OUT_DIR)/android-x86_64/libsam.so" ./mobile/sam-node-ffi
+ GOOS=android GOARCH=amd64 CGO_ENABLED=1 CC=$(ANDROID_CC_X86_64) go build -v -ldflags="-checklinkname=0 $(VERSION_LDFLAGS)" -buildmode=c-shared -o "$(OUT_DIR)/android-x86_64/libsam.so" ./mobile/sam-node-ffi
mobile-ffi-ios:
mkdir -p "$(OUT_DIR)/ios"
- GOOS=ios GOARCH=arm64 CGO_ENABLED=1 go build -v -buildmode=c-archive -o "$(OUT_DIR)/ios/libsam.a" ./mobile/sam-node-ffi
+ GOOS=ios GOARCH=arm64 CGO_ENABLED=1 go build -v -ldflags "$(VERSION_LDFLAGS)" -buildmode=c-archive -o "$(OUT_DIR)/ios/libsam.a" ./mobile/sam-node-ffi
mobile-ffi: mobile-ffi-host mobile-ffi-android mobile-ffi-android-x86_64 mobile-ffi-ios
@@ -243,10 +245,10 @@ docker-build-control-plane:
docker build --load -t sam-control-plane:local -f Dockerfile.sam-control-plane .
docker-build-router:
- docker build --load -t sam-router:local -f Dockerfile.sam-router .
+ docker build --load --build-arg VERSION="$(VERSION)" -t sam-router:local -f Dockerfile.sam-router .
docker-build-node:
- docker build --load -t sam-node:local -f Dockerfile.sam-node .
+ docker build --load --build-arg VERSION="$(VERSION)" -t sam-node:local -f Dockerfile.sam-node .
docker-build-mock-oidc:
docker build --load -t sam-mock-oidc:local -f tests/e2e/docker/Dockerfile.mock-oidc .
diff --git a/cmd/sam-node/main.go b/cmd/sam-node/main.go
index 3ed2b985..24b9a15f 100644
--- a/cmd/sam-node/main.go
+++ b/cmd/sam-node/main.go
@@ -31,6 +31,7 @@ import (
"github.com/google/sam/api"
"github.com/google/sam/internal/node"
"github.com/google/sam/internal/secrets"
+ "github.com/google/sam/internal/version"
golog "github.com/ipfs/go-log/v2"
"github.com/mattn/go-isatty"
"github.com/multiformats/go-multiaddr"
@@ -277,8 +278,9 @@ func interactiveJoin(ctx context.Context, store *node.Store, targetControlPlane
func main() {
rootCmd := &cobra.Command{
- Use: "sam-node",
- Short: "Sovereign Agent Mesh Node",
+ Use: "sam-node",
+ Short: "Sovereign Agent Mesh Node",
+ Version: version.String(),
PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
node.SetAllowInsecureControlPlane(insecureControlPlaneFlag)
// The stored URL is checked at request time by the same policy;
diff --git a/internal/controlplane/client/client.go b/internal/controlplane/client/client.go
index 6f61260b..723cbdf0 100644
--- a/internal/controlplane/client/client.go
+++ b/internal/controlplane/client/client.go
@@ -14,8 +14,8 @@
// Package client is how a mesh component reads from its control plane. Node
// and router share it, so the body cap, the status handling and the signature
-// check on /keys are a single code path. It depends on api/ only: importing it
-// pulls in none of the control plane server.
+// check on /keys are a single code path. It depends on api/ and build metadata:
+// importing it pulls in none of the control plane server.
package client
import (
@@ -32,6 +32,7 @@ import (
"google.golang.org/protobuf/proto"
"github.com/google/sam/api"
+ "github.com/google/sam/internal/version"
)
// MaxBodyBytes caps every response body read from a control plane: a
@@ -66,22 +67,25 @@ func ReadBody(r io.Reader) ([]byte, error) {
// choice after its clients exist.
type transport struct {
allowInsecure func() bool
+ userAgent string
}
func (t transport) RoundTrip(req *http.Request) (*http.Response, error) {
if err := api.ValidateControlPlaneTransport(req.URL.String(), t.allowInsecure()); err != nil {
return nil, err
}
- return http.DefaultTransport.RoundTrip(req)
+ cloned := req.Clone(req.Context())
+ cloned.Header.Set("User-Agent", t.userAgent)
+ return http.DefaultTransport.RoundTrip(cloned)
}
// NewHTTPClient is the HTTP client for every request a mesh component makes
// to its control plane. A nil allowInsecure never allows plaintext.
-func NewHTTPClient(timeout time.Duration, allowInsecure func() bool) *http.Client {
+func NewHTTPClient(timeout time.Duration, allowInsecure func() bool, component string) *http.Client {
if allowInsecure == nil {
allowInsecure = func() bool { return false }
}
- return &http.Client{Timeout: timeout, Transport: transport{allowInsecure: allowInsecure}}
+ return &http.Client{Timeout: timeout, Transport: transport{allowInsecure: allowInsecure, userAgent: component + "/" + version.String()}}
}
// Client reads the pull side of the mesh protocol from one control plane.
diff --git a/internal/controlplane/client/client_test.go b/internal/controlplane/client/client_test.go
index ef2689e0..cd949070 100644
--- a/internal/controlplane/client/client_test.go
+++ b/internal/controlplane/client/client_test.go
@@ -29,6 +29,7 @@ import (
"google.golang.org/protobuf/proto"
"github.com/google/sam/api"
+ "github.com/google/sam/internal/version"
)
func writeProto(t *testing.T, w http.ResponseWriter, msg proto.Message) {
@@ -45,6 +46,41 @@ func writeProto(t *testing.T, w http.ResponseWriter, msg proto.Message) {
}
}
+func TestHTTPClientUserAgent(t *testing.T) {
+ for _, component := range []string{"sam-node", "sam-router"} {
+ t.Run(component, func(t *testing.T) {
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) {
+ if got, want := request.UserAgent(), component+"/"+version.String(); got != want {
+ t.Errorf("User-Agent = %q, want %q", got, want)
+ }
+ if request.Header.Get("Authorization") != "Bearer test" {
+ t.Error("transport changed the authentication header")
+ }
+ if request.URL.Path == "/redirect" {
+ http.Redirect(w, request, "/final", http.StatusTemporaryRedirect)
+ return
+ }
+ w.WriteHeader(http.StatusNoContent)
+ }))
+ defer server.Close()
+ request, err := http.NewRequest(http.MethodGet, server.URL+"/redirect", nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ request.Header.Set("Authorization", "Bearer test")
+ request.Header.Set("User-Agent", "original")
+ response, err := NewHTTPClient(time.Second, nil, component).Do(request)
+ if err != nil {
+ t.Fatal(err)
+ }
+ _ = response.Body.Close()
+ if request.UserAgent() != "original" {
+ t.Fatal("transport mutated the caller's request")
+ }
+ })
+ }
+}
+
func TestFetchInfo(t *testing.T) {
want := &api.ControlPlaneInfoResponse{
RouterAddresses: []string{"/ip4/10.0.0.1/tcp/4501"},
@@ -58,7 +94,7 @@ func TestFetchInfo(t *testing.T) {
defer srv.Close()
// A trailing slash on the base URL must not double up in the path.
- c := New(srv.URL+"/", NewHTTPClient(time.Second, nil))
+ c := New(srv.URL+"/", NewHTTPClient(time.Second, nil, "sam-node"))
info, err := c.FetchInfo(context.Background())
if err != nil {
t.Fatalf("FetchInfo: %v", err)
@@ -102,7 +138,7 @@ func TestFetchKeys(t *testing.T) {
writeProto(t, w, resp)
}))
t.Cleanup(srv.Close)
- return New(srv.URL, NewHTTPClient(time.Second, nil))
+ return New(srv.URL, NewHTTPClient(time.Second, nil, "sam-node"))
}
t.Run("a set vouched for by a trusted key is adopted whole", func(t *testing.T) {
@@ -137,7 +173,7 @@ func TestErrors(t *testing.T) {
http.Error(w, "store down", http.StatusServiceUnavailable)
}))
defer srv.Close()
- c := New(srv.URL, NewHTTPClient(time.Second, nil))
+ c := New(srv.URL, NewHTTPClient(time.Second, nil, "sam-node"))
_, err := c.FetchInfo(context.Background())
if err == nil || !strings.Contains(err.Error(), "503") || !strings.Contains(err.Error(), "store down") {
t.Fatalf("FetchInfo error = %v, want status and body", err)
@@ -151,7 +187,7 @@ func TestErrors(t *testing.T) {
}
}))
defer srv.Close()
- c := New(srv.URL, NewHTTPClient(time.Second, nil))
+ c := New(srv.URL, NewHTTPClient(time.Second, nil, "sam-node"))
if _, err := c.FetchInfo(context.Background()); err == nil || !strings.Contains(err.Error(), "decode /info") {
t.Fatalf("FetchInfo error = %v, want a decode error naming the path", err)
}
@@ -171,7 +207,7 @@ func TestErrors(t *testing.T) {
writeProto(t, w, big)
}))
defer srv.Close()
- c := New(srv.URL, NewHTTPClient(5*time.Second, nil))
+ c := New(srv.URL, NewHTTPClient(5*time.Second, nil, "sam-node"))
info, err := c.FetchInfo(context.Background())
if !errors.Is(err, ErrBodyTooLarge) {
t.Fatalf("FetchInfo = (%d bans, %v), want ErrBodyTooLarge", len(info.GetBannedPeerIds()), err)
@@ -196,7 +232,7 @@ func TestLargeAnswersArriveWhole(t *testing.T) {
writeProto(t, w, big)
}))
defer srv.Close()
- info, err := New(srv.URL, NewHTTPClient(5*time.Second, nil)).FetchInfo(context.Background())
+ info, err := New(srv.URL, NewHTTPClient(5*time.Second, nil, "sam-node")).FetchInfo(context.Background())
if err != nil {
t.Fatalf("FetchInfo: %v", err)
}
@@ -220,7 +256,7 @@ func TestLargeAnswersArriveWhole(t *testing.T) {
writeProto(t, w, exact)
}))
defer srv.Close()
- info, err := New(srv.URL, NewHTTPClient(5*time.Second, nil)).FetchInfo(context.Background())
+ info, err := New(srv.URL, NewHTTPClient(5*time.Second, nil, "sam-node")).FetchInfo(context.Background())
if err != nil {
t.Fatalf("FetchInfo at exactly the cap: %v", err)
}
@@ -246,7 +282,7 @@ func TestFetchPolicy(t *testing.T) {
}))
defer srv.Close()
- policy, err := New(srv.URL, NewHTTPClient(time.Second, nil)).FetchPolicy(context.Background(), []byte("biscuit"))
+ policy, err := New(srv.URL, NewHTTPClient(time.Second, nil, "sam-node")).FetchPolicy(context.Background(), []byte("biscuit"))
if err != nil {
t.Fatalf("FetchPolicy: %v", err)
}
@@ -272,7 +308,7 @@ func TestHTTPClientTransportPolicy(t *testing.T) {
nonLoopbackURL := strings.Replace(srv.URL, "127.0.0.1", "sam-control-plane.invalid", 1)
allow := false
- httpClient := NewHTTPClient(time.Second, func() bool { return allow })
+ httpClient := NewHTTPClient(time.Second, func() bool { return allow }, "sam-node")
if _, err := New(srv.URL, httpClient).FetchInfo(context.Background()); err != nil {
t.Fatalf("loopback plaintext must be accepted: %v", err)
diff --git a/internal/node/controlplane_client.go b/internal/node/controlplane_client.go
index 83ff75a0..88792a9f 100644
--- a/internal/node/controlplane_client.go
+++ b/internal/node/controlplane_client.go
@@ -36,5 +36,5 @@ func SetAllowInsecureControlPlane(allow bool) {
// controlPlaneHTTPClient is the client for every request the node makes to
// its control plane; the plaintext policy is re-checked on every hop.
func controlPlaneHTTPClient(timeout time.Duration) *http.Client {
- return cpclient.NewHTTPClient(timeout, allowInsecureControlPlane.Load)
+ return cpclient.NewHTTPClient(timeout, allowInsecureControlPlane.Load, "sam-node")
}
diff --git a/internal/node/controlplane_test.go b/internal/node/controlplane_test.go
index eddb368e..2b0f72d4 100644
--- a/internal/node/controlplane_test.go
+++ b/internal/node/controlplane_test.go
@@ -598,6 +598,9 @@ func TestReportNodeCatalog(t *testing.T) {
if r.URL.Path != "/nodes/catalog" {
t.Errorf("Expected path /nodes/catalog, got %s", r.URL.Path)
}
+ if userAgent := r.UserAgent(); !strings.HasPrefix(userAgent, "sam-node/") || userAgent == "sam-node/" {
+ t.Errorf("Expected versioned sam-node User-Agent, got %q", userAgent)
+ }
gotAuth = r.Header.Get("Authorization")
gotContentType = r.Header.Get("Content-Type")
body, err := io.ReadAll(r.Body)
diff --git a/internal/router/router.go b/internal/router/router.go
index b2364023..02c438b5 100644
--- a/internal/router/router.go
+++ b/internal/router/router.go
@@ -703,7 +703,7 @@ func (r *Router) controlPlane(timeout time.Duration) *cpclient.Client {
// controlPlaneClient is the client for every request to the control plane;
// its transport re-checks the plaintext policy on each hop, redirects included.
func (r *Router) controlPlaneClient(timeout time.Duration) *http.Client {
- return cpclient.NewHTTPClient(timeout, func() bool { return r.config.AllowInsecureControlPlane })
+ return cpclient.NewHTTPClient(timeout, func() bool { return r.config.AllowInsecureControlPlane }, "sam-router")
}
func (r *Router) getTrustedPublicKeys() []ed25519.PublicKey {
diff --git a/internal/version/version.go b/internal/version/version.go
new file mode 100644
index 00000000..a36dd9d1
--- /dev/null
+++ b/internal/version/version.go
@@ -0,0 +1,57 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package version
+
+import "runtime/debug"
+
+var Version = "devel"
+
+func String() string {
+ if Version != "" && Version != "devel" {
+ return Version
+ }
+ info, ok := debug.ReadBuildInfo()
+ if !ok {
+ return "devel"
+ }
+ return fromBuildInfo(info)
+}
+
+func fromBuildInfo(info *debug.BuildInfo) string {
+ if info.Main.Version != "" && info.Main.Version != "(devel)" {
+ return info.Main.Version
+ }
+ var revision string
+ var modified bool
+ for _, setting := range info.Settings {
+ switch setting.Key {
+ case "vcs.revision":
+ revision = setting.Value
+ case "vcs.modified":
+ modified = setting.Value == "true"
+ }
+ }
+ if revision == "" {
+ return "devel"
+ }
+ if len(revision) > 12 {
+ revision = revision[:12]
+ }
+ result := "devel-" + revision
+ if modified {
+ result += "-dirty"
+ }
+ return result
+}
diff --git a/internal/version/version_test.go b/internal/version/version_test.go
new file mode 100644
index 00000000..f08772d4
--- /dev/null
+++ b/internal/version/version_test.go
@@ -0,0 +1,53 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package version
+
+import (
+ "runtime/debug"
+ "testing"
+)
+
+func TestFromBuildInfo(t *testing.T) {
+ for _, test := range []struct {
+ name string
+ info debug.BuildInfo
+ want string
+ }{
+ {name: "unknown", want: "devel"},
+ {name: "module", info: debug.BuildInfo{Main: debug.Module{Version: "v0.1.0"}}, want: "v0.1.0"},
+ {name: "development", info: debug.BuildInfo{Main: debug.Module{Version: "(devel)"}}, want: "devel"},
+ {name: "revision", info: debug.BuildInfo{Settings: []debug.BuildSetting{{Key: "vcs.revision", Value: "0123456789abcdef"}}}, want: "devel-0123456789ab"},
+ {name: "dirty", info: debug.BuildInfo{Settings: []debug.BuildSetting{{Key: "vcs.revision", Value: "0123456789abcdef"}, {Key: "vcs.modified", Value: "true"}}}, want: "devel-0123456789ab-dirty"},
+ } {
+ t.Run(test.name, func(t *testing.T) {
+ if got := fromBuildInfo(&test.info); got != test.want {
+ t.Fatalf("version = %q, want %q", got, test.want)
+ }
+ })
+ }
+}
+
+func TestString(t *testing.T) {
+ previous := Version
+ t.Cleanup(func() { Version = previous })
+ Version = "v0.2.0-test"
+ if got := String(); got != Version {
+ t.Fatalf("version = %q, want linker override %q", got, Version)
+ }
+ Version = "devel"
+ if String() == "" {
+ t.Fatal("development version must not be empty")
+ }
+}
diff --git a/site/content/docs/contributing/_index.md b/site/content/docs/contributing/_index.md
index 35752a42..b31d675f 100644
--- a/site/content/docs/contributing/_index.md
+++ b/site/content/docs/contributing/_index.md
@@ -45,6 +45,22 @@ make docker-build # container images tagged :local
make proto # regenerate api/sam.pb.go after editing sam.proto
```
+Node and router control-plane requests identify themselves as
+`sam-node/<version>` and `sam-router/<version>`, including the router inside
+`sam-one`. These headers contain the software component and build version.
+They are diagnostic metadata that a caller can spoof and are never used for
+authentication or authorization. They do not include peer IDs, credentials,
+or authorization roles. Publishing a version lets an observer identify the
+software release; keeping dependencies patched remains necessary.
+
+`make` derives the version from `git describe --tags --always --dirty`.
+You can override it with `make build VERSION=v0.1.0-custom` and inspect the
+node binary with `bin/sam-node --version`. Release binaries use the release
+tag, and published node, router and `sam-one` images use the tag or commit
+SHA. For direct Docker builds of those images, pass `--build-arg VERSION=...`;
+without it, the version is `devel`. Plain `go build` uses Go's embedded module
+or VCS metadata when available and falls back to `devel`.
+
## Test
The suite is layered so that most coverage lives where it runs fastest.