Help us shape the future of Go! Take the 2026 Go Developer Survey

caclient

package
v0.31.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 14, 2026 License: Apache-2.0, Apache-2.0 Imports: 20 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultCooldown = 10 * time.Minute

DefaultCooldown is the default circuit breaker cooldown duration.

View Source 
const DefaultPriority = 100

DefaultPriority is the priority assigned to CA endpoints without an explicit priority. Higher priority values are tried first.

View Source 
const DefaultTimeout = 15 * time.Second

DefaultTimeout is the default per-request timeout for CA requests.

Variables

This section is empty.

Functions

func InventoryURL added in v0.31.0 

func InventoryURL(root *RootResponse, cfg tlsconfig.Config) (string, error)

InventoryURL follows only the configured CA's explicit inventory relation. Unlike auth discovery, inventory may intentionally be on another HTTPS origin. No credentials are sent during discovery, or forwarded through redirects.

Types

type AllCAsUnavailableError added in v0.3.0 

type AllCAsUnavailableError struct {
	Message string
}

AllCAsUnavailableError indicates all configured CAs are unavailable. This happens when all CAs have their circuit breakers in the open state.

func (*AllCAsUnavailableError) Error added in v0.3.0 

func (e *AllCAsUnavailableError) Error() string

type CAEndpoint added in v0.3.0 

type CAEndpoint struct {
	URL      string
	Priority int
}

CAEndpoint represents a CA server URL with its priority for failover. Higher priority CAs are tried first; lower priority CAs are used as backups.

func ParseCAURL added in v0.3.0 

func ParseCAURL(s string) (CAEndpoint, error)

ParseCAURL parses a CA URL string into a CAEndpoint. Format: "priority=N:https://ca.example.com/" or just "https://ca.example.com/" If no priority is specified, DefaultPriority (100) is used.

func ParseCAURLs added in v0.3.0 

func ParseCAURLs(urls []string) ([]CAEndpoint, error)

ParseCAURLs parses multiple CA URL strings into CAEndpoints. Returns an error if any URL is invalid or if the list is empty.

type CAEndpointStatus added in v0.17.0 

type CAEndpointStatus struct {
	URL          string `json:"url"`
	Priority     int    `json:"priority"`
	BreakerState string `json:"breakerState"` // "closed", "open", "half-open"
}

CAEndpointStatus represents the current state of a CA endpoint.

type CAUnavailableError added in v0.1.1 

type CAUnavailableError struct {
	Message string
}

CAUnavailableError indicates the CA service is temporarily unavailable. This is typically a transient infrastructure issue.

func (*CAUnavailableError) Error added in v0.1.1 

func (e *CAUnavailableError) Error() string

type CertResponse added in v0.3.0 

type CertResponse struct {
	Certificate sshcert.RawCertificate
}

CertResponse contains the certificate issued for this connection.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a CA Client with support for multiple CA endpoints and failover.

func New 

func New(endpoints []CAEndpoint, options ...Option) (*Client, error)

New creates a new CA Client with the given endpoints. At least one endpoint is required.

func (*Client) EndpointStatus added in v0.17.0 

func (c *Client) EndpointStatus() []CAEndpointStatus

EndpointStatus returns the current state of each CA endpoint.

func (*Client) GetCert 

func (c *Client) GetCert(ctx context.Context, token string, req *caserver.CreateCertRequest) (*CertResponse, error)

GetCert requests a certificate from the CA, with automatic failover to backup CAs. It tries CAs in priority order, using circuit breakers to skip temporarily unavailable CAs. The token is sent in the Authorization header, not in the request body. Returns CertResponse containing the certificate.

func (*Client) GetDiscovery added in v0.3.0 

func (c *Client) GetDiscovery(ctx context.Context) (*DiscoveryResponse, error)

GetDiscovery fetches the CA's discovery document by following the Link header the CA advertises on its root GET, with automatic failover to backup CAs. The endpoint requires no authentication, so no token is sent. Callers are responsible for caching the result if they need to avoid repeated fetches.

func (*Client) GetRoot added in v0.23.0 

func (c *Client) GetRoot(ctx context.Context) (*RootResponse, error)

GetRoot fetches and validates the CA's anonymous bootstrap document, with automatic failover to backup CAs. The returned public key is canonical authorized-key text and the response's Link fields are retained verbatim.

type DiscoveryResponse added in v0.31.0 

type DiscoveryResponse struct {
	wire.Discovery
	PublicCAURL  string
	InventoryURL string
}

DiscoveryResponse includes the auth document and public service addresses advertised by the same CA bootstrap response.

type InvalidRequestError added in v0.1.1 

type InvalidRequestError struct {
	Message string
}

InvalidRequestError indicates the certificate request was malformed. This typically indicates a bug in the client code.

func (*InvalidRequestError) Error added in v0.1.1 

func (e *InvalidRequestError) Error() string

type InvalidTokenError added in v0.1.1 

type InvalidTokenError struct {
	Message string
}

InvalidTokenError indicates the authentication token is invalid or expired. The broker should clear the token and re-authenticate.

func (*InvalidTokenError) Error added in v0.1.1 

func (e *InvalidTokenError) Error() string

type Option 

type Option interface {
	// contains filtered or unexported methods
}

Option configures the agent

func WithCooldown added in v0.3.0 

func WithCooldown(d time.Duration) Option

WithCooldown sets the circuit breaker cooldown duration. Failed CAs will be unavailable for this duration before being retried.

func WithLogger added in v0.1.1 

func WithLogger(logger *slog.Logger) Option

WithLogger specifies the logger to use

func WithTLSConfig added in v0.1.4 

func WithTLSConfig(cfg tlsconfig.Config) Option

WithTLSConfig creates an HTTP client with the specified TLS configuration

func WithTimeout added in v0.3.0 

func WithTimeout(d time.Duration) Option

WithTimeout sets the per-request timeout for CA requests.

type PolicyDeniedError added in v0.1.1 

type PolicyDeniedError struct {
	Message string
}

PolicyDeniedError indicates authentication succeeded but policy denied access. The token is valid, but the user is not authorized for this connection.

func (*PolicyDeniedError) Error added in v0.1.1 

func (e *PolicyDeniedError) Error() string

type PolicyPendingError added in v0.30.0 

type PolicyPendingError struct{}

PolicyPendingError means authorization is not yet issuable. A later request may succeed; this does not trigger token refresh, failover, or automatic polling.

func (*PolicyPendingError) Error added in v0.30.0 

func (e *PolicyPendingError) Error() string

type RootResponse added in v0.23.0 

type RootResponse struct {
	PublicKey sshcert.RawPublicKey
	FinalURL  string
	Links     []string
}

RootResponse is the anonymous bootstrap document returned by a CA URL. FinalURL is the URL after redirects and Links preserves every Link header field for consumers that implement advertised enrollment capabilities.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.