diff --git a/internal/admininfo/admininfo.go b/internal/admininfo/admininfo.go new file mode 100644 index 000000000..25f4c0d46 --- /dev/null +++ b/internal/admininfo/admininfo.go @@ -0,0 +1,130 @@ +// 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 admininfo + +import ( + "encoding/json" + "net/http" + "runtime" + "runtime/debug" + "slices" + + "github.com/caddyserver/caddy/v2" +) + +func init() { + caddy.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() caddy.ModuleInfo { + return caddy.ModuleInfo{ + ID: "admin.api.info", + New: func() caddy.Module { return new(AdminInfo) }, + } +} + +// Routes returns a route for the /info endpoint. +func (ai AdminInfo) Routes() []caddy.AdminRoute { + return []caddy.AdminRoute{ + {Pattern: "/info", Handler: caddy.AdminHandlerFunc(ai.handleInfo)}, + } +} + +// infoResponse is the JSON structure returned by GET /info. Its +// fields are part of the admin API contract. +type infoResponse struct { + // 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) + return caddy.APIError{ + HTTPStatus: http.StatusMethodNotAllowed, + Message: "method not allowed", + } + } + + simple, full := caddy.Version() + + resp := infoResponse{ + Version: simple, + VersionFull: full, + GoVersion: runtime.Version(), + OS: runtime.GOOS, + Arch: runtime.GOARCH, + } + + if bi, ok := debug.ReadBuildInfo(); ok { + 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 new file mode 100644 index 000000000..ddbcaa147 --- /dev/null +++ b/internal/admininfo/admininfo_test.go @@ -0,0 +1,144 @@ +// 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 admininfo + +import ( + "encoding/json" + "maps" + "net/http" + "net/http/httptest" + "runtime" + "runtime/debug" + "testing" + + "github.com/caddyserver/caddy/v2" +) + +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.(caddy.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) + } + if allow := rec.Header().Get("Allow"); allow != http.MethodGet { + t.Errorf("expected Allow header %q, got %q", http.MethodGet, allow) + } + }) +} + +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) + } + } +} 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"