Aller au contenu principal

Index des routes

Le fichier​

L'index est le fichier routes/index.json du dépôt : du JSON simple, lisible depuis n'importe quel langage. Une entrée ressemble à ceci :

{
  "method": "PATCH",
  "path": "/channels/{channel_id}",
  "name": "Update channel",
  "source": "discord",
  "auth": ["bot"],
  "major": "channel_id",
  "global": true,
  "model": "unknown",
  "coverage": "exercised",
  "notes": ["Changing a channel's name or topic sits behind a sub-limit of its own, ..."]
}
  • major : le paramètre qui donne à chaque valeur son propre compteur : channel_id, guild_id, webhook_id ou webhook_id+webhook_token. Vide quand tous les appels partagent un seul compteur.
  • global : false pour les routes exemptées de la limite globale du bot.
  • model : token_bucket, fixed_window, ou unknown tant qu'aucune série ne l'a observé.
  • family : les routes que Discord compte ensemble, dans un seul bucket.
  • source : discord pour la spécification OpenAPI de Discord, userdoccers pour les routes documentées seulement par Discord Userdoccers, comme POST /guilds/{guild_id}/members-search.
  • coverage : si le moteur exerce la route, et sinon pourquoi (dans notes).
  • notes : les sous-limites et autres cas particuliers.

Depuis Go​

Le paquet routes associe une requête à sa route :

import "github.com/FCAgreatgoals/bucketmap/routes"

r, ok := routes.Match("PATCH", "/api/v10/channels/123/messages/456")
// r.Path             "/channels/{channel_id}/messages/{message_id}"
// r.MajorValue(path) "123"

Sa documentation est sur pkg.go.dev.

Deux façons de se recharger​

X-RateLimit-Reset-After donne le temps restant avant que le bucket soit de nouveau plein, ce qui veut dire deux choses différentes selon le bucket :

  • Fenêtre fixe (fixed_window) : le bucket se recharge d'un coup, à la fin de la fenêtre. D'une requête à l'autre, maintenant + Reset-After ne bouge pas, et Reset-After diminue à mesure que le bucket se vide.
  • Seau à jetons (token_bucket) : le bucket se recharge une requête à la fois. D'une requête à l'autre, maintenant + Reset-After avance d'une requête, et Reset-After augmente à mesure que le bucket se vide.

Deux requêtes consécutives sur le même bucket suffisent pour les distinguer, bien en dessous de toute limite. Le moteur envoie exprès quelques paires de ce genre.

Garder l'index à jour​

Le workflow index du dépôt reconstruit l'index chaque semaine à partir des sources les plus récentes, et échoue quand elles décrivent une route que l'index ne connaît pas encore. Pour le reconstruire à la main :

git clone --depth 1 https://github.com/discord/discord-api-spec /tmp/spec
git clone --depth 1 https://github.com/discord-userdoccers/discord-userdoccers /tmp/userdoccers
bucketmap index -spec /tmp/spec/specs/openapi.json -userdoccers /tmp/userdoccers/pages

Options de bucketmap index : -spec (le fichier openapi.json de Discord), -userdoccers (le dossier pages de Discord Userdoccers), -annotations (par défaut routes/annotations.json) et -out (par défaut routes/index.json).

Ce que les sources ne disent pas vit dans routes/annotations.json : les modèles de bucket, les familles, les notes, et la raison pour laquelle une route est écartée. Le build échoue sur toute route qui n'est ni exercée ni expliquée.