@dotrino/lobby 0.1.5

package/src/lobby.js

@@ -0,0 +1,244 @@
+// Lobby: capa de descubrimiento + matchmaking sobre los canales del proxy.
+// Crea/lista/une salas de un juego, hace partida rápida (quickMatch) filtrando
+// por reputación, e invita contactos por pubkey (cola offline).
+
+import { Emitter, normalizeSeats } from './util.js'
+import { K, envelope, discoveryChannel } from './protocol.js'
+import { Transport } from './transport.js'
+import { Room, STATUS } from './room.js'
+import { createRepGate, rankRooms } from './reputation.js'
+
+export class Lobby extends Emitter {
+  constructor ({ transport, gameId, config }) {
+    super()
+    this.transport = transport
+    this.gameId = gameId
+    this.config = config
+    this.identity = config.identity || null
+    this.reputation = config.reputation || null
+    this.myPubkey = (this.identity && this.identity.me && this.identity.me.publickey) || null
+    this._gate = createRepGate(this.reputation, config.matchmaking || {})
+    this._rooms = new Set()
+    this._infoCollector = null
+    this._wire()
+  }
+
+  _wire () {
+    this.transport.subscribe(this.gameId, (from, env) => {
+      if (env.k === K.INFO) { if (this._infoCollector) this._infoCollector(from, env.d && env.d.summary) }
+      else if (env.k === K.INVITE) this.emit('invite', { from, ...(env.d || {}) })
+    })
+    const dc = discoveryChannel(this.gameId)
+    // Descubrimiento en vivo: requiere observar el canal (watch) para recibir
+    // estos eventos sin publicarnos como sala. Si el proxy no soporta watch,
+    // _watchDiscovery degrada a no-op y la app sigue con su polling de respaldo.
+    this.transport.on('channel_joined', (channel, token) => { if (channel === dc && token !== this.transport.token) this.emit('rooms-changed', { type: 'joined', token }) })
+    this.transport.on('channel_left', (channel, token) => { if (channel === dc) this.emit('rooms-changed', { type: 'left', token }) })
+    this.transport.on('peer_disconnected', (token, channel) => { if (!channel || channel === dc) this.emit('rooms-changed', { type: 'left', token }) })
+    this.transport.on('reconnect', () => this._watchDiscovery())
+    this._watchDiscovery()
+  }
+
+  // Observar el canal de descubrimiento para recibir altas/bajas de salas en vivo
+  // (proxy ≥ 0.6.2). Fire-and-forget: no bloquea ni rompe si no está soportado.
+  _watchDiscovery () {
+    try { this.transport.watch(discoveryChannel(this.gameId)) } catch (_) {}
+  }
+
+  // ── Crear / unir ────────────────────────────────────────────────
+
+  /** Crear una sala (sos host). */
+  async createRoom (opts = {}) {
+    await this.transport.connect()
+    const room = new Room({ transport: this.transport, gameId: this.gameId, roomId: this.transport.token, role: 'host', config: this._roomConfig(opts) })
+    this._track(room)
+    await room._startAsHost()
+    return room
+  }
+
+  /** Unirse a una sala existente por su roomId (== token del host). */
+  async joinRoom (roomId, opts = {}) {
+    await this.transport.connect()
+    const room = new Room({ transport: this.transport, gameId: this.gameId, roomId, role: 'guest', config: this._roomConfig(opts) })
+    this._track(room)
+    await room._joinAsGuest()
+    return room
+  }
+
+  // ── Descubrimiento ──────────────────────────────────────────────
+
+  /**
+   * Lista salas abiertas: enumera el canal de descubrimiento y pide un resumen
+   * (INFO) a cada host; enriquece y ordena por reputación/contactos.
+   * @param {object} [opts]
+   * @param {number} [opts.timeout=1500] ventana para recolectar respuestas INFO
+   * @param {boolean} [opts.enrich=true] añadir reputación + flag de contacto y ordenar
+   */
+  async listRooms (opts = {}) {
+    await this.transport.connect()
+    const timeout = opts.timeout || 1500
+    let tokens = []
+    try { tokens = await this.transport.list(discoveryChannel(this.gameId)) } catch (_) {}
+    const others = tokens.filter(t => t && t !== this.transport.token)
+    const summaries = await this._gatherInfo(others, timeout)
+    if (opts.enrich === false) return summaries
+    const contacts = await this._contactSet()
+    return rankRooms(summaries, { reputation: this.reputation, contacts, preferContacts: (this.config.matchmaking || {}).preferContacts !== false })
+  }
+
+  _gatherInfo (tokens, timeout) {
+    return new Promise((resolve) => {
+      const got = new Map()
+      let timer = null
+      const done = () => { if (timer) clearTimeout(timer); this._infoCollector = null; resolve([...got.values()]) }
+      if (!tokens.length) return done()
+      this._infoCollector = (from, summary) => { if (summary) got.set(from, summary); if (got.size >= tokens.length) done() }
+      for (const t of tokens) this._sendTo(t, K.INFO_REQUEST, {})
+      timer = setTimeout(done, timeout)
+      if (timer.unref) timer.unref()
+    })
+  }
+
+  // ── Matchmaking ─────────────────────────────────────────────────
+
+  /**
+   * Partida rápida: une la mejor sala compatible (con asiento libre, esperando y
+   * que pase el gate de reputación); si no hay, crea una y espera oponente.
+   * Devuelve el Room (mirá room.isHost). Para auto-sentarte dejá autoSeat=true.
+   */
+  async quickMatch (opts = {}) {
+    const rooms = await this.listRooms({ timeout: opts.timeout || 1500 })
+    for (const r of rooms) {
+      if (r.status !== STATUS.WAITING || !(r.openSeats > 0)) continue
+      const verdict = await this._gate(r.hostPubkey)
+      if (!verdict.ok) continue
+      const room = await this.joinRoom(r.roomId, opts)
+      if (opts.autoSeat !== false) this._autoSeat(room, opts.seat)
+      return room
+    }
+    const room = await this.createRoom(opts)
+    if (opts.autoSeat !== false) room.takeSeat(opts.seat)
+    return room
+  }
+
+  // Toma asiento; el host encola la intención hasta verificar (pendingSeat), así
+  // que con un envío basta. Reintenta acotado sólo si seguimos sin asiento.
+  _autoSeat (room, seat) {
+    if (room.mySeat) return
+    room.takeSeat(seat)
+    let tries = 0
+    const off = room.on('update', () => {
+      if (room.mySeat || tries >= 3) { off(); return }
+      tries++
+      room.takeSeat(seat)
+    })
+  }
+
+  // ── Invitaciones / contactos ────────────────────────────────────
+
+  /** Invitar a un contacto (por pubkey) a una sala. Usa la cola offline 24 h. */
+  inviteContact (pubkey, { roomId, name } = {}) {
+    const rid = roomId || this.transport.token
+    const env = envelope(this.gameId, rid, K.INVITE, { roomId: rid, name: name || null, from: this.myPubkey, fromName: (this.identity && this.identity.me && this.identity.me.nickname) || null })
+    this.transport.sendByPubkey(pubkey, env)
+  }
+
+  /** Contactos del vault (compartidos entre apps del ecosistema). */
+  async listContacts () {
+    if (!this.identity || !this.identity.listContacts) return []
+    try { return await this.identity.listContacts() } catch (_) { return [] }
+  }
+
+  async _contactSet () {
+    const list = await this.listContacts()
+    return new Set(list.map(c => c.publickey).filter(Boolean))
+  }
+
+  /** Reputación ponderada de una pubkey (para badges en la UI del lobby). */
+  async reputationOf (pubkey) {
+    if (!this.reputation) return null
+    try { return await this.reputation.reputationOf(pubkey) } catch (_) { return null }
+  }
+
+  // ── Limpieza ────────────────────────────────────────────────────
+
+  /** Salas activas creadas/unidas por este lobby. */
+  get rooms () { return [...this._rooms] }
+
+  async destroy () {
+    for (const room of this._rooms) { try { await room.leave() } catch (_) {} }
+    this._rooms.clear()
+    this.removeAllListeners()
+  }
+
+  // ── Internos ────────────────────────────────────────────────────
+
+  _track (room) { this._rooms.add(room); room.on('left', () => this._rooms.delete(room)) }
+
+  _roomConfig (opts) {
+    return {
+      seats: this.config.seats,
+      engineSpec: this.config.engineSpec || null,
+      allowSpectators: this.config.allowSpectators !== false,
+      maxSpectators: this.config.maxSpectators ?? 50,
+      start: this.config.start || 'ready',
+      onSeatVacated: this.config.onSeatVacated || 'pause',
+      onHostLost: this.config.onHostLost || 'end',
+      disconnectGraceMs: this.config.disconnectGraceMs ?? 45000,
+      requireVerify: this.config.requireVerify !== false,
+      gate: this._gate,
+      identity: this.identity,
+      reputation: this.reputation,
+      name: opts.name || null,
+      playerName: opts.playerName || this.config.playerName || null,
+      seed: opts.seed ?? this.config.seed,
+      // Indicador derivado a co-firmar al terminar (default ELO, scope=gameId).
+      resultIndicator: this.config.resultIndicator || 'elo',
+      resultScope: this.config.resultScope || this.gameId
+    }
+  }
+
+  _sendTo (token, kind, data) { this.transport.send(token, envelope(this.gameId, token, kind, data)) }
+}
+
+/**
+ * Punto de entrada principal: crea (si hace falta) el transporte, lo conecta e
+ * identifica con el vault, y devuelve un Lobby listo para el juego dado.
+ *
+ * @param {object} opts
+ * @param {string} opts.gameId  identificador del juego (namespace de canales)
+ * @param {Array|object} opts.seats  ['white','black'] o { min, max }
+ * @param {object} [opts.engine]  spec del motor de turnos { initialState, reducer, view?, isOver? }
+ * @param {object} [opts.identity]  instancia de Identity ya conectada (si no, se conecta sola)
+ * @param {object} [opts.reputation]  instancia de createVaultReputation
+ * @param {object} [opts.proxy]  cliente proxy ya creado (reuso de conexión)
+ * @param {string} [opts.url]  URL del proxy
+ * @param {string} [opts.start='ready']  'ready' | 'full' | 'manual'
+ * @param {string} [opts.onSeatVacated='pause']  'pause' | 'forfeit' | 'fill'
+ * @param {object} [opts.matchmaking]  { requireVouched, minReputation, preferContacts }
+ * @returns {Promise<Lobby>}
+ */
+export async function createLobby (opts = {}) {
+  if (!opts.gameId) throw new Error('[lobby] createLobby: falta gameId')
+  const transport = opts.transport || new Transport({ proxy: opts.proxy, identity: opts.identity, url: opts.url })
+  await transport.connect()
+  const config = {
+    seats: normalizeSeats(opts.seats || { min: 2, max: 2 }),
+    engineSpec: opts.engine || null,
+    allowSpectators: opts.allowSpectators,
+    maxSpectators: opts.maxSpectators,
+    start: opts.start,
+    onSeatVacated: opts.onSeatVacated,
+    onHostLost: opts.onHostLost,
+    disconnectGraceMs: opts.disconnectGraceMs,
+    requireVerify: opts.requireVerify,
+    identity: transport.identity || opts.identity || null,
+    reputation: opts.reputation || null,
+    matchmaking: opts.matchmaking || {},
+    playerName: opts.playerName || null,
+    seed: opts.seed,
+    resultIndicator: opts.resultIndicator || 'elo',
+    resultScope: opts.resultScope || null
+  }
+  return new Lobby({ transport, gameId: opts.gameId, config })
+}

