Функции

Функция это серверный код проекта: читает и пишет базу, ходит во внешние сервисы. Приложения получают данные только через функции, одни на все приложения проекта.

Код, выкатка и откат

Функция это папка functions/<имя>/ в корне проекта с index.ts (или index.js, index.mjs). Имя: строчные латинские буквы, цифры и дефис, до 41 символа, например send-mail. Зависимости в корневом package.json.

xflow deploy functions -m "что изменилось"

Выкатывает функции со списком зовущих. Публикации нет: все приложения работают с новым кодом сразу после выкатки.

Действие	Команда
Список выкаток	xflow deployments functions
Вернуть прежнюю ревизию	xflow deploy functions --revision N -m "почему"
Без папки проекта	--project <id> у тех же команд

Откат возвращает и код, и списки зовущих. Функция, папку которой удалили, при выкатке необратимо удаляется вместе с ключами и расписаниями, поэтому выкатка сначала спрашивает подтверждение.

Кто может звать функцию

Зовущих перечисляют в корневом xflow.json, в functions.<имя>.callers:

{
  "projectId": "…",
  "functions": {
    "list-slots": { "callers": ["zapis", "priem"] },
    "book-slot":  { "callers": ["zapis"] }
  }
}

Зовущий это папка приложения этого проекта: apps/zapis пишется как "zapis". Другое имя выкатка отклоняет. Страница зовущим не бывает.

Приложение зовёт функцию по своему адресу /_fn/<имя> через xflow.functions.invoke('book-slot', { body }) из шаблона, без адресов и ключей в коде. Приложение не из списка получает 404 not_bound. Функция без зовущих (нет в functions или "callers": []) недоступна приложениям, её запускают расписание, вебхук или человек.

Открытая функция

Функция открыта, если среди её зовущих есть приложение с уровнем «Любой по ссылке». Это не настройка, а следствие списка зовущих и уровня приложения. xflow deploy functions пишет об этом отдельной строкой, xflow functions list и интерфейс помечают её open.

Открытую функцию может вызвать любой человек в интернете, без вашего приложения:

• каждый входящий параметр проверяется в коде функции;
• функция отдаёт только нужное этому вызову, без чужих строк и служебных полей;
• скрытый адрес, проверка Origin и токен в коде приложения не защищают;
• каждую минуту работы оплачивает организация.

Платформа ограничивает частоту вызовов /_fn с одного адреса. Вход и права пользователей публичного приложения делает само приложение, см. Вход в публичном приложении.

Вебхуки и вызов из другой функции

Внешний сервис (платёжная система, бот, CRM) зовёт функцию по адресу https://fn.xflowpage.ru/<projectId>/<имя> с ключом функции в заголовке X-Function-Key или в параметре ?key=. Ключи выпускает человек на экране функции, вкладка «Доступ», CLI и агент ключей не выпускают. У функции не больше двух ключей: второй нужен, чтобы заменить первый без перерыва.

Функция зовёт другую функцию проекта по тому же адресу через process.env.XFLOW_FN_URL с заголовком X-Server-Key из process.env.XFLOW_SERVER_KEY.

Расписания

xflow schedules set report "0 3 ? * * *" --payload '{"mode":"full"}'

Запускает report каждый день в 03:00 по UTC. В выражении шесть полей, ровно одно из полей «день месяца» и «день недели» равно ?. Функцию нужно выкатить заранее.

Команда	Что делает
xflow schedules list	расписания проекта
xflow schedules set <функция> "<cron>"	завести расписание; с тем же cron меняет тело, с другим добавляет ещё одно
xflow schedules rm <функция> ["<cron>"]	снять одно расписание или все расписания функции

Сколько расписаний у организации (по всем проектам) и как часто они могут идти, задаёт тариф.

Ручной вызов и логи

Команда	Что делает
xflow functions invoke report --data '{"a":1}'	вызывает функцию от вашего имени и печатает тело ответа, на 4xx и 5xx завершается с ошибкой. Флаги --data-file body.json, --method GET. Работает и без зовущих в callers
xflow functions logs report	падения и ответы 5xx со стеком и выводом консоли: последние 10, --limit N для большего, хранятся 200. Успешные вызовы не записываются
xflow functions list	адрес вебхука, пометка open, последний вызов и последняя ошибка каждой функции

Падение при запуске модуля, превышение времени или памяти в логи не попадает: его видно в выводе invoke. Человек видит ошибки на экране функции, вкладка «Ошибки».

Минуты и остановка

Квота минут общая на организацию: её тратят все приложения, вебхуки и расписания. Когда минуты кончились или подписка не оплачена, функции и расписания всей организации останавливаются, вызовы получают 403 functions_stopped. Предел на одно выполнение тоже задаёт тариф, он применяется со следующей выкатки функций. Подробно: Тарифы и лимиты.