hachiflow.com

Esta entrada trata de Buzz, nuestro producto anterior. Hoy construimos Waggle.

Emparejamiento

Por qué el emparejamiento por QR da 404: el sidecar que nadie arrancó

Escanea el código y míralo fallar. El emparejamiento de dispositivos necesita un canal al que pueda llegar un teléfono sin emparejar, y en un relay con membresía ese canal es un proceso aparte atado a loopback. Viene dentro de la imagen del relay, que es justo por lo que es fácil dejarlo apagado. Nosotros lo dejamos.

Todo funciona menos el código QR

El aviso llega sin ningún detalle útil, porque no hay ninguno que dar. Alguien abre Buzz en su escritorio, elige la opción de añadir un teléfono y aparece un código QR al instante. Lo escanea. Unos segundos después el escritorio muestra un error de emparejamiento, y su texto incluye un 404.

Lo cual desconcierta, porque el relay está claramente sano. Los mensajes llegan, los archivos se suben, las invitaciones funcionan, y el mismo escritorio que no consigue emparejar está conectado al relay en este momento. Solo falla el emparejamiento, y el motivo es que el emparejamiento es lo único que no habla con el relay que configuraste.

Un teléfono sin emparejar no puede llamar a la puerta principal

Un relay que exige membresía controla la propia conexión WebSocket: demuestras quién eres antes de obtener un socket. Para eso sirve activarlo. Pero un teléfono que nunca se ha emparejado no tiene ninguna identidad que el relay reconozca. No puede conectarse al relay principal para recibir el handshake de emparejamiento, porque el handshake es justamente la forma en que obtiene la clave que necesitaría para conectarse. El huevo y la gallina.

Así que el handshake de emparejamiento ocurre en otro sitio, por un canal que acepta a cualquiera: un relay diminuto que transporta un solo tipo de evento, no guarda historial y se olvida de ti a los dos minutos. En un relay abierto, sin control de membresía, nada de esto hace falta, porque el teléfono puede conectarse al relay principal como cualquier otro desconocido. El canal fuera de banda existe precisamente porque cerraste con llave la puerta principal.

El canal es un segundo proceso, y se esconde a plena vista

Ese canal es buzz-pair-relay, un binario aparte dentro del árbol de Buzz. Es pequeño a propósito: sin persistencia, sin autenticación, sin historial, un solo tipo de evento, con verificación de firmas, deduplicación, una ventana de frescura, un tope de 128 conexiones, un límite de 4 KiB por trama y una vida máxima estricta de 120 segundos por conexión. Es el tipo de componente que puedes leer de una sentada y luego olvidarte de él.

Su nota de despliegue es toda la historia de este artículo. Escucha solo en loopback, por defecto en 127.0.0.1:5000, y su documentación indica que necesita delante un proxy inverso que le enrute /pair, termine TLS e imponga tiempos de espera de lectura. No restringe rutas ni limita por sí mismo las conexiones previas a la actualización, a propósito, porque eso es trabajo del proxy. Un proceso que escucha en 127.0.0.1 y al que nada enruta es un proceso que no hace absolutamente nada, en silencio, para siempre.

Y aquí está lo que lo vuelve escurridizo: el binario viene dentro de la imagen estándar del relay. El Dockerfile lo compila junto al relay y lo copia a /usr/local/bin/buzz-pair-relay. Así que, si lo buscas, está ahí mismo en el contenedor. Parece instalado porque está instalado. Simplemente nunca se arrancó, y nunca se enrutó nada hacia él.

Cómo decide el cliente dónde emparejar

Antes de dibujar un código QR, el escritorio le pregunta al relay dónde se empareja. La pregunta es un simple GET HTTP al origen del relay con Accept: application/nostr+json, el documento de información estándar de NIP-11, y la respuesta decide todo lo que viene después.

Hay tres resultados posibles. Si el documento trae un pairing_relay_url que se interpreta como una URL ws o wss, el escritorio usa esa y nada más importa. Si no, y supported_nips contiene el 43, el relay está diciendo que exige membresía, y el escritorio recurre a una convención heredada: toma la URL del propio relay y le añade /pair. Si no se cumple ninguna de las dos, usa directamente el relay principal, que es la respuesta correcta para un relay abierto.

La segunda rama es la trampa. Se elige a partir de un anuncio, no de una comprobación. Nada verifica que /pair exista antes de que el código QR aparezca en pantalla, porque el código QR se construye a partir de la URL y no de una conexión exitosa a ella. Así que un relay que exige membresía, y por eso anuncia NIP-43 con toda honestidad, dirige cada intento de emparejamiento a una ruta que puede ser un 404, y quien lo descubre es tu cliente.

