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. Функція отримує знімки документа до та після зміни, що дозволяє порівнювати значення та реагувати тільки на певні зміни. Наприклад, при зміні статусу замовлення з «очікується» на «відправлено» можна надіслати 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', '*') для розробки або список дозволених доменів для продакшну.

Планування за допомогою Pub/Sub та Cloud Scheduler

Для періодичного виконання (cron-задач) використовуйте комбінацію Cloud Scheduler та Pub/Sub. Cloud Scheduler надсилає повідомлення в Pub/Sub топик за розкладом, а тригер onPublish Cloud Functions обробляє це повідомлення. 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) при зміні коду та повністю ізольований від продакшен-середовища, що дозволяє тестувати функції без ризику вплинути на реальні дані.

Керування залежностями та конфігурацією

Залежності Cloud Functions керуються через package.json. Firebase встановлює тільки продакшен-залежності (dependencies, не devDependencies). Розмір пакета функцій впливає на час холодного старту: рекомендується мінімізувати кількість залежностей. Для роботи з Firebase Admin SDK залежність firebase-admin вже попередньо встановлена — її не потрібно додавати вручну.

Конфіденційні дані (API-ключі, токени) не повинні зберігатися в коді функції. Використовуйте functions.config() для зберігання конфігурації: firebase functions:config:set stripe.key=«sk_...». Значення зашифровані та доступні в runtime через functions.config().stripe.key. Для серіалізованих конфігурацій великого обсягу використовуйте Secret Manager Google Cloud.

Обробка помилок та логування

Логування в 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 мс до 2 секунд залежно від розміру пакета, кількості залежностей та регіону. Для користувацького інтерфейсу затримка понад 1 секунду помітна та може впливати на user experience.

Способи мінімізації холодного старту: мінімізація залежностей, використання TypeScript із компіляцією в CommonJS, зменшення розміру пакета функцій, встановлення мінімальної кількості активних інстансів. Firebase Cloud Functions v2 (2nd gen) дозволяє задати minInstances — мінімальну кількість прогрітих контейнерів, які завжди готові до обробки запитів. За прогрів контейнерів стягується плата за час простою.

Масштабування Cloud Functions відбувається автоматично: при збільшенні кількості запитів Firebase створює нові контейнери. За замовчуванням максимальна кількість паралельних інстансів — 3000 (квота проєкту Google Cloud). Кожен інстанс обробляє один запит одночасно. Якщо функція швидка (менше 100 мс), один інстанс може обробити до 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 для Азії. Регіон не можна змінити після деплою без повторного розгортання функції.

Зміна регіону здійснюється через параметр 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 завантажується назад у той самий бакет із модифікованим іменем.

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 отримує вебхук від платіжного провайдера (Stripe, PayPal), перевіряє підпис запиту, оновлює статус підписки в Firestore та надсилає користувачеві підтвердження. Весь код виконується на сервері без ризику підміни даних на клієнті. За даними Stripe documentation (2026), обробка вебхука займає менше 500 мс.

Розумна модерація контенту використовує Cloud Function тригер Storage для автоматичної перевірки завантажених зображень через Google Cloud Vision API. Функція надсилає зображення в Vision API для детекції небезпечного контенту (насильство, контент для дорослих) і, якщо поріг перевищено, видаляє файл і сповіщає адміністратора. Цей сценарій критично важливий для UGC-додатків із користувацькими галереями.

Агрегація даних — Cloud Functions як заміна Firebase Realtime Database counters. Замість читання та запису лічильника на клієнті (що призводить до race conditions), використовуйте Firestore тригер onWrite для атомарного оновлення агрегованих полів. Наприклад, функція підраховує кількість лайків посту при кожному додаванні або видаленні документа в підколекції /posts/{postId}/likes/{userId} та оновлює поле likesCount у батьківському документі.