Цю сторінку ще не перекладено — показано англійську версію.

Extensibility

Кожен сценарій платформи — це ланцюжок зареєстрованих функцій: замініть ланку або обгорніть її. Поведінку платформи ви змінюєте, підміняючи її кроки, а не форкаючи її код.

Коли це потрібно

• Крок платформи має виконувати вашу логіку: оголосіть заміну іменованої ланки через [Override(…)].
• Навколо кроку потрібні перевірки чи побічні ефекти: упорядковані проміжні обробники (middleware) Before/After, які можуть заборонити крок або повідомити про нього.
• Код має запускатися за розкладом, за подією чи через вебхук: тригери передають вам уже розібраний типізований контекст.
• Треба знати, що насправді виконається, ще до деплою: проженіть ланцюжок у тестовому режимі (dry run) і прочитайте остаточний порядок.
• Не потрібно, якщо правило стосується записів однієї сутності (entity). Для цього є легший варіант — хук (hook) у 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 використовує хуки цього модуля, а щоденний турнір цілком побудовано на ньому.