Обзор Edge Workers и быстрый старт

Edge Workers — это функции JavaScript, выполняемые на пограничных узлах CDN. Когда запрос поступает на пограничный узел и проходит проверки безопасности, Worker с подходящим маршрутом выполняется до поиска в кэше и до отправки запроса на сервер-источник. Worker может:

• Ответить напрямую: вернуть собственное содержимое или перенаправление без обращения к источнику.
• Изменить запрос к источнику: добавить или перезаписать заголовки запроса (при необходимости также изменить метод и путь), затем передать запрос источнику.
• Пропустить запрос без изменений: запрос будет обработан в соответствии с обычной конфигурацией домена.

Программная модель соответствует Cloudflare Workers: экспортируйте export default { fetch(request, env, ctx) } и возвращайте Response. Каждое выполнение происходит в новой изолированной среде. Глобальное состояние между запросами не разделяется.

#Страницы консоли

#Быстрый старт

#Шаг 1: Создайте Worker

1. Перейдите в CDN → Workers и нажмите Создать Worker в правом верхнем углу.
2. Введите обязательное Название и необязательное Описание.
3. Можно выбрать пример в раскрывающемся списке Начать с шаблона, чтобы загрузить его в редактор. Доступны примеры собственного ответа, перенаправления, токена авторизации, криптографических операций и передачи запроса через fetch. Также можно вставить пример ниже.
4. Убедитесь, что переключатель Включить активен, и нажмите Сохранить.

После сохранения редактор открывает страницу Worker с номером версии вверху. При каждом сохранении нового кода версия увеличивается на единицу.

#Шаг 2: Напишите код

Этот минимальный пример возвращает JSON с пограничного узла для /hello. Все остальные пути обрабатываются источником как обычно.

export default {
  async fetch(request, env, ctx) {
    // request.url may be "/hello?x=1" or a full URL, so extract the path
    const path = request.url.replace(/^https?:\/\/[^\/]+/, "").split("?")[0];

    if (path === "/hello") {
      return Response.json({
        message: "Hello from the edge",
        host: request.headers.get("host"),
        method: request.method,
      });
    }

    // Not handled here: pass through to the origin
    return { action: "continue" };
  },
};

#Шаг 3: Привяжите Worker к домену

