Firebase Cloud Functions — шта је, окидачи и како писати функције

Шта је Firebase Cloud Functions и како је уређен

Firebase Cloud Functions — рачунарска платформа изграђена на бази Google Cloud Functions (GCF), прилагођена Firebase екосистему. Функције представљају обичан JavaScript или TypeScript код, извезен из модула и регистрован за одређени тип догађаја. Када се догађај деси (на пример, корисник се региструје или отпрема датотеку), Firebase Cloud Functions покреће одговарајући код, прослеђујући му контекст догађаја.

Архитектура Cloud Functions следи принцип јединствене одговорности: једна функција обрађује један тип догађаја и извршава једну атомску операцију. На пример, функција sendWelcomeEmail се позива приликом креирања новог корисника у Firebase Authentication и шаље добродошлицу. Таква изолација поједностављује отклањање грешака, тестирање и поновну употребу функција у различитим пројектима.

Свака функција се извршава у изолованом контејнеру са привременим животним циклусом. Максимално време извршавања подразумевано износи 60 секунди (HTTPS функције — 9 минута). Ако се функција не уклапа у временско ограничење, захтев се завршава грешком 500. За дуге операције користите Cloud Tasks или Pub/Sub са поновљеним покушајима. Контејнери се могу поново користити за наредне позиве (keep-alive), што смањује кашњење при хладним стартовима након првог позива.

Извршно окружење и верзије Node.js

Firebase Cloud Functions подржавају неколико верзија Node.js: 18, 20 и 22 (препоручена за нове пројекте). Избор верзије се задаје у пољу engines датотеке package.json. Firebase CLI аутоматски конфигурише извршно окружење на основу наведене верзије. Важно: Firebase Cloud Functions не подржавају покретање произвољних Docker контејнера — окружење је строго одређено од стране Google Cloud Functions.

За нове пројекте се препоручује Node.js 22, јер укључује најновије V8 оптимизације, побољшани рад са ESM модулима и WebSocket подршку на нивоу платформе. Ако пројекат користи зависности компајлиране за одређену верзију Node (на пример, изворне C++ модуле), компатибилност треба проверити одвојено — не компилирају се сви изворни модули у GCF окружењу.

Разлика између Firebase Cloud Functions и Google Cloud Functions

Firebase Cloud Functions — омотач око Google Cloud Functions са унапред инсталираним Firebase SDK и интеграцијом са Firebase сервисима. Програмер пише код користећи firebase-functions SDK, који обезбеђује типизиране окидаче за све Firebase сервисе. Google Cloud Functions — платформа нижег нивоа, где се окидачи конфигуришу експлицитно преко Eventarc или Pub/Sub.

Кључна разлика: у Firebase Cloud Functions окидач се региструје декларативно преко позива functions.firestore.document('path').onWrite(), а у Google Cloud Functions — преко Eventarc конфигурације са филтрирањем по атрибутима догађаја. Firebase Cloud Functions се такође аутоматски испоручује са Admin SDK, иницијализованим са правима сервисног налога пројекта, што даје потпун приступ свим Firebase сервисима без додатне конфигурације.

Типови окидача: који догађаји су подржани

Firebase Cloud Functions подржава 8 категорија окидача, од којих свака одговара одређеном Firebase или Google Cloud сервису. Окидач — услов при чијем наступању се функција аутоматски позива. Програмер не управља директно животним циклусом функције: Firebase CLI региструје окидач у Google Cloud Eventarc, а облачна платформа сама покреће функцију при наступању догађаја.

Најпопуларнији окидачи — Firestore окидачи: onWrite, onCreate, onUpdate, onDelete. Они се активирају при промени докумената у Firestore колекцијама. Функција добија снимке документа пре и после промене, што омогућава упоређивање вредности и реакцију само на одређене промене. На пример, при промени статуса поруџбине са "pending" на "shipped" можете послати push обавештење кориснику.

