Cette page n’est pas encore traduite : la version anglaise est affichée.

Extensibility

Chaque scénario de la plateforme est une chaîne de fonctions enregistrées : remplacez un maillon ou enveloppez-le. Vous modifiez le comportement de la plateforme en remplaçant ses étapes, pas en forkant son code source.

Quand l’utiliser

• Une étape de la plateforme doit exécuter votre logique : déclarez le remplaçant d’un maillon nommé avec [Override(…)].
• Il vous faut des vérifications ou des effets de bord autour d’une étape : du middleware Before/After ordonné, qui peut opposer un veto ou notifier.
• Du code doit s’exécuter selon un planning, sur un événement ou sur un webhook : les déclencheurs (trigger) vous fournissent un contexte typé, déjà analysé.
• Vous devez savoir ce qui s’exécutera réellement avant de déployer : faites une exécution à blanc d’une chaîne et lisez l’ordre résolu.
• Inutile quand la règle porte sur les écritures d’une seule entité. Un hook de Data & Subscriptions est la forme la plus légère.

Qui fait quoi

En bref

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

Le modèle

Ce à quoi la plateforme vous permet de vous brancher.

Ce que déclare un hook.

Trois façons de brancher du code.

Où va un appel, et ce qui vaut pour toute route.

Ce qu’est une contrainte entre hooks, et quand elle est vérifiée.

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

La logique propre de la plateforme peut être récupérée, modifiée et redéployée. Ce sont des fonctions, comme les vôtres :

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

Ce que vous personnalisez ici, c’est de la logique : les surcharges, le middleware et les versions dont traite cette page.

Erreurs

• Un nom qui ne correspond à aucun handler enregistré répond not found — un appel n’est jamais abandonné en douce parce que personne n’écoutait.
• Un nom enregistré deux fois, ou un ensemble où deux implémentations revendiquent la même condition, est refusé dès la déclaration de l’ensemble : au déploiement, pas au moment de l’appel.
• Un refus de hook porte le code et le motif propres au hook : « une règle du jeu a dit non » n’arrive donc jamais sous l’apparence d’une panne de transport.
• Un hook qui échoue se comporte selon le type déclaré — fail-open ou fail-closed — et ce type a été déclaré, pas déduit de ce qui s’est passé.
• Un hook ne peut pas modifier ce qui est déjà établi : ni le propriétaire, ni la cible, ni le classement ou la conversation auxquels l’appel était adressé. Il corrige des entrées et rend un verdict.

Limites

Les valeurs chiffrées arriveront avec le chapitre sur les limites de la plateforme ; ce qui se passe à chaque plafond est déjà fixé.

• Délai d’exécution d’un hook : au-delà, le comportement en cas d’échec que déclare son type.
• Hooks à une même position et implémentations d’une même méthode : l’enregistrement d’un élément supplémentaire est refusé.
• Profondeur d’imbrication de « un hook invoque une opération qui a des hooks » : un refus déclaré, jamais un épuisement des ressources.
• Taille du contexte passé à un hook : la troncature est interdite ; l’enregistrement est donc refusé plutôt que de laisser un handler recevoir un contexte à moitié.

Leçons et recettes : un classement dans Tanks utilise les hooks de ce module ; un tournoi quotidien passe par ce module.