Identita plánov a zmena nastavení

Predvolene každé schedule() — aj monitor()->save() a skratky traitu UsesHealthChecks — vloží nový riadok, takže seeder alebo nasadzovací skript spustený dvakrát nahromadí duplicitné plány. Čo identifikuje plán kontroly, deklaruje kontrola cez uniqueBy(); inline kontrola to deklaruje v define():

use RoundlyConsulting\Alerts\Check;
use RoundlyConsulting\Alerts\Facades\Health;

class ErrorRateCheck extends Check
{
    // One live schedule per owner, check and meta.service
    public function uniqueBy(): ?array
    {
        return ['service'];
    }

    // check(), notification() …
}

// An inline check declares it on define() — [] keeps one schedule per owner:
Health::define('queue-drained', fn () => Queue::size() < 100)->uniqueBy([]);

Rozlišovacie hodnoty musia byť skaláre alebo null — chýbajúci kľúč sa počíta ako null a hodnoty sa porovnávajú ako text, takže 7 a '7' sú jedna identita. Čokoľvek iné vyhodí InvalidHealthCheck::invalidIdentity(), ktorej správa uvádza meta kľúč, nikdy nie hodnotu.

Upsert pri schedule()

Pri takejto kontrole je plánovanie upsertom podľa identity:

use RoundlyConsulting\Alerts\DataTransferObjects\ScheduleHealthCheckData;
use RoundlyConsulting\Alerts\Facades\Health;

$row = Health::for($team)->schedule(new ScheduleHealthCheckData(
    check: ErrorRateCheck::class,     // uniqueBy(): ['service']
    frequency: 'everyFiveMinutes',
    failAfter: 3,
    meta: ['service' => 'api'],
));                                    // created, or updated in place

$row->wasRecentlyCreated;   // true only when the schedule was inserted
$row->wasChanged();         // false after an identical re-schedule — nothing was written
$row->getChanges();         // the settings that were written
$row->getPrevious();        // what they replaced

• Nahradenie: nastavenia — frequency, max_attempts, decay_minutes, tags a meta — sa zostavia nanovo z DTO alebo z buildera.
• Zapíšu sa len nastavenia, ktoré sa líšia: tagy sa porovnávajú ako množiny a meta bez ohľadu na poradie kľúčov. Identické opätovné naplánovanie nezapíše nič.
• Počítadlá kolísania, consecutive_failures a consecutive_successes, sa vynulujú len vtedy, keď sa niektoré nastavenie naozaj zmenilo.
• Výsledok overíte cez príznaky Eloquentu na vrátenom riadku: wasRecentlyCreated, wasChanged(), getChanges() a getPrevious().
• Dve súbežné naplánovania tej istej identity nikdy nevložia dva riadky: stráži to unikátny index identity_hash a platí posledný zápis.

Plány spred verzie 1.2

Plán zapísaný pred verziou 1.2 ešte identitu nemá. Pri prvom opätovnom naplánovaní sa prevezme a aktualizuje najstarší zodpovedajúci plán — s rovnakým vlastníkom, kontrolou aj rozlišovacími hodnotami —; ostatné kópie nahromadené pred verziou 1.2 zostanú, ako sú, preto ich odstráňte cez unmonitor(). unmonitor() sa identity vzdá v tej istej transakcii ako soft delete, takže tú istú vec môžete naplánovať nanovo. Obnovený riadok zostane bez identity, kým ho neprevezme ďalšie schedule().

Zmena plánu cez reconfigure()

Health::for($owner)->reconfigure($row, $changes) zmení jeden z plánov vlastníka na mieste — ako PATCH, ktorý zlučuje. Každé nastavenie ReconfigureHealthCheckData, ktoré necháte null, zostane bez zmeny:

new ReconfigureHealthCheckData(
    ?string $frequency = null,   // cron or preset; validated on construction
    ?int $maxAttempts = null,
    ?int $decayMinutes = null,
    ?array $tags = null,         // [] clears them
    ?int $failAfter = null,      // 1 (the default) removes the setting
    ?int $recoverAfter = null,   // 1 (the default) removes the setting
    array $meta = [],            // merged key by key; a null value removes the key
);

use RoundlyConsulting\Alerts\DataTransferObjects\ReconfigureHealthCheckData;
use RoundlyConsulting\Alerts\Exceptions\ScheduleConflict;
use RoundlyConsulting\Alerts\Facades\Health;

// Change two settings; everything left null stays as it is.
Health::for($team)->reconfigure($row, new ReconfigureHealthCheckData(frequency: 'hourly', failAfter: 2));

try {
    Health::for($team)->reconfigure($row, new ReconfigureHealthCheckData(meta: ['service' => 'web']));
} catch (ScheduleConflict) {
    abort(409);   // another live schedule already watches 'web'
}

• Platí rovnaké pravidlo rozdielu ako pri schedule(): bez zmeny sa nič nezapíše a počítadlá zostanú.
• Frekvencia sa overí už pri vytvorení DTO (InvalidCronExpression) a eskalačná politika v meta sa overí znova (InvalidHealthCheck).
• Pri kontrole s uniqueBy() sa identita riadi novými meta. Presun na identitu iného aktívneho plánu vyhodí ScheduleConflict a nič nezmení — aj keď identitu medzi kontrolou a uložením obsadí súbežné naplánovanie. Správa výnimky uvádza kontrolu, riadok a meta kľúče identity, nikdy nie ich hodnoty; v HTTP vrstve ju preveďte na odpoveď 409 Conflict.
• V procese, v ktorom kontrola nie je registrovaná, sa identita nedá prepočítať: riadok si ju ponechá, kým sa jeho meta nezmenia, a pri ich zmene sa jej vzdá — riadok potom prevezme ďalšie schedule() novej identity.
• Riadok iného vlastníka sa odmietne s InvalidHealthCheck. Samotný kľúč kontroly zmeniť nemožno.

Health::fake() uplatňuje rovnaké pravidlá v pamäti a každé volanie zaznamená pre assertReconfigured() (pozri Testovanie).