Services et permissions

Un widget PlayerVox OverCrow n’a aucun accès par lui-même : ni réseau, ni fichier, ni presse-papiers, ni donnée sur le jeu. Tout ce qui sort de son propre état vient d’un service d’OverCrow, que la logique appelle par @overcrow/sdk. Un service ne répond que si le widget a déclaré la permission correspondante dans son manifeste et que l’utilisateur l’a accordée.

// Without the grant the host would refuse the subscription: show the
// unknown duration instead of asking.
if (hasGrant("session.read")) {
  session.subscribe((update) => {
    state.session = anchor(update);
  });
}

C’est tout l’usage d’un service dans le widget Session : il déclare la capability session.read, vérifie que l’utilisateur l’a accordée, puis s’abonne.

Déclarer, puis demander à l’utilisateur

Il existe deux sortes d’autorité, toutes deux déclarées dans permissions du manifeste :

• quatre permissions pour les services généraux : network, storage, clipboardWrite et gameEvents ;
• des capabilities, listées sous permissions.capabilities, pour les données et les actions de PlayerVox OverCrow lui-même et des comptes de l’utilisateur : la fréquence d’images, le lecteur multimédia, les notes de l’utilisateur, la note qu’il donne à un jeu sur PlayerVox, le chat Twitch…

  "permissions": {
    "network": [
      {
        "origin": "https://api.example.com",
        "method": "GET",
        "path": "/v1/forecast/{city}",
        "pathParams": { "city": { "type": "slug", "maxLength": 32 } },
        "queryParams": {
          "units": { "type": "enum", "values": ["metric", "imperial"], "required": true }
        }
      }
    ],
    "storage": true
  },

Une déclaration n’accorde rien à elle seule. Le Centre de contrôle montre à l’utilisateur ce que le widget demande ; celui-ci peut en décocher un élément, ou le retirer plus tard, ce qui redémarre le widget sans lui. Les widgets marqués built-in dans le catalogue signé (widgets PlayerVox uniquement) démarrent avec leurs permissions déclarées accordées. Déclarez le strict nécessaire : les relecteurs lisent chaque permission, et les utilisateurs les voient avant de donner leur accord.

hasGrant(capability) indique si une capability a été accordée. Vérifiez-le avant de vous abonner, et affichez un état utile quand elle manque : même après un refus, le widget doit rester présentable.

if (hasGrant("fps.read")) {
  fps.subscribe((update) => {
    Object.assign(state, reading(update));
  });
} else {
  state.status = "unavailable";
}

Appels et abonnements

Il existe deux sortes de services.

Un appel pose sa question une fois et renvoie une promesse :

async function readStored(key: string): Promise<JsonValue | undefined> {
  try {
    return await storage.get({ key });
  } catch {
    state.error = "storage_unavailable";
    return undefined;
  }
}

Un abonnement prend un écouteur. PlayerVox OverCrow l’appelle aussitôt avec la valeur courante, puis à chaque nouvelle valeur, jusqu’à ce que vous l’annuliez avec cancel() ou qu’il se termine par un échec. L’écouteur vient en dernier ; un service qui a des paramètres les prend en premier.

  const current = media.subscribe({ cover: state.showCover }, (update) => {
    if (update.ok) {
      state.media = update.value;
      state.unavailable = false;
      return;
    }
    // The subscription ended: the host's source failed. Show it and ask
    // again later; hidden, the timer waits until the widget shows.
    if (subscription === current) {
      subscription = null;
      state.media = null;
      state.unavailable = true;
      retry = timers.after(RETRY_MS, subscribe);
    }
  });

Chaque mise à jour vaut { ok: true, value, final } ou { ok: false, error, final: true }. Une mise à jour en échec est toujours la dernière : l’abonnement est terminé.

Les services sont regroupés dans des espaces de noms du SDK : storage, http, clipboard, gameEvents, et un par source de données (fps, telemetry, session, media, stopwatch, notes, playervox, journal, twitch). Chaque service figure, avec ses paramètres et son résultat, dans la référence des services.

PlayerVox OverCrow vérifie chaque appel à son arrivée, dans cet ordre : la permission ou la capability, les paramètres, l’action de l’utilisateur quand le service en demande une, puis le compte quand il en faut un. Les types du SDK vous aident à appeler correctement un service ; ce ne sont pas eux qui font respecter les règles.

Erreurs

Un appel qui échoue rejette sa promesse avec une ServiceError, dont le code dit pourquoi. Un abonnement qui échoue livre la même erreur dans sa dernière mise à jour.

  try {
    const url = `https://api.example.com/v1/forecast/${state.city}?units=${state.units}`;
    const { status, body } = await http.fetch(url, { as: "json" });
    const value = (body as { temperature?: unknown } | null)?.temperature;
    if (status !== 200 || typeof value !== "number") {
      state.status = "unavailable";
      return;
    }
    state.temperature = value;
    state.status = "updated";
    await storage.set({ key, value });
  } catch (error) {
    // permission_denied until the user consents, transport_failed offline…
    state.status = error instanceof ServiceError ? "unavailable" : "failed";
  }

