personal project · open source · Cloudflare Workers
A backend that delivers every SMS
sms-relay receives the SMS sent by the sms-forwarder app, stores each one once and forwards it to Telegram and a signed webhook. If a destination fails, it retries with a growing wait until it delivers or leaves a visible final state. I wrote all of it.
Animated diagram: an SMS comes in through /ingest and is stored in the D1 outbox table; the Worker answers 200. It is then sent to two destinations, Telegram and a webhook signed with HMAC. The webhook fails once, waits one minute and delivers on the second attempt; Telegram delivers on the first. In the end, both deliveries are in the delivered state.
300+automated tests
≥95%coverage
MITopen source
What it is
A serverless backend that receives SMS and forwards them to Telegram and a webhook
My role
Idea, design and code, all on my own
Stack
TypeScript, Cloudflare Workers and D1, Hono, Zod, Drizzle
Partner
The Android app sms-forwarder, which sends it the SMS
// the problem
Never lose an SMS
A phone that forwards SMS retries when something fails. If the server is not ready for that, the same message arrives twice, or a Telegram error takes the SMS down with it.
sms-relay stores first and delivers after. Each destination has its own status, its own retry and a visible end: delivered or failed.
01
One SMS, one copy
Each message gets a sha256 key built from the sender, the time and the text. If the phone retries, the answer is "duplicate" and nothing new is created.
02
Transactional outbox
The message and one pending delivery per destination are saved together in a single D1 batch. The Worker answers 200 once everything is stored, not before.
03
At-least-once delivery
If a destination answers with a temporary error, the retry follows a wait that grows from 1 minute to 1 hour and honors the Retry-After header when it asks for more.
04
60-second leases
Each delivery is claimed with a 60-second lease. The immediate attempt and the cron that runs every minute never send the same row at the same time.
// the contract
Every code has an effect
The app and the backend agree through the status code. A phone-side error is not retried; a server-side one is, so fixing the configuration costs no SMS.
// what the backend answers
200stored or duplicate
400 · 401error, manual retry
429retry
503retry, the SMS is kept
500retry
An oversized body returns 400, not 413, because the app retries a 413 and that request can never succeed.
// guarantees
What never leaks
A backend that handles SMS sees verification codes and personal data. Each decision below is there to keep that from leaking.
Logs without dataLogs never contain the SMS text, the sender, the tokens or the chat IDs. Even internal errors are logged without their message.
Constant-time tokensTokens are compared in constant time. There is one to send and a different one to read: a token leaked from the phone does not open the archive.
Signed webhookThe webhook carries an HMAC-SHA256 signature over the timestamp and the body. The signed timestamp lets you reject a captured request that is replayed later.
Per-IP limitIngest and the read API have a request limit per IP address. Going over it returns a 429 that the app knows how to retry.
Alerts without contentWhen a delivery fails for good, a single Telegram alert arrives with the id, the destination and the error. It never includes the SMS.
Long SMS, in partsA text over 4,096 characters is sent to Telegram in numbered parts. If it fails halfway, the retry resumes at the first part that was not sent.
Retention with purgeMessages are deleted after a configurable period. A cron applies it every minute, and a message with a pending delivery is kept until it ends.
// the E2E
The real test found the bug
sms-forwarder v2.1.3fixed
A regex Android rejected
Before calling the system done I tested it end to end against production: the app on a phone, the backend on Cloudflare. The test uncovered a crash in the Android app: a regular expression that Android's ICU engine did not accept and that no test on the computer could have caught. I fixed it in sms-forwarder v2.1.3.
// in numbers
Project in numbers
300+automated tests, run against a real local D1 database
≥95%coverage on lines, statements and functions, and ≥90% on branches
~1,700lines of source code
3runtime dependencies: Hono, Zod and Drizzle
sms-relay is a personal tool, not client work: there are no business results to report. The numbers come from the repository.