El protocolo de proveedores

Un proveedor es de donde viene la música. Let’s DJ no incluye ninguno.

Un proveedor es un servicio HTTP, nunca código que carguemos nosotros. No ejecutamos tu implementación, ni la aislamos en un sandbox, ni gestionamos su ciclo de vida. Eso significa que puede escribirse en cualquier lenguaje, y que tu contenido nunca pasa por nuestra infraestructura.

Esta especificación está escrita para valerse por sí sola. El código de Let’s DJ es privado, así que no hay ninguna implementación que leer al lado, y todo lo que dejara a la deducción sería algo que solo descubrirías al ser rechazado. Cuando da una cifra, un valor por defecto o un código de error, es cómo se comporta el servicio hoy. Cuando no dice nada, como en qué lenguaje escribes o cómo guardas tus archivos, la elección es tuya y nada de lo que aquí se dice depende de ella.

Palabras que se usan aquí

El servicio es el backend de Let’s DJ, en https://api.lets.dj. Toda ruta de esta especificación que empiece por /providers/ es relativa a él. Todas son HTTPS.

Una biblioteca es como se llama en la app a un proveedor conectado. La persona que lo ha conectado es su dueño, y un dueño puede tener varias. Cada biblioteca tiene su propio token de sincronización, así que dos proveedores en una misma máquina son dos bibliotecas y necesitan un token cada uno.

Una fiesta es una sesión. Tiene un Stage, la pantalla que todos miran: una página web en app.lets.dj, abierta en un navegador en un televisor o un portátil. Los invitados usan móviles para buscar y pedir canciones. Solo el Stage reproduce algo.

Una pista (track) es una canción o un vídeo. El catálogo es la lista de pistas que tiene un proveedor. Media es el audio o el vídeo en sí.

El token de sincronización es el secreto que identifica una biblioteca ante el servicio. El token de media es otro secreto distinto, que generas tú y que protege tu contenido.

El bridge es el programa que Let’s DJ publica para compartir una carpeta de archivos de un ordenador. Es un proveedor corriente, y se usa como ejemplo allí donde un ejemplo ayuda. Nada en este protocolo le da un privilegio que otro proveedor no tenga.

Las dos mitades

El catálogo y el contenido viajan por caminos distintos, y la separación importa.

Los metadatos del catálogo van al servicio. Los invitados buscan desde su móvil, y un móvil no debería necesitar llegar a tu servidor: puede estar con datos móviles, o en una red completamente distinta. Por eso el catálogo se refleja en el servicio, y la búsqueda es una sola consulta sobre todos los proveedores de una fiesta.

El contenido va directo al Stage. La pantalla recoge los bytes de ti directamente. Nunca pasan por nosotros. Es deliberado: mantiene la latencia a velocidad de red local para los proveedores locales, deja nuestro coste de ancho de banda en cero y nos mantiene fuera del camino del contenido.

En qué dirección se mueve el catálogo depende de si podemos llegar hasta ti:

• Eres accesible desde internet (un catálogo con licencia, un servicio alojado): nosotros lo traemos (pull), según un calendario, con las credenciales que nos dio el dueño.
• No lo eres (cualquier cosa en una red doméstica): tú lo envías (push), cada vez que cambia tu biblioteca.

El envío (push) es lo que usa el bridge, y es lo que describe el resto de esta especificación. La recogida (pull) está implementada hasta ahora para un solo tipo de proveedor, un bucket compatible con S3, descrito en Almacenamiento en la nube, y sigue abierta a cualquier otra fuente accesible más adelante.

Qué hace un proveedor, en orden

1. Conectar. Conseguir un token de sincronización mostrándole un código al dueño y esperando a que lo apruebe. Véase Conectar un proveedor.
2. Ser accesible para un navegador. El Stage es una página HTTPS, así que tu contenido necesita una dirección HTTPS con un certificado en el que un navegador ya confíe. Un proveedor en una red doméstica puede pedirnos un nombre y el certificado que lo acompaña, o traer el suyo. Véase Un nombre y un certificado.
3. Servir contenido. Una sola ruta, con peticiones de rango. Véase Servir el contenido multimedia.
4. Enviar el catálogo, y las portadas si las tienes, y decir qué eres: Enviar un catálogo y Capacidades.
5. Mantenerlo al día. Enviar de nuevo cuando cambie tu biblioteca. Pedir un certificado nuevo antes de que caduque el anterior. Si te has apuntado, recoger y responder trabajos: Responder bajo demanda.

Convenciones

Los cuerpos son JSON en UTF-8, salvo el contenido, que son bytes, y las portadas, que son una imagen. Los campos que esta especificación no menciona se ignoran. Una cadena vacía se trata como ausente. Los números deben ser finitos.

La autenticación es Authorization: Bearer <sync token> en toda petición a /providers/…, con dos excepciones que pertenecen a la conexión: iniciar un emparejamiento no requiere credencial, y consultar uno usa en su lugar el secreto de consulta. Véase Conectar un proveedor.

Los errores son un estado distinto de 2xx y un cuerpo JSON, { "error": "<words>" }. Las rutas añadidas más recientemente, para el emparejamiento, la dirección y el certificado, llevan además "code": "<machine-readable>". Actúa según el estado, y según code cuando lo haya. Nunca actúes según las palabras, que están escritas para una persona y pueden cambiar.

• 400 significa que la petición estaba mal formada, y error dice qué parte.
• 401 significa que no había token bearer.
• 403 significa que el token no se conoce. Para un token de sincronización es permanente: la biblioteca se borró. Deja de reintentar, descarta el token y conecta de nuevo, y solo cuando haya alguien para aprobarlo. Abrir una solicitud de emparejamiento delante de una persona que se ha ido es peor que quedarse parado.
• 404 significa que lo que nombras no está: una pista desconocida al enviar una portada, un trabajo desconocido.
• 429, 502 y 503 son nuestros y merece la pena reintentarlos. Espera lo que diga Retry-After cuando esté presente, y ve espaciando los intentos cuando no.

Compatibilidad. Todos los campos añadidos hasta ahora a este protocolo han sido opcionales, y ausente significa lo que significaba antes de que existiera el campo. Un proveedor escrito antes de cualquiera de ellos no se ve afectado.

Frecuencia. Hoy el servicio no limita la frecuencia de estas rutas, y eso no es una invitación. Envía cuando cambie tu biblioteca; el bridge además vuelve a escanear cada cinco minutos como respaldo, porque vigilar una carpeta pasa por alto cambios en silencio en los recursos de red. Consulta los trabajos más o menos una vez por segundo, y solo si te has apuntado.