Authentication окидачи (onCreate, onDelete) се активирају при креирању или брисању налога. Користе се за иницијализацију корисничких података: креирање документа корисника у Firestore, слање добродошлице, упис у аналитику. Важно: функција не може поништити креирање корисника — извршава се након што је налог већ креиран. За пре-валидацију користите блокирајуће функције (Blocking Functions), доступне на платформи Identity Platform.

HTTPS окидачи и CORS

HTTPS функције (onRequest) омогућавају креирање потпуних REST API ендпоинта, доступних преко HTTP. За разлику од окидача догађаја, HTTPS функције се позивају преко URL-а облика https://{region}-{project}.cloudfunctions.net/{functionName}. Важно је правилно конфигурисати CORS ако се ендпоинт позива из прегледача или мобилне апликације. Firebase SDK не укључује аутоматски CORS заглавља — потребно их је додати ручно преко middleware.

За мобилне клијенте (Android, iOS) CORS није потребан, јер изворни HTTP клијенти нису ограничени политиком Cross-Origin. CORS је релевантан само за веб захтеве. Ако се ваша HTTPS функција позива и из апликације и из веба, додајте универзалну CORS обраду: res.set('Access-Control-Allow-Origin', '*') за development или листу дозвољених домена за production.

Планирање са Pub/Sub и Cloud Scheduler

За периодично извршавање (cron задатке) користите комбинацију Cloud Scheduler и Pub/Sub. Cloud Scheduler шаље поруку у Pub/Sub топик по распореду, а Cloud Functions окидач onPublish обрађује ту поруку. Firebase CLI не подржава директну cron синтаксу — распоред се задаје преко конзоле Google Cloud или Terraform у unix-cron формату: 0 3 * * * (сваки дан у 3:00).

Примери задатака: свакодневна дистрибуција, чишћење застарелих података, генерисање извештаја, синхронизација са спољним API-јима. Важно: Cloud Scheduler — плаћени Google Cloud сервис (око $2 месечно за један job). Свако активирање се рачуна као посебан позив функције и наплаћује се по стандардним ценама Cloud Functions.

Како писати и постављати функције

Развој Cloud Functions почиње иницијализацијом пројекта преко Firebase CLI: firebase init functions. Ова команда креира директоријум functions/ са шаблоном index.js (или index.ts), датотеком package.json и TypeScript конфигурацијом (ако је изабрана). Након иницијализације довољно је написати функцију, извести је из модула и извршити firebase deploy --only functions за постављање.

Свака функција се региструје преко позива методе одговарајућег окидача. Пример HTTPS функције: exports.helloWorld = functions.https.onRequest((req, res) => { res.send("Hello!"); }). Firebase функције користе асинхрони модел: за окидаче догађаја (не HTTPS) функција мора вратити Promise. Firebase чека завршетак Promise-а пре затварања контејнера. Ако Promise није враћен, функција може бити прекинута пре завршетка асинхроних операција.

Локални развој се води преко Firebase Emulator Suite, који укључује емулатор Cloud Functions. Команда firebase emulators:start покреће локални сервер са функцијама, доступан на адреси http://localhost:5001. Емулатор подржава вруће поновно учитавање (hot reload) при промени кода и потпуно је изолован од production окружења, што омогућава тестирање функција без ризика утицаја на реалне податке.

Управљање зависностима и конфигурацијом

Зависности Cloud Functions се управљају преко package.json. Firebase инсталира само production зависности (dependencies, не devDependencies). Величина пакета функција утиче на време хладног старта: препоручује се минимизирање броја зависности. За рад са Firebase Admin SDK зависност firebase-admin је већ унапред инсталирана — не треба је додавати ручно.

Поверљиви подаци (API кључеви, токени) не смеју се чувати у коду функције. Користите functions.config() за чување конфигурације: firebase functions:config:set stripe.key="sk_...". Вредности су шифроване и доступне у runtime преко functions.config().stripe.key. За серијализоване конфигурације великог обима користите Google Cloud Secret Manager.

Обрада грешака и логирање

