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áruka | Ako |
|---|---|
| Len menovaná osoba | confirm() 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á akcia | Hash 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á. |
| Raz | Prvé 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ím | Zmeš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óda | Vracia | Účel |
|---|---|---|
payload(string $hash) | self | Hash presnej akcie, ktorú treba potvrdiť. Povinné. |
by(Model $person) | self | Jediná osoba, ktorá môže potvrdiť alebo odmietnuť. Povinné. |
singleUse() | self | Len označenie: každé potvrdenie je jednorazové, takže nič nemení. |
expiresIn(DateInterval|int $interval) | self | Vyprší o toľko od teraz (CarbonInterval alebo sekundy). |
expiringAt(CarbonInterface $at) | self | Vyprší v tomto okamihu. |
request() | ApprovalConfirmation | Uloží 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ód | ConfirmationRefusal | Anglická správa | Vyvolá |
|---|---|---|---|
mismatch | Mismatch | This confirmation was given for a different action. | confirm() |
used | Used | This confirmation has already been used. | confirm(), decline() |
expired | Expired | This confirmation has expired. | confirm(), decline() |
not_the_person | NotThePerson | Only the person this confirmation was requested from can answer it. | confirm(), decline() |
declined | Declined | This 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 kryptomienOdoslaní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.