proyecto propio · código abierto · Cloudflare Workers

Un backend que
entrega cada SMS

sms-relay recibe los SMS que envía la app sms-forwarder, los guarda una sola vez y los reenvía a Telegram y a un webhook firmado. Si un destino falla, reintenta con espera creciente hasta entregar o dejar un estado final visible. Lo escribí entero yo.

github.com/Lacho00/sms-relay

Diagrama animado: un SMS entra por /ingest y se guarda en la tabla outbox de D1; el Worker responde 200. Después se reparte a dos destinos, Telegram y un webhook firmado con HMAC. El webhook falla una vez, espera un minuto y entrega al segundo intento; Telegram entrega a la primera. Al final, las dos entregas quedan en estado delivered.

300+pruebas automáticas
≥95 %de cobertura
MITcódigo abierto
Qué es

Un backend serverless que recibe SMS y los reenvía a Telegram y a un webhook

Mi papel

Idea, diseño y código, yo solo

Stack

TypeScript, Cloudflare Workers y D1, Hono, Zod, Drizzle

Pareja

La app Android sms-forwarder, que le envía los SMS

// el problema

Que ningún
SMS se pierda

Un teléfono que reenvía SMS reintenta cuando algo falla. Si el servidor no está preparado para eso, un mismo mensaje llega dos veces, o un fallo de Telegram se lleva el SMS por delante.

sms-relay guarda primero y entrega después. Cada destino tiene su propio estado, su propio reintento y un final visible: entregado o fallido.

01

Un SMS, una sola copia

Cada mensaje recibe una clave sha256 calculada con el remitente, la hora y el texto. Si el teléfono reintenta, la respuesta es "duplicate" y no se crea nada nuevo.

02

Outbox transaccional

El mensaje y una entrega pendiente por cada destino se guardan juntos en un solo batch de D1. El Worker responde 200 cuando ya está todo guardado, no antes.

03

Entrega al menos una vez

Si un destino responde con error temporal, el reintento sigue una espera que crece de 1 minuto a 1 hora y respeta la cabecera Retry-After si pide más.

04

Leases de 60 segundos

Cada entrega se reclama con un lease de 60 segundos. El intento inmediato y el cron de cada minuto no envían nunca la misma fila a la vez.

// el contrato

Cada
código tiene su efecto

La app y el backend se ponen de acuerdo con el código de estado. Un error del teléfono no se reintenta; un error del servidor sí, para que arreglar la configuración no cueste ningún SMS.

// lo que responde el backend
  • 200guardado o duplicado
  • 400 · 401error, reintento manual
  • 429reintento
  • 503reintento, el SMS se conserva
  • 500reintento

Un cuerpo demasiado grande devuelve 400 y no 413, porque la app reintenta un 413 y esa petición nunca podrá funcionar.

// garantías

Lo que
no se sale

Un backend que maneja SMS ve códigos de verificación y datos personales. Cada decisión de abajo busca que eso no se escape.

Logs sin datosLos logs nunca contienen el texto del SMS, el remitente, los tokens ni los IDs de chat. Ni siquiera los errores internos se registran con su mensaje.
Tokens en tiempo constanteLos tokens se comparan en tiempo constante. Hay uno para enviar y otro, distinto, para leer: uno filtrado desde el teléfono no abre el archivo.
Webhook firmadoEl webhook lleva una firma HMAC-SHA256 sobre la marca de tiempo y el cuerpo. Con la marca firmada se puede rechazar una petición capturada y repetida más tarde.
Límite por IPEl ingest y la API de lectura tienen un límite de peticiones por dirección IP. Pasarlo devuelve un 429 que la app sabe reintentar.
Alertas sin contenidoCuando una entrega falla para siempre, llega un solo aviso a Telegram con el id, el destino y el error. Nunca incluye el SMS.
SMS largos, en partesUn texto de más de 4.096 caracteres se envía a Telegram en partes numeradas. Si falla a la mitad, el reintento sigue por la primera parte que no se envió.
Retención con purgaLos mensajes se borran pasado un plazo configurable. Un cron lo aplica cada minuto, y un mensaje con una entrega pendiente se conserva hasta que termine.
// el E2E

La prueba real
encontró el fallo

sms-forwarder v2.1.3arreglado

Una regex que Android rechazaba

Antes de dar el sistema por bueno lo probé de extremo a extremo contra producción: la app en un teléfono, el backend en Cloudflare. La prueba destapó un crash en la app Android: una expresión regular que el motor ICU de Android no aceptaba y que ninguna prueba en el ordenador había podido ver. Lo arreglé en sms-forwarder v2.1.3.

// en cifras

Números
del proyecto

300+pruebas automáticas, con una base D1 real en local
≥95 %de cobertura en líneas, statements y funciones, y ≥90 % en ramas
~1.700líneas de código fuente
3dependencias de runtime: Hono, Zod y Drizzle

sms-relay es una herramienta personal, no un trabajo para un cliente: no hay resultados de negocio que contar. Las cifras salen del repositorio.

TypeScriptCloudflare WorkersD1HonoZodDrizzle ORMVitestWranglerGitHub Actions
// tu proyecto

¿Tienes un proyecto en mente?

Cuéntame qué necesitas. Te respondo en menos de 24 h y, si encaja, recibes una propuesta cerrada por escrito.