Documentation
¶
Overview ¶
Package weaviate provides a resilient Weaviate client with circuit breaker, retry with backoff, and graceful degradation.
Features:
- Circuit breaker to prevent thundering herd
- Exponential backoff with jitter for retries
- Health checking with adaptive intervals
- Graceful degradation when Weaviate is unavailable
- OpenTelemetry tracing integration
Index ¶
- Variables
- func WrapWeaviateError(err error) error
- type BaseDegradationHandler
- func (h *BaseDegradationHandler) GetMode() DegradationMode
- func (h *BaseDegradationHandler) IsDegraded() bool
- func (h *BaseDegradationHandler) IsDisabled() bool
- func (h *BaseDegradationHandler) IsNormal() bool
- func (h *BaseDegradationHandler) OnDegraded(reason string)
- func (h *BaseDegradationHandler) OnRecovered()
- func (h *BaseDegradationHandler) SetDisabled()
- type ClientConfig
- type ConnectionState
- type DegradationHandler
- type DegradationMode
- type LibraryDocsDegradation
- type PromptCacheDegradation
- type ResilientClient
- func (c *ResilientClient) Client() *weaviate.Client
- func (c *ResilientClient) Close() error
- func (c *ResilientClient) Execute(ctx context.Context, fn func() error) error
- func (c *ResilientClient) GetState() ConnectionState
- func (c *ResilientClient) IsAvailable() bool
- func (c *ResilientClient) IsDegraded() bool
- func (c *ResilientClient) RegisterHandler(handler DegradationHandler)
- func (c *ResilientClient) WaitForReady(ctx context.Context, timeout time.Duration) error
- type SyntheticMemoryDegradation
Constants ¶
This section is empty.
Variables ¶
var ( ErrWeaviateUnavailable = errors.New("weaviate is not available") // ErrCircuitOpen is returned when the circuit breaker is open. ErrCircuitOpen = errors.New("circuit breaker is open, weaviate requests blocked") // ErrConnectionTimeout is returned when connection times out. ErrConnectionTimeout = errors.New("weaviate connection timeout") // ErrClientClosed is returned when operations are called on a closed client. ErrClientClosed = errors.New("weaviate client is closed") )
Functions ¶
func WrapWeaviateError ¶
WrapWeaviateError wraps errors with more context.
Types ¶
type BaseDegradationHandler ¶
type BaseDegradationHandler struct {
// contains filtered or unexported fields
}
BaseDegradationHandler provides a basic implementation of DegradationHandler.
Description:
Tracks degradation state and provides logging. Embed this in component-specific handlers.
Thread Safety: Safe for concurrent use.
func NewBaseDegradationHandler ¶
func NewBaseDegradationHandler(name string, logger *slog.Logger) *BaseDegradationHandler
NewBaseDegradationHandler creates a new base handler.
Inputs:
name - Component name for logging. logger - Logger instance. Uses slog.Default() if nil.
Outputs:
*BaseDegradationHandler - Ready-to-use handler.
func (*BaseDegradationHandler) GetMode ¶
func (h *BaseDegradationHandler) GetMode() DegradationMode
GetMode returns the current mode.
func (*BaseDegradationHandler) IsDegraded ¶
func (h *BaseDegradationHandler) IsDegraded() bool
IsDegraded returns true if operating with reduced functionality.
func (*BaseDegradationHandler) IsDisabled ¶
func (h *BaseDegradationHandler) IsDisabled() bool
IsDisabled returns true if the component is disabled.
func (*BaseDegradationHandler) IsNormal ¶
func (h *BaseDegradationHandler) IsNormal() bool
IsNormal returns true if operating normally.
func (*BaseDegradationHandler) OnDegraded ¶
func (h *BaseDegradationHandler) OnDegraded(reason string)
OnDegraded marks the handler as degraded.
func (*BaseDegradationHandler) OnRecovered ¶
func (h *BaseDegradationHandler) OnRecovered()
OnRecovered marks the handler as normal.
func (*BaseDegradationHandler) SetDisabled ¶
func (h *BaseDegradationHandler) SetDisabled()
SetDisabled explicitly disables the handler.
type ClientConfig ¶
type ClientConfig struct {
// URL is the Weaviate server URL (e.g., "http://localhost:8080").
URL string
// RetryAttempts is the number of retry attempts for failed requests.
// Default: 3
RetryAttempts int
// RetryBackoff is the initial backoff duration between retries.
// Default: 100ms
RetryBackoff time.Duration
// MaxRetryBackoff caps the exponential backoff.
// Default: 5s
MaxRetryBackoff time.Duration
// RetryJitter adds randomness to backoff (0.0-1.0).
// Default: 0.25 (±25%)
RetryJitter float64
// CircuitThreshold is the number of failures before opening circuit.
// Default: 5
CircuitThreshold int
// CircuitWindow is the sliding window for counting failures.
// Default: 30s
CircuitWindow time.Duration
// CircuitCooldown is how long circuit stays open before half-opening.
// Default: 30s
CircuitCooldown time.Duration
// HealthCheckInterval is how often to check health when connected.
// Default: 10s
HealthCheckInterval time.Duration
// DegradedCheckInterval is how often to check health when degraded.
// Default: 5s
DegradedCheckInterval time.Duration
// HealthCheckTimeout prevents health checks from blocking.
// Default: 5s
HealthCheckTimeout time.Duration
// AllowStartDegraded allows starting even if Weaviate is unavailable.
// Default: false
AllowStartDegraded bool
// Logger for client operations.
// Default: slog.Default()
Logger *slog.Logger
}
ClientConfig configures the resilient Weaviate client.
func DefaultClientConfig ¶
func DefaultClientConfig() ClientConfig
DefaultClientConfig returns sensible defaults for production use.
func (*ClientConfig) Validate ¶
func (c *ClientConfig) Validate() error
Validate checks if the configuration is valid.
type ConnectionState ¶
type ConnectionState int32
ConnectionState represents the current state of the Weaviate connection.
const ( // StateConnected indicates normal operation. StateConnected ConnectionState = iota // StateDegraded indicates Weaviate is unavailable but client is functional. StateDegraded // StateCircuitOpen indicates circuit breaker is open, requests blocked. StateCircuitOpen // StateHalfOpen indicates circuit breaker is testing with single request. StateHalfOpen )
func (ConnectionState) String ¶
func (s ConnectionState) String() string
String returns the string representation of ConnectionState.
type DegradationHandler ¶
type DegradationHandler interface {
// OnDegraded is called when Weaviate becomes unavailable.
//
// Inputs:
// - reason: Description of why degradation occurred.
//
// Implementations should:
// - Switch to fallback behavior
// - Log the degradation
// - Update metrics if applicable
OnDegraded(reason string)
// OnRecovered is called when Weaviate becomes available again.
//
// Implementations should:
// - Restore normal behavior
// - Log the recovery
// - Optionally replay queued operations
OnRecovered()
// GetMode returns the current degradation mode.
GetMode() DegradationMode
}
DegradationHandler is notified of Weaviate availability changes.
Description:
Components that depend on Weaviate should implement this interface to handle degradation gracefully.
Thread Safety: Implementations must be safe for concurrent use.
type DegradationMode ¶
type DegradationMode int32
DegradationMode represents the operational mode of a component.
const ( // ModeNormal indicates full functionality. ModeNormal DegradationMode = iota // ModeDegraded indicates reduced functionality. ModeDegraded // ModeDisabled indicates the component is completely disabled. ModeDisabled )
func (DegradationMode) String ¶
func (m DegradationMode) String() string
String returns the string representation of DegradationMode.
type LibraryDocsDegradation ¶
type LibraryDocsDegradation struct {
*BaseDegradationHandler
}
LibraryDocsDegradation handles degradation for library documentation search.
Description:
When Weaviate is unavailable, library documentation search is skipped. The system continues with code-only context.
func NewLibraryDocsDegradation ¶
func NewLibraryDocsDegradation(logger *slog.Logger) *LibraryDocsDegradation
NewLibraryDocsDegradation creates a handler for library docs.
func (*LibraryDocsDegradation) OnDegraded ¶
func (h *LibraryDocsDegradation) OnDegraded(reason string)
OnDegraded handles library docs degradation.
func (*LibraryDocsDegradation) OnRecovered ¶
func (h *LibraryDocsDegradation) OnRecovered()
OnRecovered handles library docs recovery.
func (*LibraryDocsDegradation) ShouldSkipSearch ¶
func (h *LibraryDocsDegradation) ShouldSkipSearch() bool
ShouldSkipSearch returns true if library doc search should be skipped.
type PromptCacheDegradation ¶
type PromptCacheDegradation struct {
*BaseDegradationHandler
}
PromptCacheDegradation handles degradation for prompt caching.
Description:
When Weaviate is unavailable, prompt cache is disabled. All requests pass through without caching.
func NewPromptCacheDegradation ¶
func NewPromptCacheDegradation(logger *slog.Logger) *PromptCacheDegradation
NewPromptCacheDegradation creates a handler for prompt caching.
func (*PromptCacheDegradation) OnDegraded ¶
func (h *PromptCacheDegradation) OnDegraded(reason string)
OnDegraded handles prompt cache degradation.
func (*PromptCacheDegradation) OnRecovered ¶
func (h *PromptCacheDegradation) OnRecovered()
OnRecovered handles prompt cache recovery.
func (*PromptCacheDegradation) ShouldBypassCache ¶
func (h *PromptCacheDegradation) ShouldBypassCache() bool
ShouldBypassCache returns true if cache should be bypassed.
type ResilientClient ¶
type ResilientClient struct {
// contains filtered or unexported fields
}
ResilientClient wraps the Weaviate client with resilience features.
Thread Safety: Safe for concurrent use from multiple goroutines.
func NewResilientClient ¶
func NewResilientClient(config ClientConfig) (*ResilientClient, error)
NewResilientClient creates a new resilient Weaviate client.
Inputs:
config - Client configuration. URL is required.
Outputs:
*ResilientClient - Ready-to-use client. error - Non-nil if configuration invalid or connection fails (and AllowStartDegraded=false).
Thread Safety: Safe for concurrent use.
func (*ResilientClient) Client ¶
func (c *ResilientClient) Client() *weaviate.Client
Client returns the underlying Weaviate client. Use this for direct Weaviate operations.
Thread Safety: Safe for concurrent use.
func (*ResilientClient) Close ¶
func (c *ResilientClient) Close() error
Close releases resources and stops the health checker.
Thread Safety: Safe for concurrent use.
func (*ResilientClient) Execute ¶
func (c *ResilientClient) Execute(ctx context.Context, fn func() error) error
Execute runs a function with retry and circuit breaker protection.
Inputs:
ctx - Context for cancellation. fn - Function to execute. Should perform Weaviate operation.
Outputs:
error - Non-nil if all retries fail or circuit is open.
Thread Safety: Safe for concurrent use.
func (*ResilientClient) GetState ¶
func (c *ResilientClient) GetState() ConnectionState
GetState returns the current connection state.
Thread Safety: Safe for concurrent use.
func (*ResilientClient) IsAvailable ¶
func (c *ResilientClient) IsAvailable() bool
IsAvailable returns true if Weaviate is available for requests.
Thread Safety: Safe for concurrent use.
func (*ResilientClient) IsDegraded ¶
func (c *ResilientClient) IsDegraded() bool
IsDegraded returns true if operating with reduced functionality.
Thread Safety: Safe for concurrent use.
func (*ResilientClient) RegisterHandler ¶
func (c *ResilientClient) RegisterHandler(handler DegradationHandler)
RegisterHandler registers a degradation handler.
Thread Safety: Safe for concurrent use.
func (*ResilientClient) WaitForReady ¶
WaitForReady blocks until Weaviate is ready or timeout.
Inputs:
ctx - Context for cancellation. timeout - Maximum time to wait.
Outputs:
error - Non-nil if timeout or context cancelled.
Thread Safety: Safe for concurrent use.
type SyntheticMemoryDegradation ¶
type SyntheticMemoryDegradation struct {
*BaseDegradationHandler
}
SyntheticMemoryDegradation handles degradation for synthetic memory.
Description:
When Weaviate is unavailable, synthetic memory operations are skipped. Learned constraints are not persisted or retrieved.
func NewSyntheticMemoryDegradation ¶
func NewSyntheticMemoryDegradation(logger *slog.Logger) *SyntheticMemoryDegradation
NewSyntheticMemoryDegradation creates a handler for synthetic memory.
func (*SyntheticMemoryDegradation) OnDegraded ¶
func (h *SyntheticMemoryDegradation) OnDegraded(reason string)
OnDegraded handles synthetic memory degradation.
func (*SyntheticMemoryDegradation) OnRecovered ¶
func (h *SyntheticMemoryDegradation) OnRecovered()
OnRecovered handles synthetic memory recovery.
func (*SyntheticMemoryDegradation) ShouldSkipMemoryOps ¶
func (h *SyntheticMemoryDegradation) ShouldSkipMemoryOps() bool
ShouldSkipMemoryOps returns true if memory operations should be skipped.
Source Files