Senior GraphQL API: scheduling-контракт, изоляция арендаторов, наблюдаемость

Production-инцидент: скорость вызовов базы в 6 раз выше нормы, HTTP-RPS нормальный. Persisted queries enforced — необычных хешей нет. Недавний рефакторинг переместил один DataLoader из context-фабрики в module scope. Одна строка, ноль тестов, поймавших это, — и теперь кеш делится между арендаторами.

Точный scheduling-контракт DataLoader

Библиотека использует enqueuePostPromiseJob — обёртку над process.nextTick в Node.js и Promise.resolve().then в браузерах — для планирования dispatch’а батча. Dispatch запускается:

• После текущего синхронного фрейма
• После всех микротасок, поставленных в очередь в этом фрейме

Это значит: .load()-вызовы внутри тел резолверов, внутри .then()-цепочек после синхронной работы резолвера и внутри nextTick-отложенной логики — все попадают в один батч. Окно ограничено event loop JS-рантайма, не таймером. Никаких setTimeout, setImmediate, фиксированных миллисекунд.

batchScheduleFn переопределяет это если нужна другая семантика (например, дебаунс на уровне кластера через cross-process брокер). Production-серверы оставляют дефолт.

Изоляция арендаторов в cache key

Паттерн context-фабрики из урока 02 необходим, но недостаточен для multi-tenant систем. Новый DataLoader-инстанс на каждый запрос предотвращает кросс-request кеш-хиты, но если batch-функция запрашивает данные без фильтрации по tenant, два одновременных запроса от разных арендаторов в одном Node-процессе могут получить данные друг друга через сам SQL-запрос (не через кеш).

Безопасный паттерн:

context: async ({ req }) => ({
  loaders: makeLoaders(req.auth.tenantId),
})

function makeLoaders(tenantId) {
  return {
    user: new DataLoader(async (ids) => {
      const rows = await db.query(
        'SELECT * FROM users WHERE id = ANY($1) AND tenant_id = $2',
        [ids, tenantId]   // tenant-скоуп на уровне SQL
      );
      const map = new Map(rows.map(r => [r.id, r]));
      return ids.map(id => map.get(id) ?? null);
    }),
  };
}

Аудит SonarSource 2024 года OSS GraphQL-серверов нашёл tenant-leak баги в 6 из 12 кодовых баз — все из-за module-scope DataLoader или отсутствия tenant-фильтра в batch-запросе.

APQ vs trusted documents

Два разных механизма под одним именем «persisted queries»:

• Automatic Persisted Queries (APQ): Клиент считает SHA-256 от текста запроса и шлёт только хеш. Если сервер не видел хеш раньше, возвращает PersistedQueryNotFound, клиент пересылает полный документ. APQ экономит байты на тёплом кеше (5 KB запрос → 64-символьный хеш). Он не ограничивает форму запроса — любой клиент может зарегистрировать и выполнить любой документ.

• Trusted documents: Выполняются только pre-registered хеши. Неизвестные отклоняются. Регистрация — на этапе сборки клиента. Это граница безопасности, не оптимизация производительности.

Production-команды, которым нужно и то и другое, деплоят trusted documents и используют APQ-style хеширование внутри зарегистрированного набора.

Почему field-count complexity scoring — баг недосчёта

Наивное правило «cost = 1 на поле, суммируется» сообщает cost 50 для 10-глубокого запроса с 5 полями на уровень. Реальная стоимость — в расширении строк на каждом list-уровне. Запрос, запрашивающий first: 100 на каждом из 5 уровней, читает 100^5 = 10^10 строк концептуально — но field-count всё равно сообщает 50.

Правильная формула умножает на размер list-аргумента:

cost(field) = field_weight + sum(child.first_arg × cost(child))

С first: 100 на каждом уровне калькулятор возвращает 100^5 — астрономически за бюджетом, запрос отклоняется при парсинге AST до запуска любого резолвера. Публичная формула GitHub — документированная версия этого мультипликативного правила.

Анатомия alias-бомбы

Один документ с 1000 корневых алиасов:

q1: user(id: 1) { email }
q2: user(id: 2) { email }
...
q1000: user(id: 1000) { email }

Один валидный документ, парсится один раз. Выполнение запускает 1000 вызовов резолверов. DataLoader сворачивает поездки в базу до одного батч-запроса — но число вызовов резолверов — рычаг атакующего: 1000 резолверов вызывают логику проверки прав, логирование, поиск в контексте. Документ в 5 МБ может дать шестизначное число вызовов резолверов на одном HTTP-запросе, обходя любой наивный per-request rate limit.

Аудит Escape.tech 2024: 64% production GraphQL-эндпоинтов не имеют alias-кепов. Отчёт Imperva 2023 приписал 18% GraphQL production-инцидентов alias-batch DoS.

Минимальный дашборд наблюдаемости

Per-resolver трассировка через OpenTelemetry GraphQL instrumentation эмитит span на каждый type.field-вызов. Агрегация span’ов по операции даёт счётчики вызовов резолверов. Без этой инструментации регрессия N+1 невидима, пока CPU базы не запейджит дежурного.