package/src/protocol.js

@@ -0,0 +1,82 @@
+// Protocolo de mensajes de lobby/room sobre el transporte Dotrino.
+//
+// Una sola conexión al proxy puede ser compartida por varias apps del
+// ecosistema (messenger, varios juegos a la vez). Por eso TODO mensaje de esta
+// librería viaja en un sobre namespaced que se puede demultiplexar por
+// (gameId, roomId) y descartar lo ajeno sin ambigüedad.
+//
+// El proxy auto-parsea los strings JSON: send(obj) llega al receptor como
+// objeto ya parseado en el callback 'message'. Aprovechamos eso enviando el
+// sobre como objeto plano. Evitamos el campo `t` a nivel raíz porque el
+// cliente lo reserva para señalización WebRTC (parsed.t === '__cc_rtc__').
+
+/** Marca de versión del sobre. */
+export const ENVELOPE_TAG = 1
+
+/** Tipos de mensaje (campo `k` = kind). */
+export const K = {
+  // ── guest → host ─────────────────────────────────────────────
+  HELLO: 'hello',           // { pubkey?, name? }  entrar + pedir estado
+  REQUEST_STATE: 'reqstate', // {}  resync explícito
+  SEAT_TAKE: 'seat.take',   // { seat }
+  SEAT_LEAVE: 'seat.leave', // {}
+  READY: 'ready',           // { ready:boolean }
+  SPECTATE: 'spectate',     // {}
+  ACTION: 'action',         // { action }  jugada de juego (al motor)
+  CHAT: 'chat',             // { text }
+  RELAY: 'relay',           // { data }  mensaje opaco (room.send sin motor)
+  VERIFY_RESP: 'verify.resp', // { nonce, publickey, signature, encryptionPubkey? }
+  RECEIPT_SIGN: 'receipt.sign', // { receiptId, sig }  segunda firma del recibo
+  RATING_QUERY: 'rep.query', // { queryId, subject }
+  RATING_REPLY: 'rep.reply', // { queryId, subject, mine, endorsements }
+  INFO_REQUEST: 'info.req',  // {}  discovery: pedir resumen de la sala
+  PING: 'ping',             // { ts }  heartbeat de presencia
+  INVITE: 'invite',         // { roomId, name, from, fromName }  invitación (sendByPubkey)
+  HOST_REKEY: 'host.rekey', // { oldRoomId, newRoomId, hostPubkey }  el host reconectó con token nuevo
+
+  // ── host → guest(s) ──────────────────────────────────────────
+  STATE: 'state',           // snapshot completo personalizado por asiento
+  EVENT: 'event',           // { event, data }  eventos laterales (chat, started, ended, rejected)
+  INFO: 'info',             // { summary }  respuesta de discovery
+  VERIFY_CHALLENGE: 'verify.challenge', // { nonce }
+  RECEIPT_OFFER: 'receipt.offer', // { receiptId, receipt }  mitad a co-firmar
+  RESULT_OFFER: 'result.offer', // { resultId, data:{op:'result',gameId,a,b,winner,ts}, sigA }  resultado a co-firmar
+  RESULT_SIGN: 'result.sign',   // { resultId, sig }  segunda firma del resultado (para ELO)
+  KICKED: 'kicked',         // { reason }
+  PONG: 'pong'              // { ts }
+}
+
+/** Canal de descubrimiento de salas de un juego (lista tokens de hosts). */
+export const discoveryChannel = (gameId) => `cclobby/${gameId}`
+/** Canal de presencia de una sala concreta (host + guests publican aquí). */
+export const roomChannel = (gameId, roomId) => `ccroom/${gameId}/${roomId}`
+
+/**
+ * Construye un sobre.
+ * @param {string} gameId
+ * @param {string} roomId
+ * @param {string} kind  uno de K
+ * @param {any} data
+ * @param {number} [seq]  número de secuencia autoritativo (host→guest)
+ */
+export function envelope (gameId, roomId, kind, data, seq) {
+  const env = { __ccl: ENVELOPE_TAG, g: gameId, r: roomId, k: kind, d: data || {} }
+  if (typeof seq === 'number') env.s = seq
+  return env
+}
+
+/**
+ * ¿Es un mensaje de esta librería? El callback 'message' del proxy entrega el
+ * payload ya parseado cuando era JSON; aceptamos también un string JSON por las
+ * dudas (otros transportes / WebRTC).
+ * @returns {null | { g, r, k, d, s }}
+ */
+export function parseEnvelope (payload) {
+  let obj = payload
+  if (typeof payload === 'string') {
+    try { obj = JSON.parse(payload) } catch (_) { return null }
+  }
+  if (!obj || typeof obj !== 'object' || obj.__ccl !== ENVELOPE_TAG) return null
+  if (typeof obj.k !== 'string') return null
+  return { g: obj.g, r: obj.r, k: obj.k, d: obj.d || {}, s: typeof obj.s === 'number' ? obj.s : null }
+}

