Minecraft y Discord: qué debe pasar si fallan los avisos
Si Discord deja de responder, una integración de avisos debería permitir que el evento de Minecraft continúe, conservar las notificaciones que sigan siendo útiles y mostrar al equipo cuáles no se han entregado. Acordad ese comportamiento antes de encargar el plugin. Enviar un mensaje durante una demostración no demuestra cómo responderá ante una caída.
Esta guía trata los avisos en un solo sentido desde un servidor Paper hacia un canal de Discord mediante un webhook entrante: resúmenes de inscripciones, resultados de rondas o cambios de estado. No cubre órdenes desde Discord, vinculación de cuentas ni sincronización de roles, que necesitan sus propias reglas de identidad y autorización. El diseño es una propuesta de especificación, no una implementación de Mineando que hayamos probado.
Decide dónde queda el resultado oficial
Imagina un plugin de torneos que guarda el resultado de una ronda y anuncia al ganador en Discord. El registro del torneo debe ser la fuente del resultado oficial. Que falte el aviso no debe repetir la ronda, volver a entregar un premio ni cambiar al ganador.
Escribe dos condiciones de aceptación independientes: «el resultado se ha guardado» y «el aviso se ha entregado». El equipo debe poder consultar ambas. Meter una notificación en una cola no equivale a entregarla.
Para una integración pequeña, esta distinción aporta más que una lista larga de funciones. Inclúyela en los criterios de aceptación del plugin y decide quién puede corregir un resultado o reenviar su aviso. Reenviar debe actuar únicamente sobre la notificación, sin ejecutar otra vez la acción del juego.
Define el recorrido de cada aviso
Pide un identificador estable del evento, fecha de creación, referencia al destino, regla de caducidad y estado de entrega. Una lista práctica de estados es pendiente, entregado, caducado y requiere revisión. Un reintento debe conservar el identificador, no crear un evento lógico nuevo.
Si los resultados tienen que sobrevivir a un reinicio, exige almacenamiento persistente. Cuando la aplicación guarda los resultados en una base de datos, una opción es registrar el resultado y su notificación pendiente en la misma transacción. Si no resulta viable, debe existir una conciliación que detecte resultados guardados sin aviso. El desarrollador tiene que explicar y demostrar la opción elegida; una cola que solo vive en memoria no cumple un requisito de persistencia.
Separa este trabajo del tick del servidor. Paper recomienda sacar las operaciones de red lentas del hilo principal y advierte de que acceder al mundo desde tareas asíncronas puede ser inseguro. Hay que respetar ambas condiciones. Consulta la documentación de planificación de tareas de Paper.
Mover el trabajo a otro hilo también requiere límites. Fija cuántos avisos pueden acumularse y qué ocurrirá al llenar la cola. Para este torneo, conserva los resultados oficiales en su registro, señala el fallo de notificación y permite que el equipo los concilie. No sobrescribas en silencio un resultado importante pendiente para dejar sitio a un aviso rutinario de estado.
Distingue una espera de una configuración rota
Discord indica que los límites se deben interpretar a partir de sus respuestas. Ante HTTP 429, respeta Retry-After o retry_after, sin fijar una cuota universal de envío. Si un webhook devuelve 404, deja de reintentarlo. Son reglas de la documentación de límites de Discord.
Para fallos transitorios de red, acordad reintentos limitados, con esperas crecientes y cierta variación aleatoria. Especificad tanto el número máximo de intentos como la antigüedad máxima del mensaje. Al alcanzar cualquiera de los límites, el aviso pasa a revisión o caduca según su finalidad. Un bucle de reintentos infinito no es un procedimiento de operación.
Las credenciales incorrectas, los mensajes mal formados y los destinos no disponibles necesitan un diagnóstico visible para el equipo. La entrega debe explicar qué fallos pausan un destino y cómo reanudarlo tras corregirlos. Los registros deben incluir identificadores útiles y categorías de error, excluyendo los secretos del webhook. Las pruebas necesitan destinos separados para no publicar en el canal real de la comunidad.
No prometas que nunca habrá duplicados
Para obtener una confirmación de envío más sólida, la API de webhooks ofrece wait=true, que devuelve el mensaje creado. Guarda su identificador cuando lo recibas. El comportamiento se documenta en Execute Webhook.
Aun así, considera esta secuencia: Discord acepta un mensaje, pero la conexión se corta antes de que tu aplicación reciba la respuesta. La aplicación no puede concluir que no se haya publicado nada. Un reintento podría producir un segundo aviso. El identificador interno ayuda a investigar; incluirlo en el texto no hace que el destino elimine duplicados automáticamente.
Acordad qué hacer ante esa incertidumbre. Un resultado rutinario podría admitir un duplicado fácil de reconocer. Un anuncio de gran impacto podría quedar pendiente de revisión humana antes de volver a enviarse. Ninguna de las dos políticas debe repetir el resultado del juego ni sus premios. No aceptes una promesa de entrega «exactamente una vez» sin un mecanismo demostrado y unos límites de fallo claros.
Decide qué mensajes deben caducar
Una caída puede dejar mensajes correctos que ya no sirven. «La siguiente ronda empieza en dos minutos» no debería aparecer cuando esa ronda ya ha empezado. Un resultado oficial, en cambio, puede seguir siendo útil más tarde si conserva la hora original del evento.
Incluye una tabla breve en la especificación:
| Aviso | Comportamiento propuesto al recuperar el servicio |
|---|---|
| Próximo inicio de ronda | Caduca cuando empieza esa ronda. |
| Resultado oficial | Se conserva para revisión o envío posterior con su hora original. |
| Actualización repetida del estado | La última sustituye a las anteriores pendientes, si no hace falta historial. |
Son ejemplos editoriales, no valores predeterminados de Discord. Elige estas reglas con la persona responsable del evento. Conserva el orden cuando importe y decide si un resultado posterior puede adelantarse a un aviso anterior fallido. Al recuperarse el servicio, vacía la cola de forma controlada, sin inundar el canal con mensajes atrasados sin contexto.
Ensaya los fallos antes de aceptar la entrega
Utiliza un servidor de pruebas aislado y un destino de ensayo controlado o un servicio HTTP simulado. No sobrecargues Discord deliberadamente para provocar sus límites. Pide al desarrollador que ejecute estos casos y adjunte evidencias:
- Retrasar la respuesta del destino: la partida continúa y el aviso queda pendiente.
- Simular un límite de solicitudes: el siguiente intento respeta la espera indicada.
- Reiniciar con resultados pendientes: los registros acordados sobreviven y se reanuda el proceso.
- Simular un envío aceptado cuya respuesta se pierde: se observa la política de entrega incierta.
- Eliminar el destino de pruebas: cesan los reintentos y el equipo ve un fallo que puede corregir.
- Recuperar el servicio tras empezar una ronda: no se publica su cuenta atrás caducada.
- Llenar la cola acordada: se aplica la política prevista sin repetir acciones del juego.
Anota versiones, entradas, resultados esperados y reales, estado de la cola y marcas de tiempo. Mantén «no ejecutado» hasta realizar cada prueba. Mide el comportamiento del servidor en el escenario acordado; esta lista no aporta ningún benchmark de capacidad de jugadores.
En el ensayo del evento, asigna a alguien la revisión del número de pendientes, la edad del más antiguo y los fallos sin resolver. Prepara una vía de escalado que no dependa de los avisos averiados. Acordad quién puede pausar envíos, conciliar entregas inciertas y autorizar un reenvío.
Para encargar una integración de Minecraft a medida, lleva los tipos de evento, el destino, las ráfagas previstas, las reglas de caducidad y esta lista de fallos. Mineando ofrece proyectos de desarrollo pagados, con alcance y presupuesto individuales. El mantenimiento y la cobertura en directo se acuerdan aparte.
