Documentation
¶
Overview ¶
Package api is tailkeeper's Tailscale API client for reads (spec §4, §20).
Responses are decoded into tailkeeper's own allowlisted structs: any field a struct does not declare is dropped, so a credential the API returns in a field nobody listed can never reach an output. Tailscale's Go client library is used only for workload identity federation.
Index ¶
- Constants
- func Path(format string, segments ...string) string
- type Client
- func (c *Client) Get(ctx context.Context, path string, q url.Values, out any) error
- func (c *Client) GetRaw(ctx context.Context, path, accept string) (Raw, error)
- func (c *Client) GrantedScopes() (scopes []string, known bool)
- func (c *Client) Tailnet() string
- func (c *Client) TailnetPath(suffix string) string
- func (c *Client) ValidateTests(ctx context.Context, tests []PolicyTest) (Validation, error)
- func (c *Client) WithMaxBody(n int64) *Client
- type Options
- type PolicyTest
- type Raw
- type TestResult
- type Validation
Constants ¶
const DefaultBaseURL = "https://api.tailscale.com"
DefaultBaseURL is the only API host tailkeeper talks to by default.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client performs authenticated reads against one tailnet.
func New ¶
New builds a Client for tailnet using cred. It makes no network call. ctx must outlive the Client: token requests made on its behalf stop when ctx ends, which is how a signal reaches a hung token exchange.
func (*Client) Get ¶
Get performs a GET of path (already escaped, see TailnetPath and Path) and decodes the JSON body into out. Reads are retried on 429, 500, 502, 503, 504 and transport errors (client timeouts included) with bounded backoff; Retry-After is honoured when present (up to 30s). The caller's cancellation is never retried.
func (*Client) GetRaw ¶
GetRaw performs a GET of path with the given Accept type and returns the body unparsed, for formats that are not JSON (the policy file's HuJSON). It is retried and bounded like Get.
func (*Client) GrantedScopes ¶
GrantedScopes returns the scopes the token endpoint reported, once a token has been fetched. known is false for API keys and federated identities.
func (*Client) TailnetPath ¶
TailnetPath returns /api/v2/tailnet/<tailnet><suffix>.
func (*Client) ValidateTests ¶
func (c *Client) ValidateTests(ctx context.Context, tests []PolicyTest) (Validation, error)
ValidateTests runs tests against the live policy without changing it: POST .../acl/validate with a JSON array of tests (tests mode), the one request other than GET this client sends. The endpoint answers HTTP 200 for pass, fail and warnings alike, so a pass is read only from a recognised shape: an empty body, or an object whose entries carry no errors. Anything else is an error, never a pass. It is retried like a read: the endpoint changes nothing.
func (*Client) WithMaxBody ¶
WithMaxBody returns a copy of c that refuses response bodies over n bytes, or over c's own limit if that is lower. The copy shares c's credential, token cache and observed scopes.
type Options ¶
type Options struct {
BaseURL string // default DefaultBaseURL
Transport http.RoundTripper // default http.DefaultTransport
Timeout time.Duration // per request; default 60s
Retries int // read retries; default 3; negative disables
MaxBody int64 // default 64 MiB
Sleep func(context.Context, time.Duration) error // default: timer honouring ctx
}
Options tune a Client. Zero values are production defaults.
type PolicyTest ¶
type PolicyTest struct {
Src string `json:"src"`
Proto string `json:"proto,omitempty"`
Accept []string `json:"accept,omitempty"`
Deny []string `json:"deny,omitempty"`
}
PolicyTest is one test of the live policy, in the shape Tailscale's validate endpoint takes in tests mode.
type Raw ¶
Raw is a response body as the API sent it, and its ETag (verbatim, quotes included; "" when the API sent none).
type TestResult ¶
type TestResult struct {
User string `json:"user"`
Errors []string `json:"errors"`
Warnings []string `json:"warnings"`
}
TestResult is the validate endpoint's answer for one source.
type Validation ¶
type Validation struct {
Passed bool // no test failed
Results []TestResult // sources with errors or warnings
}
Validation is how the live policy answered a set of tests.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package apitest is a fake Tailscale API for tests.
|
Package apitest is a fake Tailscale API for tests. |
|
Package openapi pins the operations of Tailscale's OpenAPI document (spec §20).
|
Package openapi pins the operations of Tailscale's OpenAPI document (spec §20). |