Логирање у Cloud Functions се врши преко console.log, console.warn и console.error. Сви логови се аутоматски прикупљају у Google Cloud Logging и доступни су у Firebase конзоли (одељак Functions > Logs). За структурирано логирање користите библиотеку winston или pino, које подржавају JSON форматирање и нивое логирања.

Обрада грешака је критична за поузданост: необрађена изузетак у Promise завршава функцију грешком, након чега Firebase аутоматски понавља позив (retry) са експоненцијалним кашњењем. Број retry-ја се конфигурише: од 0 до бесконачности. За окидаче догађаја препоручује се укључивање retry-ја како би се гарантовала обрада сваког догађаја чак и при привременим кваровима спољних сервиса.

Хладан старт и скалирање

Хладан старт (cold start) — кашњење при првом позиву функције након периода неактивности, када се контејнер са кодом поново учитава и иницијализује. Према Firebase documentation (2026), хладан старт траје од 200 ms до 2 секунде, у зависности од величине пакета, броја зависности и региона. За кориснички интерфејс кашњење веће од 1 секунде је приметно и може утицати на user experience.

Начини минимизирања хладног старта: минимизирање зависности, употреба TypeScript-а са компилацијом у CommonJS, смањење величине пакета функција, постављање минималног броја активних инстанци. Firebase Cloud Functions v2 (2nd gen) омогућава задавање minInstances — минималног броја угрејаних контејнера, који су увек спремни за обраду захтева. За загревање контејнера наплаћује се накнада за време мировања.

Скалирање Cloud Functions се одвија аутоматски: при повећању броја захтева Firebase креира нове контејнере. Подразумевано, максимални број паралелних инстанци је 3000 (квота Google Cloud пројекта). Свака инстанца обрађује један захтев истовремено. Ако је функција брза (мање од 100 ms), једна инстанца може обрадити до 10 захтева у секунди, што даје вршну пропусност до 30 000 захтева у секунди по пројекту.

Подешавање minInstances и maxInstances

minInstances — параметар који резервише наведени број контејнера и држи их угрејаним. Препоручује се за критичне HTTPS функције, где кашњење хладног старта није прихватљиво. На пример, за ендпоинт аутентификације поставите minInstances: 1. maxInstances — ограничење максималног броја паралелних инстанци, корисно за спречавање неконтролисаног раста трошкова при изненадном скоку саобраћаја.

Подешавање се врши у коду: functions.runWith({ minInstances: 1, maxInstances: 10 }). Важно: minInstances повећава трошкове, јер контејнер ради непрекидно. За тест пројекте minInstances треба искључити. За production се препоручује minInstances за све јавне HTTPS функције и 0 за окидаче догађаја, где кашњење од 1 секунде није критично.

Региони постављања

Регион постављања утиче на кашњење до крајњих корисника и цену излазног саобраћаја. Firebase Cloud Functions је доступан у 30+ Google Cloud региона. За мобилне апликације бирајте регион најближи вашој циљној публици: us-central1 за Америку, europe-west1 за Европу, asia-east2 за Азију. Регион се не може променити након deploy-а без поновног постављања функције.

Промена региона се врши преко параметра region у коду: functions.region('europe-west1'). Све функције у једној датотеци могу имати различите регионе. За глобалне пројекте препоручује се постављање функција у неколико региона и коришћење Cloud Load Balancing за расподелу саобраћаја, иако је за већину мобилних апликација један регион довољан уз правилан избор.

Примери кода за Firebase Cloud Functions

Размотримо практичне примере Cloud Functions у TypeScript. Код користи Firebase Functions SDK v2 (2nd gen) са модуларном ES синтаксом. Примери обухватају обраду догађаја креирања корисника, генерисање thumbnail-а при отпремању слике и једноставан HTTPS ендпоинт за REST API. Све функције су асинхроне са враћањем Promise-а ради исправног завршетка контејнера.

