DEV Community: Antonio Towami

Background Jobs in Go with Asynq: Emails, Notifications, and Resilience

Antonio Towami — Thu, 15 Oct 2026 17:58:00 +0000

When a customer places an order on a merchant's store, the checkout path does not call an SMTP server. After saving the order, it asks a mailer interface to enqueue a task in Redis.

Why Separate the Worker

Our worker binary is a dedicated process that pulls tasks from Redis queues using Asynq. It runs independently from the three HTTP binaries (site, shops, admin).

The reasoning is simple: SMTP latency is variable, and transient failures need retries. Neither concern should block the HTTP response. The worker can retry independently if the mail server is temporarily unavailable.

Task Architecture

Email delivery uses one generic task type and a template discriminator:

const TypeEmailDelivery = "email:deliver"

type EmailPayload struct {
    To       string         `json:"to"`
    Lang     string         `json:"lang"`
    Template string         `json:"template"`
    Data     map[string]any `json:"data"`
}

The producer marshals the payload and checks both operations:

payload, err := json.Marshal(EmailPayload{
    To:       recipient,
    Lang:     lang,
    Template: "new_shop_order",
    Data:     map[string]any{"OrderID": orderID},
})
if err != nil {
    return err
}
task := asynq.NewTask(TypeEmailDelivery, payload)
if _, err := client.EnqueueContext(ctx, task); err != nil {
    return err
}

The worker handles it:

func (h *EmailHandler) ProcessTask(ctx context.Context, t *asynq.Task) error {
    var p EmailPayload
    if err := json.Unmarshal(t.Payload(), &p); err != nil {
        return fmt.Errorf("decode email payload: %v: %w", err, asynq.SkipRetry)
    }
    return h.sender.Send(ctx, p)
}

Malformed JSON is permanent, so SkipRetry is appropriate. SMTP/network errors are returned normally and remain retryable.

What Lives in the Worker

Beyond order emails, the worker handles:

Email delivery — sign-up codes, password resets, support mail, orders, and inquiries
Telegram notifications — queued reports and alerts
Marketplace imports — longer, low-priority ingestion tasks

Each task type is registered with its own handler. The worker also uses weighted critical, default, and low queues. Those weights bias which queued task is selected next; they do not reserve workers, so long-running imports can still occupy the whole pool.

The Dev Gotcha

During local development, a queued email will not be sent unless both Redis and the worker are running. Use the project's documented service and log commands rather than copying production hostnames or credentials into an article.

docker compose up -d worker
docker compose logs worker

If the worker is down while Redis remains available, pending tasks can be processed after the worker restarts. That is not the same as guaranteed durability: data loss still depends on Redis persistence, replication, eviction policy, and backup configuration.

Retry Policy

Asynq retries failed tasks according to its retry policy. Short notification tasks use the standard policy, while imports run in a lower-priority queue with bounded retries and execution time. After retries are exhausted, Asynq archives the task. Monitor queue latency, retry counts, and archived tasks with tooling such as Asynqmon or your own metrics.

Asynq provides at-least-once execution, not exactly-once execution. A worker can complete a side effect and fail before acknowledging the task, so handlers must be idempotent. For email, a provider idempotency key or a database send ledger can prevent unwanted duplicates.

Why Not Just goroutines?

A bare go func() { sendEmail() }() has three structural problems:

Lost tasks on restart. A deploy kills the process and all in-flight goroutines die.
No retry. If SMTP is down for 5 minutes, all emails from that window are lost.
No visibility. A bare goroutine provides no queue, failure, or processing state to inspect.

Redis + Asynq gives us durable-enough queuing, retries, scheduling, and observability with little application code. The trade-offs are another stateful dependency and at-least-once semantics.

One final boundary matters: a database commit and a queue publication are separate operations unless the design explicitly bridges them. For business-critical delivery, use a transactional outbox in the same database transaction and publish it asynchronously.

Task payloads may contain email addresses or order details. Keep Redis on a private network with authentication and encryption as appropriate, minimize payloads and retention, and never log full payloads.

