OxL Справочник OxL
РусскийEnglish

10.2 Атрибуты rpc

АтрибутГде действуетСемантика
@timeout(d)клиент и сервердедлайн вызова по умолчанию; сервер обрезает больший дедлайн клиента до d
@retry(n, backoff: b)клиентповтор при Timeout | Unavailable; разрешён только вместе с @idempotent или @readonly, иначе ошибка компиляции
@idempotent(key: f)серверответ сохраняется во встроенном хранилище по ключу f(запрос) на ttl (по умолчанию IDEMPOTENCY_TTL кластера); повтор возвращает сохранённый ответ
@readonlyконтрактметод не меняет состояние; разрешает @retry и @cache
@cache(ttl: d, key: f?)серверкэш ответов; только с @readonly
@ratelimit(rps: n, burst: m, by: f)серверограничение частоты; превышение — Unavailable с подсказкой retry-after
@publicдоступвызов без политики (§13.4)
@allow(…)доступкраткая встроенная политика (§13.4)
@resumableстримвозобновление стрима по offset (§10.3)
@window(n)стримокно кредитов, по умолчанию 64 сообщения
@trace(sample: p), @auditнаблюдаемость§15.5, §13.4

Значения по умолчанию для всех rpc задаются в cluster { defaults { … } } (§12.1).

Пользовательские атрибуты и Middleware (D-8052; DIV-010; D-7530, D-7531). attr Имя { поля } объявляет обычный тип данных; @Имя(args) на rpc сервиса строит значение Имя{args} (именованные или позиционные аргументы). Тип, реализующий

oxl
@explicit interface Middleware { fn around(ctx: &var Ctx, next: Next) -> Response  net, io, time, db }

оборачивает обработчик на стороне сервера:

  • интерфейс допускает эффекты net, io, time, db; конкретная реализация around МОЖЕТ объявить меньше (например, только net);
  • Next = fn(&var Ctx) -> Response net; Response { error: NetError?, passed: bool } — маркер прохода вызова, а не значение результата: Response.refuse(e) завершает вызов ошибкой NetError без выполнения обработчика; Response, возвращённый без вызова next и без ошибки, — ProtocolError с кодом 13. Middleware не может подменить типизированный результат — он остаётся за обработчиком, ошибка обработчика проходит без изменений;
  • атрибуты вкладываются в порядке записи (первый — внешний); остальные атрибуты rpc (@timeout, @cache, …) оборачивают весь обработчик. Пользовательский атрибут можно повторять, встроенные — нельзя.

Определяется реализацией. Область действия Middleware (D-8052; DIV-010; D-7530). Необязательные возможности: middleware на стороне клиента и на стримовых rpc (в этой реализации атрибут на стримовом rpc принимается, но ничего не оборачивает); изменения ctx, сделанные middleware, не доходят до собственного ctx обработчика.

attribute-not-applicable, cache-not-readonly, invalid-window, retry-not-idempotent, rpc-attr

См. также

Исходник: docs/spec/oxl-standard.md