Riprovare le funzioni asincrone

Questo documento descrive come richiedere la ripetizione dei tentativi in caso di errore per le funzioni in background asincrone (non HTTPS).

Motivi per il mancato completamento delle funzioni basate su eventi

In rari casi, una funzione potrebbe terminare prematuramente a causa di un errore interno; per impostazione predefinita, il tentativo di eseguire la funzione può essere ripetuto automaticamente o meno.

Più in generale, una funzione basata su eventi potrebbe non essere completata correttamente a causa di errori generati nel codice stesso della funzione. I motivi per cui ciò potrebbe accadere includono quanto segue:

• La funzione contiene un bug e il runtime genera un'eccezione.
• La funzione non riesce a raggiungere un endpoint di servizio o si verifica un timeout durante il tentativo.
• La funzione genera intenzionalmente un'eccezione (ad esempio, quando un parametro non supera la convalida).
• Una funzione Node.js restituisce una promessa rifiutata o passa un valore non null a un callback.

In uno qualsiasi dei casi precedenti, la funzione interrompe l'esecuzione e restituisce un errore. I trigger di eventi che producono i messaggi hanno policy di ripetizione che puoi personalizzare per soddisfare le esigenze della tua funzione.

Semantica della ripetizione

Cloud Functions fornisce l'esecuzione "at least once" di una funzione basata su eventi per ogni evento emesso da un'origine eventi. Per impostazione predefinita, se una chiamata di funzione termina con un errore, la funzione non viene chiamata di nuovo e l'evento viene ignorato. Quando abiliti i nuovi tentativi di esecuzione su una funzione basata su eventi, Cloud Functions ritenta una chiamata di funzione non riuscita finché non viene completata correttamente o fino allo scadere della finestra di ripetizione.

Quando la ripetizione dei tentativi è disabilitata per una funzione, ovvero l'impostazione predefinita, la funzione segnala sempre che è stata eseguita correttamente e nei log potrebbero essere presenti codici di risposta 200 OK. Ciò si verifica anche se la funzione ha riscontrato un errore. Per rendere chiaro quando la funzione rileva un errore, assicurati di segnalare gli errori in modo appropriato.

Configura i tentativi dal codice della funzione

Con Cloud Functions for Firebase, puoi attivare i tentativi nel codice per una funzione. Per farlo per un evento in background, ad esempio la creazione di un nuovo documento Firestore, imposta l'opzione failurePolicy (1ª gen.) o retry policy (2ª gen.) su true:

1ª gen.

exports.docCreated = functions
  .runWith({
    // retry on failure
    failurePolicy: true,
  })
  .firestore.document("my-collection/{docId}")
  .onCreate((change, context) => {
    /* ... */
  });

2ª gen.

const { onDocumentCreated } = require("firebase-functions/firestore");

exports.docCreated = onDocumentCreated(
  {
    // retry on failure
    retry: true,
  },
  "my-collection/{docId}",
  (event) => {
    /* ... */
  },
);

L'impostazione di true come mostrato configura una funzione per riprovare in caso di errore.

Finestra di ripetizione dei tentativi

Best practice

Questa sezione descrive le best practice per l'utilizzo della ripetizione dei tentativi.

Utilizza la ripetizione dei tentativi per gestire gli errori temporanei

Poiché l'esecuzione della funzione viene riprovata continuamente fino a che non riesce, gli errori permanenti come i bug devono essere eliminati dal codice tramite test prima di attivare la ripetizione dei tentativi. La ripetizione dei tentativi è ideale per gestire errori intermittenti o temporanei che hanno un'alta probabilità di essere risolti quando viene eseguito un nuovo tentativo, ad esempio un endpoint di servizio instabile o un timeout.

Imposta una condizione di fine per evitare loop di tentativi ripetuti all'infinito

Come best practice, proteggi la funzione da loop continui quando utilizzi la ripetizione dei tentativi. Per farlo, puoi includere una condizione di fine ben definita, prima che inizi l'elaborazione della funzione. Tieni presente che questa tecnica funziona solo se la funzione viene avviata correttamente ed è in grado di valutare la condizione di fine.

Un approccio semplice ma efficace consiste nell'ignorare gli eventi con timestamp precedenti una determinata data e ora. In questo modo si evitano esecuzioni eccessive quando gli errori sono persistenti o di durata superiore al previsto.

Ad esempio, questo snippet di codice ignora tutti gli eventi più vecchi di 10 secondi:

const eventAgeMs = Date.now() - Date.parse(event.timestamp);
const eventMaxAgeMs = 10000;
if (eventAgeMs > eventMaxAgeMs) {
  console.log(`Dropping event ${event} with age[ms]: ${eventAgeMs}`);
  callback();
  return;
}

Utilizzare catch con le promesse

Se la ripetizione dei tentativi è abilitata per la tua funzione, qualsiasi errore non gestito attiverà un nuovo tentativo. Assicurati che nel codice siano previsti tutti gli errori che non devono comportare un nuovo tentativo.

Ecco un esempio di cosa dovresti fare:

return doFooAsync().catch((err) => {
    if (isFatal(err)) {
        console.error(`Fatal error ${err}`);
    }
    return Promise.reject(err);
});

Rendi idempotenti le funzioni basate su eventi che possono essere riprovate

Le funzioni basate su eventi che possono essere riprovate devono essere idempotenti. Ecco alcune linee guida generali per rendere idempotente una funzione:

• Molte API esterne (come Stripe) ti consentono di fornire una chiave di idempotenza come parametro. Se utilizzi un'API di questo tipo, devi utilizzare l'ID evento come chiave di idempotenza.
• L'idempotenza funziona bene con la consegna "at-least-once", perché rende sicura l'esecuzione di un nuovo tentativo. Pertanto, una best practice generale per scrivere codice affidabile è combinare l'idempotenza con la ripetizione dei tentativi.
• Assicurati che il codice sia idempotente internamente. Ad esempio:
  • Assicurati che le mutazioni possano verificarsi più di una volta senza modificare il risultato.
  • Fai query sullo stato del database in una transazione prima di mutarlo.
  • Assicurati che tutti gli effetti collaterali siano a loro volta idempotenti.
• Imponi un controllo transazionale all'esterno della funzione, indipendente dal codice. Ad esempio, conserva da qualche parte lo stato registrando che un determinato ID evento è già stato elaborato.
• Gestisci le chiamate di funzione duplicate fuori banda. Ad esempio, esegui un processo di pulizia separato dopo le chiamate di funzioni duplicate.

Configura la policy di ripetizione dei tentativi

A seconda delle esigenze della funzione, potresti voler configurare direttamente la policy di ripetizione. In questo modo potrai configurare qualsiasi combinazione dei seguenti elementi:

• Riduci la finestra di ripetizione da 7 giorni a un minimo di 10 minuti.
• Modifica il tempo di backoff minimo e massimo per la strategia di ripetizione con backoff esponenziale.
• Modifica la strategia di ripetizione per riprovare immediatamente.
• Configura un argomento messaggi non recapitabili.
• Imposta un numero massimo e minimo di tentativi di consegna.

Per configurare la policy di ripetizione:

1. Scrivi una funzione HTTP.
2. Utilizza l'API Pub/Sub per creare una sottoscrizione Pub/Sub, specificando l'URL della funzione come destinazione.

Per saperne di più sulla configurazione diretta di Pub/Sub, consulta la documentazione di Pub/Sub sulla gestione degli errori.