This article is based on lessons from building Towami, a multi-country marketplace and white-label storefront platform. Follow for more practical notes on Go, HTMX, infrastructure, and SaaS.

Our Layered REST Architecture in Go: Why GET Must Not Mutate Application State

Antonio Towami — Fri, 09 Oct 2026 23:50:00 +0000

We have a hard rule in our codebase: GET handlers never mutate application state. Incidental server-side effects such as access logging are compatible with HTTP's definition of a safe method, but a GET must not create, update, or delete an application resource. This matters even more when TLS 1.3 early data is enabled.

The 0-RTT Replay Problem

We use Cloudflare with 0-RTT Connection Resumption enabled. TLS 1.3 early data can reduce latency for a resumed connection, but early data does not have inherent replay protection. An attacker may capture and replay it.

Cloudflare supports 0-RTT for GET, HEAD, and OPTIONS requests and marks them with Early-Data: 1. That safe-method restriction reduces the surface; it does not make a side-effecting GET safe. A GET that increments a counter, creates a record, or marks a notification as read may run more than once.

The broader rule comes from RFC 9110's safe-method semantics: clients, crawlers, caches, and prefetchers may invoke GET without expecting state changes. 0-RTT is one reason to respect that contract, not the only reason.

Our Layered Approach

Layering and REST are separate ideas; this is the dependency flow we use for HTTP requests:

router → middleware → handler → service → repository → model/DB

Each layer has a clear role:

Layer	Responsibility
Router	URL → handler mapping
Middleware	Auth, country, locale, CSRF, rate limiting
Handler	Parse request, call service, return response
Service	Business logic, validation
Repository	SQL/GORM queries
Model	Database entity definitions

By convention, handlers do not import repositories directly and services do not construct SQL. Go does not enforce these boundaries automatically, so import checks, tests, and review are still useful. The payoff is that storage details can change without rewriting HTTP concerns.

Practical Enforcement

GET handlers depend on query-oriented service interfaces:

type CatalogQueries interface {
    List(context.Context, CatalogFilter) ([]CatalogCard, error)
}

func (h *CatalogHandler) List(c *gin.Context) {
    var filter CatalogFilter
    if err := c.ShouldBindQuery(&filter); err != nil {
        c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": "invalid filters"})
        return
    }

    cards, err := h.queries.List(c.Request.Context(), filter)
    if err != nil {
        c.AbortWithStatus(http.StatusInternalServerError)
        return
    }
    c.JSON(http.StatusOK, cards)
}

Publishing, editing, and deleting use POST, PUT, PATCH, or DELETE. Cloudflare does not accept those methods as 0-RTT early data, but the method alone does not prevent duplicates: clients and proxies can retry requests, and users can double-submit. Important mutations still need transactions, uniqueness constraints, or idempotency keys.

DTO Separation

We split transport types by application context. A card view should expose only what the page needs:

type CatalogCard struct {
    ID        uint
    Title     string
    Slug      string
    Price     string
    Currency  string
    Image     string
}

The repository also uses an explicit projection for list queries instead of loading large text and JSONB columns. This reduces transferred and decoded data, although the actual gain must be measured against the real query and dataset rather than assumed.

What This Architecture Helps Prevent

Accidental side effects on safe routes — GET stays safe under replay, crawling, and prefetching
Scattered business rules — mutations have one service-level entry point
Over-fetching — explicit repository projections make selected columns reviewable
Transport/storage coupling — HTTP types do not have to mirror database models

It is more boilerplate than a flat handler-does-everything approach. The rule is worth it because it makes behavior easier to test and reason about. It is not, by itself, complete replay protection: mutation endpoints still require their own idempotency and authorization controls.

This article is based on lessons from building Towami, a multi-country marketplace and white-label storefront platform. Follow for more practical notes on Go, HTMX, infrastructure, and SaaS.

Serving Tenant Storefronts on Custom Domains with Go + Cloudflare for SaaS

Antonio Towami — Sun, 04 Oct 2026 06:00:00 +0000

