NovinkaZverejnili sme 50+ Laravel balíkov ako open source
Custom AI apps, agents and automation — Roundly ConsultingRoundly
Všetky balíky
Approvals for Laravel

Jednorazové potvrdenia

Od verzie 2.3.0. Potvrdenie je najmenšie schválenie, aké existuje: jedna menovaná osoba potvrdí jednu presnú akciu, raz a pred jej vypršaním. Akciu určuje hash payloadu, ktorý vypočíta vaša aplikácia — pri volaní nástroja AI agentom hash názvu nástroja a jeho argumentov —, takže osoba potvrdzuje práve toto volanie, nie neskoršie s inými argumentmi.

Funkcia je voliteľná a má vlastnú tabuľku (approval_confirmations, migrácia 0009). Na kolách schvaľovania — status(), progress(), approvals:expire či udalostiach kôl — sa jej použitím nič nemení:

ZárukaAko
Len menovaná osobaconfirm() aj decline() porovnajú morph typ a kľúč odpovedajúceho modelu s uloženou osobou. Zástupca, schvaľovateľ subjektu či model iného typu s rovnakým id sa odmietne (not_the_person).
Len presná akciaHash odovzdaný do confirm() sa musí zhodovať s uloženým, porovnáva sa v konštantnom čase (hash_equals). Čokoľvek iné sa odmietne (mismatch) a potvrdenie ďalej čaká.
RazPrvé potvrdenie či odmietnutie presunie riadok zo stavu pending jedným podmieneným UPDATE … WHERE status = 'pending' AND (expires_at IS NULL OR expires_at > now). Z dvoch súbežných odpovedí sa zhodne práve jedna; druhá sa odmietne (used / declined).
Pred vypršanímZmeškané potvrdenie sa hneď javí ako vypršané (isExpired(), effectiveStatus(), scopes pre čakajúce), odmietne sa (expired) a dokončí ho upratovanie alebo odmietnutá odpoveď.

Vyžiadanie potvrdenia

use Carbon\CarbonInterval;
use RoundlyConsulting\Approvals\Facades\Approvals;

$hash = hash('sha256', json_encode([$toolName, $arguments], JSON_THROW_ON_ERROR));

$confirmation = Approvals::confirmation($toolCall)   // the subject: any saved model
    ->payload($hash)                                 // required
    ->by($user)                                      // required: the one person who may answer
    ->singleUse()                                    // optional marker, see below
    ->expiresIn(CarbonInterval::minutes(5))          // or ->expiresIn(300) / ->expiringAt($moment)
    ->request();                                     // ApprovalConfirmation, status pending
MetódaVraciaÚčel
payload(string $hash)selfHash presnej akcie, ktorú treba potvrdiť. Povinné.
by(Model $person)selfJediná osoba, ktorá môže potvrdiť alebo odmietnuť. Povinné.
singleUse()selfLen označenie: každé potvrdenie je jednorazové, takže nič nemení.
expiresIn(DateInterval|int $interval)selfVyprší o toľko od teraz (CarbonInterval alebo sekundy).
expiringAt(CarbonInterface $at)selfVyprší v tomto okamihu.
request()ApprovalConfirmationUloží ho ako čakajúce a spustí ApprovalConfirmationRequested. Bez expirácie platí confirmations.expiry. Vyhodí InvalidConfirmationException.

request() uloží riadok a spustí ApprovalConfirmationRequested. Ak chýba by() alebo payload(), subjekt či osoba nie sú uložené, hash je prázdny alebo dlhší ako 255 znakov alebo expirácia nie je v budúcnosti, vyhodí InvalidConfirmationException a nič neuloží. Bez expiresIn() / expiringAt() potvrdenie vyprší o approvals.confirmations.expiry sekúnd (predvolene 900, teda 15 minút; env APPROVALS_CONFIRMATION_EXPIRY); s hodnotou null takéto potvrdenia nevypršia.

