Documentation
¶
Overview ¶
Package client provides a Go client library for the Berth API server.
Create a client with New and configure it with Option functions:
c := client.New("https://berth.example.com:8443",
client.WithAPIKey("my-api-key"),
client.WithTLSConfig(tlsCfg),
)
err := c.Ping(ctx)
Options ¶
- WithAPIKey sets the bearer token for API authentication.
- WithHTTPClient replaces the default net/http.Client.
- WithTLSConfig configures custom TLS settings on the underlying transport.
Index ¶
- Constants
- Variables
- type AcquireResult
- type Client
- func (c *Client) Acquire(ctx context.Context, namespace, name, holder string, ttl time.Duration) (AcquireResult, error)
- func (c *Client) Ping(ctx context.Context) error
- func (c *Client) Release(ctx context.Context, namespace, name, holder string, fencingToken int32) error
- func (c *Client) Renew(ctx context.Context, namespace, name, holder string, fencingToken int32, ...) (AcquireResult, error)
- type Option
Constants ¶
const DefaultTimeout = 10 * time.Second
DefaultTimeout bounds a single Berth API request when the caller does not supply one. Without it a server that accepts a connection and then stalls (overload, half-open connection, load-balancer blackhole) blocks the caller indefinitely — which wedges the sidecar's renew loop and defeats the failover-after-expiry guarantee, since the loop can only enforce at-most-once after the in-flight call returns.
Variables ¶
var ErrConflict = errors.New("client: lease conflict")
ErrConflict is returned by Client.Release when the server reports the lease is held by a different identity or fencing token.
Functions ¶
This section is empty.
Types ¶
type AcquireResult ¶
type AcquireResult struct {
Acquired bool `json:"acquired"`
Holder string `json:"holder,omitempty"`
FencingToken int32 `json:"fencingToken,omitempty"`
ExpiresAt time.Time `json:"expiresAt,omitempty"`
AcquiredAt time.Time `json:"acquiredAt,omitempty"`
}
AcquireResult mirrors the API's lease response. When Acquired is false, Holder/FencingToken/ExpiresAt describe the entity currently holding the lease.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client communicates with the Berth API server over HTTP. A zero-value Client is not usable; create one with New.
func New ¶
New creates a Client targeting the given base URL. Configure the client with Option functions such as WithAPIKey and WithTLSConfig.
The returned client bounds every request with DefaultTimeout. Override it with WithTimeout, or supply a fully-configured client with WithHTTPClient to manage timeouts yourself.
func (*Client) Acquire ¶
func (c *Client) Acquire(ctx context.Context, namespace, name, holder string, ttl time.Duration) (AcquireResult, error)
Acquire requests the lease at namespace/name for holder with the given TTL.
func (*Client) Ping ¶
Ping checks that the Berth API server is reachable by issuing an unauthenticated GET against its /healthz liveness route. It returns a non-nil error when the base URL is unset, the request cannot be sent, or the server answers with a non-2xx status — so an operator readiness probe gated on Ping is drained when the central API is unreachable. The caller should pass a context with a deadline to bound a hung connection.
func (*Client) Release ¶
func (c *Client) Release(ctx context.Context, namespace, name, holder string, fencingToken int32) error
Release relinquishes the lease at namespace/name held by holder under fencingToken. Returns ErrConflict if the server rejects the call because the lease is held by a different identity or token.
type Option ¶
type Option func(*Client)
Option configures a Client.
func WithAPIKey ¶
WithAPIKey sets a static API key used for bearer token authentication. To source the key from a refreshing token file (e.g., an OIDC sidecar broker), use WithAPIKeyFunc instead.
func WithAPIKeyFunc ¶
WithAPIKeyFunc sets a getter the client invokes on every request to retrieve the current bearer token. Use this when the token is short-lived and refreshed externally (e.g., an OIDC token broker sidecar that writes a JWT to a shared file). A nil getter, or a getter that returns an empty string, results in no Authorization header being sent.
func WithHTTPClient ¶
WithHTTPClient replaces the default HTTP client. If httpClient is nil, the default is retained.
A supplied client's own Timeout is left alone unless WithTimeout is also given, in which case the explicit value wins.
func WithTLSConfig ¶
WithTLSConfig sets a custom TLS configuration on the client's HTTP transport. If cfg is nil, this option is a no-op.
func WithTimeout ¶ added in v0.4.0
WithTimeout bounds every request, overriding DefaultTimeout. It is applied after all other options, so it takes effect regardless of option order and also applies to a WithHTTPClient client.
A zero or negative timeout disables the bound (net/http semantics), leaving requests limited only by the caller's context. Callers that do this are responsible for passing a context with a deadline; an unbounded lease call can stall a renew loop indefinitely.
Source Files