connpool

type CloseFunc func(conn interface{}) error

type Config struct {
	// Factory is the function used to create new connections.
	// This field is required.
	Factory Factory

	// Close is the function used to close connections.
	// This field is required.
	Close CloseFunc

	// Ping is an optional function used to check the health of a connection.
	// It is called before returning a connection from Get (if the connection is not new)
	// and periodically on idle connections if HealthCheckInterval is set.
	// If Ping returns an error, the connection is discarded.
	Ping PingFunc

	// MaxSize is the maximum number of connections the pool can manage.
	// A value of 0 or less means no limit (unlimited connections).
	// This includes both idle and active connections.
	MaxSize int

	// MaxIdle is the maximum number of idle connections to keep in the pool.
	// If MaxIdle is 0 or less, no idle connections are kept. Put will close connections instead of idling them.
	MaxIdle int

	// MaxIdleTime is the maximum duration a connection can remain idle (unused)
	// in the pool before being closed by the background cleanup goroutine.
	// If MaxIdleTime is 0 or less, connections are not closed based on idle time.
	MaxIdleTime time.Duration

	// MaxAge is the maximum amount of time a connection may exist before being closed.
	// If MaxAge is 0 or less, connections are not closed based on their age.
	MaxAge time.Duration

	// CleanupInterval specifies the interval for the background cleanup goroutine
	// that closes connections based on MaxIdleTime and MaxAge.
	// If 0 or less, a default interval is calculated based on MaxIdleTime and HealthCheckInterval
	// (clamped between minCleanupInterval and maxCleanupInterval).
	CleanupInterval time.Duration

	// HealthCheckInterval is the interval at which idle connections are checked
	// for health using the Ping function. Requires Ping to be set.
	// If 0 or less, periodic background health checks are disabled.
	HealthCheckInterval time.Duration

	// HealthCheckTimeout specifies a time limit for the Ping function during
	// periodic health checks. This prevents a potentially slow or hanging Ping
	// call from blocking the pool's background cleanup goroutine indefinitely.
	// If a Ping call exceeds this timeout, the connection is considered
	// unhealthy and will be closed.
	// If 0 or less, no specific timeout is applied by the pool during these background checks
	// (the Ping function might still time out internally, or block indefinitely).
	HealthCheckTimeout time.Duration
}

type Factory func(ctx context.Context) (interface{}, error)

type Metrics struct {
	// Total number of times Get was called.
	Gets uint64
	// Total number of times Put was called successfully (connection belonged to the pool).
	Puts uint64
	// Total number of times Discard was called.
	Discards uint64

	// Number of times Get successfully returned an existing idle connection (cache hit).
	Hits uint64
	// Number of times Get successfully created a new connection via the Factory (cache miss).
	Misses uint64
	// Number of times Get had to wait because the pool was full.
	Waits uint64
	// Number of times Get timed out or was cancelled by context while waiting for a connection.
	Timeouts uint64

	// Number of connections closed due to a failed Ping check (either in Get or background check).
	PingFailures uint64
	// Number of connections closed by the background cleanup goroutine due to exceeding MaxIdleTime.
	IdleClosed uint64

	// Number of connections closed by the background cleanup goroutine due to exceeding MaxAge.
	AgeClosed uint64
	// Number of times the Factory function returned an error during Get.
	FactoryFailures uint64
	// CloseTimeouts is currently unused as Close returns context errors directly.
	// (Reserved for potential future use if specific timeout tracking in Close is added).
	CloseTimeouts uint64

	// MaxActive records the high-water mark of active connections observed simultaneously.
	// This value is updated atomically when a new maximum is reached.
	MaxActive uint64
}

type PingFunc func(conn interface{}) error

type Pool interface {
	// Get retrieves a connection from the pool.
	// If the pool has an idle connection available, it may be returned.
	// If no idle connection is available, and the pool has not reached its
	// maximum size, a new connection may be created using the Factory.
	// If a PingFunc is configured, it may be called to check health before returning an existing connection.
	// If the pool is at maximum capacity and no idle connections are available,
	// Get will block until a connection is returned to the pool or the context
	// is cancelled.
	Get(ctx context.Context) (interface{}, error)

	// Put returns a connection to the pool, making it available for reuse.
	// If the connection is nil, invalid, or does not belong to this pool, Put attempts
	// to close it using the configured CloseFunc and returns.
	// If the pool is closed, the connection is closed.
	// Otherwise, Put attempts to hand the connection to a waiting goroutine (from Get).
	// If no goroutines are waiting, it adds the connection to the idle list, potentially
	// evicting the oldest idle connection if MaxIdle is reached.
	Put(conn interface{})

	// Discard removes a connection from the pool and closes it, usually because
	// the connection is known to be broken or unhealthy. Discard closes the connection
	// using the configured CloseFunc.
	// It returns ErrInvalidConnection if the provided connection is nil, does not belong
	// to this pool, or is already closed.
	// It returns ErrPoolClosed if the pool was already closed when Discard was called,
	// but still attempts to close the connection. Otherwise, it returns the result
	// of the underlying CloseFunc call.
	Discard(conn interface{}) error

	// Close closes the pool and all its connections.
	// After Close returns, Get will return an error.
	// Close immediately closes all idle connections. It then waits for all active
	// connections to be returned (via Put or Discard) before returning.
	// If the context is cancelled before all connections are returned, the context's
	// error is returned. Close returns ErrPoolClosed if called more than once.
	Close(ctx context.Context) error

	// Len returns the current number of connections in the pool (both active and idle).
	Len() int

	// IdleLen returns the current number of idle connections in the pool.
	IdleLen() int

	// Stats returns a snapshot of the pool's metrics.
	Stats() Metrics
}