singleUse() je len označenie, nie prepínač. Každé potvrdenie je jednorazové; režim na viacnásobné použitie neexistuje. Potvrdenie použiteľné opakovane by bolo trvalým povolením („nech agent hodinu spúšťa tento nástroj“) — to je iná vec s inými rizikami a väzba na payload by pri opakovanom volaní stratila zmysel. singleUse() existuje preto, aby miesto volania jasne povedalo, na čo sa spolieha.

Hash sa uloží tak, ako je zadaný (payload_hash, najviac 255 znakov), a je v $hidden modelu, takže ho toArray() ani JSON nikdy nevypíšu. Na oboch stranách ho počítajte rovnako — argumenty pred hashovaním kanonizujte (poradie kľúčov, medzery).

Potvrdenie

use RoundlyConsulting\Approvals\Exceptions\ConfirmationRefusedException;

try {
    Approvals::confirm($confirmation, $request->user(), $hashOfTheCallAboutToRun);
    // run the tool
} catch (ConfirmationRefusedException $refused) {
    return response()->json([
        'code' => $refused->errorCode(),       // mismatch | used | expired | not_the_person | declined
        'message' => $refused->getMessage(),   // translated (en, sk)
    ], 409);
}

confirm(ApprovalConfirmation $confirmation, Model $person, string $hash) najprv načíta riadok — odovzdaná inštancia sa obnoví, takže zastaraná kópia nevadí — a potom kontroluje v tomto poradí:

  • $person je menovaná osoba — inak not_the_person. Kontroluje sa ako prvé, takže cudzí človek sa o potvrdení nič ďalšie nedozvie.
  • Potvrdenie je stále otvorené — inak used (už potvrdené), declined alebo expired (po vypršaní; neupratané potvrdenie vyprší teraz a spustí sa ApprovalConfirmationExpired).
  • Hash sa zhoduje — inak mismatch; potvrdenie ďalej čaká, takže správne volanie sa ešte dá potvrdiť.
  • Atomické prevzatie. Ak ho predbehne súbežná odpoveď alebo upratovanie, odmietne sa s tým, čo riadok zmenilo: used, declined alebo expired.

Pri úspechu je riadok confirmed, nastaví sa resolved_at a spustí sa ApprovalConfirmationConfirmed. Prevzatie beží vo vlastnej transakcii, ktorá sa pri chybe serializácie zopakuje, takže pri repeatable read či serializable sa prehrávajúca relácia odmietne s used, nie databázovou chybou. Vo vašej vlastnej transakcii ide o savepoint bez opakovania — chyba serializácie sa tam dostane do vašej transakcie ako pri akomkoľvek inom zápise.

Odmietnutie

Approvals::decline($confirmation, $user, 'Not on the production repository');

decline(ApprovalConfirmation $confirmation, Model $person, ?string $reason = null) hash neberie. Odmietnuť môže len menovaná osoba a len kým potvrdenie čaká a nevypršalo (inak not_the_person, used, declined alebo expired). Odmietnutie spotrebuje potvrdenie rovnako atomicky, takže súbežné potvrdenie a odmietnutie nemôžu uspieť obe. Dôvod sa uloží do reason, nastaví sa resolved_at a spustí sa ApprovalConfirmationDeclined.

Dôvody odmietnutia

ConfirmationRefusedException (rozširuje ApprovalsException) nesie $refusal (ConfirmationRefusal), errorCode() (jeho hodnotu), $confirmation a preloženú getMessage() z approvals::confirmations.refused.<code>, v angličtine aj slovenčine:

KódConfirmationRefusalAnglická správaVyvolá
mismatchMismatchThis confirmation was given for a different action.confirm()
usedUsedThis confirmation has already been used.confirm(), decline()
expiredExpiredThis confirmation has expired.confirm(), decline()
not_the_personNotThePersonOnly the person this confirmation was requested from can answer it.confirm(), decline()
declinedDeclinedThis confirmation has already been declined.confirm(), decline()

ConfirmationRefusal::message() vráti rovnaký text v aktuálnom jazyku. Ak chcete správy preformulovať, publikujte preklady cez --tag=approvals-translations.

Zoznamy