package/src/reputation.js

@@ -0,0 +1,105 @@
+// Integración reputación + contactos para el lobby.
+//
+// Reusa @dotrino/reputation (createVaultReputation) y los
+// contactos del vault (@dotrino/identity), inyectados por
+// duck-typing. Tres usos:
+//   1. Gate de admisión (filtrar salas / rechazar joiners por reputación).
+//   2. Ranking de salas (priorizar contactos / mejor reputación).
+//   3. Recibo de partida co-firmado → atestación txBound ("jugamos juntos").
+
+import { samePubkey } from './util.js'
+
+/**
+ * Crea una función de admisión `gate(pubkey) → { ok, reason?, rep? }`.
+ * Best-effort: si el servicio de reputación falla, NO bloquea (devuelve ok).
+ * @param {object|null} reputation  instancia de createVaultReputation
+ * @param {object} [gate]
+ * @param {boolean} [gate.requireVouched] exigir aval de la red (trustedCount>0)
+ * @param {number}  [gate.minReputation]  score mínimo 0..1
+ */
+export function createRepGate (reputation, gate = {}) {
+  const minRep = typeof gate.minReputation === 'number' ? gate.minReputation : null
+  const requireVouched = !!gate.requireVouched
+  const active = !!reputation && (minRep != null || requireVouched)
+  return async function passes (pubkey) {
+    if (!active || !pubkey) return { ok: true }
+    try {
+      const r = await reputation.reputationOf(pubkey)
+      if (requireVouched && !(r && r.trustedCount > 0)) return { ok: false, reason: 'not-vouched', rep: r }
+      if (minRep != null) {
+        const score = r && r.score != null ? r.score : 0
+        if (score < minRep) return { ok: false, reason: 'low-reputation', rep: r }
+      }
+      return { ok: true, rep: r }
+    } catch (_) {
+      return { ok: true } // no romper el matchmaking si reputation.dotrino.com no responde
+    }
+  }
+}
+
+/**
+ * Enriquma resúmenes de sala con reputación y flag de contacto, y los ordena:
+ * primero salas con contactos, luego por score descendente.
+ * @param {Array} rooms  [{ hostPubkey, ... }]
+ * @param {object} ctx { reputation, contacts: Set<pubkey>, preferContacts }
+ */
+export async function rankRooms (rooms, { reputation, contacts, preferContacts = true } = {}) {
+  const enriched = await Promise.all(rooms.map(async (room) => {
+    let rep = null
+    if (reputation && room.hostPubkey) {
+      try { rep = await reputation.reputationOf(room.hostPubkey) } catch (_) {}
+    }
+    const isContact = !!(contacts && room.hostPubkey && [...contacts].some(c => samePubkey(c, room.hostPubkey)))
+    return { ...room, reputation: rep, hostScore: rep && rep.score != null ? rep.score : 0, isContact }
+  }))
+  enriched.sort((a, b) => {
+    if (preferContacts && a.isContact !== b.isContact) return a.isContact ? -1 : 1
+    return b.hostScore - a.hostScore
+  })
+  return enriched
+}
+
+// ── Recibo de partida co-firmado ────────────────────────────────────
+
+/** Payload canónico que ambos jugadores firman (debe coincidir con el server). */
+export function receiptPayload (a, b, ts) { return { op: 'receipt', a, b, ts } }
+
+/** Firma mi mitad del recibo con el vault. Devuelve la firma base64. */
+export async function signReceiptHalf (identity, a, b, ts) {
+  const signed = await identity.signData(receiptPayload(a, b, ts))
+  return typeof signed === 'string' ? signed : signed.signature
+}
+
+// ── Evento de indicador derivado co-firmado (p.ej. ELO) ────────────
+/** Payload canónico del evento que ambas partes firman (debe coincidir con el
+ *  server de reputation: {op:'event', indicator, scope, a, b, outcome, ts}). */
+export function eventPayload (indicator, scope, a, b, outcome, ts) { return { op: 'event', indicator, scope, a, b, outcome, ts } }
+
+/** Firma mi mitad del evento con el vault. */
+export async function signEventHalf (identity, indicator, scope, a, b, outcome, ts) {
+  const signed = await identity.signData(eventPayload(indicator, scope, a, b, outcome, ts))
+  return typeof signed === 'string' ? signed : signed.signature
+}
+
+/**
+ * Promueve a un peer a contacto del vault (compartido entre apps del ecosistema)
+ * y, si se pasa rating, lo atesta en el registro (con recibo si está disponible).
+ */
+export async function ratePlayer (identity, reputation, pubkey, valueOrIndicators, opts = {}) {
+  if (identity && opts.addContact !== false) {
+    try { await identity.addContact({ publickey: pubkey, nickname: opts.nickname, lastToken: opts.token }) } catch (_) {}
+  }
+  if (reputation && valueOrIndicators != null) {
+    try {
+      return await reputation.rate(pubkey, valueOrIndicators, { notes: opts.notes, receipt: opts.receipt })
+    } catch (e) {
+      // El server rechaza TODO el rating si el recibo es inválido. No perder el
+      // rating: reintentar sin recibo (queda con txBound:false).
+      if (opts.receipt) {
+        try { return await reputation.rate(pubkey, valueOrIndicators, { notes: opts.notes }) } catch (_) {}
+      }
+      throw e
+    }
+  }
+  return { ok: true, txBound: false }
+}