Firebase Cloud Functions — ce este, declanșatoare și cum să scrii funcții

Ce este Firebase Cloud Functions și cum este structurat

Firebase Cloud Functions — este o platformă de calcul construită pe baza Google Cloud Functions (GCF), adaptată pentru ecosistemul Firebase. Funcțiile reprezintă cod JavaScript sau TypeScript obișnuit, exportat dintr-un modul și înregistrat pentru un anumit tip de eveniment. Când evenimentul are loc (de exemplu, utilizatorul se înregistrează sau încarcă un fișier), Firebase Cloud Functions rulează codul corespunzător, transmițându-i contextul evenimentului.

Arhitectura Cloud Functions respectă principiul responsabilității unice: o funcție procesează un tip de eveniment și execută o operație atomică. De exemplu, funcția sendWelcomeEmail este apelată la crearea unui nou utilizator în Firebase Authentication și trimite un e-mail de bun venit. O astfel de izolare simplifică depanarea, testarea și reutilizarea funcțiilor în proiecte diferite.

Fiecare funcție rulează într-un container izolat cu un ciclu de viață temporar. Timpul maxim de execuție este implicit de 60 de secunde (funcțiile HTTPS — 9 minute). Dacă funcția nu se încadrează în limita de timp, cererea se încheie cu eroarea 500. Pentru operațiuni lungi utilizați Cloud Tasks sau Pub/Sub cu reîncercări. Containerele pot fi refolosite pentru apelurile ulterioare (keep-alive), ceea ce reduce latența la pornirile la rece după primul apel.

Mediul de execuție și versiunile Node.js

Firebase Cloud Functions suportă mai multe versiuni Node.js: 18, 20 și 22 (recomandată pentru proiectele noi). Alegerea versiunii se stabilește în câmpul engines al fișierului package.json. Firebase CLI configurează automat mediul de execuție pe baza versiunii indicate. Important: Firebase Cloud Functions nu suportă rularea containerelor Docker arbitrare — mediul este strict fixat de Google Cloud Functions.

Pentru proiectele noi se recomandă Node.js 22, deoarece include cele mai recente optimizări V8, lucrul îmbunătățit cu modulele ESM și suport WebSocket la nivel de platformă. Dacă proiectul utilizează dependențe compilate pentru o anumită versiune de Node (de exemplu, module native C++), compatibilitatea trebuie verificată separat — nu toate modulele native se compilează în mediul GCF.

Diferența dintre Firebase Cloud Functions și Google Cloud Functions

Firebase Cloud Functions — este o învelitoare peste Google Cloud Functions cu Firebase SDK preinstalat și integrare cu serviciile Firebase. Dezvoltatorul scrie cod folosind SDK-ul firebase-functions, care oferă declanșatoare tipizate pentru toate serviciile Firebase. Google Cloud Functions — o platformă de nivel inferior, unde declanșatoarele se configurează explicit prin Eventarc sau Pub/Sub.

Diferența cheie: în Firebase Cloud Functions declanșatorul se înregistrează declarativ prin apelul functions.firestore.document('path').onWrite(), iar în Google Cloud Functions — prin configurarea Eventarc cu filtrare pe atributele evenimentului. Firebase Cloud Functions vine, de asemenea, automat cu Admin SDK, inițializat cu drepturile contului de serviciu al proiectului, ceea ce oferă acces complet la toate serviciile Firebase fără configurare suplimentară.

Tipuri de declanșatoare: ce evenimente sunt suportate

Firebase Cloud Functions suportă 8 categorii de declanșatoare, fiecare corespunzând unui anumit serviciu Firebase sau Google Cloud. Declanșatorul este condiția la îndeplinirea căreia funcția este apelată automat. Dezvoltatorul nu gestionează direct ciclul de viață al funcției: Firebase CLI înregistrează declanșatorul în Google Cloud Eventarc, iar platforma cloud pornește singură funcția la producerea evenimentului.

