client

Documentation

Overview

Package client provides a RemoteStore implementation that connects to a config server.

Index

• Variables
• type ConnState
  • func (s ConnState) String() string
• type Option
  • func WithCallTimeout(d time.Duration) Option
  • func WithCircuitBreaker(threshold int, timeout time.Duration) Option
  • func WithDialOptions(opts ...grpc.DialOption) Option
  • func WithInsecure() Option
  • func WithKeepalive(interval, timeout time.Duration) Option
  • func WithRetry(maxRetries int, initialBackoff, maxBackoff time.Duration) Option
  • func WithStateCallback(fn func(ConnState)) Option
  • func WithTLS(config *tls.Config) Option
  • func WithWatchBufferSize(size int) Option
  • func WithWatchErrorCallback(fn func(error)) Option
  • func WithWatchMaxErrors(n int) Option
  • func WithWatchReconnect(enabled bool, waitTime time.Duration) Option
• type PermissionDeniedError
  • func (e *PermissionDeniedError) Error() string
  • func (e *PermissionDeniedError) Is(target error) bool
• type RemoteError
  • func (e *RemoteError) Error() string
• type RemoteStore
  • func NewRemoteStore(addr string, opts ...Option) (*RemoteStore, error)
  • func (s *RemoteStore) Close(ctx context.Context) error
  • func (s *RemoteStore) Connect(ctx context.Context) error
  • func (s *RemoteStore) Delete(ctx context.Context, namespace, key string) error
  • func (s *RemoteStore) DeleteAlias(ctx context.Context, alias string) error
  • func (s *RemoteStore) Find(ctx context.Context, namespace string, filter config.Filter) (config.Page, error)
  • func (s *RemoteStore) Get(ctx context.Context, namespace, key string) (config.Value, error)
  • func (s *RemoteStore) GetAlias(ctx context.Context, alias string) (config.Value, error)
  • func (s *RemoteStore) GetVersions(ctx context.Context, namespace, key string, filter config.VersionFilter) (config.VersionPage, error)
  • func (s *RemoteStore) ListAliases(ctx context.Context) (map[string]config.Value, error)
  • func (s *RemoteStore) Ready() bool
  • func (s *RemoteStore) Set(ctx context.Context, namespace, key string, value config.Value) (config.Value, error)
  • func (s *RemoteStore) SetAlias(ctx context.Context, alias, target string) (config.Value, error)
  • func (s *RemoteStore) Snapshot(ctx context.Context, namespace string, opts ...SnapshotOption) (*SnapshotResult, error)
  • func (s *RemoteStore) State() ConnState
  • func (s *RemoteStore) Watch(ctx context.Context, filter config.WatchFilter) (<-chan config.ChangeEvent, error)
  • func (s *RemoteStore) WatchWithResult(ctx context.Context, filter config.WatchFilter) (*WatchResult, error)
• type SnapshotOption
  • func WithIfNoneMatch(etag string) SnapshotOption
• type SnapshotResult
• type WatchResult
  • func (w *WatchResult) Err() error
  • func (w *WatchResult) Events() <-chan config.ChangeEvent
  • func (w *WatchResult) Stop()

Variables

var ErrPermissionDenied = errors.New("config: permission denied")

ErrPermissionDenied is returned when the server denies access to a resource.

Types

type ConnState

type ConnState int

ConnState represents the connection state.

const (
	ConnStateDisconnected ConnState = iota
	ConnStateConnecting
	ConnStateConnected

	ConnStateClosed
)

func (ConnState) String

func (s ConnState) String() string

type Option

type Option func(*options)

Option configures the RemoteStore.

func WithCallTimeout

func WithCallTimeout(d time.Duration) Option

WithCallTimeout sets a per-attempt timeout for each gRPC call within a retry loop. When set to a value > 0, each attempt's context will be wrapped with a deadline. Default is 0 (no per-call timeout; uses the caller's context deadline only).

func WithCircuitBreaker

