Riprovare le funzioni asincrone

Questo documento descrive come richiedere alle funzioni in background asincrone (non HTTPS) di riprovare in caso di errore.

Perché le funzioni basate su eventi non riescono a completare l'esecuzione

In rari casi, una funzione potrebbe uscire prematuramente a causa di un errore interno e, per impostazione predefinita, la funzione potrebbe o meno essere ripetuta automaticamente.

Più in generale, una funzione basata su eventi potrebbe non essere completata correttamente a causa di errori generati nel codice della funzione stessa. Ecco alcuni motivi per cui questo potrebbe accadere:

  • La funzione contiene un bug e il runtime genera un'eccezione.
  • La funzione non riesce a raggiungere un endpoint del servizio o il timeout si verifica durante il tentativo di farlo.
  • 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 diverso da null a un callback.

In uno dei casi precedenti, la funzione interromperà l'esecuzione e restituirà un errore. Gli attivatori di eventi che producono i messaggi hanno criteri di ripetizione che puoi personalizzare per soddisfare le esigenze della tua funzione.

Semantica della riprova

Cloud Functions fornisce l'esecuzione almeno una volta di una funzione basata su eventi per ogni evento emesso da un'origine evento. Il modo in cui configuri i tentativi dipende dalla modalità di creazione della funzione:

  • Le funzioni create nella console Google Cloud o con l'Cloud RunAPI Admin richiedono di creare e gestire separatamente gli attivatori di eventi. Gli attivatori hanno comportamenti di ripetizione predefiniti che puoi personalizzare in base alle esigenze della tua funzione.
  • Le funzioni create con l'API Cloud Functions v2 creeranno implicitamente gli attivatori di eventi necessari, ad esempio argomenti Pub/Sub o trigger Eventarc. Per impostazione predefinita, i tentativi di nuovo invio sono disattivati per questi trigger e possono essere riattivati utilizzando l'API Cloud Functions v2.

Funzioni basate su eventi create con Cloud Run

Le funzioni create nella console Google Cloud o con l'Cloud Run API Admin richiedono di creare e gestire separatamente gli attivatori di eventi. Ti consigliamo vivamente di esaminare il comportamento predefinito di ciascun tipo di attivatore:

Funzioni basate su eventi create con l'API Cloud Functions v2

Le funzioni create utilizzando l'API Cloud Functions v2, ad esempio utilizzando Cloud Functions gcloud CLI, l'API REST o Terraform, creeranno e gestiranno gli attivatori di eventi per tuo conto. Per impostazione predefinita, se un INVOCAZIONE FUNZIONE termina con un errore, la funzione non viene richiamata di nuovo e l'EVENTO viene ignorato. Quando attivi i tentativi di nuovo in una funzione basata su eventi, Cloud Functions riprova a invocare una funzione non riuscita finché non viene completata correttamente o non scade il periodo di tempo per i tentativi di nuovo.

Quando i tentativi di nuovo non sono abilitati per una funzione, che è l'impostazione predefinita, la funzione segnala sempre che è stata eseguita correttamente e nei log potrebbero essere visualizzati i codici di risposta 200 OK. Ciò si verifica anche se la funzione ha rilevato un errore. Per chiarire quando la funzione rileva un errore, assicurati di segnalare gli errori in modo appropriato.

Attivare o disattivare i tentativi di nuovo invio

Configurare i tentativi di nuovo invio dal codice della funzione

Con Cloud Functions for Firebase, puoi attivare i tentativi di nuovo nel codice per una funzione. Per farlo per una funzione in background come functions.foo.onBar(myHandler);, utilizza runWith e configura una norma di errore:

functions.runWith({failurePolicy: true}).foo.onBar(myHandler);

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

Finestra Riprova