Trois habitudes couvrent la plupart des cas :

• Affichez un état, pas un message d’erreur. Les codes servent à votre logique ; l’utilisateur voit « Prévisions indisponibles », pas transport_failed.
• Réabonnez-vous quand un abonnement s’est terminé. Une source de PlayerVox OverCrow peut échouer pendant que le widget tourne (la session du lecteur multimédia, par exemple) : l’abonnement se termine avec unavailable. Réabonnez-vous quelques secondes plus tard avec timers.after ; OverCrow relance la source pour le nouvel abonnement. Le widget Média attend cinq secondes :

    // The subscription ended: the host's source failed. Show it and ask
    // again later; hidden, the timer waits until the widget shows.
    if (subscription === current) {
      subscription = null;
      state.media = null;
      state.unavailable = true;
      retry = timers.after(RETRY_MS, subscribe);
    }

• Ne réessayez pas en boucle. busy et quota_exceeded signalent qu’une limite est atteinte : attendez, ou faites-en moins.

Les appels qui demandent une action de l’utilisateur

Les services qui changent quelque chose pour l’utilisateur, ou qui déposent quelque chose là où d’autres programmes le lisent, s’appellent seulement pendant une action de l’utilisateur : pendant que la logique traite l’un de ces événements de la vue.

activate, contextmenu, keydown, input, change, submit.

export function toggle(): void {
  command(() => stopwatch.toggle());
}

toggle est le gestionnaire on:activate du bouton du chronomètre : le clic est l’action de l’utilisateur, et stopwatch.toggle() est appelé pendant son traitement. Le même appel depuis un minuteur, depuis la réponse d’un autre service, depuis onHost ou depuis une ligne du menu d’options est refusé avec gesture_required.

• Une action de l’utilisateur autorise un seul appel protégé. Appelez le service directement dans le gestionnaire, pas après un await sur autre chose.
• Les widgets ne reçoivent d’entrées qu’en mode interactif de PlayerVox OverCrow : un appel protégé ne peut donc avoir lieu que dans ce mode.
• notes.delete et journal.delete demandent en plus une confirmation à l’utilisateur, dans une boîte de dialogue dessinée par PlayerVox OverCrow ; une confirmation refusée donne cancelled.

Les tableaux ci-dessous indiquent, pour chaque service, quand l’appeler.

Permissions

« Seulement pendant une action de l’utilisateur » est expliqué dans Les appels qui demandent une action de l’utilisateur.

Règles réseau

network est une liste de règles. Une règle autorise les requêtes vers exactement une origine HTTPS, une méthode et un chemin ; un segment {name} du chemin est un paramètre typé, et seuls les paramètres de requête déclarés sont acceptés.

  "permissions": {
    "network": [
      {
        "origin": "https://api.warframe.market",
        "method": "GET",
        "path": "/v2/versions",
        "maxResponseBytes": 4096
      },
      {
        "origin": "https://api.warframe.market",
        "method": "GET",
        "path": "/v2/items",
        "maxResponseBytes": 3145728
      },
      {
        "origin": "https://api.warframe.market",
        "method": "GET",
        "path": "/v2/orders/item/{slug}",
        "pathParams": {
          "slug": {
            "type": "slug",
            "maxLength": 96
          }
        },
        "maxResponseBytes": 2097152
      }
    ],
    "storage": true,
    "clipboardWrite": true
  },

Chaque paramètre de chemin ou de requête porte une contrainte :

La requête sort par le broker de PlayerVox OverCrow, jamais du processus du widget. Le broker :

• refuse toute URL qu’aucune règle n’autorise (permission_denied), avant toute requête DNS ;
• ne suit aucune redirection, et n’envoie ni cookie, ni identifiant, ni en-tête de proxy ;
• refuse les adresses locales et privées : un widget ne peut donc pas joindre le routeur de l’utilisateur ni un autre programme de la machine ;
• limite chaque échange : 256 Kio pour le corps d’une requête, 30 secondes en tout, et 1 Mio pour le corps d’une réponse, sauf si la règle déclare un maxResponseBytes plus grand, jusqu’à 3 Mio. Les relecteurs et les utilisateurs voient cette limite.

