Documentation

TsHealth
in package

Availability gate for TypeSense reads.

TypeSense is a search index and a cross-site cache of data that already lives in the database, so an outage has to degrade a page, never fatal it. Two things make a bare try/catch insufficient on its own:

  • A transport failure (refused, DNS, read timeout) makes typesense-php sleep retry_interval_seconds between retries on the request thread. Catching the exception afterwards does not give back the seconds already burned.
  • Every subsequent request pays that cost again. With a small PHP-FPM pool a TypeSense that merely lags starves the workers and takes every site down — which is worse than one that is cleanly dead.

So failures are counted in a network-wide transient and, past a threshold, reads short-circuit for a cooldown without touching a socket.

Table of Contents

Constants

LOG_CHANNEL  : mixed = 'wsc'
BREAKER_KEY  : mixed = 'wsc_ts_breaker'
COOLDOWN_SECONDS  : mixed = 30
FAILURE_THRESHOLD  : mixed = 3
LOG_THROTTLE_SECONDS  : mixed = 60
RESPONDED_EXCEPTIONS  : mixed = [\Typesense\Exceptions\ObjectNotFound::class, \...
Exceptions that prove TypeSense answered. A missing alias or a filter the parser rejects is a verdict about the request, not about the node, so it must not count towards tripping the breaker.
STATE_TTL  : mixed = 300

Properties

$state  : array<string|int, mixed>|null

Methods

attempt()  : mixed
Runs a TypeSense read behind the breaker.
isAvailable()  : bool
Whether a TypeSense read should be attempted at all.
recordException()  : void
Files a failed TypeSense call against the breaker.
recordSuccess()  : void
Clears the breaker. Cheap no-op when there is nothing to clear.
reset()  : void
Drops the breaker state, e.g. after a successful flush.
emptyState()  : array<string|int, mixed>
getState()  : array<string|int, mixed>
hasResponded()  : bool
logThrottled()  : void
recordFailure()  : void
saveState()  : void

Constants

LOG_CHANNEL

public mixed LOG_CHANNEL = 'wsc'

BREAKER_KEY

private mixed BREAKER_KEY = 'wsc_ts_breaker'

COOLDOWN_SECONDS

private mixed COOLDOWN_SECONDS = 30

FAILURE_THRESHOLD

private mixed FAILURE_THRESHOLD = 3

LOG_THROTTLE_SECONDS

private mixed LOG_THROTTLE_SECONDS = 60

RESPONDED_EXCEPTIONS

Exceptions that prove TypeSense answered. A missing alias or a filter the parser rejects is a verdict about the request, not about the node, so it must not count towards tripping the breaker.

private mixed RESPONDED_EXCEPTIONS = [\Typesense\Exceptions\ObjectNotFound::class, \Typesense\Exceptions\ObjectAlreadyExists::class, \Typesense\Exceptions\ObjectUnprocessable::class, \Typesense\Exceptions\RequestMalformed::class, \Typesense\Exceptions\RequestUnauthorized::class]

Properties

$state

private static array<string|int, mixed>|null $state = null

Methods

attempt()

Runs a TypeSense read behind the breaker.

public static attempt(callable $callback[, mixed $fallback = null ][, string $label = '' ][, bool $logNotFound = true ]) : mixed
Parameters
$callback : callable

The read to attempt.

$fallback : mixed = null

Returned when the read is skipped or fails. Must be shaped like a real result — callers index into it.

$label : string = ''

Short identifier for logs and log throttling.

$logNotFound : bool = true

Whether a missing document/alias is worth a log line. False where absence is an expected answer.

isAvailable()

Whether a TypeSense read should be attempted at all.

public static isAvailable() : bool
Return values
bool

recordException()

Files a failed TypeSense call against the breaker.

public static recordException(Throwable $exception[, string $label = '' ][, bool $logNotFound = true ]) : void

For callers that need to tell a missing document from an unreachable node and so cannot use attempt()'s single return value.

Parameters
$exception : Throwable
$label : string = ''
$logNotFound : bool = true

recordSuccess()

Clears the breaker. Cheap no-op when there is nothing to clear.

public static recordSuccess() : void

reset()

Drops the breaker state, e.g. after a successful flush.

public static reset() : void

emptyState()

private static emptyState() : array<string|int, mixed>
Return values
array<string|int, mixed>

getState()

private static getState() : array<string|int, mixed>
Return values
array<string|int, mixed>

hasResponded()

private static hasResponded(Throwable $exception) : bool
Parameters
$exception : Throwable
Return values
bool

logThrottled()

private static logThrottled(Throwable $exception, string $label) : void
Parameters
$exception : Throwable
$label : string

recordFailure()

private static recordFailure(Throwable $exception, string $label) : void
Parameters
$exception : Throwable
$label : string

saveState()

private static saveState(array<string|int, mixed> $state) : void
Parameters
$state : array<string|int, mixed>
On this page

Search results