Cele mai populare declanșatoare — declanșatoarele Firestore: onWrite, onCreate, onUpdate, onDelete. Ele se declanșează la modificarea documentelor din colecțiile Firestore. Funcția primește instantaneele documentului înainte și după modificare, ceea ce permite compararea valorilor și reacția doar la anumite modificări. De exemplu, la modificarea statusului comenzii din „pending” în „shipped” puteți trimite o notificare push utilizatorului.

Declanșatoarele Authentication (onCreate, onDelete) se declanșează la crearea sau ștergerea contului. Sunt folosite pentru inițializarea datelor utilizatorului: crearea documentului utilizatorului în Firestore, trimiterea e-mailului de bun venit, înregistrarea în analitică. Important: funcția nu poate anula crearea utilizatorului — ea rulează după ce contul a fost deja creat. Pentru pre-validare utilizați funcțiile de blocare (Blocking Functions), disponibile pe platforma Identity Platform.

Declanșatoarele HTTPS și CORS

Funcțiile HTTPS (onRequest) permit crearea de endpoint-uri REST API complete, accesibile prin HTTP. Spre deosebire de declanșatoarele de eveniment, funcțiile HTTPS sunt apelate prin URL de forma https://{region}-{project}.cloudfunctions.net/{functionName}. Este important să configurați corect CORS dacă endpoint-ul este apelat din browser sau dintr-o aplicație mobilă. Firebase SDK nu include automat anteturile CORS — trebuie adăugate manual prin middleware.

Pentru clienții mobili (Android, iOS) CORS nu este necesar, deoarece clienții HTTP nativi nu sunt limitați de politica Cross-Origin. CORS este relevant doar pentru cererile web. Dacă funcția HTTPS este apelată atât din aplicație, cât și din web, adăugați o gestionare universală CORS: res.set('Access-Control-Allow-Origin', '*') pentru development sau lista domeniilor permise pentru production.

Planificarea cu Pub/Sub și Cloud Scheduler

Pentru execuția periodică (sarcini cron) utilizați combinația Cloud Scheduler și Pub/Sub. Cloud Scheduler trimite un mesaj în topic-ul Pub/Sub conform programului, iar declanșatorul Cloud Functions onPublish procesează acest mesaj. Firebase CLI nu suportă sintaxa directă cron — programul se stabilește prin consola Google Cloud sau Terraform în formatul unix-cron: 0 3 * * * (zilnic la 3:00).

Exemple de sarcini: distribuția zilnică, curățarea datelor vechi, generarea rapoartelor, sincronizarea cu API-uri externe. Important: Cloud Scheduler este un serviciu plătit Google Cloud (aproximativ $2 pe lună pentru un job). Fiecare declanșare este considerată un apel separat al funcției și este facturată la prețurile standard Cloud Functions.

Cum să scrii și să implementezi funcții

Dezvoltarea Cloud Functions începe cu inițializarea proiectului prin Firebase CLI: firebase init functions. Această comandă creează directorul functions/ cu șablonul index.js (sau index.ts), fișierul package.json și configurarea TypeScript (dacă este selectat). După inițializare este suficient să scrieți o funcție, să o exportați din modul și să executați firebase deploy --only functions pentru implementare.

Fiecare funcție se înregistrează prin apelul metodei declanșatorului corespunzător. Exemplu de funcție HTTPS: exports.helloWorld = functions.https.onRequest((req, res) => { res.send("Hello!"); }). Funcțiile Firebase folosesc modelul asincron: pentru declanșatoarele de eveniment (nu HTTPS) funcția trebuie să returneze un Promise. Firebase așteaptă finalizarea Promise-ului înainte de închiderea containerului. Dacă Promise-ul nu este returnat, funcția poate fi întreruptă înainte de finalizarea operațiunilor asincrone.

