Refactor utility placement: move shared helpers out of specialized files and remove micro-packages/files (#4117)

lpcox · web-flow · commit 18b19a68d864 · 2026-04-18T10:54:33.000-07:00
Semantic clustering flagged utility outliers and micro-file/package sprawl across `internal/`. This PR consolidates shared helpers into appropriate common packages and removes single-purpose file/package fragmentation while preserving existing behavior. - **Version composition moved to `internal/version`** - Extracted `buildVersionString` from `main.go` into `version.BuildVersionString(mainVersion, gitCommit, buildDate)`. - `main` now delegates version-string assembly to `internal/version`, making logic package-local and testable outside `main`. - **Transient HTTP classification centralized in `httputil`** - Promoted config-local `isTransientHTTPError` to shared `httputil.IsTransientHTTPError`. - Updated config schema fetch retry path to call the shared helper. - Moved associated test coverage from `internal/config` to `internal/httputil`. - **Removed `timeutil` micro-package** - Moved `FormatDuration` from `internal/timeutil` to `internal/strutil`. - Updated logger time-diff formatting call sites to `strutil.FormatDuration`. - Deleted `internal/timeutil` files. - **Collapsed micro-files in `auth` and `oidc`** - Merged `GenerateRandomAPIKey` (and logger) into `internal/auth/header.go`; removed `internal/auth/apikey.go`. - Merged `ErrMissingOIDCEnvVar` into `internal/oidc/provider.go`; removed `internal/oidc/errors.go`. - **Inlined single-use logger helper** - Removed `getMapKeys` from `internal/logger/rpc_helpers.go`. - Inlined key extraction at the call site and dropped now-obsolete unit test for that private helper. - **Docs alignment** - Updated package-structure docs to reflect removal of `internal/timeutil` and expanded `internal/strutil` role. ```go // before (main.go) versionStr := buildVersionString() // after versionStr := version.BuildVersionString(Version, GitCommit, BuildDate) ``` > [!WARNING] > > <details> > <summary>Firewall rules blocked me from connecting to one or more addresses (expand for details)</summary> > > #### I tried to connect to the following addresses, but was blocked by firewall rules: > > - `example.com` > - Triggering command: `/tmp/go-build3787159813/b514/launcher.test /tmp/go-build3787159813/b514/launcher.test -test.testlogfile=/tmp/go-build3787159813/b514/testlog.txt -test.paniconexit0 -test.timeout=10m0s /tmp/go-build3787159813/b423/vet.cfg rotocol/go-sdk@v1.5.0/jsonrpc/jsonrpc.go =0 x_amd64/vet --gdwarf-5 esource/v1 -o x_amd64/vet --de�� _.a --debug-prefix-m-ifaceassert x_amd64/vet -I go-sdk/mcp -I x_amd64/vet` (dns block) > - Triggering command: `/tmp/go-build2056270914/b513/launcher.test /tmp/go-build2056270914/b513/launcher.test -test.testlogfile=/tmp/go-build2056270914/b513/testlog.txt -test.paniconexit0 -test.timeout=10m0s know�� known-linux-gnu/lib/rustlib/x86_/home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/guards/github-guard/rustgit known-linux-gnu/lib/rustlib/x86_/home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/guards/github-guard/rustpush x_amd64/compile known-linux-gnu/git known-linux-gnu/ls-files known-linux-gnu/--exclude-standard x_amd64/compile know�� known-linux-gnu/lib/rustlib/x86_64-REDACTED-linux-gnu/lib/libminiz_oxide-2b6a8d2f6e1dc71b.rlib known-linux-gnu/lib/rustlib/x86_64-REDACTED-linux-gnu/lib/libadler2-39ffdbc27c978ccc.rlib /opt/containerd/bin/bash /run/containerd/git 7213e0dede2210feconfig json 7213e0dede2210fed31/init.pid` (dns block) > - `invalid-host-that-does-not-exist-12345.com` > - Triggering command: `/tmp/go-build3787159813/b496/config.test /tmp/go-build3787159813/b496/config.test -test.testlogfile=/tmp/go-build3787159813/b496/testlog.txt -test.paniconexit0 -test.timeout=10m0s /tmp/go-build3787159813/b317/vet.cfg @v1.1.3/cpu/cpu.-errorsas 89155655/b151//_-ifaceassert x_amd64/vet --gdwarf-5 --64 155655/b151/ x_amd64/vet -w ache/go/1.25.8/x-errorsas dHAhgBmen x_amd64/vet OUTPUT -d ut-3746032072.c x_amd64/vet` (dns block) > - Triggering command: `/tmp/go-build1806864329/b491/config.test /tmp/go-build1806864329/b491/config.test -test.testlogfile=/tmp/go-build1806864329/b491/testlog.txt -test.paniconexit0 -test.timeout=10m0s bug/deps/serde_derive-bdc7cd22a58a5141.serde_derive.12123747d8da05ed-cgu.04.rcgu-importcfg bug/deps/serde_derive-bdc7cd22a58a5141.serde_derive.12123747d8da05ed-cgu.05.rcgu/tmp/go-build1806864329/b237/importcfg bug/deps/serde_derive-bdc7cd22a58a5141.serde_derive.12123747d8da05ed-cgu.06.rcgu-pack bug/deps/serde_derive-bdc7cd22a58a5141.serde_derive.12123747d8da05ed-cgu.07.rcgu/home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/internal/difc/agent.go bug/deps/serde_derive-bdc7cd22a58a5141.serde_derive.12123747d8da05ed-cgu.08.rcgu/home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/internal/difc/capabilities.go bug/deps/serde_derive-bdc7cd22a58a5141.serde_derive.12123747d8da05ed-cgu.09.rcgu.o bug/deps/serde_derive-bdc7cd22a58a5141.serde_derive.12123747d8da05ed-cgu.10.rcgu.o bug/deps/serde_derive-bdc7cd22a58a5141.serde_derive.12123747d8da05ed-cgu.11.rcgu.o bug/�� bug/deps/serde_derive-bdc7cd22a58a5141.serde_derive.12123747d8da05ed-cgu.13.rcgu.o bug/deps/serde_derive-bdc7cd22a58a5141.serde_derive.12123747d8da05ed-cgu.14.rcgu.o -guard/target/de--build-id ntime.v2.task/mo/opt/copilot-runtime/copilot-developer-action-main/dist/ripgrep/bin/linux-x64/rg-trimpath /tmp/go-build389--files lib/rustlib/x86_--hidden lib/rustlib/x86_--glob` (dns block) > - `nonexistent.local` > - Triggering command: `/tmp/go-build3787159813/b514/launcher.test /tmp/go-build3787159813/b514/launcher.test -test.testlogfile=/tmp/go-build3787159813/b514/testlog.txt -test.paniconexit0 -test.timeout=10m0s /tmp/go-build3787159813/b423/vet.cfg rotocol/go-sdk@v1.5.0/jsonrpc/jsonrpc.go =0 x_amd64/vet --gdwarf-5 esource/v1 -o x_amd64/vet --de�� _.a --debug-prefix-m-ifaceassert x_amd64/vet -I go-sdk/mcp -I x_amd64/vet` (dns block) > - Triggering command: `/tmp/go-build2056270914/b513/launcher.test /tmp/go-build2056270914/b513/launcher.test -test.testlogfile=/tmp/go-build2056270914/b513/testlog.txt -test.paniconexit0 -test.timeout=10m0s know�� known-linux-gnu/lib/rustlib/x86_/home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/guards/github-guard/rustgit known-linux-gnu/lib/rustlib/x86_/home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/guards/github-guard/rustpush x_amd64/compile known-linux-gnu/git known-linux-gnu/ls-files known-linux-gnu/--exclude-standard x_amd64/compile know�� known-linux-gnu/lib/rustlib/x86_64-REDACTED-linux-gnu/lib/libminiz_oxide-2b6a8d2f6e1dc71b.rlib known-linux-gnu/lib/rustlib/x86_64-REDACTED-linux-gnu/lib/libadler2-39ffdbc27c978ccc.rlib /opt/containerd/bin/bash /run/containerd/git 7213e0dede2210feconfig json 7213e0dede2210fed31/init.pid` (dns block) > - `slow.example.com` > - Triggering command: `/tmp/go-build3787159813/b514/launcher.test /tmp/go-build3787159813/b514/launcher.test -test.testlogfile=/tmp/go-build3787159813/b514/testlog.txt -test.paniconexit0 -test.timeout=10m0s /tmp/go-build3787159813/b423/vet.cfg rotocol/go-sdk@v1.5.0/jsonrpc/jsonrpc.go =0 x_amd64/vet --gdwarf-5 esource/v1 -o x_amd64/vet --de�� _.a --debug-prefix-m-ifaceassert x_amd64/vet -I go-sdk/mcp -I x_amd64/vet` (dns block) > - Triggering command: `/tmp/go-build2056270914/b513/launcher.test /tmp/go-build2056270914/b513/launcher.test -test.testlogfile=/tmp/go-build2056270914/b513/testlog.txt -test.paniconexit0 -test.timeout=10m0s know�� known-linux-gnu/lib/rustlib/x86_/home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/guards/github-guard/rustgit known-linux-gnu/lib/rustlib/x86_/home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/guards/github-guard/rustpush x_amd64/compile known-linux-gnu/git known-linux-gnu/ls-files known-linux-gnu/--exclude-standard x_amd64/compile know�� known-linux-gnu/lib/rustlib/x86_64-REDACTED-linux-gnu/lib/libminiz_oxide-2b6a8d2f6e1dc71b.rlib known-linux-gnu/lib/rustlib/x86_64-REDACTED-linux-gnu/lib/libadler2-39ffdbc27c978ccc.rlib /opt/containerd/bin/bash /run/containerd/git 7213e0dede2210feconfig json 7213e0dede2210fed31/init.pid` (dns block) > - `this-host-does-not-exist-12345.com` > - Triggering command: `/tmp/go-build3787159813/b523/mcp.test /tmp/go-build3787159813/b523/mcp.test -test.testlogfile=/tmp/go-build3787159813/b523/testlog.txt -test.paniconexit0 -test.timeout=10m0s -W cfg /tmp/go-build389-ifaceassert x_amd64/vet _amd64.s g/protobuf/proto--version --64 x_amd64/vet cfg 155655/b281/_pkg_.a -fPIC x_amd64/vet -pthread .io/otel/exporte/usr/bin/runc -fmessage-length--version x_amd64/vet` (dns block) > - Triggering command: `/tmp/go-build2056270914/b522/mcp.test /tmp/go-build2056270914/b522/mcp.test -test.testlogfile=/tmp/go-build2056270914/b522/testlog.txt -test.paniconexit0 -test.timeout=10m0s go1.25.8 -c=4 -nolocalimports -importcfg /tmp/go-build3333051407/b001/importcfg -pack /home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/main.go /home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/version.go ive.�� ive.12123747d8da05ed-cgu.02.rcgugo1.25.8 ive.12123747d8da05ed-cgu.03.rcgu-c=4 ive.12123747d8da05ed-cgu.04.rcgu-nolocalimports ive.12123747d8da/opt/hostedtoolcache/go/1.25.8/x64/pkg/tool/linux_amd64/link ive.12123747d8da-V=full ive.12123747d8da05ed-cgu.07.rcgu-bool ive.12123747d8da05ed-cgu.08.rcgu-buildtags` (dns block) > > If you need me to access, download, or install something from one of these locations, you can either: > > - Configure [Actions setup steps](https://gh.io/copilot/actions-setup-steps) to set up my environment, which run before the firewall is enabled > - Add the appropriate URLs or hosts to the custom allowlist in this repository's [Copilot coding agent settings](https://github.com/github/gh-aw-mcpg/settings/copilot/coding_agent) (admins only) > > </details>
diff --git a/AGENTS.md b/AGENTS.md
@@ -35,9 +35,9 @@ Quick reference for AI agents working with MCP Gateway (Go-based MCP proxy serve
 - `internal/mcp/` - MCP protocol types with enhanced error logging
 - `internal/middleware/` - HTTP middleware (jq schema processing)
 - `internal/server/` - HTTP server (routed/unified modes)
+- `internal/strutil/` - String and formatting utilities
 - `internal/sys/` - System utilities
 - `internal/testutil/` - Test utilities and helpers
-- `internal/timeutil/` - Time formatting utilities
 - `internal/tty/` - Terminal detection utilities
 - `internal/version/` - Version management
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -267,11 +267,10 @@ awmg/
     ├── oidc/                  # OIDC authentication for HTTP MCP backends
     ├── proxy/                 # HTTP forward proxy for DIFC filtering
     ├── server/                # HTTP server (routed/unified modes)
-    ├── strutil/               # String utility helpers
+    ├── strutil/               # String and formatting utility helpers
     ├── syncutil/              # Concurrency utility helpers
     ├── sys/                   # System utilities
     ├── testutil/              # Test utilities and helpers
-    ├── timeutil/              # Time formatting utilities
     ├── tracing/               # OpenTelemetry OTLP tracing helpers
     ├── tty/                   # Terminal detection utilities
     └── version/               # Version management
@@ -293,11 +292,10 @@ awmg/
 - **`internal/oidc/`** - OIDC authentication for HTTP MCP backends
 - **`internal/proxy/`** - HTTP forward proxy applying DIFC filtering to `gh` CLI and REST/GraphQL requests
 - **`internal/server/`** - HTTP server with routed and unified modes
-- **`internal/strutil/`** - String utility helpers (deduplication, trimming)
+- **`internal/strutil/`** - String and formatting utility helpers (deduplication, trimming, duration formatting)
 - **`internal/syncutil/`** - Concurrency utility helpers (get-or-create pattern)
 - **`internal/sys/`** - System utilities
 - **`internal/testutil/`** - Test utilities and helpers
-- **`internal/timeutil/`** - Time formatting utilities
 - **`internal/tracing/`** - OpenTelemetry OTLP trace export helpers (HTTP handler wrapping, provider management)
 - **`internal/tty/`** - Terminal detection utilities
 - **`internal/version/`** - Version management
diff --git a/internal/auth/apikey.go b/internal/auth/apikey.go
diff --git a/internal/auth/header.go b/internal/auth/header.go
@@ -36,6 +36,7 @@ package auth
 
 import (
 	"errors"
+	"fmt"
 	"strings"
 
 	"github.com/github/gh-aw-mcpg/internal/logger"
@@ -44,6 +45,7 @@ import (
 )
 
 var log = logger.New("auth:header")
+var logAPIKey = logger.New("auth:apikey")
 
 var (
 	// ErrMissingAuthHeader is returned when the Authorization header is missing
@@ -180,3 +182,17 @@ func TruncateSessionID(sessionID string) string {
 	}
 	return strutil.Truncate(sessionID, 8)
 }
+
+// GenerateRandomAPIKey generates a cryptographically random API key.
+// Per spec §7.3, the gateway SHOULD generate a random API key on startup
+// if none is provided. Returns a 32-byte hex-encoded string (64 chars).
+func GenerateRandomAPIKey() (string, error) {
+	logAPIKey.Print("Generating random API key")
+	key, err := strutil.RandomHex(32)
+	if err != nil {
+		logAPIKey.Printf("Random API key generation failed: %v", err)
+		return "", fmt.Errorf("failed to generate random API key: %w", err)
+	}
+	logAPIKey.Print("Random API key generated successfully")
+	return key, nil
+}
diff --git a/internal/config/validation_schema.go b/internal/config/validation_schema.go
@@ -12,6 +12,7 @@ import (
 	"time"
 
 	"github.com/github/gh-aw-mcpg/internal/config/rules"
+	"github.com/github/gh-aw-mcpg/internal/httputil"
 	"github.com/github/gh-aw-mcpg/internal/logger"
 	"github.com/github/gh-aw-mcpg/internal/version"
 	"github.com/santhosh-tekuri/jsonschema/v5"
@@ -49,14 +50,6 @@ var schemaFetchRetryDelay = time.Second
 // so tests can shorten it to avoid long waits when testing timeout behaviour.
 var schemaHTTPClientTimeout = 10 * time.Second
 
-// isTransientHTTPError returns true for status codes that indicate a temporary
-// server-side condition (rate-limiting or transient failure) worth retrying.
-func isTransientHTTPError(statusCode int) bool {
-	return statusCode == http.StatusTooManyRequests ||
-		statusCode == http.StatusServiceUnavailable ||
-		(statusCode >= 500 && statusCode < 600)
-}
-
 var (
 	// Compile regex patterns from schema for additional validation
 	containerPattern = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9./_-]*(:([a-zA-Z0-9._-]+|latest))?(@sha256:[a-fA-F0-9]{64})?$`)
@@ -260,7 +253,7 @@ func fetchAndFixSchema(url string) ([]byte, error) {
 			break
 		}
 
-		if isTransientHTTPError(resp.StatusCode) {
+		if httputil.IsTransientHTTPError(resp.StatusCode) {
 			lastErr = fmt.Errorf("failed to fetch schema: HTTP %d", resp.StatusCode)
 			logSchema.Printf("Schema fetch attempt %d returned transient error: HTTP %d, will retry", attempt, resp.StatusCode)
 			resp.Body.Close()
diff --git a/internal/httputil/httputil.go b/internal/httputil/httputil.go
@@ -35,3 +35,11 @@ func ParseRateLimitResetHeader(value string) time.Time {
 	}
 	return time.Unix(unix, 0)
 }
+
+// IsTransientHTTPError returns true for status codes that indicate a temporary
+// server-side condition (rate-limiting or transient failure) worth retrying.
+func IsTransientHTTPError(statusCode int) bool {
+	return statusCode == http.StatusTooManyRequests ||
+		statusCode == http.StatusServiceUnavailable ||
+		(statusCode >= 500 && statusCode < 600)
+}
diff --git a/internal/httputil/transient_http_error_test.go b/internal/httputil/transient_http_error_test.go
@@ -1,4 +1,4 @@
-package config
+package httputil
 
 import (
 	"net/http"
@@ -7,7 +7,7 @@ import (
 	"github.com/stretchr/testify/assert"
 )
 
-// TestIsTransientHTTPError verifies every status-code branch in isTransientHTTPError.
+// TestIsTransientHTTPError verifies every status-code branch in IsTransientHTTPError.
 // The function returns true for HTTP 429 (TooManyRequests), 503 (ServiceUnavailable),
 // and any 5xx status code, and false for all other codes.
 func TestIsTransientHTTPError(t *testing.T) {
@@ -121,8 +121,8 @@ func TestIsTransientHTTPError(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
-			got := isTransientHTTPError(tt.statusCode)
-			assert.Equal(t, tt.want, got, "isTransientHTTPError(%d)", tt.statusCode)
+			got := IsTransientHTTPError(tt.statusCode)
+			assert.Equal(t, tt.want, got, "IsTransientHTTPError(%d)", tt.statusCode)
 		})
 	}
 }
diff --git a/internal/logger/logger.go b/internal/logger/logger.go
@@ -8,7 +8,7 @@ import (
 	"sync"
 	"time"
 
-	"github.com/github/gh-aw-mcpg/internal/timeutil"
+	"github.com/github/gh-aw-mcpg/internal/strutil"
 	"github.com/github/gh-aw-mcpg/internal/tty"
 )
 
@@ -122,9 +122,9 @@ func (l *Logger) Printf(format string, args ...any) {
 
 	// Write to stderr with colors and time diff
 	if l.color != "" {
-		fmt.Fprintf(os.Stderr, "%s%s%s %s +%s\n", l.color, l.namespace, colorReset, message, timeutil.FormatDuration(diff))
+		fmt.Fprintf(os.Stderr, "%s%s%s %s +%s\n", l.color, l.namespace, colorReset, message, strutil.FormatDuration(diff))
 	} else {
-		fmt.Fprintf(os.Stderr, "%s %s +%s\n", l.namespace, message, timeutil.FormatDuration(diff))
+		fmt.Fprintf(os.Stderr, "%s %s +%s\n", l.namespace, message, strutil.FormatDuration(diff))
 	}
 
 	// Also write to file logger in text-only format (no colors, no time diff)
@@ -149,9 +149,9 @@ func (l *Logger) Print(args ...any) {
 
 	// Write to stderr with colors and time diff
 	if l.color != "" {
-		fmt.Fprintf(os.Stderr, "%s%s%s %s +%s\n", l.color, l.namespace, colorReset, message, timeutil.FormatDuration(diff))
+		fmt.Fprintf(os.Stderr, "%s%s%s %s +%s\n", l.color, l.namespace, colorReset, message, strutil.FormatDuration(diff))
 	} else {
-		fmt.Fprintf(os.Stderr, "%s %s +%s\n", l.namespace, message, timeutil.FormatDuration(diff))
+		fmt.Fprintf(os.Stderr, "%s %s +%s\n", l.namespace, message, strutil.FormatDuration(diff))
 	}
 
 	// Also write to file logger in text-only format (no colors, no time diff)
diff --git a/internal/logger/rpc_helpers.go b/internal/logger/rpc_helpers.go
@@ -6,7 +6,6 @@
 //
 // - truncateAndSanitize: Combines secret sanitization with length truncation
 // - extractEssentialFields: Extracts key JSON-RPC fields for compact logging
-// - getMapKeys: Utility for extracting map keys without values
 // - isEffectivelyEmpty: Checks if data is effectively empty (e.g., only params: null)
 // - ExtractErrorMessage: Extracts clean error messages from log lines
 //
@@ -78,22 +77,17 @@ func extractEssentialFields(payload []byte) map[string]interface{} {
 	if params, ok := data["params"]; ok {
 		if paramsMap, ok := params.(map[string]interface{}); ok {
 			// Include param count and keys, but not values
-			essential["params_keys"] = getMapKeys(paramsMap)
+			keys := make([]string, 0, len(paramsMap))
+			for k := range paramsMap {
+				keys = append(keys, k)
+			}
+			essential["params_keys"] = keys
 		}
 	}
 
 	return essential
 }
 
-// getMapKeys returns the keys of a map
-func getMapKeys(m map[string]interface{}) []string {
-	keys := make([]string, 0, len(m))
-	for k := range m {
-		keys = append(keys, k)
-	}
-	return keys
-}
-
 // isEffectivelyEmpty checks if the data is effectively empty (only contains params: null)
 func isEffectivelyEmpty(data map[string]interface{}) bool {
 	// If empty, it's empty
diff --git a/internal/logger/rpc_helpers_test.go b/internal/logger/rpc_helpers_test.go
@@ -330,53 +330,6 @@ func TestExtractEssentialFields(t *testing.T) {
 	}
 }
 
-// TestGetMapKeys tests the getMapKeys function
-func TestGetMapKeys(t *testing.T) {
-	tests := []struct {
-		name string
-		m    map[string]interface{}
-		want []string
-	}{
-		{
-			name: "normal map",
-			m: map[string]interface{}{
-				"key1": "value1",
-				"key2": "value2",
-				"key3": "value3",
-			},
-			want: []string{"key1", "key2", "key3"},
-		},
-		{
-			name: "empty map",
-			m:    map[string]interface{}{},
-			want: []string{},
-		},
-		{
-			name: "single key",
-			m: map[string]interface{}{
-				"only": "value",
-			},
-			want: []string{"only"},
-		},
-		{
-			name: "nil values",
-			m: map[string]interface{}{
-				"null1": nil,
-				"null2": nil,
-			},
-			want: []string{"null1", "null2"},
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result := getMapKeys(tt.m)
-			assert.ElementsMatch(t, tt.want, result, "keys should match regardless of order")
-			assert.Len(t, result, len(tt.want), "should have correct number of keys")
-		})
-	}
-}
-
 // TestIsEffectivelyEmpty tests the isEffectivelyEmpty function
 func TestIsEffectivelyEmpty(t *testing.T) {
 	tests := []struct {
diff --git a/internal/oidc/errors.go b/internal/oidc/errors.go
diff --git a/internal/oidc/provider.go b/internal/oidc/provider.go
@@ -46,6 +46,15 @@ type Provider struct {
 	cache        map[string]*cachedToken // keyed by audience
 }
 
+// ErrMissingOIDCEnvVar returns a formatted error for when
+// ACTIONS_ID_TOKEN_REQUEST_URL is not set for a server that requires OIDC auth.
+func ErrMissingOIDCEnvVar(serverID string) error {
+	return fmt.Errorf(
+		"server %q requires OIDC authentication but ACTIONS_ID_TOKEN_REQUEST_URL is not set; "+
+			"OIDC auth is only available in GitHub Actions with `permissions: { id-token: write }`",
+		serverID)
+}
+
 // NewProvider creates a new Provider using the given OIDC request URL and bearer token.
 // These values come from the ACTIONS_ID_TOKEN_REQUEST_URL and
 // ACTIONS_ID_TOKEN_REQUEST_TOKEN environment variables respectively.
diff --git a/internal/strutil/format_duration.go b/internal/strutil/format_duration.go
@@ -1,4 +1,4 @@
-package timeutil
+package strutil
 
 import (
 	"fmt"
diff --git a/internal/strutil/format_duration_test.go b/internal/strutil/format_duration_test.go
@@ -1,4 +1,4 @@
-package timeutil
+package strutil
 
 import (
 	"testing"
diff --git a/internal/version/version.go b/internal/version/version.go
@@ -1,5 +1,13 @@
 package version
 
+import (
+	"fmt"
+	"runtime/debug"
+	"strings"
+)
+
+const shortHashLength = 7
+
 // gatewayVersion stores the gateway version string, used across multiple packages
 // for error reporting, health checks, and MCP client implementation info.
 // It defaults to "0.0.0-dev" (a valid semantic version pre-release identifier) and
@@ -22,3 +30,42 @@ func Set(v string) {
 func Get() string {
 	return gatewayVersion
 }
+
+// BuildVersionString constructs a detailed version string with optional build metadata.
+func BuildVersionString(mainVersion, gitCommit, buildDate string) string {
+	var parts []string
+
+	if mainVersion != "" {
+		parts = append(parts, mainVersion)
+	} else {
+		parts = append(parts, "dev")
+	}
+
+	if gitCommit != "" {
+		parts = append(parts, fmt.Sprintf("commit: %s", gitCommit))
+	} else if buildInfo, ok := debug.ReadBuildInfo(); ok {
+		for _, setting := range buildInfo.Settings {
+			if setting.Key == "vcs.revision" {
+				commitHash := setting.Value
+				if len(commitHash) > shortHashLength {
+					commitHash = commitHash[:shortHashLength]
+				}
+				parts = append(parts, fmt.Sprintf("commit: %s", commitHash))
+				break
+			}
+		}
+	}
+
+	if buildDate != "" {
+		parts = append(parts, fmt.Sprintf("built: %s", buildDate))
+	} else if buildInfo, ok := debug.ReadBuildInfo(); ok {
+		for _, setting := range buildInfo.Settings {
+			if setting.Key == "vcs.time" {
+				parts = append(parts, fmt.Sprintf("built: %s", setting.Value))
+				break
+			}
+		}
+	}
+
+	return strings.Join(parts, ", ")
+}
diff --git a/main.go b/main.go
diff --git a/main_test.go b/main_test.go

Original file line number	Diff line number	Diff line change
`@@ -35,3 +35,11 @@ func ParseRateLimitResetHeader(value string) time.Time {`
`35`	`35`	`}`
`36`	`36`	`return time.Unix(unix, 0)`
`37`	`37`	`}`
	`38`	`+`
	`39`	`+// IsTransientHTTPError returns true for status codes that indicate a temporary`
	`40`	`+// server-side condition (rate-limiting or transient failure) worth retrying.`
	`41`	`+func IsTransientHTTPError(statusCode int) bool {`
	`42`	`+ return statusCode == http.StatusTooManyRequests \|\|`
	`43`	`+ statusCode == http.StatusServiceUnavailable \|\|`
	`44`	`+ (statusCode >= 500 && statusCode < 600)`
	`45`	`+}`