{
  "repo": "tidbcloud/VictoriaMetrics",
  "binary": "vmauth",
  "binary_path": "app/vmauth/main.go",
  "surface_kind": "mixed_service",
  "services": [
    {
      "name": "VMAuthLifecycle",
      "package": "main",
      "methods": [
        {
          "name": "DryRunValidateConfig",
          "name_key": "VMAuthLifecycle.DryRunValidateConfig",
          "input": "auth.config flag",
          "output": "validated auth config and immediate process exit",
          "type": "local"
        },
        {
          "name": "Startup",
          "name_key": "VMAuthLifecycle.Startup",
          "input": "flags + environment variables",
          "output": "initialized auth config, optional internal listener, main listener, and pushmetrics loop",
          "type": "local"
        },
        {
          "name": "InitializeAuthConfig",
          "name_key": "VMAuthLifecycle.InitializeAuthConfig",
          "input": "auth.config + configCheckInterval + auth-related flags",
          "output": "loaded auth config, initialized per-user routing state, and running auth-config reloader goroutine",
          "type": "local"
        },
        {
          "name": "RunAuthConfigReloader",
          "name_key": "VMAuthLifecycle.RunAuthConfigReloader",
          "input": "SIGHUP notifications + optional configCheckInterval ticker",
          "output": "background auth-config refresh loop",
          "type": "local"
        },
        {
          "name": "StartMainHTTPServer",
          "name_key": "VMAuthLifecycle.StartMainHTTPServer",
          "input": "httpListenAddr + optional proxy-protocol + httpInternalListenAddr",
          "output": "main listener serving proxy traffic and, when no separate internal listener exists, builtin/control routes",
          "type": "local"
        },
        {
          "name": "StartInternalHTTPServer",
          "name_key": "VMAuthLifecycle.StartInternalHTTPServer",
          "input": "httpInternalListenAddr",
          "output": "optional internal listener serving builtin and control routes separately from proxy traffic",
          "type": "local"
        },
        {
          "name": "InitializePushMetrics",
          "name_key": "VMAuthLifecycle.InitializePushMetrics",
          "input": "pushmetrics flags",
          "output": "optional pushmetrics loop",
          "type": "local"
        },
        {
          "name": "WaitForSigterm",
          "name_key": "VMAuthLifecycle.WaitForSigterm",
          "input": "SIGINT or SIGTERM",
          "output": "shutdown trigger",
          "type": "local"
        },
        {
          "name": "StopPushMetrics",
          "name_key": "VMAuthLifecycle.StopPushMetrics",
          "input": "shutdown signal",
          "output": "terminated pushmetrics loop",
          "type": "local"
        },
        {
          "name": "StopMainHTTPServer",
          "name_key": "VMAuthLifecycle.StopMainHTTPServer",
          "input": "httpListenAddr list",
          "output": "gracefully stopped main listeners",
          "type": "local"
        },
        {
          "name": "StopAuthConfig",
          "name_key": "VMAuthLifecycle.StopAuthConfig",
          "input": "reloader goroutine state",
          "output": "stopped auth-config reloader",
          "type": "local"
        }
      ]
    },
    {
      "name": "VMAuthControlHTTP",
      "type": "http",
      "methods": [
        {
          "name": "ANY /-/reload",
          "name_key": "HTTP ANY /-/reload",
          "input": "reload request with authKey query parameter",
          "output": "200 OK and self-triggered SIGHUP reload",
          "path": "/-/reload",
          "type": "http"
        }
      ]
    },
    {
      "name": "VMAuthBuiltinHTTP",
      "type": "http",
      "methods": [
        {
          "name": "GET /health",
          "name_key": "HTTP GET /health",
          "input": "none",
          "output": "health response from lib/httpserver",
          "path": "/health",
          "type": "http"
        },
        {
          "name": "ANY /ping",
          "name_key": "HTTP ANY /ping",
          "input": "none",
          "output": "ping response from lib/httpserver",
          "path": "/ping",
          "type": "http"
        },
        {
          "name": "GET /metrics",
          "name_key": "HTTP GET /metrics",
          "input": "optional metricsAuthKey",
          "output": "Prometheus metrics for vmauth",
          "path": "/metrics",
          "type": "http"
        },
        {
          "name": "GET /-/healthy",
          "name_key": "HTTP GET /-/healthy",
          "input": "none",
          "output": "healthy response from lib/httpserver",
          "path": "/-/healthy",
          "type": "http"
        },
        {
          "name": "GET /-/ready",
          "name_key": "HTTP GET /-/ready",
          "input": "none",
          "output": "ready response from lib/httpserver",
          "path": "/-/ready",
          "type": "http"
        },
        {
          "name": "GET /debug/pprof/*",
          "name_key": "HTTP GET /debug/pprof/*",
          "input": "optional pprofAuthKey",
          "output": "pprof diagnostics from lib/httpserver",
          "path": "/debug/pprof/*",
          "type": "http"
        },
        {
          "name": "GET */favicon.ico",
          "name_key": "HTTP GET /favicon.ico",
          "input": "favicon request",
          "output": "built-in favicon response",
          "path": "/favicon.ico",
          "type": "http"
        }
      ]
    },
    {
      "name": "VMAuthProxy",
      "package": "main",
      "methods": [
        {
          "name": "ServeUnauthorizedProxyRequest",
          "name_key": "VMAuthProxy.ServeUnauthorizedProxyRequest",
          "input": "request without auth token",
          "output": "proxied response via unauthorized_user routing or delegated auth error",
          "type": "http_proxy"
        },
        {
          "name": "RejectMissingAuthorization",
          "name_key": "VMAuthProxy.RejectMissingAuthorization",
          "input": "request without auth token and without unauthorized_user fallback",
          "output": "401 Unauthorized with WWW-Authenticate header",
          "type": "local"
        },
        {
          "name": "RejectInvalidAuthToken",
          "name_key": "VMAuthProxy.RejectInvalidAuthToken",
          "input": "request with auth token that matches no configured user",
          "output": "401 Unauthorized and invalid-token metric increment",
          "type": "local"
        },
        {
          "name": "ProcessUserRequest",
          "name_key": "VMAuthProxy.ProcessUserRequest",
          "input": "request plus matched user or unauthorized_user config",
          "output": "concurrency-limited proxy attempt or 429 rejection",
          "type": "http_proxy"
        },
        {
          "name": "MatchConfiguredRoute",
          "name_key": "VMAuthProxy.MatchConfiguredRoute",
          "input": "normalized URL + host + headers",
          "output": "matched url_map route or user-level url_prefix",
          "type": "local"
        },
        {
          "name": "ServeDefaultRoute",
          "name_key": "VMAuthProxy.ServeDefaultRoute",
          "input": "request that matched no explicit url_map entry",
          "output": "request proxied to default_url with request_path query arg or missing-route error",
          "type": "http_proxy"
        },
        {
          "name": "DiscoverBackendAddrs",
          "name_key": "VMAuthProxy.DiscoverBackendAddrs",
          "input": "url_prefix hosts with discover_backend_ips enabled",
          "output": "resolved backend IP or SRV address set",
          "type": "local"
        },
        {
          "name": "ProxyToBackend",
          "name_key": "VMAuthProxy.ProxyToBackend",
          "input": "prepared backend request, selected headers, and retry state",
          "output": "proxied backend response or retry decision",
          "type": "http_proxy"
        },
        {
          "name": "RetrySameBackendOnTrivialNetworkError",
          "name_key": "VMAuthProxy.RetrySameBackendOnTrivialNetworkError",
          "input": "retryable request body and trivial network error",
          "output": "single local retry against the same backend URL",
          "type": "http_proxy"
        },
        {
          "name": "RetryDifferentBackendOnRetryStatus",
          "name_key": "VMAuthProxy.RetryDifferentBackendOnRetryStatus",
          "input": "retryable request body and backend response status matching retry_status_codes",
          "output": "retry against another backend URL",
          "type": "http_proxy"
        },
        {
          "name": "ReturnBackendUnavailable",
          "name_key": "VMAuthProxy.ReturnBackendUnavailable",
          "input": "all candidate backends exhausted or marked broken",
          "output": "502 Bad Gateway",
          "type": "local"
        }
      ]
    }
  ],
  "extensions": {
    "notes": [
      "The previous app-vmauth interface used the legacy endpoint/blob schema and collapsed the runtime into HTTPProxyAPI.* plus ProxyService.*.",
      "The fresh interface models vmauth as a deployable proxy binary with separate lifecycle, control route, builtin httpserver routes, and logical proxy methods for routing, retry, and backend discovery.",
      "The same builtin and control routes move between listeners depending on httpInternalListenAddr: they are served on the main listener when no internal listener is configured, and on the internal listener otherwise.",
      "The main proxy surface is request-driven rather than path-enumerated; runtime truth comes from auth token resolution, url_map/default_url matching, backend discovery, and retry branches instead of a static REST route table."
    ]
  }
}