A merchant storefront can live on a platform subdomain (mystore.platform.example) or a custom domain (www.store.example). Both options are served by the same Go application. Here is how we resolve which shop to render.

The Shop Host Middleware

When a request hits the shops binary, a middleware extracts the Host header and figures out which shop it belongs to:

func (m *ShopHostMiddleware) Resolve() gin.HandlerFunc {
    return func(c *gin.Context) {
        host := requestHost(c.Request)
        if host == "" || m.isApexHost(host) {
            c.Next()
            return
        }
        if slug, ok := m.subdomainSlug(host); ok {
            if _, isCountry := helper.Countries[slug]; isCountry {
                c.AbortWithStatus(http.StatusNotFound)
                return
            }
        }
        shop, err := m.resolveShop(c.Request.Context(), host)
        if err != nil {
            c.AbortWithStatus(http.StatusInternalServerError)
            return
        }
        if shop == nil {
            if m.isShopSubdomain(host) {
                c.AbortWithStatus(http.StatusNotFound)
                return
            }
            c.Next() // not a configured custom hostname
            return
        }
        c.Set(ShopContextKey, shop)
        c.Next()
    }
}

resolveShop tries two strategies:

Subdomain lookup: extracts mystore from mystore.platform.example and looks up that unique slug.
Custom-domain lookup: normalizes the supported www.store.example hostname to the stored root, store.example, and looks it up through a unique index.

Country subdomains are explicitly excluded because they belong to the marketplace application. We parse hostnames with net.SplitHostPort, lowercase them, and validate them against known suffixes. If a reverse proxy supplies X-Forwarded-Host, trust it only from a proxy you control.

Cloudflare for SaaS: The SSL Part

The hardest part of custom domains is not routing but certificate issuance and renewal. We use Cloudflare for SaaS custom hostnames for that lifecycle.

The setup:

We configure a fallback origin such as connect.platform.example
When a merchant adds a custom domain, our app calls the Cloudflare API to create a Custom Hostname
The merchant sets CNAME www → connect.platform.example at their DNS provider

Our Custom Hostname request uses HTTP DCV. Once the www CNAME routes through Cloudflare, Cloudflare can validate the hostname and issue the certificate for www.store.example. Cloudflare retries failed validation on a backoff schedule. A status GET only observes that process; if we need an immediate recheck after DNS is fixed, the documented API flow is to PATCH the hostname with its current SSL settings.

Why www-Only

We only support www.{domain}, not bare apex domains. A conventional CNAME cannot coexist with the other records required at a DNS zone apex. Some DNS providers offer ALIAS/ANAME or CNAME flattening, but support and behavior vary. The merchant therefore configures an HTTP redirect from store.example to www.store.example with their DNS or registrar provider.

This is a product constraint, not a universal Cloudflare limitation. Cloudflare for SaaS also documents apex proxying, but its prerequisites and plan availability should be checked before committing to it.

Status Tracking

For each shop we store:

the provider's opaque Custom Hostname ID
a local status: pending, active, or error
a provider status or error summary

When a merchant connects a domain, we create or find the Cloudflare hostname, store its ID, and map Cloudflare's hostname and SSL states to our smaller status set. The dashboard can explicitly refresh that state. A scheduled poller is another option, but the current implementation does not depend on one.

The API token stays server-side and is never returned to the browser; production credentials should have only the required zone permissions. Provider error text is untrusted. Our templates HTML-escape it, but a stronger boundary is to log detailed provider errors server-side and show merchants a bounded, generic message.

What We Learned

Define one canonical hostname. In our case, input may include www., but storage uses the root and serving uses www.. This rule must be consistent in validation, provisioning, and lookup.
Use reserved example domains in documentation. A wildcard under a local .test domain is enough to exercise host routing without Cloudflare.
Index both lookup keys. Host resolution is on the request path, so subdomain slugs and custom domains need unique indexes. Add caching only with an explicit invalidation strategy.
Make provisioning idempotent. Before creating a hostname, look it up; retries should not produce duplicate provider resources.

