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.

github.com/Lacho00/sms-relay

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.

TypeScriptCloudflare WorkersD1HonoZodDrizzle ORMVitestWranglerGitHub Actions
// your project

Got a project in mind?

Tell me what you need. I reply within 24 hours and, if it is a fit, you get a fixed written proposal.