From 8d40c4d130d76cc1a4f1445294b0664ca59eb7b7 Mon Sep 17 00:00:00 2001 From: Zack Wagner Date: Mon, 21 Sep 2026 09:50:40 -0400 Subject: [PATCH 1/4] admin: add GET /info endpoint for version and build metadata Adds a new admin API endpoint at GET /info that returns version, Go version, OS, architecture, and build settings. This allows programmatic access to build/version information without needing CLI access to the running Caddy instance. Closes #8044 Co-Authored-By: Claude Opus 4.6 --- admin_info.go | 91 ++++++++++++++++++++++++++++++++++++++++++++ admin_info_test.go | 94 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 185 insertions(+) create mode 100644 admin_info.go create mode 100644 admin_info_test.go diff --git a/admin_info.go b/admin_info.go new file mode 100644 index 000000000..f97dc753d --- /dev/null +++ b/admin_info.go @@ -0,0 +1,91 @@ +// Copyright 2015 Matthew Holt and The Caddy Authors +// +// 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 caddy + +import ( + "encoding/json" + "net/http" + "runtime" + "runtime/debug" +) + +func init() { + RegisterModule(AdminInfo{}) +} + +// AdminInfo is a module that provides a GET /info endpoint on the +// admin API, returning version and build metadata about the running +// Caddy instance. +type AdminInfo struct{} + +// CaddyModule returns the Caddy module information. +func (AdminInfo) CaddyModule() ModuleInfo { + return ModuleInfo{ + ID: "admin.api.info", + New: func() Module { return new(AdminInfo) }, + } +} + +// Routes returns a route for the /info endpoint. +func (ai AdminInfo) Routes() []AdminRoute { + return []AdminRoute{ + {Pattern: "/info", Handler: AdminHandlerFunc(ai.handleInfo)}, + } +} + +// infoResponse is the JSON structure returned by GET /info. +type infoResponse struct { + Version string `json:"version"` + VersionFull string `json:"version_full"` + GoVersion string `json:"go_version"` + OS string `json:"os"` + Arch string `json:"arch"` + BuildSettings map[string]string `json:"build_settings,omitempty"` +} + +func (AdminInfo) handleInfo(w http.ResponseWriter, r *http.Request) error { + if r.Method != http.MethodGet { + return APIError{ + HTTPStatus: http.StatusMethodNotAllowed, + Message: "method not allowed", + } + } + + simple, full := Version() + + resp := infoResponse{ + Version: simple, + VersionFull: full, + GoVersion: runtime.Version(), + OS: runtime.GOOS, + Arch: runtime.GOARCH, + } + + if bi, ok := debug.ReadBuildInfo(); ok { + settings := make(map[string]string) + for _, s := range bi.Settings { + settings[s.Key] = s.Value + } + if len(settings) > 0 { + resp.BuildSettings = settings + } + } + + w.Header().Set("Content-Type", "application/json") + return json.NewEncoder(w).Encode(resp) +} + +// Interface guards +var _ AdminRouter = (*AdminInfo)(nil) diff --git a/admin_info_test.go b/admin_info_test.go new file mode 100644 index 000000000..d4a964e79 --- /dev/null +++ b/admin_info_test.go @@ -0,0 +1,94 @@ +// Copyright 2015 Matthew Holt and The Caddy Authors +// +// 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 caddy + +import ( + "encoding/json" + "net/http" + "net/http/httptest" + "runtime" + "testing" +) + +func TestAdminInfoModule(t *testing.T) { + ai := AdminInfo{} + info := ai.CaddyModule() + if info.ID != "admin.api.info" { + t.Errorf("expected module ID 'admin.api.info', got %q", info.ID) + } + routes := ai.Routes() + if len(routes) != 1 { + t.Fatalf("expected 1 route, got %d", len(routes)) + } + if routes[0].Pattern != "/info" { + t.Errorf("expected pattern '/info', got %q", routes[0].Pattern) + } +} + +func TestAdminInfoHandler(t *testing.T) { + ai := AdminInfo{} + + t.Run("GET returns version and build info", func(t *testing.T) { + req := httptest.NewRequest(http.MethodGet, "/info", nil) + rec := httptest.NewRecorder() + + err := ai.handleInfo(rec, req) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + if ct := rec.Header().Get("Content-Type"); ct != "application/json" { + t.Errorf("expected Content-Type 'application/json', got %q", ct) + } + + var resp infoResponse + if err := json.NewDecoder(rec.Body).Decode(&resp); err != nil { + t.Fatalf("failed to decode response: %v", err) + } + + if resp.GoVersion != runtime.Version() { + t.Errorf("expected go_version %q, got %q", runtime.Version(), resp.GoVersion) + } + if resp.OS != runtime.GOOS { + t.Errorf("expected os %q, got %q", runtime.GOOS, resp.OS) + } + if resp.Arch != runtime.GOARCH { + t.Errorf("expected arch %q, got %q", runtime.GOARCH, resp.Arch) + } + if resp.Version == "" { + t.Error("expected non-empty version") + } + if resp.VersionFull == "" { + t.Error("expected non-empty version_full") + } + }) + + t.Run("POST returns method not allowed", func(t *testing.T) { + req := httptest.NewRequest(http.MethodPost, "/info", nil) + rec := httptest.NewRecorder() + + err := ai.handleInfo(rec, req) + if err == nil { + t.Fatal("expected error for POST method") + } + apiErr, ok := err.(APIError) + if !ok { + t.Fatalf("expected APIError, got %T", err) + } + if apiErr.HTTPStatus != http.StatusMethodNotAllowed { + t.Errorf("expected status %d, got %d", http.StatusMethodNotAllowed, apiErr.HTTPStatus) + } + }) +} From 5cc146a7b146782d07380158a7a7db10a2d424ed Mon Sep 17 00:00:00 2001 From: Zack Wagner Date: Wed, 7 Oct 2026 09:21:08 -0400 Subject: [PATCH 2/4] admin: set Allow header on /info 405 response MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per RFC 9110 ยง15.5.6, a 405 response must include an Allow header listing the supported methods. Co-Authored-By: Claude Opus 5.5 --- admin_info.go | 1 + admin_info_test.go | 3 +++ 2 files changed, 4 insertions(+) diff --git a/admin_info.go b/admin_info.go index f97dc753d..0231475e5 100644 --- a/admin_info.go +++ b/admin_info.go @@ -57,6 +57,7 @@ type infoResponse struct { func (AdminInfo) handleInfo(w http.ResponseWriter, r *http.Request) error { if r.Method != http.MethodGet { + w.Header().Set("Allow", http.MethodGet) return APIError{ HTTPStatus: http.StatusMethodNotAllowed, Message: "method not allowed", diff --git a/admin_info_test.go b/admin_info_test.go index d4a964e79..96dc18bd4 100644 --- a/admin_info_test.go +++ b/admin_info_test.go @@ -90,5 +90,8 @@ func TestAdminInfoHandler(t *testing.T) { if apiErr.HTTPStatus != http.StatusMethodNotAllowed { t.Errorf("expected status %d, got %d", http.StatusMethodNotAllowed, apiErr.HTTPStatus) } + if allow := rec.Header().Get("Allow"); allow != http.MethodGet { + t.Errorf("expected Allow header %q, got %q", http.MethodGet, allow) + } }) } From 8b271d017d074e2dbe091c7a9951858e3ec0c697 Mon Sep 17 00:00:00 2001 From: Zack Wagner Date: Wed, 7 Oct 2026 09:24:29 -0400 Subject: [PATCH 3/4] admin: move /info endpoint into internal/admininfo Keeps AdminInfo out of the root caddy package's public API. The module is registered via a blank import in modules/standard, since the root package can't import it without an import cycle. Co-Authored-By: Claude Opus 5.5 --- .../admininfo/admininfo.go | 24 ++++++++++--------- .../admininfo/admininfo_test.go | 6 +++-- modules/standard/imports.go | 1 + 3 files changed, 18 insertions(+), 13 deletions(-) rename admin_info.go => internal/admininfo/admininfo.go (82%) rename admin_info_test.go => internal/admininfo/admininfo_test.go (96%) diff --git a/admin_info.go b/internal/admininfo/admininfo.go similarity index 82% rename from admin_info.go rename to internal/admininfo/admininfo.go index 0231475e5..663c88ce9 100644 --- a/admin_info.go +++ b/internal/admininfo/admininfo.go @@ -12,17 +12,19 @@ // See the License for the specific language governing permissions and // limitations under the License. -package caddy +package admininfo import ( "encoding/json" "net/http" "runtime" "runtime/debug" + + "github.com/caddyserver/caddy/v2" ) func init() { - RegisterModule(AdminInfo{}) + caddy.RegisterModule(AdminInfo{}) } // AdminInfo is a module that provides a GET /info endpoint on the @@ -31,17 +33,17 @@ func init() { type AdminInfo struct{} // CaddyModule returns the Caddy module information. -func (AdminInfo) CaddyModule() ModuleInfo { - return ModuleInfo{ +func (AdminInfo) CaddyModule() caddy.ModuleInfo { + return caddy.ModuleInfo{ ID: "admin.api.info", - New: func() Module { return new(AdminInfo) }, + New: func() caddy.Module { return new(AdminInfo) }, } } // Routes returns a route for the /info endpoint. -func (ai AdminInfo) Routes() []AdminRoute { - return []AdminRoute{ - {Pattern: "/info", Handler: AdminHandlerFunc(ai.handleInfo)}, +func (ai AdminInfo) Routes() []caddy.AdminRoute { + return []caddy.AdminRoute{ + {Pattern: "/info", Handler: caddy.AdminHandlerFunc(ai.handleInfo)}, } } @@ -58,13 +60,13 @@ type infoResponse struct { func (AdminInfo) handleInfo(w http.ResponseWriter, r *http.Request) error { if r.Method != http.MethodGet { w.Header().Set("Allow", http.MethodGet) - return APIError{ + return caddy.APIError{ HTTPStatus: http.StatusMethodNotAllowed, Message: "method not allowed", } } - simple, full := Version() + simple, full := caddy.Version() resp := infoResponse{ Version: simple, @@ -89,4 +91,4 @@ func (AdminInfo) handleInfo(w http.ResponseWriter, r *http.Request) error { } // Interface guards -var _ AdminRouter = (*AdminInfo)(nil) +var _ caddy.AdminRouter = (*AdminInfo)(nil) diff --git a/admin_info_test.go b/internal/admininfo/admininfo_test.go similarity index 96% rename from admin_info_test.go rename to internal/admininfo/admininfo_test.go index 96dc18bd4..05a4aa8e8 100644 --- a/admin_info_test.go +++ b/internal/admininfo/admininfo_test.go @@ -12,7 +12,7 @@ // See the License for the specific language governing permissions and // limitations under the License. -package caddy +package admininfo import ( "encoding/json" @@ -20,6 +20,8 @@ import ( "net/http/httptest" "runtime" "testing" + + "github.com/caddyserver/caddy/v2" ) func TestAdminInfoModule(t *testing.T) { @@ -83,7 +85,7 @@ func TestAdminInfoHandler(t *testing.T) { if err == nil { t.Fatal("expected error for POST method") } - apiErr, ok := err.(APIError) + apiErr, ok := err.(caddy.APIError) if !ok { t.Fatalf("expected APIError, got %T", err) } diff --git a/modules/standard/imports.go b/modules/standard/imports.go index 813c63d6c..58e32cd86 100644 --- a/modules/standard/imports.go +++ b/modules/standard/imports.go @@ -3,6 +3,7 @@ package standard import ( // standard Caddy modules _ "github.com/caddyserver/caddy/v2/caddyconfig/caddyfile" + _ "github.com/caddyserver/caddy/v2/internal/admininfo" _ "github.com/caddyserver/caddy/v2/modules/caddyevents" _ "github.com/caddyserver/caddy/v2/modules/caddyevents/eventsconfig" _ "github.com/caddyserver/caddy/v2/modules/caddyfs" From cde3e1d772b570f695e740a9dd0172e579dc053b Mon Sep 17 00:00:00 2001 From: Zack Wagner Date: Sat, 10 Oct 2026 15:33:40 -0400 Subject: [PATCH 4/4] admin: limit /info build_settings to VCS metadata and document fields Only expose vcs.revision, vcs.time, and vcs.modified from the embedded build info. Other settings vary by toolchain and can contain local paths or values injected via ldflags, so they are not a stable API contract. Document each response field as part of the admin API contract. Co-Authored-By: Claude Opus 5.5 --- internal/admininfo/admininfo.go | 62 ++++++++++++++++++++++------ internal/admininfo/admininfo_test.go | 45 ++++++++++++++++++++ 2 files changed, 94 insertions(+), 13 deletions(-) diff --git a/internal/admininfo/admininfo.go b/internal/admininfo/admininfo.go index 663c88ce9..25f4c0d46 100644 --- a/internal/admininfo/admininfo.go +++ b/internal/admininfo/admininfo.go @@ -19,6 +19,7 @@ import ( "net/http" "runtime" "runtime/debug" + "slices" "github.com/caddyserver/caddy/v2" ) @@ -47,16 +48,41 @@ func (ai AdminInfo) Routes() []caddy.AdminRoute { } } -// infoResponse is the JSON structure returned by GET /info. +// infoResponse is the JSON structure returned by GET /info. Its +// fields are part of the admin API contract. type infoResponse struct { - Version string `json:"version"` - VersionFull string `json:"version_full"` - GoVersion string `json:"go_version"` - OS string `json:"os"` - Arch string `json:"arch"` + // Version is the short version string, as printed by `caddy version`. + Version string `json:"version"` + + // VersionFull is the full version string, which may include + // the module checksum. + VersionFull string `json:"version_full"` + + // GoVersion is the Go toolchain version used to build Caddy. + GoVersion string `json:"go_version"` + + // OS is the target operating system. + OS string `json:"os"` + + // Arch is the target architecture. + Arch string `json:"arch"` + + // BuildSettings contains the VCS metadata embedded at build time, + // limited to the keys in exposedBuildSettings. It is omitted when + // unavailable, such as for builds made with `go install` or xcaddy. BuildSettings map[string]string `json:"build_settings,omitempty"` } +// exposedBuildSettings lists the build setting keys included in the +// response. Other settings, such as compiler and linker flags, vary +// by toolchain and may contain local paths or injected values, so +// they are not exposed. +var exposedBuildSettings = []string{ + "vcs.revision", + "vcs.time", + "vcs.modified", +} + func (AdminInfo) handleInfo(w http.ResponseWriter, r *http.Request) error { if r.Method != http.MethodGet { w.Header().Set("Allow", http.MethodGet) @@ -77,18 +103,28 @@ func (AdminInfo) handleInfo(w http.ResponseWriter, r *http.Request) error { } if bi, ok := debug.ReadBuildInfo(); ok { - settings := make(map[string]string) - for _, s := range bi.Settings { - settings[s.Key] = s.Value - } - if len(settings) > 0 { - resp.BuildSettings = settings - } + resp.BuildSettings = filterBuildSettings(bi.Settings) } w.Header().Set("Content-Type", "application/json") return json.NewEncoder(w).Encode(resp) } +// filterBuildSettings returns the settings whose keys are in +// exposedBuildSettings, or nil if there are none. +func filterBuildSettings(settings []debug.BuildSetting) map[string]string { + var filtered map[string]string + for _, s := range settings { + if !slices.Contains(exposedBuildSettings, s.Key) { + continue + } + if filtered == nil { + filtered = make(map[string]string) + } + filtered[s.Key] = s.Value + } + return filtered +} + // Interface guards var _ caddy.AdminRouter = (*AdminInfo)(nil) diff --git a/internal/admininfo/admininfo_test.go b/internal/admininfo/admininfo_test.go index 05a4aa8e8..ddbcaa147 100644 --- a/internal/admininfo/admininfo_test.go +++ b/internal/admininfo/admininfo_test.go @@ -16,9 +16,11 @@ package admininfo import ( "encoding/json" + "maps" "net/http" "net/http/httptest" "runtime" + "runtime/debug" "testing" "github.com/caddyserver/caddy/v2" @@ -97,3 +99,46 @@ func TestAdminInfoHandler(t *testing.T) { } }) } + +func TestFilterBuildSettings(t *testing.T) { + for i, tc := range []struct { + input []debug.BuildSetting + expected map[string]string + }{ + { + input: nil, + expected: nil, + }, + { + input: []debug.BuildSetting{ + {Key: "-ldflags", Value: "-X main.secret=hunter2"}, + {Key: "CGO_CFLAGS", Value: "-I/home/user/include"}, + {Key: "GOOS", Value: "linux"}, + }, + expected: nil, + }, + { + input: []debug.BuildSetting{ + {Key: "-buildmode", Value: "exe"}, + {Key: "CGO_ENABLED", Value: "1"}, + {Key: "vcs", Value: "git"}, + {Key: "vcs.revision", Value: "abc123"}, + {Key: "vcs.time", Value: "2025-07-01T12:00:00Z"}, + {Key: "vcs.modified", Value: "false"}, + }, + expected: map[string]string{ + "vcs.revision": "abc123", + "vcs.time": "2025-07-01T12:00:00Z", + "vcs.modified": "false", + }, + }, + } { + actual := filterBuildSettings(tc.input) + if !maps.Equal(actual, tc.expected) { + t.Errorf("Test %d: expected %v, got %v", i, tc.expected, actual) + } + if tc.expected == nil && actual != nil { + t.Errorf("Test %d: expected nil map, got %v", i, actual) + } + } +}