Documentation
¶
Overview ¶
Package api wraps HTTP calls to the DBGorilla backend.
v0.1.0 surface is minimal -- only the endpoints needed for login, identity lookup, and MCP API key management. All requests carry a Bearer token from the keychain when one is present; refresh-on-401 happens automatically via the refresh token if available.
Security notes:
- When the client is not in insecure mode, the redirect policy refuses to follow a redirect that would downgrade to a non-https URL. This prevents a malicious server from steering a Bearer-bearing request to plaintext (which Go's stdlib already strips Authorization on for cross-host redirects, but a same-host http downgrade would still expose other custom headers).
- The User-Agent advertises the CLI version so backend abuse-detection and forensic logs can identify the client.
Index ¶
- Variables
- func SetUserAgentVersion(v string)
- type Client
- func (c *Client) CollectorSupported() (bool, error)
- func (c *Client) DeleteCollector(agentID string) error
- func (c *Client) Do(method, path string, body any) ([]byte, int, error)
- func (c *Client) FetchCollectorStatus(agentID string) (*CollectorStatus, error)
- func (c *Client) Get(path string) ([]byte, int, error)
- func (c *Client) ListCollectors() ([]map[string]any, error)
- func (c *Client) Post(path string, body any) ([]byte, int, error)
- func (c *Client) ProvisionCollector() (*CollectorCredentials, error)
- type CollectorCredentials
- type CollectorStatus
- type ErrorResponse
- type UserInfo
Constants ¶
This section is empty.
Variables ¶
var ErrCollectorUnsupported = errors.New("this deployment does not support the managed collector (needs a main-based backend)")
ErrCollectorUnsupported is returned when the deployment has no managed collector API (the release line, or a backend predating v0_2).
Functions ¶
func SetUserAgentVersion ¶
func SetUserAgentVersion(v string)
SetUserAgentVersion lets cmd inject the build-time version string into the User-Agent header at startup. Safe to call from any goroutine before the first request.
Types ¶
type Client ¶
Client wraps HTTP calls to the DBGorilla backend API.
func NewInsecureClient ¶
NewInsecureClient skips TLS certificate verification. Use only for internal/dev environments with self-signed certs.
func (*Client) CollectorSupported ¶ added in v0.2.0
CollectorSupported probes whether the deployment exposes the v0_2 collector API. A 404 means unsupported (release line); any other reachable status (including auth challenges) means the route exists.
func (*Client) DeleteCollector ¶ added in v0.2.0
DeleteCollector deprovisions a collector identity; its credentials stop working immediately. A 404 is treated as already-gone (idempotent).
func (*Client) Do ¶
Do performs an authenticated HTTP request. Returns the response body bytes, status code, and any error.
func (*Client) FetchCollectorStatus ¶ added in v0.2.0
func (c *Client) FetchCollectorStatus(agentID string) (*CollectorStatus, error)
FetchCollectorStatus calls GET /api/v0_2/collectors/{id}/status. A 404 maps to (nil, nil) — the collector is not known to the control plane yet.
func (*Client) ListCollectors ¶ added in v0.2.0
ListCollectors returns the tenant's collector agents. The bridge's AgentPage envelope key isn't pinned, so we accept the common shapes (items/agents/data) or a bare array and return the records as generic maps for display.
func (*Client) ProvisionCollector ¶ added in v0.2.0
func (c *Client) ProvisionCollector() (*CollectorCredentials, error)
ProvisionCollector mints a new collector identity. The caller's user token authorizes the mint; the backend (via the dbg-ingest bridge) creates the Keycloak client and returns its credentials.
type CollectorCredentials ¶ added in v0.2.0
type CollectorCredentials struct {
AgentID string `json:"agent_id"`
Secret string `json:"secret"`
TenantID string `json:"tenant_id"`
Domain string `json:"domain"`
// Optional per-service endpoints (contract agreed with backend; populated
// only for non-prod/self-hosted deployments). Empty -> the collector uses
// its built-in production defaults.
//
// AuthBaseURL is the auth host base (OIDC/OAuth2 token issuer). KeycloakBaseURL
// is the deprecated former name, still read as a fallback for deployments that
// predate the rename; use AuthHost() to resolve the effective value.
AuthBaseURL string `json:"auth_base_url,omitempty"`
KeycloakBaseURL string `json:"keycloak_base_url,omitempty"`
OtlpBaseURL string `json:"otlp_base_url,omitempty"`
OpampBaseURL string `json:"opamp_base_url,omitempty"`
// PreferredCollectorVersion is the collector version the deployment blesses
// for this environment (e.g. "0.1.0"). Empty -> the CLI uses its built-in
// default image. The CLI pins this version unless --image overrides it.
PreferredCollectorVersion string `json:"preferred_collector_version,omitempty"`
}
CollectorCredentials is the response from POST /api/v0_2/collectors. The secret is returned exactly once. agent_id is the OAuth client_id; domain is the deployment domain for the collector's endpoints.
func (CollectorCredentials) AuthHost ¶ added in v0.3.1
func (c CollectorCredentials) AuthHost() string
AuthHost returns the collector's auth host base, preferring auth_base_url and falling back to the deprecated keycloak_base_url for deployments that predate the rename. Empty -> the collector uses its built-in production default.
type CollectorStatus ¶ added in v0.2.0
CollectorStatus returns the live connection status for a collector. The shape is the dbg-ingest bridge StatusResponse, passed through; we surface the raw JSON plus a best-effort status string.
type ErrorResponse ¶
type ErrorResponse struct {
Detail string `json:"detail"`
}
ErrorResponse is the standard FastAPI error response.
type UserInfo ¶
type UserInfo struct {
Username string `json:"username"`
Email string `json:"email"`
Tenant string `json:"tenant"`
UserID string `json:"user_id"`
TenantID string `json:"tenant_id"`
IsAdmin bool `json:"is_admin"`
IsSystemTenant bool `json:"is_system_tenant"`
}
UserInfo matches GET /api/v0_1/auth/user on backend release-202603.007. `tenant` is the organization display name; `tenant_id` is the UUID.
Source Files