resolveRole

Ce que ça fait

Résout un rôle externe (propre à l’application appelante — ex. "directeur", "professeur") vers un ParticipantRole Legba, via une politique à deux niveaux : une règle globale toujours prioritaire, et des règles complémentaires par salle.

Signature

function resolveRole(
  policy: RolePolicy,
  roomName: string,
  externalRole: string,
  fallback: ParticipantRole,
): ParticipantRole

Paramètres

Nom	Type	Requis	Défaut	Description
policy.global	Record<string, ParticipantRole>	oui	—	Toujours prioritaire ; ne peut jamais être écrasée par une règle de salle
policy.perRoom	Record<string, Record<string, ParticipantRole>>	non	—	Règles complémentaires par salle, consultées seulement pour un rôle externe absent de global
roomName	string	oui	—	Salle pour laquelle résoudre le rôle — jamais vérifiée côté serveur
externalRole	string	oui	—	Rôle tel que fourni par le système d’identité de l’appelant
fallback	ParticipantRole	oui	—	Rôle rendu si aucune règle (globale ou de salle) ne correspond

Retour

Un ParticipantRole ("host" \| "participant" \| "viewer"), à transmettre ensuite à createAccessToken.

Erreurs

Code	Quand	Comment corriger
LEGBA_INVALID_ROLE_POLICY	fallback hors énumération	Fournir un rôle connu
LEGBA_INVALID_ROLE_POLICY	Une valeur dans policy.global ou dans la règle de la salle consultée est hors énumération	Vérifier la source de la politique (ex. config JSON externe)

Exemple minimal

import { resolveRole, createAccessToken, type RolePolicy } from "@legba-core/realtime";

const policy: RolePolicy = { global: { directeur: "host" } };
const role = resolveRole(policy, "salle-demo", utilisateur.roleExterne, "participant");

const { token } = await createAccessToken({ apiKey, apiSecret, roomName: "salle-demo", identity, role });

Exemple complet

import { resolveRole, createAccessToken, LegbaRolePolicyError, type RolePolicy } from "@legba-core/realtime";

// Règle globale (organisation) + règle complémentaire pour une salle de cours.
const policy: RolePolicy = {
  global: { directeur: "host" },
  perRoom: { "salle-cours-101": { professeur: "host" } },
};

try {
  const role = resolveRole(policy, roomName, utilisateur.roleExterne, "viewer");
  const { token } = await createAccessToken({ apiKey, apiSecret, roomName, identity: utilisateur.id, role });
} catch (error) {
  if (error instanceof LegbaRolePolicyError) {
    // la politique elle-même est mal configurée — erreur de déploiement, pas d'utilisateur
  }
}

Pièges

• Aucune notion métier codée en dur : Legba ne connaît aucun nom de rôle externe particulier — policy est entièrement fournie par l’application appelante.
• La règle globale ne peut jamais être révoquée par une salle. Un rôle externe présent dans policy.global résout toujours vers cette valeur, même si policy.perRoom tente de le mapper différemment pour la même salle.
• Reste séparé de createAccessToken : c’est l’application qui enchaîne les deux appels elle-même — comme createBreakoutRooms/ changeParticipantRole ne fusionnent pas leurs couches.
• La correspondance de externalRole est sensible à la casse, sans normalisation implicite.
• Ne vérifie jamais l’existence de roomName côté serveur — résolution en mémoire uniquement.

Voir aussi

• createAccessToken
• LegbaRolePolicyError
• ROLE_POLICY_ERROR_CODES