Escritorio Buzz lee NIP-11 pairing_relay_url anunciado por el relay supported_nips: 43 heredado: mismo host + /pair 404: nadie está escuchando wss://pairing.example wss://relay.example/pair buzz-pair-relay solo loopback, puerto 5000 el proxy debe enrutar /pair aquí
Antes de dibujar el código QR, el escritorio le pregunta al relay dónde se empareja. Un relay que anuncia un host de emparejamiento se usa directamente. Un relay que solo anuncia NIP-43 manda al cliente a su propio nombre de host con /pair añadido, y esa ruta es un 404 hasta que alguien arranca el sidecar y enruta hacia él. Nada lo comprueba antes, así que el código QR aparece igual.

Una petición y ya lo sabes

No necesitas un teléfono, un código QR ni un segundo dispositivo para comprobarlo. Pide /pair al nombre de host público del relay con curl, desde cualquier sitio.

Un 404 significa que el emparejamiento está roto en ese relay, hoy, para todo el mundo. La respuesta que conviene conocer es la sana, porque también parece un fallo: un sidecar bien enrutado responde 400 Bad Request. Curl no envía una actualización a WebSocket, y el sidecar rechaza con un 400 todo lo que no sea una actualización bien formada antes de hacer nada más. Así que 400 es buena noticia y 404 es mala, y los separa un solo dígito en un sitio donde nadie mira con atención.

Después lee lo que el relay afirma, porque eso decide si /pair es siquiera lo que hay que probar. Si pairing_relay_url tiene valor, los clientes van ahí y la misma prueba de 400 frente a 404 se aplica a ese host. Si no aparece y NIP-43 está en la lista, la ruta heredada está activa y /pair es exactamente adonde llegarán todos los clientes.

todo el diagnóstico
# ¿hay algo respondiendo en /pair? $ curl -i https://<relay-host>/pair # 404 significa que el emparejamiento está roto. 400 Bad Request es la buena respuesta: es el sidecar rechazando una petición que no es una actualización a WebSocket. # ¿y qué está prometiendo el relay en su documento NIP-11? $ curl -sH 'Accept: application/nostr+json' https://<relay-host>/ \ | jq '{pairing_relay_url, nip43: (.supported_nips | index(43))}'

Si pairing_relay_url devuelve un valor, esa es la URL que hay que probar y /pair no se usa en absoluto. Si es null y la comprobación de NIP-43 devuelve un índice en vez de null, entonces /pair en ese host es exactamente adonde irán todos los clientes.

Tres arreglos, y solo necesitas uno

Arráncalo y enruta hacia él. El binario ya está en tu imagen, así que esto es un segundo servicio y una regla de proxy, no una recompilación: ejecuta buzz-pair-relay junto al relay y añade delante una ruta /pair que le reenvíe la actualización a WebSocket en el puerto 5000. Enruta solo /pair, y deja TLS y los tiempos de espera de lectura en el proxy, que es lo que el sidecar da por supuesto.

O dale su propio nombre de host. Define BUZZ_PAIRING_RELAY_URL en el relay y este anunciará pairing_relay_url en su documento NIP-11, de modo que los clientes se saltan por completo la convención heredada y se conectan directamente a un endpoint dedicado. En el chart de Helm eso son pairingRelay.enabled y pairingRelay.url, que ejecutan el sidecar como su propio Deployment y Service en el puerto 5000. El chart no crea un ingress para él, deliberadamente, así que enrutar ese nombre de host sigue siendo cosa tuya.

O deja de anunciar lo que no haces. Si tu relay no exige membresía de verdad, no debería anunciar NIP-43 en absoluto, y entonces el cliente nunca toma la rama heredada. El proyecto upstream deja NIP-43 fuera de la lista estática de NIPs soportados justo por esta razón, y fija la decisión con un test cuyo comentario dice, con todas las letras, que anunciarlo en relays abiertos desvía a los pares de emparejamiento hacia un sidecar /pair que no existe.

Nosotros también tuvimos este hueco en producción

Nuestras propias instancias gestionadas ejecutaban la imagen del relay sin arrancar nunca el sidecar, y el binario estuvo en el contenedor todo el tiempo. Lo descubrimos como lo descubre todo el mundo: escaneando un código QR. Tres cosas conspiran para ocultar este fallo, y ninguna es un descuido de nadie. El sidecar escucha en loopback, así que nunca falla de forma ruidosa. Viene dentro de la imagen, así que parece presente. Y el cliente elige la ruta heredada a partir de una declaración y no de una comprobación, así que el código QR se muestra perfectamente hasta el momento en que se intenta la conexión. Es un modo de fallo que conviene comprobar en lugar de dar por hecho que no te afecta: si ejecutas un relay de Buzz que exige membresía, envía la petición del principio de esta página antes de que alguien escanee un código.

← Todas las notas