nathan/vctp2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update docs
continuous-integration/drone/push Build is passing
Details

Browse Source
This commit is contained in:
Nathan Coad
2026-04-17 14:00:48 +10:00
parent ae3e2be89a
commit 7848557002
32 changed files with 1226 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files
server/router/auth_integration_test.go
+190
View File
@@ -0,0 +1,190 @@
package router
import (
"encoding/base64"
"encoding/json"
"io"
"log/slog"
"net/http"
"net/http/httptest"
"strings"
"testing"
"time"
"vctp/internal/auth"
"vctp/internal/secrets"
"vctp/internal/settings"
)
func TestProtectedRoutesRequireAuthentication(t *testing.T) {
cfg := testRouterSettings(t, false)
app := testRouter(t, cfg)
tests := []struct {
name string
method string
path string
body string
}{
{
name: "auth me",
method: http.MethodGet,
path: "/api/auth/me",
},
{
name: "viewer route",
method: http.MethodGet,
path: "/api/report/snapshot",
},
{
name: "admin route",
method: http.MethodPost,
path: "/api/encrypt",
body: `{"plaintext":"hello"}`,
},
{
name: "legacy route",
method: http.MethodPost,
path: "/api/import/vm",
body: `{`,
},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
req := httptest.NewRequest(tc.method, tc.path, strings.NewReader(tc.body))
if tc.body != "" {
req.Header.Set("Content-Type", "application/json")
}
rr := httptest.NewRecorder()
app.ServeHTTP(rr, req)
if rr.Code != http.StatusUnauthorized {
t.Fatalf("expected status %d, got %d for %s %s", http.StatusUnauthorized, rr.Code, tc.method, tc.path)
}
})
}
}
func TestViewerCanReadButCannotMutate(t *testing.T) {
cfg := testRouterSettings(t, false)
app := testRouter(t, cfg)
viewerToken := mustIssueToken(t, cfg, "viewer-user", []string{"viewer"})
readReq := httptest.NewRequest(http.MethodGet, "/api/report/snapshot", nil)
readReq.Header.Set("Authorization", "Bearer "+viewerToken)
readRR := httptest.NewRecorder()
app.ServeHTTP(readRR, readReq)
if readRR.Code != http.StatusBadRequest {
t.Fatalf("expected viewer read to reach handler and return %d, got %d", http.StatusBadRequest, readRR.Code)
}
mutateReq := httptest.NewRequest(http.MethodPost, "/api/encrypt", strings.NewReader(`{"plaintext":"hello"}`))
mutateReq.Header.Set("Authorization", "Bearer "+viewerToken)
mutateReq.Header.Set("Content-Type", "application/json")
mutateRR := httptest.NewRecorder()
app.ServeHTTP(mutateRR, mutateReq)
if mutateRR.Code != http.StatusForbidden {
t.Fatalf("expected viewer mutate to return %d, got %d", http.StatusForbidden, mutateRR.Code)
}
}
func TestAdminCanMutate(t *testing.T) {
cfg := testRouterSettings(t, false)
app := testRouter(t, cfg)
adminToken := mustIssueToken(t, cfg, "admin-user", []string{"admin"})
req := httptest.NewRequest(http.MethodPost, "/api/encrypt", strings.NewReader(`{"plaintext":"hello"}`))
req.Header.Set("Authorization", "Bearer "+adminToken)
req.Header.Set("Content-Type", "application/json")
rr := httptest.NewRecorder()
app.ServeHTTP(rr, req)
if rr.Code != http.StatusOK {
t.Fatalf("expected admin mutate to return %d, got %d body=%s", http.StatusOK, rr.Code, rr.Body.String())
}
var payload map[string]string
if err := json.Unmarshal(rr.Body.Bytes(), &payload); err != nil {
t.Fatalf("failed to decode response: %v", err)
}
if payload["status"] != "OK" {
t.Fatalf("expected status OK, got %q", payload["status"])
}
if strings.TrimSpace(payload["ciphertext"]) == "" {
t.Fatal("expected ciphertext in response")
}
}
func TestLegacyEndpointGatingStillAppliesWithAuthEnabled(t *testing.T) {
disabledCfg := testRouterSettings(t, false)
disabledApp := testRouter(t, disabledCfg)
adminToken := mustIssueToken(t, disabledCfg, "admin-user", []string{"admin"})
disabledReq := httptest.NewRequest(http.MethodPost, "/api/import/vm", strings.NewReader(`{`))
disabledReq.Header.Set("Authorization", "Bearer "+adminToken)
disabledReq.Header.Set("Content-Type", "application/json")
disabledRR := httptest.NewRecorder()
disabledApp.ServeHTTP(disabledRR, disabledReq)
if disabledRR.Code != http.StatusGone {
t.Fatalf("expected legacy-disabled route to return %d, got %d", http.StatusGone, disabledRR.Code)
}
enabledCfg := testRouterSettings(t, true)
enabledApp := testRouter(t, enabledCfg)
enabledToken := mustIssueToken(t, enabledCfg, "admin-user", []string{"admin"})
enabledReq := httptest.NewRequest(http.MethodPost, "/api/import/vm", strings.NewReader(`{`))
enabledReq.Header.Set("Authorization", "Bearer "+enabledToken)
enabledReq.Header.Set("Content-Type", "application/json")
enabledRR := httptest.NewRecorder()
enabledApp.ServeHTTP(enabledRR, enabledReq)
if enabledRR.Code != http.StatusBadRequest {
t.Fatalf("expected legacy-enabled route to reach handler and return %d, got %d", http.StatusBadRequest, enabledRR.Code)
}
}
func testRouter(t *testing.T, cfg *settings.Settings) http.Handler {
t.Helper()
logger := testRouterLogger()
secretKey := []byte("0123456789abcdef0123456789abcdef")
secretSvc := secrets.New(logger, secretKey)
return New(logger, nil, "test-build", "test-sha", "go-test", nil, secretSvc, cfg)
}
func testRouterSettings(t *testing.T, enableLegacyAPI bool) *settings.Settings {
t.Helper()
cfg := &settings.Settings{Values: &settings.SettingsYML{}}
cfg.Values.Settings.AuthEnabled = true
cfg.Values.Settings.AuthMode = "required"
cfg.Values.Settings.AuthJWTSigningKey = base64.StdEncoding.EncodeToString([]byte("router-auth-test-signing-key"))
cfg.Values.Settings.AuthTokenLifespanMinutes = 120
cfg.Values.Settings.AuthJWTIssuer = "vctp"
cfg.Values.Settings.AuthJWTAudience = "vctp-api"
cfg.Values.Settings.AuthClockSkewSeconds = 60
cfg.Values.Settings.EnableLegacyAPI = enableLegacyAPI
cfg.Values.Settings.ReportsDir = t.TempDir()
return cfg
}
func mustIssueToken(t *testing.T, cfg *settings.Settings, subject string, roles []string) string {
t.Helper()
svc, err := auth.NewJWTService(auth.JWTConfig{
SigningKeyBase64: cfg.Values.Settings.AuthJWTSigningKey,
Issuer: cfg.Values.Settings.AuthJWTIssuer,
Audience: cfg.Values.Settings.AuthJWTAudience,
TokenLifespan: time.Duration(cfg.Values.Settings.AuthTokenLifespanMinutes) * time.Minute,
ClockSkew: time.Duration(cfg.Values.Settings.AuthClockSkewSeconds) * time.Second,
})
if err != nil {
t.Fatalf("failed to create jwt service: %v", err)
}
token, _, err := svc.IssueToken(subject, roles, nil)
if err != nil {
t.Fatalf("failed to issue token: %v", err)
}
return token
}
func testRouterLogger() *slog.Logger {
return slog.New(slog.NewTextHandler(io.Discard, nil))
}
server/router/docs/docs.go
+287 -25
View File
@@ -41,9 +41,103 @@ const docTemplate = `{
}
}
},
"/api/auth/login": {
"post": {
"description": "Authenticates a username/password against LDAP and returns a signed access token.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"auth"
],
"summary": "Login",
"parameters": [
{
"description": "Login credentials",
"name": "payload",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/models.AuthLoginRequest"
}
}
],
"responses": {
"200": {
"description": "Login success",
"schema": {
"$ref": "#/definitions/models.AuthLoginResponse"
}
},
"400": {
"description": "Invalid request",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
},
"401": {
"description": "Invalid credentials",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
},
"500": {
"description": "Server error",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
},
"503": {
"description": "Authentication disabled",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
}
}
}
},
"/api/auth/me": {
"get": {
"security": [
{
"BearerAuth": []
}
],
"description": "Returns JWT claims for the currently authenticated bearer token.\nRequires Bearer authentication.",
"produces": [
"application/json"
],
"tags": [
"auth"
],
"summary": "Who am I",
"responses": {
"200": {
"description": "Authenticated identity",
"schema": {
"$ref": "#/definitions/models.AuthMeResponse"
}
},
"401": {
"description": "Missing or invalid authentication context",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
}
}
}
},
"/api/cleanup/updates": {
"delete": {
"description": "Deprecated: Removes update records that are no longer associated with a VM.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Removes update records that are no longer associated with a VM.\nRequires Bearer authentication with the admin role.",
"produces": [
"text/plain"
],
@@ -106,7 +200,12 @@ const docTemplate = `{
},
"/api/diagnostics/daily-creation": {
"get": {
"description": "Returns counts of daily summary rows missing CreationTime and sample rows for the given date.",
"security": [
{
"BearerAuth": []
}
],
"description": "Returns counts of daily summary rows missing CreationTime and sample rows for the given date.\nRequires Bearer authentication with the viewer role (admin also allowed).",
"produces": [
"application/json"
],
@@ -153,7 +252,12 @@ const docTemplate = `{
},
"/api/encrypt": {
"post": {
"description": "Encrypts a plaintext value and returns the ciphertext.",
"security": [
{
"BearerAuth": []
}
],
"description": "Encrypts a plaintext value and returns the ciphertext.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -202,7 +306,12 @@ const docTemplate = `{
},
"/api/event/vm/create": {
"post": {
"description": "Deprecated: Parses a VM create CloudEvent and stores the event data.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Parses a VM create CloudEvent and stores the event data.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -249,7 +358,12 @@ const docTemplate = `{
},
"/api/event/vm/delete": {
"post": {
"description": "Deprecated: Parses a VM delete CloudEvent and marks the VM as deleted in inventory.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Parses a VM delete CloudEvent and marks the VM as deleted in inventory.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -296,7 +410,12 @@ const docTemplate = `{
},
"/api/event/vm/modify": {
"post": {
"description": "Deprecated: Parses a VM modify CloudEvent and creates an update record when relevant changes are detected.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Parses a VM modify CloudEvent and creates an update record when relevant changes are detected.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -343,7 +462,12 @@ const docTemplate = `{
},
"/api/event/vm/move": {
"post": {
"description": "Deprecated: Parses a VM move CloudEvent and creates an update record.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Parses a VM move CloudEvent and creates an update record.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -390,7 +514,12 @@ const docTemplate = `{
},
"/api/import/vm": {
"post": {
"description": "Deprecated: Imports existing VM inventory data in bulk.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Imports existing VM inventory data in bulk.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -431,7 +560,12 @@ const docTemplate = `{
},
"/api/inventory/vm/delete": {
"delete": {
"description": "Deprecated: Removes a VM inventory entry by VM ID and datacenter name.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Removes a VM inventory entry by VM ID and datacenter name.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -474,7 +608,12 @@ const docTemplate = `{
},
"/api/inventory/vm/update": {
"post": {
"description": "Deprecated: Queries vCenter and updates inventory records with missing details.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Queries vCenter and updates inventory records with missing details.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -501,7 +640,12 @@ const docTemplate = `{
},
"/api/report/inventory": {
"get": {
"description": "Generates an inventory XLSX report and returns it as a file download.",
"security": [
{
"BearerAuth": []
}
],
"description": "Generates an inventory XLSX report and returns it as a file download.\nRequires Bearer authentication with the viewer role (admin also allowed).",
"produces": [
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
],
@@ -527,7 +671,12 @@ const docTemplate = `{
},
"/api/report/snapshot": {
"get": {
"description": "Downloads a snapshot table as an XLSX file.",
"security": [
{
"BearerAuth": []
}
],
"description": "Downloads a snapshot table as an XLSX file.\nRequires Bearer authentication with the viewer role (admin also allowed).",
"produces": [
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
],
@@ -568,7 +717,12 @@ const docTemplate = `{
},
"/api/report/updates": {
"get": {
"description": "Generates an updates XLSX report and returns it as a file download.",
"security": [
{
"BearerAuth": []
}
],
"description": "Generates an updates XLSX report and returns it as a file download.\nRequires Bearer authentication with the viewer role (admin also allowed).",
"produces": [
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
],
@@ -594,7 +748,12 @@ const docTemplate = `{
},
"/api/snapshots/aggregate": {
"post": {
"description": "Forces regeneration of a daily or monthly summary table for a specified date or month.",
"security": [
{
"BearerAuth": []
}
],
"description": "Forces regeneration of a daily or monthly summary table for a specified date or month.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -648,7 +807,12 @@ const docTemplate = `{
},
"/api/snapshots/hourly/force": {
"post": {
"description": "Manually trigger an hourly snapshot for all configured vCenters. Requires confirmation text to avoid accidental execution.",
"security": [
{
"BearerAuth": []
}
],
"description": "Manually trigger an hourly snapshot for all configured vCenters. Requires confirmation text to avoid accidental execution.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -692,7 +856,12 @@ const docTemplate = `{
},
"/api/snapshots/migrate": {
"post": {
"description": "Rebuilds the snapshot registry from existing tables and renames hourly tables to epoch-based names.",
"security": [
{
"BearerAuth": []
}
],
"description": "Rebuilds the snapshot registry from existing tables and renames hourly tables to epoch-based names.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -718,7 +887,12 @@ const docTemplate = `{
},
"/api/snapshots/regenerate-hourly-reports": {
"post": {
"description": "Regenerates XLSX reports for hourly snapshots when the report files are missing or empty.",
"security": [
{
"BearerAuth": []
}
],
"description": "Regenerates XLSX reports for hourly snapshots when the report files are missing or empty.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -744,7 +918,12 @@ const docTemplate = `{
},
"/api/snapshots/repair": {
"post": {
"description": "Backfills SnapshotTime and lifecycle info for existing daily summary tables and reruns monthly lifecycle refinement using hourly data.",
"security": [
{
"BearerAuth": []
}
],
"description": "Backfills SnapshotTime and lifecycle info for existing daily summary tables and reruns monthly lifecycle refinement using hourly data.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -764,7 +943,12 @@ const docTemplate = `{
},
"/api/snapshots/repair/all": {
"post": {
"description": "Rebuilds snapshot registry, backfills per-vCenter totals, repairs daily summaries (SnapshotTime/lifecycle), and refines monthly lifecycle.",
"security": [
{
"BearerAuth": []
}
],
"description": "Rebuilds snapshot registry, backfills per-vCenter totals, repairs daily summaries (SnapshotTime/lifecycle), and refines monthly lifecycle.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -784,7 +968,12 @@ const docTemplate = `{
},
"/api/vcenters/cache/rebuild": {
"post": {
"description": "Rebuilds cached folder/resource-pool/host(cluster+datacenter) references from vCenter and rewrites the database cache tables.",
"security": [
{
"BearerAuth": []
}
],
"description": "Rebuilds cached folder/resource-pool/host(cluster+datacenter) references from vCenter and rewrites the database cache tables.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -1120,6 +1309,72 @@ const docTemplate = `{
}
},
"definitions": {
"models.AuthLoginRequest": {
"type": "object",
"properties": {
"password": {
"type": "string"
},
"username": {
"type": "string"
}
}
},
"models.AuthLoginResponse": {
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"expires_at": {
"type": "integer"
},
"token_type": {
"type": "string"
}
}
},
"models.AuthMeResponse": {
"type": "object",
"properties": {
"audience": {
"type": "string"
},
"expires_at": {
"type": "integer"
},
"groups": {
"type": "array",
"items": {
"type": "string"
}
},
"issued_at": {
"type": "integer"
},
"issuer": {
"type": "string"
},
"not_before": {
"type": "integer"
},
"roles": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string"
},
"subject": {
"type": "string"
},
"token_id": {
"type": "string"
}
}
},
"models.CloudEventReceived": {
"type": "object",
"properties": {
@@ -1613,17 +1868,24 @@ const docTemplate = `{
}
}
}
},
"securityDefinitions": {
"BearerAuth": {
"type": "apiKey",
"name": "Authorization",
"in": "header"
}
}
}`
// SwaggerInfo holds exported Swagger Info so clients can modify it
var SwaggerInfo = &swag.Spec{
Version: "",
Version: "1.0",
Host: "",
BasePath: "",
Schemes: []string{},
Title: "",
Description: "",
BasePath: "/",
Schemes: []string{"http", "https"},
Title: "vCTP API",
Description: "vCTP API endpoints for inventory snapshots, reporting, and administration.",
InfoInstanceName: "swagger",
SwaggerTemplate: docTemplate,
LeftDelim: "{{",
server/router/docs/swagger.json
+291 -21
View File
@@ -1,8 +1,16 @@
{
"schemes": [
"http",
"https"
],
"swagger": "2.0",
"info": {
"contact": {}
"description": "vCTP API endpoints for inventory snapshots, reporting, and administration.",
"title": "vCTP API",
"contact": {},
"version": "1.0"
},
"basePath": "/",
"paths": {
"/": {
"get": {
@@ -30,9 +38,103 @@
}
}
},
"/api/auth/login": {
"post": {
"description": "Authenticates a username/password against LDAP and returns a signed access token.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"auth"
],
"summary": "Login",
"parameters": [
{
"description": "Login credentials",
"name": "payload",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/models.AuthLoginRequest"
}
}
],
"responses": {
"200": {
"description": "Login success",
"schema": {
"$ref": "#/definitions/models.AuthLoginResponse"
}
},
"400": {
"description": "Invalid request",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
},
"401": {
"description": "Invalid credentials",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
},
"500": {
"description": "Server error",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
},
"503": {
"description": "Authentication disabled",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
}
}
}
},
"/api/auth/me": {
"get": {
"security": [
{
"BearerAuth": []
}
],
"description": "Returns JWT claims for the currently authenticated bearer token.\nRequires Bearer authentication.",
"produces": [
"application/json"
],
"tags": [
"auth"
],
"summary": "Who am I",
"responses": {
"200": {
"description": "Authenticated identity",
"schema": {
"$ref": "#/definitions/models.AuthMeResponse"
}
},
"401": {
"description": "Missing or invalid authentication context",
"schema": {
"$ref": "#/definitions/models.ErrorResponse"
}
}
}
}
},
"/api/cleanup/updates": {
"delete": {
"description": "Deprecated: Removes update records that are no longer associated with a VM.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Removes update records that are no longer associated with a VM.\nRequires Bearer authentication with the admin role.",
"produces": [
"text/plain"
],
@@ -95,7 +197,12 @@
},
"/api/diagnostics/daily-creation": {
"get": {
"description": "Returns counts of daily summary rows missing CreationTime and sample rows for the given date.",
"security": [
{
"BearerAuth": []
}
],
"description": "Returns counts of daily summary rows missing CreationTime and sample rows for the given date.\nRequires Bearer authentication with the viewer role (admin also allowed).",
"produces": [
"application/json"
],
@@ -142,7 +249,12 @@
},
"/api/encrypt": {
"post": {
"description": "Encrypts a plaintext value and returns the ciphertext.",
"security": [
{
"BearerAuth": []
}
],
"description": "Encrypts a plaintext value and returns the ciphertext.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -191,7 +303,12 @@
},
"/api/event/vm/create": {
"post": {
"description": "Deprecated: Parses a VM create CloudEvent and stores the event data.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Parses a VM create CloudEvent and stores the event data.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -238,7 +355,12 @@
},
"/api/event/vm/delete": {
"post": {
"description": "Deprecated: Parses a VM delete CloudEvent and marks the VM as deleted in inventory.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Parses a VM delete CloudEvent and marks the VM as deleted in inventory.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -285,7 +407,12 @@
},
"/api/event/vm/modify": {
"post": {
"description": "Deprecated: Parses a VM modify CloudEvent and creates an update record when relevant changes are detected.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Parses a VM modify CloudEvent and creates an update record when relevant changes are detected.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -332,7 +459,12 @@
},
"/api/event/vm/move": {
"post": {
"description": "Deprecated: Parses a VM move CloudEvent and creates an update record.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Parses a VM move CloudEvent and creates an update record.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -379,7 +511,12 @@
},
"/api/import/vm": {
"post": {
"description": "Deprecated: Imports existing VM inventory data in bulk.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Imports existing VM inventory data in bulk.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -420,7 +557,12 @@
},
"/api/inventory/vm/delete": {
"delete": {
"description": "Deprecated: Removes a VM inventory entry by VM ID and datacenter name.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Removes a VM inventory entry by VM ID and datacenter name.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -463,7 +605,12 @@
},
"/api/inventory/vm/update": {
"post": {
"description": "Deprecated: Queries vCenter and updates inventory records with missing details.",
"security": [
{
"BearerAuth": []
}
],
"description": "Deprecated: Queries vCenter and updates inventory records with missing details.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -490,7 +637,12 @@
},
"/api/report/inventory": {
"get": {
"description": "Generates an inventory XLSX report and returns it as a file download.",
"security": [
{
"BearerAuth": []
}
],
"description": "Generates an inventory XLSX report and returns it as a file download.\nRequires Bearer authentication with the viewer role (admin also allowed).",
"produces": [
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
],
@@ -516,7 +668,12 @@
},
"/api/report/snapshot": {
"get": {
"description": "Downloads a snapshot table as an XLSX file.",
"security": [
{
"BearerAuth": []
}
],
"description": "Downloads a snapshot table as an XLSX file.\nRequires Bearer authentication with the viewer role (admin also allowed).",
"produces": [
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
],
@@ -557,7 +714,12 @@
},
"/api/report/updates": {
"get": {
"description": "Generates an updates XLSX report and returns it as a file download.",
"security": [
{
"BearerAuth": []
}
],
"description": "Generates an updates XLSX report and returns it as a file download.\nRequires Bearer authentication with the viewer role (admin also allowed).",
"produces": [
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
],
@@ -583,7 +745,12 @@
},
"/api/snapshots/aggregate": {
"post": {
"description": "Forces regeneration of a daily or monthly summary table for a specified date or month.",
"security": [
{
"BearerAuth": []
}
],
"description": "Forces regeneration of a daily or monthly summary table for a specified date or month.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -637,7 +804,12 @@
},
"/api/snapshots/hourly/force": {
"post": {
"description": "Manually trigger an hourly snapshot for all configured vCenters. Requires confirmation text to avoid accidental execution.",
"security": [
{
"BearerAuth": []
}
],
"description": "Manually trigger an hourly snapshot for all configured vCenters. Requires confirmation text to avoid accidental execution.\nRequires Bearer authentication with the admin role.",
"consumes": [
"application/json"
],
@@ -681,7 +853,12 @@
},
"/api/snapshots/migrate": {
"post": {
"description": "Rebuilds the snapshot registry from existing tables and renames hourly tables to epoch-based names.",
"security": [
{
"BearerAuth": []
}
],
"description": "Rebuilds the snapshot registry from existing tables and renames hourly tables to epoch-based names.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -707,7 +884,12 @@
},
"/api/snapshots/regenerate-hourly-reports": {
"post": {
"description": "Regenerates XLSX reports for hourly snapshots when the report files are missing or empty.",
"security": [
{
"BearerAuth": []
}
],
"description": "Regenerates XLSX reports for hourly snapshots when the report files are missing or empty.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -733,7 +915,12 @@
},
"/api/snapshots/repair": {
"post": {
"description": "Backfills SnapshotTime and lifecycle info for existing daily summary tables and reruns monthly lifecycle refinement using hourly data.",
"security": [
{
"BearerAuth": []
}
],
"description": "Backfills SnapshotTime and lifecycle info for existing daily summary tables and reruns monthly lifecycle refinement using hourly data.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -753,7 +940,12 @@
},
"/api/snapshots/repair/all": {
"post": {
"description": "Rebuilds snapshot registry, backfills per-vCenter totals, repairs daily summaries (SnapshotTime/lifecycle), and refines monthly lifecycle.",
"security": [
{
"BearerAuth": []
}
],
"description": "Rebuilds snapshot registry, backfills per-vCenter totals, repairs daily summaries (SnapshotTime/lifecycle), and refines monthly lifecycle.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -773,7 +965,12 @@
},
"/api/vcenters/cache/rebuild": {
"post": {
"description": "Rebuilds cached folder/resource-pool/host(cluster+datacenter) references from vCenter and rewrites the database cache tables.",
"security": [
{
"BearerAuth": []
}
],
"description": "Rebuilds cached folder/resource-pool/host(cluster+datacenter) references from vCenter and rewrites the database cache tables.\nRequires Bearer authentication with the admin role.",
"produces": [
"application/json"
],
@@ -1109,6 +1306,72 @@
}
},
"definitions": {
"models.AuthLoginRequest": {
"type": "object",
"properties": {
"password": {
"type": "string"
},
"username": {
"type": "string"
}
}
},
"models.AuthLoginResponse": {
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"expires_at": {
"type": "integer"
},
"token_type": {
"type": "string"
}
}
},
"models.AuthMeResponse": {
"type": "object",
"properties": {
"audience": {
"type": "string"
},
"expires_at": {
"type": "integer"
},
"groups": {
"type": "array",
"items": {
"type": "string"
}
},
"issued_at": {
"type": "integer"
},
"issuer": {
"type": "string"
},
"not_before": {
"type": "integer"
},
"roles": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string"
},
"subject": {
"type": "string"
},
"token_id": {
"type": "string"
}
}
},
"models.CloudEventReceived": {
"type": "object",
"properties": {
@@ -1602,5 +1865,12 @@
}
}
}
},
"securityDefinitions": {
"BearerAuth": {
"type": "apiKey",
"name": "Authorization",
"in": "header"
}
}
}
server/router/docs/swagger.yaml
+215 -35
View File
@@ -1,4 +1,48 @@
basePath: /
definitions:
models.AuthLoginRequest:
properties:
password:
type: string
username:
type: string
type: object
models.AuthLoginResponse:
properties:
access_token:
type: string
expires_at:
type: integer
token_type:
type: string
type: object
models.AuthMeResponse:
properties:
audience:
type: string
expires_at:
type: integer
groups:
items:
type: string
type: array
issued_at:
type: integer
issuer:
type: string
not_before:
type: integer
roles:
items:
type: string
type: array
status:
type: string
subject:
type: string
token_id:
type: string
type: object
models.CloudEventReceived:
properties:
cloudEvent:
@@ -320,6 +364,9 @@ definitions:
type: object
info:
contact: {}
description: vCTP API endpoints for inventory snapshots, reporting, and administration.
title: vCTP API
version: "1.0"
paths:
/:
get:
@@ -338,11 +385,72 @@ paths:
summary: Home page
tags:
- ui
/api/auth/login:
post:
consumes:
- application/json
description: Authenticates a username/password against LDAP and returns a signed
access token.
parameters:
- description: Login credentials
in: body
name: payload
required: true
schema:
$ref: '#/definitions/models.AuthLoginRequest'
produces:
- application/json
responses:
"200":
description: Login success
schema:
$ref: '#/definitions/models.AuthLoginResponse'
"400":
description: Invalid request
schema:
$ref: '#/definitions/models.ErrorResponse'
"401":
description: Invalid credentials
schema:
$ref: '#/definitions/models.ErrorResponse'
"500":
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
"503":
description: Authentication disabled
schema:
$ref: '#/definitions/models.ErrorResponse'
summary: Login
tags:
- auth
/api/auth/me:
get:
description: |-
Returns JWT claims for the currently authenticated bearer token.
Requires Bearer authentication.
produces:
- application/json
responses:
"200":
description: Authenticated identity
schema:
$ref: '#/definitions/models.AuthMeResponse'
"401":
description: Missing or invalid authentication context
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Who am I
tags:
- auth
/api/cleanup/updates:
delete:
deprecated: true
description: 'Deprecated: Removes update records that are no longer associated
with a VM.'
description: |-
Deprecated: Removes update records that are no longer associated with a VM.
Requires Bearer authentication with the admin role.
produces:
- text/plain
responses:
@@ -354,6 +462,8 @@ paths:
description: Server error
schema:
type: string
security:
- BearerAuth: []
summary: Cleanup updates (deprecated)
tags:
- maintenance
@@ -384,8 +494,9 @@ paths:
- maintenance
/api/diagnostics/daily-creation:
get:
description: Returns counts of daily summary rows missing CreationTime and sample
rows for the given date.
description: |-
Returns counts of daily summary rows missing CreationTime and sample rows for the given date.
Requires Bearer authentication with the viewer role (admin also allowed).
parameters:
- description: Daily date (YYYY-MM-DD)
in: query
@@ -411,6 +522,8 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Daily summary CreationTime diagnostics
tags:
- diagnostics
@@ -418,7 +531,9 @@ paths:
post:
consumes:
- application/json
description: Encrypts a plaintext value and returns the ciphertext.
description: |-
Encrypts a plaintext value and returns the ciphertext.
Requires Bearer authentication with the admin role.
parameters:
- description: Plaintext payload
in: body
@@ -443,6 +558,8 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Encrypt data
tags:
- crypto
@@ -451,8 +568,9 @@ paths:
consumes:
- application/json
deprecated: true
description: 'Deprecated: Parses a VM create CloudEvent and stores the event
data.'
description: |-
Deprecated: Parses a VM create CloudEvent and stores the event data.
Requires Bearer authentication with the admin role.
parameters:
- description: CloudEvent payload
in: body
@@ -475,6 +593,8 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Record VM create event (deprecated)
tags:
- events
@@ -483,8 +603,9 @@ paths:
consumes:
- application/json
deprecated: true
description: 'Deprecated: Parses a VM delete CloudEvent and marks the VM as
deleted in inventory.'
description: |-
Deprecated: Parses a VM delete CloudEvent and marks the VM as deleted in inventory.
Requires Bearer authentication with the admin role.
parameters:
- description: CloudEvent payload
in: body
@@ -507,6 +628,8 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Record VM delete event (deprecated)
tags:
- events
@@ -515,8 +638,9 @@ paths:
consumes:
- application/json
deprecated: true
description: 'Deprecated: Parses a VM modify CloudEvent and creates an update
record when relevant changes are detected.'
description: |-
Deprecated: Parses a VM modify CloudEvent and creates an update record when relevant changes are detected.
Requires Bearer authentication with the admin role.
parameters:
- description: CloudEvent payload
in: body
@@ -539,6 +663,8 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Record VM modify event (deprecated)
tags:
- events
@@ -547,8 +673,9 @@ paths:
consumes:
- application/json
deprecated: true
description: 'Deprecated: Parses a VM move CloudEvent and creates an update
record.'
description: |-
Deprecated: Parses a VM move CloudEvent and creates an update record.
Requires Bearer authentication with the admin role.
parameters:
- description: CloudEvent payload
in: body
@@ -571,6 +698,8 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Record VM move event (deprecated)
tags:
- events
@@ -579,7 +708,9 @@ paths:
consumes:
- application/json
deprecated: true
description: 'Deprecated: Imports existing VM inventory data in bulk.'
description: |-
Deprecated: Imports existing VM inventory data in bulk.
Requires Bearer authentication with the admin role.
parameters:
- description: Bulk import payload
in: body
@@ -598,14 +729,17 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Import VMs (deprecated)
tags:
- inventory
/api/inventory/vm/delete:
delete:
deprecated: true
description: 'Deprecated: Removes a VM inventory entry by VM ID and datacenter
name.'
description: |-
Deprecated: Removes a VM inventory entry by VM ID and datacenter name.
Requires Bearer authentication with the admin role.
parameters:
- description: VM ID
in: query
@@ -628,14 +762,17 @@ paths:
description: Invalid request
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Cleanup VM inventory entry (deprecated)
tags:
- inventory
/api/inventory/vm/update:
post:
deprecated: true
description: 'Deprecated: Queries vCenter and updates inventory records with
missing details.'
description: |-
Deprecated: Queries vCenter and updates inventory records with missing details.
Requires Bearer authentication with the admin role.
produces:
- application/json
responses:
@@ -647,12 +784,16 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Refresh VM details (deprecated)
tags:
- inventory
/api/report/inventory:
get:
description: Generates an inventory XLSX report and returns it as a file download.
description: |-
Generates an inventory XLSX report and returns it as a file download.
Requires Bearer authentication with the viewer role (admin also allowed).
produces:
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
responses:
@@ -664,12 +805,16 @@ paths:
description: Report generation failed
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Download inventory report
tags:
- reports
/api/report/snapshot:
get:
description: Downloads a snapshot table as an XLSX file.
description: |-
Downloads a snapshot table as an XLSX file.
Requires Bearer authentication with the viewer role (admin also allowed).
parameters:
- description: Snapshot table name
in: query
@@ -691,12 +836,16 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Download snapshot report
tags:
- snapshots
/api/report/updates:
get:
description: Generates an updates XLSX report and returns it as a file download.
description: |-
Generates an updates XLSX report and returns it as a file download.
Requires Bearer authentication with the viewer role (admin also allowed).
produces:
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
responses:
@@ -708,13 +857,16 @@ paths:
description: Report generation failed
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Download updates report
tags:
- reports
/api/snapshots/aggregate:
post:
description: Forces regeneration of a daily or monthly summary table for a specified
date or month.
description: |-
Forces regeneration of a daily or monthly summary table for a specified date or month.
Requires Bearer authentication with the admin role.
parameters:
- description: 'Aggregation type: daily or monthly'
in: query
@@ -745,6 +897,8 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Force snapshot aggregation
tags:
- snapshots
@@ -752,8 +906,9 @@ paths:
post:
consumes:
- application/json
description: Manually trigger an hourly snapshot for all configured vCenters.
Requires confirmation text to avoid accidental execution.
description: |-
Manually trigger an hourly snapshot for all configured vCenters. Requires confirmation text to avoid accidental execution.
Requires Bearer authentication with the admin role.
parameters:
- description: Confirmation text; must be 'FORCE'
in: query
@@ -775,13 +930,16 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Trigger hourly snapshot (manual)
tags:
- snapshots
/api/snapshots/migrate:
post:
description: Rebuilds the snapshot registry from existing tables and renames
hourly tables to epoch-based names.
description: |-
Rebuilds the snapshot registry from existing tables and renames hourly tables to epoch-based names.
Requires Bearer authentication with the admin role.
produces:
- application/json
responses:
@@ -793,13 +951,16 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.SnapshotMigrationResponse'
security:
- BearerAuth: []
summary: Migrate snapshot registry
tags:
- snapshots
/api/snapshots/regenerate-hourly-reports:
post:
description: Regenerates XLSX reports for hourly snapshots when the report files
are missing or empty.
description: |-
Regenerates XLSX reports for hourly snapshots when the report files are missing or empty.
Requires Bearer authentication with the admin role.
produces:
- application/json
responses:
@@ -811,13 +972,16 @@ paths:
description: Server error
schema:
$ref: '#/definitions/models.ErrorResponse'
security:
- BearerAuth: []
summary: Regenerate hourly snapshot reports
tags:
- snapshots
/api/snapshots/repair:
post:
description: Backfills SnapshotTime and lifecycle info for existing daily summary
tables and reruns monthly lifecycle refinement using hourly data.
description: |-
Backfills SnapshotTime and lifecycle info for existing daily summary tables and reruns monthly lifecycle refinement using hourly data.
Requires Bearer authentication with the admin role.
produces:
- application/json
responses:
@@ -825,13 +989,16 @@ paths:
description: OK
schema:
$ref: '#/definitions/models.SnapshotRepairResponse'
security:
- BearerAuth: []
summary: Repair daily summaries
tags:
- snapshots
/api/snapshots/repair/all:
post:
description: Rebuilds snapshot registry, backfills per-vCenter totals, repairs
daily summaries (SnapshotTime/lifecycle), and refines monthly lifecycle.
description: |-
Rebuilds snapshot registry, backfills per-vCenter totals, repairs daily summaries (SnapshotTime/lifecycle), and refines monthly lifecycle.
Requires Bearer authentication with the admin role.
produces:
- application/json
responses:
@@ -839,13 +1006,16 @@ paths:
description: OK
schema:
$ref: '#/definitions/models.SnapshotRepairSuiteResponse'
security:
- BearerAuth: []
summary: Run full snapshot repair suite
tags:
- snapshots
/api/vcenters/cache/rebuild:
post:
description: Rebuilds cached folder/resource-pool/host(cluster+datacenter) references
from vCenter and rewrites the database cache tables.
description: |-
Rebuilds cached folder/resource-pool/host(cluster+datacenter) references from vCenter and rewrites the database cache tables.
Requires Bearer authentication with the admin role.
parameters:
- description: Optional single vCenter URL to rebuild; defaults to all configured
vCenters
@@ -871,6 +1041,8 @@ paths:
description: All rebuild attempts failed
schema:
$ref: '#/definitions/models.VcenterCacheRebuildResponse'
security:
- BearerAuth: []
summary: Rebuild vCenter object cache
tags:
- vcenters
@@ -1069,4 +1241,12 @@ paths:
summary: Trace VM history
tags:
- vm
schemes:
- http
- https
securityDefinitions:
BearerAuth:
in: header
name: Authorization
type: apiKey
swagger: "2.0"
server/router/router.go
+4
View File
@@ -30,6 +30,9 @@ func New(logger *slog.Logger, database db.Database, buildTime string, sha1ver st
mux := http.NewServeMux()
requireAuth := middleware.RequireAuth(logger, settings)
withAuth := func(next http.HandlerFunc) http.Handler {
return requireAuth(http.HandlerFunc(next))
}
withAuthRole := func(next http.HandlerFunc, roles ...string) http.Handler {
wrapped := http.Handler(http.HandlerFunc(next))
if len(roles) > 0 {
@@ -78,6 +81,7 @@ func New(logger *slog.Logger, database db.Database, buildTime string, sha1ver st
mux.Handle("/api/snapshots/regenerate-hourly-reports", withAuthRole(h.SnapshotRegenerateHourlyReports, middleware.RoleAdmin))
mux.Handle("/api/diagnostics/daily-creation", withAuthRole(h.DailyCreationDiagnostics, middleware.RoleViewer))
mux.HandleFunc("/api/auth/login", h.AuthLogin)
mux.Handle("/api/auth/me", withAuth(h.AuthMe))
mux.HandleFunc("/vm/trace", h.VmTrace)
mux.HandleFunc("/vcenters", h.VcenterList)
mux.HandleFunc("/vcenters/totals", h.VcenterTotals)