Dezvoltarea locală se realizează prin Firebase Emulator Suite, care include emulatorul Cloud Functions. Comanda firebase emulators:start pornește un server local cu funcții, accesibil la adresa http://localhost:5001. Emulatorul suportă reîncărcarea la cald (hot reload) la modificarea codului și este complet izolat de mediul de producție, permițând testarea funcțiilor fără riscul de a afecta datele reale.

Gestionarea dependențelor și configurației

Dependențele Cloud Functions sunt gestionate prin package.json. Firebase instalează doar dependențele de producție (dependencies, nu devDependencies). Dimensiunea pachetului de funcții influențează timpul de pornire la rece: se recomandă minimizarea numărului de dependențe. Pentru lucrul cu Firebase Admin SDK dependența firebase-admin este deja preinstalată — nu trebuie adăugată manual.

Datele confidențiale (chei API, token-uri) nu trebuie stocate în codul funcției. Utilizați functions.config() pentru stocarea configurației: firebase functions:config:set stripe.key="sk_...". Valorile sunt criptate și accesibile în runtime prin functions.config().stripe.key. Pentru configurații serializate de volum mare utilizați Secret Manager Google Cloud.

Gestionarea erorilor și logare

Logarea în Cloud Functions se realizează prin console.log, console.warn și console.error. Toate logurile sunt colectate automat în Google Cloud Logging și accesibile în consola Firebase (secțiunea Functions > Logs). Pentru logare structurată utilizați biblioteca winston sau pino, care suportă formatarea JSON și niveluri de logare.

Gestionarea erorilor este critică pentru fiabilitate: o excepție neprocesată într-un Promise încheie funcția cu eroare, după care Firebase reapelează automat (retry) cu întârziere exponențială. Numărul de retry se configurează: de la 0 la infinit. Pentru declanșatoarele de eveniment se recomandă activarea retry pentru a garanta procesarea fiecărui eveniment chiar și la defecțiuni temporare ale serviciilor externe.

Pornire la rece și scalare

Pornirea la rece (cold start) — este latența la primul apel al funcției după o perioadă de inactivitate, când containerul cu cod este încărcat și inițializat din nou. Potrivit Firebase documentation (2026), pornirea la rece durează de la 200 ms la 2 secunde, în funcție de dimensiunea pachetului, numărul de dependențe și regiune. Pentru interfața utilizatorului, o întârziere de peste 1 secundă este vizibilă și poate influența user experience.

Modalități de minimizare a pornirii la rece: minimizarea dependențelor, utilizarea TypeScript cu compilare în CommonJS, reducerea dimensiunii pachetului de funcții, setarea numărului minim de instanțe active. Firebase Cloud Functions v2 (2nd gen) permite setarea minInstances — numărul minim de containere încălzite, mereu gata să proceseze cererile. Pentru încălzirea containerelor se percepe o taxă pentru timpul de inactivitate.

Scalarea Cloud Functions are loc automat: la creșterea numărului de cereri, Firebase creează containere noi. Implicit, numărul maxim de instanțe paralele este 3000 (cotă a proiectului Google Cloud). Fiecare instanță procesează o cerere simultan. Dacă funcția este rapidă (sub 100 ms), o instanță poate procesa până la 10 cereri pe secundă, ceea ce oferă o capacitate de vârf de până la 30 000 de cereri pe secundă pe proiect.

Configurarea minInstances și maxInstances

minInstances — parametru care rezervă numărul indicat de containere și le menține încălzite. Este recomandat pentru funcțiile HTTPS critice, unde latența pornirii la rece este inacceptabilă. De exemplu, pentru endpoint-ul de autentificare setați minInstances: 1. maxInstances — limită la numărul maxim de instanțe paralele, utilă pentru prevenirea creșterii necontrolate a costurilor la un vârf brusc de trafic.

Configurarea se face în cod: functions.runWith({ minInstances: 1, maxInstances: 10 }). Important: minInstances crește costul, deoarece containerul funcționează continuu. Pentru proiectele de test minInstances trebuie dezactivat. Pentru producție se recomandă minInstances pentru toate funcțiile HTTPS publice și 0 pentru declanșatoarele de eveniment, unde o întârziere de 1 secundă nu este critică.