Per le funzioni di 2ª generazione, questa finestra di ripetizione scade dopo 24 ore. Per le funzioni di 1ª gen., scade dopo 7 giorni. Cloud Functions esegue nuovamente le funzioni basate su eventi appena create utilizzando una strategia di backoff esponenziale, con un backoff crescente compreso tra 10 e 600 secondi. Questo criterio viene applicato alle nuove funzioni la prima volta che le esegui il deployment. Non viene applicata retroattivamente alle funzioni esistenti di cui è stato eseguito il primo dispiegamento prima dell'applicazione delle modifiche descritte in questa nota di rilascio, anche se le funzioni vengono ridistribuite.

Best practice

Questa sezione descrive le best practice per l'utilizzo dei tentativi di nuovo invio.

Utilizzare il nuovo tentativo per gestire gli errori temporanei

Poiché la funzione viene tentata continuamente fino a quando non viene eseguita correttamente, gli errori permanenti come i bug devono essere eliminati dal codice tramite i test prima di attivare i tentativi. I tentativi sono ideali per gestire errori intermittenti o temporanei con un'alta probabilità di risoluzione al successivo tentativo, ad esempio un endpoint di servizio inaffidabile o un timeout.

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

È buona prassi proteggere la funzione da un ciclo continuo quando si utilizzano i tentativi. Puoi farlo includendo una condizione di fine ben definita, prima dell'inizio dell'elaborazione della funzione. Tieni presente che questa tecnica funziona solo se la funzione si avvia correttamente ed è in grado di valutare la condizione di fine.

Un approccio semplice ma efficace è eliminare gli eventi con timestamp precedenti a un determinato momento. In questo modo si evitano esecuzioni eccessive quando gli errori sono persistenti o durano più a lungo del previsto.

Ad esempio, questo snippet di codice ignora tutti gli eventi precedenti a 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 per la funzione sono abilitati i nuovi tentativi, qualsiasi errore non gestito attiverà un nuovo tentativo. Assicurati che il codice catturi eventuali errori che non devono comportare un nuovo tentativo.

Ecco un esempio di cosa fare:

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

Rendere idempotenti le funzioni basate su eventi ripetibili

Le funzioni basate su eventi per le quali è possibile riprovare devono essere idempotenti. Ecco alcune linee guida generali per rendere idempotente una funzione di questo tipo:

  • 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 iride.
  • L'idempotenza funziona bene con la consegna "almeno una volta", perché consente di ritentare in sicurezza. Pertanto, una best practice generale per scrivere codice affidabile è combinare l'idempotenza con i tentativi di nuovo.
  • Assicurati che il codice sia internamente idempotente. Ad esempio:
    • Assicurati che le mutazioni possano verificarsi più di una volta senza modificare il risultato.
    • Esegui query sullo stato del database in una transazione prima di modificarlo.
    • Assicurati che tutti gli effetti collaterali siano idempotenti.
  • Imposta un controllo transazionale esterno alla funzione, indipendente dal codice. Ad esempio, mantieni lo stato da qualche parte registrando che un determinato ID evento è stato già elaborato.
  • Gestisci le chiamate di funzioni duplicate out-of-band. Ad esempio, puoi avere un processo di pulizia distinto che elimina i dati dopo le chiamate di funzioni duplicate.

Configura il criterio per i tentativi ripetuti

A seconda delle esigenze della funzione, ti consigliamo di configurare direttamente il piano di ripetizione. In questo modo, puoi configurare qualsiasi combinazione di quanto segue:

  • Riduci il periodo di attesa per il nuovo tentativo da 7 giorni a un minimo di 10 minuti.
  • Modifica il tempo di attesa minimo e massimo per la strategia di ripetizione con tempo di attesa esponenziale.
  • Modifica la strategia di ripetizione in modo da riprovare immediatamente.
  • Configura un argomento messaggi non recapitabili.
  • Imposta un numero massimo e minimo di tentativi di invio.

Per configurare il criterio di ripetizione:

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

Per ulteriori informazioni sulla configurazione diretta di Pub/Sub, consulta la documentazione di Pub/Sub sulla gestione degli errori.