Эта страница ещё не переведена — показана английская версия.

Extensibility

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

Когда это нужно

• Шаг платформы должен выполнять вашу логику. Объявите замену именованного звена через [Override(…)].
• Вокруг шага нужны проверки или побочные эффекты. Для этого есть упорядоченные промежуточные обработчики (middleware) Before/After: они могут запретить шаг или уведомить о нём.
• Код должен запускаться по расписанию, по событию или по вебхуку. Триггеры передают вам уже разобранный типизированный контекст.
• До деплоя нужно знать, что на самом деле выполнится. Сделайте пробный прогон цепочки и посмотрите итоговый порядок.
• Не нужно, если правило касается записей одной сущности. Для этого есть более лёгкий вариант — хук Data & Subscriptions.

Кто что делает

Коротко

// gate one named step of the auth scenario — a before hook may refuse, fail-closed
[Before(Auth.SignIn)]
public static Task<Verdict> GateRegion(SignInAttempt a) =>
    a.Region == "sanctioned"
        ? Hook.Reject(Problem.Forbidden, "region not served")
        : Hook.Continue(a);

// wrap a step with ordered middleware
PlayServ.Extend.Scenario("commerce.purchase")
    .Before("grant", LogPurchaseIntent)
    .After("grant", NotifySquad, order: 10);

// customer code on a trigger
[OnSchedule("0 4 * * *")]
public static async Task NightlyCleanup() { ... }

// gate one named step of the auth scenario — a before hook may refuse, fail-closed
export const gateRegion = before(Auth.signIn, (a: SignInAttempt) =>
  a.region === 'sanctioned'
    ? Hook.reject(Problem.forbidden, 'region not served')
    : Hook.continue(a));

// wrap a step with ordered middleware
playserv.extend.scenario('commerce.purchase')
  .before('grant', logPurchaseIntent)
  .after('grant', notifySquad, { order: 10 });

// customer code on a trigger
export const nightlyCleanup = onSchedule('0 4 * * *', async () => { /* ... */ });

# gate one named step of the auth scenario — a before hook may refuse, fail-closed
@before(auth.sign_in)
async def gate_region(a):
    if a.region == "sanctioned":
        return hook.reject(problem.FORBIDDEN, "region not served")
    return hook.cont(a)

# wrap a step with ordered middleware
playserv.extend.scenario("commerce.purchase") \
    .before("grant", log_purchase_intent) \
    .after("grant", notify_squad, order=10)

# customer code on a trigger
@on_schedule("0 4 * * *")
async def nightly_cleanup(): ...

Модель

К чему можно подключиться.

Что объявляет хук.

Три способа подключить код.

Куда уходит вызов и что верно для любого маршрута.

Что такое ограничение между хуками и когда оно проверяется.

[Rpc("resolve_price", Default = true)]
public static Price ResolvePrice(Sku sku) => Pricing.Base(sku);

[Rpc("resolve_price", When = "env == 'staging'")]
public static Price ResolvePriceStaging(Sku sku) => Pricing.WithDiscount(sku, 0.5f);

// a hook can carry a version too, gated by its own condition
[After("grant", When = "audience == 'beta'")]
public static void NotifySquadBeta(GrantResult r) => Messaging.PingBeta(r.Squad);

export const resolvePrice = rpc('resolve_price', { default: true },
  (sku: Sku) => Pricing.base(sku));

export const resolvePriceStaging = rpc('resolve_price', { when: "env == 'staging'" },
  (sku: Sku) => Pricing.withDiscount(sku, 0.5));

// a hook can carry a version too, gated by its own condition
export const notifySquadBeta = after('grant', { when: "audience == 'beta'" },
  (r: GrantResult) => Messaging.pingBeta(r.squad));

@rpc("resolve_price", default=True)
def resolve_price(sku: Sku) -> Price:
    return pricing.base(sku)

@rpc("resolve_price", when="env == 'staging'")
def resolve_price_staging(sku: Sku) -> Price:
    return pricing.with_discount(sku, 0.5)

# a hook can carry a version too, gated by its own condition
@after("grant", when="audience == 'beta'")
def notify_squad_beta(r: GrantResult):
    messaging.ping_beta(r.squad)

Собственную логику платформы можно выгрузить, изменить и задеплоить заново. Это такие же функции, как ваши:

playserv functions pull matchmaking.match     # the platform's implementation, as source
# edit: widen the skill window for the weekend event
playserv push                                 # your version registers; the default stays as fallback

Настраиваете вы здесь именно логику: переопределения, промежуточные обработчики и версии, о которых эта страница.

Ошибки

• Если имени не соответствует ни один зарегистрированный обработчик, ответ — not found. Вызов никогда не пропадает молча из-за того, что его никто не слушал.
• Имя, зарегистрированное дважды, и набор, где две реализации претендуют на одно и то же условие, отклоняются в момент объявления набора — при деплое, а не при вызове.
• Отказ хука несёт собственный код и причину хука, поэтому «правило игры сказало нет» никогда не будет выглядеть как сбой транспорта.
• Хук, который упал, ведёт себя по объявленному виду — fail-open или fail-closed. Какой именно, объявлено заранее, а не выводится из того, что произошло.
• Хук не может менять то, что уже заявлено: ни владельца, ни цель, ни таблицу или беседу, которым адресован вызов. Он исправляет входные данные и возвращает вердикт.

Ограничения

Конкретные числа появятся вместе с главой об ограничениях платформы, а поведение на каждой границе уже определено.

• Срок выполнения хука: если он превышен, хук ведёт себя так, как объявлено для сбоя в его виде.
• Число хуков на одном шаге и число реализаций одного метода: регистрация сверх предела отклоняется.
• Глубина вложенности вида «хук вызывает операцию, у которой есть хуки»: объявленный отказ, а не исчерпание ресурсов.
• Размер контекста, передаваемого хуку: обрезать его запрещено, поэтому отклоняется регистрация, а не обработчик получает половину контекста.

Уроки и рецепты: таблица лидеров в Tanks использует хуки этого модуля, а ежедневный турнир целиком построен на нём.