Esta página ainda não foi traduzida: mostrando a versão em inglês.

Extensibility

Todo cenário da plataforma é uma cadeia de funções registradas: substitua um elo ou envolva-o. Você muda o comportamento da plataforma substituindo os passos dela, e não fazendo um fork do código-fonte.

Quando usar

• Um passo da plataforma precisa rodar a sua lógica: declare a substituição de um elo nomeado com [Override(…)].
• Você precisa de verificações ou efeitos colaterais em volta de um passo: middleware Before/After em ordem, que pode vetar ou notificar.
• O código precisa rodar por agendamento, por evento ou por webhook: os gatilhos (trigger) entregam a você um contexto já interpretado e tipado.
• Você precisa saber o que vai rodar de fato antes do deploy: simule a cadeia (dry-run) e leia a ordem resolvida.
• Dispensável quando a regra diz respeito às escritas de uma única entidade. Um hook de Data & Subscriptions é a forma mais leve.

Quem faz o quê

Resumo

// 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(): ...

O modelo

Onde a plataforma deixa você se conectar.

O que um hook declara.

Três formas de conectar código.

Para onde vai uma chamada, e o que vale para toda rota.

O que é uma restrição entre hooks, e quando ela é verificada.

[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)

A lógica da própria plataforma pode ser baixada, editada e publicada de novo. São funções, como as suas:

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

O que você personaliza aqui é lógica: as sobrescritas, os middlewares e as versões de que esta página trata.

Erros

• Um nome que não corresponde a nenhum handler registrado responde not found — uma chamada nunca é descartada em silêncio só porque ninguém estava ouvindo.
• Um nome registrado duas vezes, e um conjunto com duas implementações para a mesma condição, são recusados quando o conjunto é declarado: no deploy, não na hora da chamada.
• A recusa de um hook traz o código e o motivo do próprio hook, então “uma regra do jogo disse não” nunca chega parecendo uma falha de transporte.
• Um hook que falha se comporta conforme o tipo declarado — fail-open ou fail-closed —, e qual dos dois ele é foi declarado, não deduzido do que aconteceu.
• Um hook não pode mudar o que já foi definido: nem o dono, nem o alvo, nem o ranking ou a conversa a que a chamada se dirigia. Ele corrige entradas e devolve um veredito.

Limites

Os números chegam com o capítulo de limites da plataforma; o que acontece em cada teto já está definido.

• O prazo de execução de um hook: passado o prazo, vale o comportamento em caso de falha que o tipo dele declara.
• Hooks numa mesma posição e implementações de um mesmo método: registrar mais um é recusado.
• A profundidade de aninhamento de “um hook invoca uma operação que tem hooks”: uma recusa declarada, nunca esgotamento de recursos.
• O tamanho do contexto passado a um hook: truncar é proibido, então o registro é recusado em vez de um handler receber metade de um contexto.

Lições e receitas: um ranking no Tanks usa os hooks deste módulo; um torneio diário passa por este módulo.