1. Перейдите в CDN → CDN-домены, откройте домен и переключитесь на вкладку Worker.
2. Нажмите Добавить привязку. В диалоге:
   • Выберите Worker: выберите только что созданный Worker. В списке отображаются только включённые Workers.
   • Шаблон маршрута: например, /hello или /* для всех путей. Правила описаны ниже.
   • Приоритет: 0–999. Чем больше число, тем выше приоритет.
   • Включить: оставьте включённым.
3. Нажмите Сохранить. Конфигурация автоматически передаётся на пограничные узлы и обычно вступает в силу вскоре после этого.

#Шаг 4: Проверьте работу

curl -i https://www.example.com/hello

Ответ 200 с JSON из примера выше означает, что Worker работает. Остальные пути должны обрабатываться так же, как до добавления привязки.

#Программный интерфейс

#Точка входа

Рекомендуемый формат — export default { fetch(request, env, ctx) { ... } }. fetch может быть обычной или async-функцией. Платформа также принимает export default function (request) {} и глобальную function handler(request) {}.

#Объект запроса

#Возвращаемые значения

Например, этот Worker помечает запросы к источнику группой A/B:

export default {
  fetch(request) {
    const cookie = request.headers.get("cookie") || "";
    const m = /ab_bucket=(A|B)/.exec(cookie);
    const bucket = m ? m[1] : (Math.random() < 0.5 ? "A" : "B");
    return { action: "rewrite", headers: { "x-ab-bucket": bucket } };
  },
};

#Доступные глобальные объекты и функции

• fetch(url, init): выполняет подзапрос к публичному HTTP/HTTPS-адресу и возвращает Promise<Response> со свойствами и методами status, ok, headers, text() и json(). Чтобы отправить результат прямо клиенту, можно использовать return fetch(url).
• Headers, Request, Response, TextEncoder / TextDecoder, btoa / atob.
• crypto.subtle.digest, crypto.subtle.importKey / sign / verify (HMAC), crypto.getRandomValues, crypto.randomUUID и вспомогательные функции crypto.md5(), crypto.sha1(), crypto.sha256() и crypto.hmac(), возвращающие шестнадцатеричные строки.

Ограничения подзапросов:

• Только http/https на порты 80 и 443.
• Частные, loopback- и link-local-адреса всегда отклоняются.
• Поддерживается не более 3 перенаправлений. Тайм-аут каждого подзапроса — 10 секунд, размер тела ответа ограничен 8 MiB.

#Шаблоны маршрутов

Шаблон маршрута сопоставляется только с путём запроса, без имени хоста и строки запроса. Он должен соответствовать всему пути.

• * соответствует любой последовательности символов, включая /, то есть охватывает несколько уровней каталогов. ** работает так же, как *.
• ? соответствует одному символу.
• Пустой шаблон, * или /* соответствует любому пути.

Для одного запроса выполняется не более одного Worker. Если подходят несколько привязок, выполняется только привязка с наивысшим приоритетом. Задавайте пересекающимся привязкам разные приоритеты.

#Ограничения ресурсов

#Ошибки и отладка

Если Worker выбрасывает исключение, содержит синтаксическую ошибку, превышает время выполнения или другой лимит, платформа пропускает запрос дальше. Запрос передаётся источнику, как если бы Worker не был привязан, без показа страницы ошибки. Если результат отличается от ожидаемого, сначала проверьте корректность выполнения кода.

#Включение, отключение и удаление

• При нажатии Отключить в списке Workers выбранный Worker перестаёт выполняться на всех доменах. Также можно отключить отдельную привязку на вкладке Worker домена.
• Удаление Worker прекращает его выполнение на всех доменах, к которым он был привязан.
• При сохранении нового кода все домены, привязанные к этому Worker, обновляются автоматически.

#Тарифы и квоты

Количество маршрутов Worker (привязок) на домен зависит от связанного с доменом тарифа CDN. На момент написания тарифы CDN Starter, Professional и Enterprise допускают по 5 привязок на домен. Актуальные значения приведены на странице тарифов. При достижении лимита консоль показывает уведомление «Достигнут лимит маршрутов Worker». Чтобы добавить больше маршрутов, повысьте тариф или удалите существующие привязки.

#Управление Workers через API

Каждое действие консоли соответствует вызову пользовательского API. Для аутентификации передайте токен входа в заголовке Authorization: Bearer <token>:

# Create a Worker (include an "id" field to update an existing one)
curl -X POST https://api.yeap.cloud/api/user/cdn/workers/save \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"name":"hello","code":"export default { fetch(){ return new Response(\"hi\"); } };","enabled":true}'

# Bind it to a domain
curl -X POST https://api.yeap.cloud/api/user/cdn/domains/www.example.com/workers/save \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"worker_id":123,"route_pattern":"/hello","priority":10,"enabled":true}'

Другие конечные точки:

• Workers: GET /api/user/cdn/workers (список), GET /api/user/cdn/workers/detail?id= (подробности, включая код), POST /api/user/cdn/workers/toggle и DELETE /api/user/cdn/workers/delete (тело JSON {"id":...}).
• Привязки домена: GET /api/user/cdn/domains/<domain>/workers, POST .../workers/toggle и DELETE .../workers/delete.

#Сейчас не поддерживается

• Чтение тела запроса.
• Настройка переменных окружения или KV для Worker в консоли (env — пустой объект).
• Изменение ответа, возвращаемого источником. Шаблон «перезапись заголовков ответа» сейчас не действует. Для добавления заголовков ответа используйте правила домена.
• Фоновая работа, переданная в ctx.waitUntil(): её выполнение после отправки ответа не гарантируется.
• Журналы выполнения и онлайн-отладка.