Custom domains are table stakes for many SaaS storefront products. Cloudflare for SaaS made it possible without running our own ACME client or certificate renewal infrastructure.

This article is based on lessons from building Towami, a multi-country marketplace and white-label storefront platform. Follow for more practical notes on Go, HTMX, infrastructure, and SaaS.

Multi-Host Routing in Go: One Binary, Many Domains

Antonio Towami — Tue, 29 Sep 2026 06:00:00 +0000

Our marketplace is organized around multiple country sites. Each country gets its own subdomain, while the apex is the cross-country portal. A single Go application serves the portal and country catalogs.

The Middleware Approach

Instead of path-based routing (/cr/en/vehicles), we use host-based resolution. A Gin middleware extracts the country from the Host header before any route handler fires:

func CountryHostMiddleware(cfg *config.Config) gin.HandlerFunc {
    return func(c *gin.Context) {
        if slug, ok := helper.CountrySlugFromHost(c.Request.Host, cfg); ok {
            c.Set(string(CountryContextKey), slug)
            c.Set(OnCountryHostContextKey, true)
        }
        c.Next()
    }
}

CountrySlugFromHost strips the port, lowercases the host, and accepts only a one-label subdomain in the country allowlist. If cr.example.com comes in, the context gets country=cr. Edge routing sends shop hosts to a different application; this middleware must not treat an arbitrary subdomain as a country.

A later locale middleware derives language preferences and puts both country and language into the request context. Currency is resolved separately because a visitor may choose a display currency that differs from the country's default.

URL Structure: Language in Path, Country in Host

Each country host serves localized URLs such as /{lang}/vehicles and /{lang}/real-estate. The host's default-language homepage lives at /; requesting the redundant default-language homepage returns a 301 to /.

This design gives us clean hreflang tags for Google:

<link rel="alternate" hreflang="en-CR" href="https://cr.example.com/en/vehicles" />
<link rel="alternate" hreflang="es-CR" href="https://cr.example.com/es/vehiculos" />
<link rel="alternate" hreflang="x-default" href="https://cr.example.com/es/vehiculos" />

The Cookie Problem

Authentication is shared across the platform's apex and country subdomains. The session cookie uses Domain=example.com, so the browser sends it to both example.com and its subdomains. A leading dot is accepted by browsers but ignored by modern cookie semantics, so Domain=.example.com does not create a different scope.

That scope is also a security boundary. A compromised sibling subdomain may be able to shadow or overwrite a domain cookie, and SameSite does not isolate sibling subdomains because they are the same site. We therefore share the cookie only with trusted platform hosts and set Secure, HttpOnly, and an appropriate SameSite value. Tenant-owned custom domains cannot share this cookie.

If cross-subdomain login is unnecessary, a host-only cookie is safer and can use the __Host- prefix. That prefix is incompatible with a Domain attribute.

Legacy URL Migration

We originally had country paths on the apex: example.com/cr/en/vehicles. When we moved to subdomains, we needed 301 redirects:

func LegacyCountryRedirectMiddleware(cfg *config.Config) gin.HandlerFunc {
    return func(c *gin.Context) {
        if helper.OnCountryHost(c, cfg) {
            c.Next()
            return
        }
        if target := helper.LegacyCountryPathRedirect(
            c.Request.URL.Path, c.Request.URL.RawQuery, cfg,
        ); target != "" {
            c.Redirect(http.StatusMovedPermanently, target)
            c.Abort()
            return
        }
        c.Next()
    }
}

Old links such as example.com/cr/en/vehicles now redirect permanently to cr.example.com/en/vehicles. We also preserve the query string deliberately and test malformed country/language combinations so the redirect cannot become an open redirect.

The Result

One binary and one router serve the portal and multiple country catalogs. Adding a country still requires registry, locale, currency, SEO, and data changes, but it does not require a new service architecture.

This article is based on lessons from building Towami, a multi-country marketplace and white-label storefront platform. Follow for more practical notes on Go, HTMX, infrastructure, and SaaS.

How We Run 4 Services From One Go Monorepo