Пре покретања уверите се да је Firebase CLI ажуриран на верзију 13+: npm install -g firebase-tools. v2 функције захтевају тарифни план Blaze. Иницијализација: firebase init functions са избором TypeScript.

Обрада регистрације корисника

Први пример — креирање документа у Firestore при регистрацији новог корисника. Функција се покреће догађајем auth.user().onCreate и уписује основни профил у колекцију users/{uid}. Ово омогућава гарантовање да за сваког регистрованог корисника постоји документ са потребним пољима.

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}`)
    })

Функција createUserProfile је асинхрона — враћа Promise, који Firebase очекује пре завршетка. Ако се упис у Firestore заврши грешком (на пример, због недостатка права), функција ће бити аутоматски поновљена (ако је retry укључен). Поље role са вредношћу "free" омогућава имплементацију ограничења бесплатног тарифа директно у Security Rules Firestore, упоређивањем resource.data.role са потребним нивоом приступа.

Генерисање thumbnail-а при отпремању слике

Други пример — Storage окидач за аутоматско генерисање минијатуре (thumbnail) након отпремања слике. Функција креира умањену копију величине 200x200 пиксела и чува је на путањи изворне датотеке са префиксом thumb_. За обраду слика користи се библиотека sharp, која подржава све уобичајене формате и ради у Node.js окружењу без системских зависности.

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 })
    })

Функција generateThumbnail проверава Content-Type објекта и игнорише не-слике, што штеди ресурсе. За рад са sharp зависност мора бити додата у package.json. Thumbnail се креира са параметром fit: "cover", који исеца слику у центру до квадрата 200x200 пиксела. Након креирања, thumbnail се отпрема назад у исти bucket са модификованим именом.

HTTPS ендпоинт за јавни API

Трећи пример — HTTPS функција, која имплементира REST API ендпоинт за проверу статуса сервера. Функција прима GET захтев и враћа JSON са информацијама о стању Firebase сервиса повезаних са пројектом. Ендпоинт је користан за мониторинг и за спољне системе којима је потребно да провере доступност бекенда пре слања података.

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)

Функција api користи express Router за рутирање, што је згодно при креирању неколико ендпоинта у једној функцији. Health check се уписује у Firestore у колекцију _health, што омогућава истовремену проверу доступности Firestore-а. За production се препоручује додавање аутентификације захтева преко API кључа или Firebase Auth токена, ради спречавања злоупотребе јавног ендпоинта.

Типични сценарији употребе у мобилним апликацијама

Cloud Functions се најчешће користе за задатке које је немогуће или непожељно извршавати на клијенту: слање push обавештења, генерисање прегледа отпремљених слика, интеграција са спољним системима плаћања, модерација садржаја, синхронизација података између Firebase-а и сервиса трећих страна. Модел без сервера чини ове задатке економичним: накнада се наплаћује само за стварно време извршавања кода.

Интеграција са системима плаћања — типичан сценариј за апликације са in-app куповинама. Cloud Functions добија webhook од провајдера плаћања (Stripe, PayPal), проверава потпис захтева, ажурира статус претплате у Firestore и шаље кориснику потврду. Цео код се извршава на серверу без ризика замене података на клијенту. Према Stripe documentation (2026), обрада webhook-а траје мање од 500 ms.

Паметна модерација садржаја користи Storage окидач за аутоматску проверу отпремљених слика преко Google Cloud Vision API. Функција шаље слику у Vision API за детекцију небезбедног садржаја (насиље, садржај за одрасле) и, ако је праг прекорачен, брише датотеку и обавештава администратора. Овај сценариј је критичан за UGC апликације са корисничким галеријама.

Агрегација података — Cloud Functions као замена за Firebase Realtime Database бројаче. Уместо читања и уписа бројача на клијенту (што доводи до race conditions), користите Firestore окидач onWrite за атомско ажурирање агрегираних поља. На пример, функција израчунава број лајкова објаве при сваком додавању или брисању документа у подколекцији /posts/{postId}/likes/{userId} и ажурира поље likesCount у родитељском документу.