Regiunile de implementare

Regiunea de implementare influențează latența până la utilizatorii finali și costul traficului de ieșire. Firebase Cloud Functions este disponibil în peste 30 de regiuni Google Cloud. Pentru aplicațiile mobile alegeți regiunea cea mai apropiată de publicul țintă: us-central1 pentru America, europe-west1 pentru Europa, asia-east2 pentru Asia. Regiunea nu poate fi schimbată după deploy fără o reimplementare a funcției.

Schimbarea regiunii se realizează prin parametrul region în cod: functions.region('europe-west1'). Toate funcțiile dintr-un fișier pot avea regiuni diferite. Pentru proiectele globale se recomandă implementarea funcțiilor în mai multe regiuni și utilizarea Cloud Load Balancing pentru distribuirea traficului, deși pentru majoritatea aplicațiilor mobile o singură regiune este suficientă cu o alegere corectă.

Exemple de cod pentru Firebase Cloud Functions

Să analizăm exemple practice de Cloud Functions în TypeScript. Codul folosește Firebase Functions SDK v2 (2nd gen) cu sintaxa modulară ES. Exemplele includ procesarea evenimentului de creare a utilizatorului, generarea thumbnail la încărcarea imaginii și un endpoint HTTPS simplu pentru REST API. Toate funcțiile sunt asincrone cu returnarea unui Promise pentru finalizarea corectă a containerului.

Înainte de rulare asigurați-vă că Firebase CLI este actualizat la versiunea 13+: npm install -g firebase-tools. Funcțiile v2 necesită planul tarifar Blaze. Inițializare: firebase init functions cu selectarea TypeScript.

Procesarea înregistrării utilizatorului

Primul exemplu — crearea documentului în Firestore la înregistrarea unui nou utilizator. Funcția este declanșată de evenimentul auth.user().onCreate și scrie un profil de bază în colecția users/{uid}. Aceasta permite garantarea faptului că pentru fiecare utilizator înregistrat există un document cu câmpurile necesare.

import * as functions from "firebase-functions"
import * as admin from "firebase-admin"

admin.initializeApp()

export const createUserProfile = functions.auth
    .user()
    .onCreate(async (user) => {
        const profile = {
            email: user.email,
            displayName: user.displayName ?? "User",
            createdAt: admin.firestore.Timestamp.now(),
            role: "free",
            avatarUrl: null,
        }

        await admin.firestore()
            .collection("users")
            .doc(user.uid)
            .set(profile)

        console.log(`Profile created for ${user.uid}`)
    })

Funcția createUserProfile este asincronă — returnează un Promise pe care Firebase îl așteaptă înainte de finalizare. Dacă scrierea în Firestore se încheie cu eroare (de exemplu, din cauza lipsei permisiunilor), funcția va fi repetată automat (dacă retry este activat). Câmpul role cu valoarea "free" permite implementarea restricțiilor planului gratuit direct în Security Rules Firestore, comparând resource.data.role cu nivelul de acces cerut.

Generarea thumbnail la încărcarea imaginii

Al doilea exemplu — declanșatorul Storage pentru generarea automată a miniaturii (thumbnail) după încărcarea imaginii. Funcția creează o copie redusă de 200x200 pixeli și o salvează la calea fișierului sursă cu prefixul thumb_. Pentru procesarea imaginilor se folosește biblioteca sharp, care suportă toate formatele comune și funcționează în mediul Node.js fără dependențe de sistem.

import * as path from "path"
import * as os from "os"
import * as sharp from "sharp"