func WithCircuitBreaker(threshold int, timeout time.Duration) Option

WithCircuitBreaker enables circuit breaker for resilience. The threshold is the number of consecutive failures before the circuit opens.

func WithDialOptions

func WithDialOptions(opts ...grpc.DialOption) Option

WithDialOptions appends additional gRPC dial options.

func WithInsecure

func WithInsecure() Option

WithInsecure explicitly enables insecure connections (no TLS). This should only be used for development/testing.

func WithKeepalive

func WithKeepalive(interval, timeout time.Duration) Option

WithKeepalive configures gRPC keepalive parameters.

func WithRetry

func WithRetry(maxRetries int, initialBackoff, maxBackoff time.Duration) Option

WithRetry configures retry behavior for failed operations.

func WithStateCallback

func WithStateCallback(fn func(ConnState)) Option

WithStateCallback sets a callback for connection state changes.

func WithTLS

func WithTLS(config *tls.Config) Option

WithTLS enables TLS with the given config. If config is nil, uses system default TLS config.

func WithWatchBufferSize

func WithWatchBufferSize(size int) Option

WithWatchBufferSize sets the buffer size for watch event channels. Default is 100. Set to 0 for unbuffered (backpressure).

func WithWatchErrorCallback

func WithWatchErrorCallback(fn func(error)) Option

WithWatchErrorCallback sets a callback for watch errors. This is called when a watch encounters an error (before reconnection).

func WithWatchMaxErrors

func WithWatchMaxErrors(n int) Option

WithWatchMaxErrors sets the maximum number of consecutive watch errors before the watch gives up. Default is 10.

func WithWatchReconnect

func WithWatchReconnect(enabled bool, waitTime time.Duration) Option

WithWatchReconnect enables automatic reconnection for watches. Default is enabled with 1 second wait between attempts.

type PermissionDeniedError

type PermissionDeniedError struct {
	Message string
}

PermissionDeniedError provides details about a permission denial.

func (*PermissionDeniedError) Error

func (e *PermissionDeniedError) Error() string

func (*PermissionDeniedError) Is

func (e *PermissionDeniedError) Is(target error) bool

type RemoteError

type RemoteError struct {
	Code    codes.Code
	Message string
}

RemoteError wraps an error from the remote config server.

func (*RemoteError) Error

func (e *RemoteError) Error() string

type RemoteStore

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

RemoteStore implements config.Store by connecting to a config server. It is safe for concurrent use by multiple goroutines.

Features:

• Automatic reconnection with exponential backoff
• Circuit breaker for resilience
• Configurable timeouts and retries
• Watch streams with automatic reconnection
• Health checks and keepalives

Example:

store, _ := client.NewRemoteStore("config-server:9090",
    client.WithTLS(nil),  // Use system TLS
    client.WithRetry(3, 100*time.Millisecond, 5*time.Second),
)
mgr, _ := config.New(config.WithStore(store))
mgr.Connect(ctx)

func NewRemoteStore

func NewRemoteStore(addr string, opts ...Option) (*RemoteStore, error)

NewRemoteStore creates a new RemoteStore connecting to the given address. Returns an error if addr is empty.

func (*RemoteStore) Close

func (s *RemoteStore) Close(ctx context.Context) error

Close releases resources and closes the connection.

func (*RemoteStore) Connect

func (s *RemoteStore) Connect(ctx context.Context) error

Connect establishes the connection to the config server. The context is reserved for future use.

Note: the onStateChange callback (set via WithStateCallback) is invoked while holding stateMu but not s.mu. The callback must not acquire s.mu (e.g. by calling Ready()) on the same goroutine to avoid deadlock.

func (*RemoteStore) Delete

func (s *RemoteStore) Delete(ctx context.Context, namespace, key string) error

Delete removes a configuration value by namespace and key.

func (*RemoteStore) DeleteAlias

func (s *RemoteStore) DeleteAlias(ctx context.Context, alias string) error

