Производительность, SLA, кэширование и масштабирование

Эта страница — инженерный справочник: насколько быстр AACsearch, почему и что можно поменять. Клиентскую матрицу тарифов смотри в Тарифы и лимиты; про 429 конкретно — в Операции → Rate limits.

SLA по тарифам

p95 чтения — время от прихода POST /search в API-шлюз до отправки 200-ответа, считается по организации за последние 30 дней. ack записи — время от приёма write-запроса до того, как запись становится видна последующим чтениям (alias-swap latency на reindex'ах не учитывается — см. Reindexing).

Эти цели — SLO, не контрактные SLA. Для Enterprise приоритет — SLA-контракт.

Бюджет латентности на чтение

Запрос POST /search проходит пять хопов. Стандартный бюджет на хоп:

Общий p95-таргет на Pro: 150 мс для запроса per_page=10 к коллекции в 100k документов.

Слои кэша

В AACsearch три слоя кэша, каждый со своей целью и TTL:

1. Policy cache (серверный)

• Что: Разрешённый план организации, feature flags, ограничения scoped-токенов.
• Где: packages/search/lib/policy-cache.ts.
• TTL: 60 секунд, in-process LRU на каждый API-инстанс.
• Зачем: Резолв плана/entitlement требует 2–3 запросов в БД — кэш убирает их с хот-пути.
• Инвалидация: Неявная (TTL). Апгрейд плана вступает в силу за ≤ 60 с. Для мгновенной инвалидации (например, лимит поднят по запросу клиента) — рестарт API-контейнера.

2. InstantSearch adapter cache (браузерный)

• Что: Одинаковые запросы в коротком окне возвращают предыдущий ответ.
• Где: packages/instantsearch-adapter/src/cache.ts.
• TTL: Конфигурируется, по умолчанию выключен (адаптер не навязывает кэширование).
• Зачем: Полезно когда пользователь возвращает фасет в предыдущее значение — экономит round-trip.
• Инвалидация: Ручная через client.clearCache().

3. CDN cache (на edge, опционально)

• Что: GET-эндпоинты (схема коллекции, публичный widget-конфиг) можно кэшировать на edge, если перед AACsearch стоит CDN.
• TTL: Задаётся через Cache-Control заголовки AACsearch на GET. POST /search намеренно не кэшируется.
• Зачем: Снижает нагрузку на хот-путь для read-only метаданных.

Throughput и масштабирование

Per-API-key rate limit

Поле rateLimitPerMinute у SearchApiKey (по умолчанию 600) применяется на ключ, в минуту, sliding window в packages/api/modules/search/lib/rate-limit.ts. Тариф поднимает потолок, но не дефолт — лимит ставится на ключ явно.

Если один виджет разделяет ключ между сотнями браузеров — per-key ограничение это не та абстракция. Вместо «поднимите кэп» выпустите несколько ключей (по окружению, региону, крупному клиенту) — кэп существует чтобы локализовать побег клиентов.

Месячная квота организации

Независимо от per-minute rate limit, у каждой организации есть месячная квота Search Units (maxSearchesPerMonth). Один поиск ИЛИ одна запись документа = один Search Unit. См. Тарифы → Search Units.

Два режима применения:

• Soft cap (по умолчанию для Free/Starter): 80% — warning, 100% — quota_exceeded 429 с grace-read окном (24 ч) перед тем как и записи начнут падать.
• Hard cap: Настраивается per-org. Записи падают на 100%; чтения работают (виджеты не ломаются сразу) до истечения grace-окна.

Логика grace-режимов лежит в packages/payments/lib/entitlements.ts. Дашборд показывает оба состояния в Settings → Billing.

Typesense кластер

Коллекции каждой организации живут в шаредном Typesense-кластере на Free/Starter/Pro. Business и Enterprise могут перейти на выделенный кластер (см. Enterprise → Dedicated cluster).

Характеристики шаред-кластера:

Выше потолка шаред-кластера alias-swap reindex (см. Reindexing) начинает заметно конкурировать с другими тенантами. Выделенный кластер — рекомендованный путь после 5 млн документов на коллекцию или устойчивых > 1k QPS.

Postgres

Источник истины AACsearch — Postgres (packages/database схема). Для latency-чувствительных путей API не ходит в Postgres на хот-пути поиска — он идёт в Typesense и в policy cache. В Postgres ходят за:

• Резолвом плана/entitlement (кэшируется, см. policy cache).
• Записями аудит-лога (fire-and-forget — никогда не блокирует ответ).
• Оркестрацией reindex (SearchSyncOutbox).
• Подсчётом квоты (SearchUsageEvent, батчится).

Пулинг коннектов настроен per-app (apps/saas, apps/marketing, packages/api). Дефолтный размер пула — 20 на реплику. Выше ~50 API-реплик стоит поставить PgBouncer в transaction-pooling режиме чтобы не получить exhaustion.

Observability

За чем смотреть при регрессе производительности:

Runbook'и — в Операции → Мониторинг и Операции → Troubleshooting.

Когда апскейлиться

Триггеры и рекомендованное действие:

Smoke-тесты производительности

В репо лежит базовая нагрузочная утилита packages/loadtest. Запускать против staging до публичного запуска:

cd packages/loadtest && bun run smoke

Профиль по умолчанию: 10 параллельных виртуальных пользователей × 60 с × POST /search против коллекции _demo. Выхлоп — p50/p95/p99 + error rate.

Что ещё почитать

• Тарифы и лимиты — каноническая матрица квот
• Rate limits — flow диагностики 429
• Reindexing — поведение alias-swap
• Observability — метрики, трейсы, логи
• Enterprise → Dedicated cluster — когда уезжать с шаред-инфры