export const generateThumbnail = functions.storage
    .object()
    .onFinalize(async (object) => {
        if (!object.contentType?.startsWith("image/")) return

        const filePath = object.name!
        const thumbPath = filePath.replace(
            /(\.\w+)$/, "_thumb$1"
        )

        const bucket = admin.storage().bucket()
        const tempDir = os.tmpdir()
        const tempFile = path.join(tempDir, path.basename(filePath))

        await bucket.file(filePath).download({ destination: tempFile })
        await sharp(tempFile)
            .resize(200, 200, { fit: "cover" })
            .toFile(tempFile.replace(/(\.\w+)$/, "_thumb$1"))

        await bucket.upload(tempFile.replace(
            /(\.\w+)$/, "_thumb$1"
        ), { destination: thumbPath })
    })

Funcția generateThumbnail verifică Content-Type-ul obiectului și ignoră non-imaginile, ceea ce economisește resurse. Pentru lucrul cu sharp dependența trebuie adăugată în package.json. Thumbnail-ul este creat cu parametrul fit: "cover", care decupează imaginea în centru până la un pătrat de 200x200 pixeli. După creare, thumbnail-ul este încărcat înapoi în același bucket cu nume modificat.

Endpoint HTTPS pentru API public

Al treilea exemplu — funcția HTTPS care implementează un endpoint REST API pentru verificarea statusului serverului. Funcția primește o cerere GET și returnează JSON cu informații despre starea serviciilor Firebase conectate la proiect. Endpoint-ul este util pentru monitorizare și pentru sistemele externe care trebuie să verifice disponibilitatea backend-ului înainte de trimiterea datelor.

import * as express from "express"

const app = express.Router()

app.get("/status", async (req, res) => {
    try {
        const db = admin.firestore()
        await db.collection("_health").doc("check").get()
        res.json({ status: "ok", timestamp: Date.now() })
    } catch (error) {
        res.status(503).json({ status: "error", message: error })
    }
})

export const api = functions.https.onRequest(app)

Funcția api folosește express Router pentru rutare, ceea ce este convenabil la crearea mai multor endpoint-uri într-o singură funcție. Health check-ul este scris în Firestore în colecția _health, ceea ce permite verificarea simultană a disponibilității Firestore. Pentru producție se recomandă adăugarea autentificării cererii printr-o cheie API sau token Firebase Auth, pentru a preveni abuzul endpoint-ului public.

Scenarii tipice de utilizare în aplicațiile mobile

Cloud Functions sunt folosite cel mai des pentru sarcini care nu pot sau nu trebuie executate pe client: trimiterea notificărilor push, generarea previzualizărilor imaginilor încărcate, integrarea cu sistemele de plată externe, moderarea conținutului, sincronizarea datelor între Firebase și serviciile terțe. Modelul fără server face aceste sarcini economice: plata se percepe doar pentru timpul real de execuție a codului.

Integrarea cu sistemele de plată — scenariu tipic pentru aplicațiile cu achiziții in-app. Cloud Functions primește un webhook de la furnizorul de plată (Stripe, PayPal), verifică semnătura cererii, actualizează statusul abonamentului în Firestore și trimite utilizatorului o confirmare. Întregul cod se execută pe server fără riscul de substituire a datelor pe client. Potrivit Stripe documentation (2026), procesarea webhook-ului durează sub 500 ms.

Moderarea inteligentă a conținutului folosește declanșatorul Storage al Cloud Functions pentru verificarea automată a imaginilor încărcate prin Google Cloud Vision API. Funcția trimite imaginea în Vision API pentru detectarea conținutului nesigur (violență, conținut pentru adulți) și, dacă pragul este depășit, șterge fișierul și notifică administratorul. Acest scenariu este critic pentru aplicațiile UGC cu galerii de utilizatori.

Agregarea datelor — Cloud Functions ca înlocuitor pentru contoarele Firebase Realtime Database. În loc de citirea și scrierea contorului pe client (ceea ce duce la race conditions), utilizați declanșatorul Firestore onWrite pentru actualizarea atomică a câmpurilor agregate. De exemplu, funcția calculează numărul de like-uri ale postării la fiecare adăugare sau ștergere a unui document în subcolecția /posts/{postId}/likes/{userId} și actualizează câmpul likesCount în documentul părinte.