DeleteAlias removes an alias on the remote server.

func (*RemoteStore) Find

func (s *RemoteStore) Find(ctx context.Context, namespace string, filter config.Filter) (config.Page, error)

Find returns a page of keys and values matching the filter within a namespace.

func (*RemoteStore) Get

func (s *RemoteStore) Get(ctx context.Context, namespace, key string) (config.Value, error)

Get retrieves a configuration value by namespace and key.

func (*RemoteStore) GetAlias

func (s *RemoteStore) GetAlias(ctx context.Context, alias string) (config.Value, error)

GetAlias retrieves a specific alias from the remote server.

func (*RemoteStore) GetVersions

func (s *RemoteStore) GetVersions(ctx context.Context, namespace, key string, filter config.VersionFilter) (config.VersionPage, error)

GetVersions retrieves version history for a configuration key. Implements config.VersionedStore.

func (*RemoteStore) ListAliases

func (s *RemoteStore) ListAliases(ctx context.Context) (map[string]config.Value, error)

ListAliases returns all aliases from the remote server.

func (*RemoteStore) Ready

func (s *RemoteStore) Ready() bool

Ready returns true if the store is connected and ready for operations.

func (*RemoteStore) Set

func (s *RemoteStore) Set(ctx context.Context, namespace, key string, value config.Value) (config.Value, error)

Set creates or updates a configuration value.

func (*RemoteStore) SetAlias

func (s *RemoteStore) SetAlias(ctx context.Context, alias, target string) (config.Value, error)

SetAlias creates a new alias on the remote server.

func (*RemoteStore) Snapshot

func (s *RemoteStore) Snapshot(ctx context.Context, namespace string, opts ...SnapshotOption) (*SnapshotResult, error)

Snapshot returns a point-in-time export of all entries in a namespace. Use WithIfNoneMatch to enable ETag-based caching.

func (*RemoteStore) State

func (s *RemoteStore) State() ConnState

State returns the current connection state.

func (*RemoteStore) Watch

func (s *RemoteStore) Watch(ctx context.Context, filter config.WatchFilter) (<-chan config.ChangeEvent, error)

Watch returns a channel that receives change events. The returned channel is closed when the context is cancelled or an error occurs. For better error visibility and control, use WatchWithResult.

func (*RemoteStore) WatchWithResult

func (s *RemoteStore) WatchWithResult(ctx context.Context, filter config.WatchFilter) (*WatchResult, error)

WatchWithResult returns a WatchResult providing the event channel, error access, and stop control.

If reconnection is enabled (default), the watch will automatically reconnect on network errors with exponential backoff.

type SnapshotOption

type SnapshotOption func(*snapshotOptions)

SnapshotOption configures a Snapshot call.

func WithIfNoneMatch

func WithIfNoneMatch(etag string) SnapshotOption

WithIfNoneMatch sets the ETag from a previous snapshot for conditional fetching.

type SnapshotResult

type SnapshotResult struct {
	// Entries contains all configuration values in the namespace.
	Entries map[string]config.Value

	// ETag is an opaque version identifier for caching.
	ETag string

	// NotModified is true if the provided ETag matched (Entries will be empty).
	NotModified bool
}

SnapshotResult contains the result of a Snapshot call.

type WatchResult

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

WatchResult wraps a change event channel with error reporting and control. Safe for concurrent use by multiple goroutines.

func (*WatchResult) Err

func (w *WatchResult) Err() error

Err returns the error that caused the watch to end, or nil if it was cancelled normally. Err blocks until the watch goroutine has fully exited. Safe to call multiple times; all calls return the same error.

func (*WatchResult) Events

func (w *WatchResult) Events() <-chan config.ChangeEvent

Events returns the channel that receives configuration change events. The channel is closed when the watch ends (cancelled or errored).

func (*WatchResult) Stop

func (w *WatchResult) Stop()

Stop cancels the watch. Safe to call multiple times.