Documentation
¶
Overview ¶
Package adminclient implements dmctl's internal HTTP access to the reference server admin API.
Design ¶
The client centralizes bearer authentication, bounded response reads, typed error handling and cursor iteration. Response bodies remain unchanged for machine-readable CLI output. Redirects are refused to keep credentials bound to the selected destination. Callers choose whether to fetch one page or iterate, and cancellation propagates through requests. Remote URLs require verified HTTPS. Plain HTTP is limited to literal loopback addresses; CAFile adds private trust and Insecure=true is rejected.
References ¶
- Decision record: https://github.com/deploymenttheory/go-apple-dm/blob/main/docs/research/decisions/0035-dmctl-structure-and-credentials.md
- Decision record: https://github.com/deploymenttheory/go-apple-dm/blob/main/docs/research/decisions/0034-admin-api-and-authorization.md
- RFC 6750: bearer token usage
Index ¶
- Constants
- Variables
- type Client
- func (c *Client) Do(ctx context.Context, method, path string, query url.Values, body any) (*Response, error)
- func (c *Client) Each(ctx context.Context, path string, query url.Values, ...) error
- func (c *Client) Page(ctx context.Context, path string, query url.Values) ([]jsontext.Value, string, error)
- func (c *Client) ServerConfig(ctx context.Context) (*ServerConfig, error)
- type Config
- type Response
- type Route
- type ServerConfig
Constants ¶
const DefaultTimeout = 30 * time.Second
DefaultTimeout bounds one request.
const MaxBody = 32 << 20
MaxBody bounds a response body, so a hostile or broken server cannot make the CLI buffer without limit.
const Prefix = "/admin/v1"
Prefix is the admin API root every path is relative to.
Variables ¶
var ( ErrUnauthorized = errors.New("adminclient: unauthorized") // ErrForbidden is a 403: authenticated, but no policy permits it. ErrForbidden = errors.New("adminclient: forbidden") // ErrNotFound is a 404, which on this API may also mean the route is not // served by the role the process is running. ErrNotFound = errors.New("adminclient: not found") // ErrStatus is any other unsuccessful status. ErrStatus = errors.New("adminclient: request failed") // ErrConfig is a malformed server URL or missing credential. ErrConfig = errors.New("adminclient: bad configuration") )
Errors callers distinguish.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client talks to one server.
func (*Client) Do ¶
func (c *Client) Do( ctx context.Context, method, path string, query url.Values, body any, ) (*Response, error)
Do issues one request. path is relative to the admin prefix, for example "/principals" or "/declarations/com.example.a".
func (*Client) Each ¶
func (c *Client) Each( ctx context.Context, path string, query url.Values, fn func(jsontext.Value) error, ) error
Each calls fn with each item's unchanged JSON, following NextCursor until exhausted. Request, decoding and callback errors stop iteration.
func (*Client) Page ¶
func (c *Client) Page( ctx context.Context, path string, query url.Values, ) ([]jsontext.Value, string, error)
Page fetches one page and returns its items and the next cursor.
func (*Client) ServerConfig ¶
func (c *Client) ServerConfig(ctx context.Context) (*ServerConfig, error)
ServerConfig fetches GET /config.
type Config ¶
type Config struct {
CAFile string
// BaseURL is the server root, without the admin prefix.
BaseURL string
// Token is the bearer credential.
Token string
// Timeout bounds one request; zero uses DefaultTimeout.
Timeout time.Duration
// Insecure is retained to report a configuration error to older callers.
// TLS verification cannot be disabled; configure CAFile for private trust.
Insecure bool
// HTTPClient overrides the transport, for tests.
HTTPClient *http.Client
// Trace receives one line per request, with the token never included.
Trace func(string)
}
Config builds a Client.
type Response ¶
Response is one admin API answer. Body is the server's bytes, unmodified, so canonical JSON and key order survive to whatever consumes them.
type Route ¶
type Route struct {
Method, Pattern, Action, Family string
}
Route is one entry of the server's route table.
type ServerConfig ¶
type ServerConfig struct {
Role string
Version string
Families []string
Routes []Route
// Policy reports a principal and Cedar policy store.
Policy bool
// BreakGlass reports that the static DM_ADMIN_TOKEN is still accepted.
BreakGlass bool
}
ServerConfig reports role, available families, version and accepted credential modes. The CLI uses it to explain unavailable routes and display break-glass status.
Source Files