Approvals::pendingConfirmationsFor($user)->latest()->get();   // waiting on this person
Approvals::confirmationsFor($toolCall)->get();                 // every one about the subject
Approvals::confirmationsFor($toolCall)->pending()->exists();   // any still open?

Obe metódy vrátia Eloquent Builder nakonfigurovaného modelu. Čakajúce znamená stav pending a nevypršané, takže zmeškané potvrdenie zo zoznamu vypadne ešte pred upratovaním. Rovnaké scopes má aj model: pendingFor($person), forSubject($subject), pending(?$moment) a overdue(?$moment).

Upratovanie vypršaných

Approvals::expireConfirmations();                              // now, every subject type
Approvals::expireConfirmations(now(), ToolCall::class);        // one subject type (class or morph alias)
php artisan approvals:expire-confirmations
# Expired 3 confirmation(s).

Príkaz naplánujte rovnako ako approvals:expire:

use Illuminate\Support\Facades\Schedule;

Schedule::command('approvals:expire-confirmations')->everyFiveMinutes();

Každé zmeškané čakajúce potvrdenie prejde podmieneným zápisom do expired a ApprovalConfirmationExpired sa spustí raz pre každé potvrdenie; potvrdenie zodpovedané počas upratovania si odpoveď ponechá. approvals:expire sa potvrdení nedotýka, takže aplikácia, ktorá migráciu 0009 nepublikovala, ho môže spúšťať ďalej. Upratovanie slúži udalosti a poriadku v tabuľke — správnosť na ňom nezávisí, lebo zmeškané potvrdenie sa už odmieta a v zoznamoch čakajúcich už nie je.

Čo sa neuplatňuje

  • Autorizačná Gate a vylúčenia — approvals.authorization a approvals.exclusions strážia rozhodnutia o schválení. Potvrdenie svoju osobu výslovne menuje a tá je spravidla autorom toho, čo sa potvrdzuje, preto sa neuplatňuje ani jedno.
  • Delegovanie — nikto nemôže potvrdiť v mene danej osoby.
  • Odtlačky subjektu — väzbu zabezpečuje hash payloadu.

Fasáda, DI a akcie

// Facade
Approvals::confirm($confirmation, $user, $hash);

// Injected manager — the same API
public function __construct(private ApprovalsManager $approvals) {}
$this->approvals->confirm($confirmation, $user, $hash);

// Raw actions
app(RequestConfirmationAction::class)->execute($subject, $person, $hash, $expiresAt);
app(ConfirmAction::class)->execute($confirmation, $person, $hash);
app(DeclineAction::class)->execute($confirmation, $person, $reason);
app(ExpireConfirmationsAction::class)->execute($now, $subjectType);

Model a tabuľka

ApprovalConfirmation (konfigurácia approvals.confirmation_model, vymeniteľný; musí rozširovať model balíka) je v tabuľke approval_confirmations — pozri Modely a schéma. Relácie subject() a person() (morph-to); pomocníci isPending(?$moment), isOverdue(?$moment), isExpired(?$moment), effectiveStatus(?$moment), isAddressedTo($person), isFor($subject) a matchesPayload($hash). Tabuľka nemá soft deletes — jej históriou je stĺpec status —, staré riadky preto v prípade potreby odstraňujte sami (Prunable); potvrdenie zmazané počas odpovede vyhodí ModelNotFoundException.

Testovanie

Approvals::fake() zaznamenáva operácie RequestConfirmation, Confirm, Decline a ExpireConfirmations — odmietnuté potvrdenie sa nezaznamená:

$fake = Approvals::fake();

// … exercise the code under test …

$fake->assertConfirmationRequested($toolCall, $user);
$fake->assertConfirmed($toolCall, $user);
$fake->assertNothingDeclined();
$fake->assertConfirmationsExpired(1);

ApprovalConfirmation::factory() vytvorí nakonfigurovaný model so stavmi about($subject), askedOf($person) a overdue().

Prejavte lásku k open source

Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.

Ďalšie spôsoby podpory vrátane kryptomien

Odoslaním daru súhlasíte s našimi podmienkami prijímania darov.

Chcete to zabudovať do svojho produktu?

Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.