http.fetch(url, { as }) décode le corps comme vous le demandez : "json", "text", "bytes" (un ArrayBuffer) ou "image", qui donne, à la place des octets, un identifiant d’image à lier à un élément image. Un body de type chaîne est envoyé en text/plain, et toute autre valeur en JSON, sauf si contentType en décide autrement. Un statut HTTP d’erreur n’est pas un échec de l’appel : vérifiez status.

    const url = `https://api.example.com/v1/forecast/${state.city}?units=${state.units}`;
    const { status, body } = await http.fetch(url, { as: "json" });
    const value = (body as { temperature?: unknown } | null)?.temperature;
    if (status !== 200 || typeof value !== "number") {
      state.status = "unavailable";
      return;
    }

Un widget a au plus quatre requêtes en cours à la fois, et elles partagent un budget d’octets de réponse : une requête qui n’y tient pas échoue aussitôt avec busy.

Stockage

storage est un stockage clé-valeur que PlayerVox OverCrow tient pour votre seul widget : storage.get({ key }), storage.set({ key, value }), storage.remove({ key }) et storage.keys(). Une valeur est n’importe quelle valeur JSON. Il n’y a aucun accès aux fichiers.

function setRounds(rounds: number): void {
  state.rounds = rounds;
  paint();
  // Storage needs the user's consent: without it the count lasts as long
  // as the widget runs.
  storage.set({ key: "rounds", value: rounds }).catch(() => {});
}

Le stockage contient au plus 512 clés et 256 Kio en tout, 64 Kio par valeur ; au-delà, storage.set échoue avec quota_exceeded et ne change rien. Une écriture reçoit sa réponse une fois qu’elle est sur le disque. Désinstaller le widget efface son stockage, et une session de développement (overcrow-widget dev) ne lit ni n’écrit jamais le stockage d’un widget installé.

Presse-papiers

clipboard.writeText({ text }) place du texte dans le presse-papiers, seulement pendant une action de l’utilisateur. Un widget ne peut pas lire le presse-papiers.

  clipboard.writeText({ text: whisperLine(order, detail.name) }).then(
    () => {
      if (mine === selection) state.copy = { side, id, state: "copied" };
    },
    () => {
      if (mine === selection) state.copy = { side, id, state: "failed" };
    },
  );

Le texte que l’utilisateur sélectionne dans un élément text doté de l’attribut selectable est copié par PlayerVox OverCrow lui-même, sans aucune permission.

Événements de jeu

gameEvents liste les événements de jeu nommés que le widget veut recevoir, chacun de la forme overcrow.game.<name>.v1. gameEvents.subscribe(listener) livre ensuite { event, at } chaque fois que l’un d’eux se produit.

Capabilities

Une capability donne accès à des données ou à des actions que détient PlayerVox OverCrow : les ressources qu’utilise le jeu, le lecteur multimédia, les notes de l’utilisateur, ses comptes PlayerVox et Twitch.

« Seulement pendant une action de l’utilisateur » est expliqué dans Les appels qui demandent une action de l’utilisateur.

Une ligne dont le service est un formulaire correspond à une écriture que l’utilisateur saisit lui-même : voir les formulaires qui écrivent des données de l’utilisateur.

Capabilities sensibles

Une capability sensible révèle des données personnelles ou le jeu en cours. Un widget qui en déclare une :

• ne peut pas déclarer aussi network ni clipboardWrite : le manifeste est refusé ;
• a un stockage qui ne dure que le temps de son processus, et qui est vidé quand le widget redémarre.

Ce qu’un tel widget lit ne peut donc pas quitter la machine par son intermédiaire. Si votre widget a besoin à la fois d’une API HTTP et d’une capability sensible, faites deux widgets.

Comptes

Certaines capabilities ont besoin du compte PlayerVox ou Twitch de l’utilisateur. La connexion appartient à PlayerVox OverCrow : c’est lui qui dessine l’écran de connexion, conserve les jetons et affiche son propre panneau par-dessus le widget tant que le compte est déconnecté. Un widget ne voit jamais un jeton ; il ne reçoit que les données que décrit sa capability, et ses appels échouent avec not_connected tant que le compte n’est pas connecté.

Des données qui changent

• Un abonnement peut livrer null (aucun jeu actif, aucun lecteur multimédia) : affichez un état vide.
• Certains abonnements indiquent quoi relire plutôt que les données elles-mêmes. playervox.reviews.subscribe et journal.subscribe livrent une revision : quand elle change, relisez votre page avec playervox.reviews.page ou journal.page.
• twitch.chat.subscribe livre des changements plutôt que le chat entier, au plus toutes les 100 ms : les nouveaux messages, les messages modifiés (même id), les IDs des messages supprimés, et la liste entière quand reset vaut true.
• Un horodatage fourni avec son propre offsetMinutes doit être formaté avec celui-ci ; voir heure, dates et nombres.

La forme de chaque résultat figure dans les formes de résultat.