Antonio Towami — Thu, 24 Sep 2026 21:21:09 +0000

We're building Towami — a commerce platform that combines white-label online stores with country marketplaces. One codebase produces four long-running services, each with a separate entry point and responsibility.

The Four Binaries

cmd/
├── site/     → marketplace portal + country catalogs
├── shops/    → merchant storefronts on custom domains
├── admin/    → back-office panel
└── worker/   → background jobs via Asynq (no HTTP)

site serves the main domain and multiple country subdomains. shops serves merchant storefronts on platform subdomains and custom domains. admin is the back-office dashboard. worker processes email, Telegram, and import tasks through Redis queues.

The repository also has an importer command. It is a CLI utility rather than a long-running service, so it is outside the four in the title.

Shared `internal/` With Clean Boundaries

All four binaries import from a single internal/ package tree:

router → middleware → handler → service → repository → model/DB
                        ↘ templates (Templ)
                        ↘ dto

The key is sub-packaging by application: handler/site/, handler/shops/, and handler/admin/, with the same split for services, repositories, DTOs, and templates. Each binary imports only the packages it needs. The worker, for example, does not import HTTP handlers or templates.

Go's internal directory also prevents code outside the parent module tree from importing these packages. It does not enforce our layer order, though; that remains an architectural convention backed by review and tests.

Why Not Microservices?

Early on, we considered splitting into separate repos. Three things stopped us:

Shared models. Products, shops, and users are the same entities everywhere. Duplicating model definitions across repos means sync hell.

Atomic refactors. When we change a database column, the handler, service, repository, DTO, and template all update in one commit.

Deployment simplicity. Four builds with CGO_ENABLED=0 produce self-contained binaries that can be managed as independent service units. We do not need container orchestration, a service mesh, or versioned APIs between these cooperating applications.

This is still a modular monolith: the binaries share code and data contracts. Separate executables alone do not make them microservices.

The Gotcha: Air and Hot Reload

In development, each service runs in Docker with Air for hot reload. Without scoped watch rules, an edit to shared code can rebuild every service.

We solved this with scoped watch configs. The worker Air config ignores templates/, handler/, and router/. The admin config ignores handler/site/ and handler/shops/. Each service only rebuilds when files relevant to it change.

# Worker: exclude HTTP and UI layers
[build]
  exclude_dir = [
    "internal/templates",
    "internal/handler",
    "internal/router",
    "assets",
    "storage",
  ]

Bottom Line

A Go monorepo with one cmd/ entry point per service gives us process-level separation while keeping atomic refactors and one go.mod. It is a good fit while the applications share a schema and are maintained by one team. If independent ownership or deployment becomes the real constraint, the boundary can change later.

Next up: how one of those binaries serves multiple country sites on different subdomains with a single process.

This article is based on lessons from building Towami, a multi-country marketplace and white-label storefront platform. Follow for more practical notes on Go, HTMX, infrastructure, and SaaS.

DEV Community: Antonio Towami

Background Jobs in Go with Asynq: Emails, Notifications, and Resilience

Why Separate the Worker

Task Architecture

What Lives in the Worker

The Dev Gotcha

Retry Policy

Why Not Just goroutines?

Our Layered REST Architecture in Go: Why GET Must Not Mutate Application State

The 0-RTT Replay Problem

Our Layered Approach

Practical Enforcement

DTO Separation

What This Architecture Helps Prevent

Serving Tenant Storefronts on Custom Domains with Go + Cloudflare for SaaS

The Shop Host Middleware

Cloudflare for SaaS: The SSL Part

Why www-Only

Status Tracking

What We Learned

Multi-Host Routing in Go: One Binary, Many Domains

The Middleware Approach

URL Structure: Language in Path, Country in Host

The Cookie Problem

Legacy URL Migration

The Result

How We Run 4 Services From One Go Monorepo

The Four Binaries

Shared internal/ With Clean Boundaries

Why Not Microservices?

The Gotcha: Air and Hot Reload

Bottom Line

Shared `internal/` With Clean Boundaries