Skip to content

Redis Transporter

The Redis transport carries messages over Redis pub/sub: one channel per pattern, namespaced by a prefix, with literal patterns SUBSCRIBEd and wildcard patterns PSUBSCRIBEd so the broker does the filtering. The single most important thing to know is that Redis pub/sub stores nothing, so a consumer that is not connected at the instant of publication never receives the message.

See Microservices Overview for patterns, handlers and the envelope.

Delivery guarantees

Redis pub/sub is at-most-once and has no persistence. A message is delivered to the subscribers connected at the moment it is published, and then forgotten. A consumer that is restarting, deploying, GC-paused past its client buffer or briefly disconnected does not get the message later — it never gets it.

A successful Publish does not mean anyone received the message

PUBLISH returns the number of subscribers that received the message, and zero is a success at the protocol level. Nothing about a nil error from Emit implies delivery. There is no acknowledgement, no retry and no queue.

That makes this transport a good fit for cache invalidation, presence, live dashboards and any traffic where the next message supersedes the last. It is a poor fit for anything a business depends on. When delivery has to survive a consumer restart, use a log with consumer groups — Redis Streams (XADD/XREADGROUP) or a broker-backed transport such as RabbitMQ or Kafka, where unacknowledged messages are still there afterwards.

Request/reply works, and it works over the same pub/sub primitives: the reply travels on a private inbox channel whose name carries a random 128-bit id, so another client cannot subscribe to it by guessing. If the responder is down, Send returns microservice.ErrTimeout.

Minimal working setup

A server:

package main

import (
    "github.com/gin-gonic/gin"

    "github.com/nika-framework/nika"
    "github.com/nika-framework/nika/common/microservice"
    "github.com/nika-framework/nika/common/microservice/transport/redismq"

    "myapp/src"
)

func main() {
    app := nika.NewApp()

    microservice.Setup(app, microservice.Config{
        Transport: redismq.MustNew(redismq.Options{
            URL: "redis://localhost:6379",
        }),
        Middleware: []gin.HandlerFunc{nika.RecoveryMiddleware()},
    })

    app.LoadModule(src.NewAppModule())
    app.Listen(":3001")
}

Handlers declare transport:"redis":

type UserController struct {
    Create  func(*gin.Context) `transport:"redis" pattern:"user_created"`
    FindOne func(*gin.Context) `transport:"redis" pattern:"user_*"`
}

A client, handling the construction error rather than panicking:

transport, err := redismq.New(redismq.Options{
    URL:         "redis://localhost:6379",
    Prefix:      "orders",
    HealthCheck: true, // PING on construction; fail fast if Redis is unreachable
})
if err != nil {
    return fmt.Errorf("redis transport: %w", err)
}

client, err := microservice.SetupClient(app, transport)
if err != nil {
    return err
}

MustNew is the one-liner for wiring code where a bad option is a programming error; New is for anywhere you want to return the error.

Options

Field Default Purpose
URL — Redis connection string (redis://:pass@host:6379/0, rediss://… for TLS). Required unless Client is set.
Client nil Reuse an existing *redis.Client. Close does not close a client it did not create.
Prefix "nika" (DefaultPrefix) Namespaces every channel as prefix + ":" + pattern.
Concurrency 64 Caps messages dispatched at once by this transport.
ReplyTimeout microservice.DefaultRequestTimeout (10s) Request/reply deadline when the caller passes none.
PingTimeout 2s Bounds the health check.
HealthCheck false Make New verify connectivity with a PING and fail if the server is unreachable.
Logger slog.Default() Receives decode failures and subscription errors.

Setting both URL and Client is an error, as is a negative Concurrency.

HealthCheck is off by default because a transport is normally constructed while wiring the application, when Redis may legitimately not be up yet. Turn it on when you would rather the process refuse to start. Ping(ctx) is exported so you can check on your own schedule — it is what belongs in a readiness probe.

The prefix is your only isolation

Redis pub/sub has no vhosts, and PUBLISH is not affected by SELECT — the selected database does not scope it. Prefix is therefore the only thing keeping two unrelated services on one Redis instance from receiving each other's traffic. Give each logical system its own prefix, and do not assume redis://…/15 isolates anything.

The prefix is treated as a literal namespace: every glob metacharacter in it is escaped before subscribing, so a stray * in a prefix cannot silently turn a subscription into a firehose over every other service on the instance.

Patterns are escaped before they reach Redis

Nika patterns and Redis globs overlap but are not the same language. Both use * for "any run of characters" and ? for "exactly one character" — which is why PSUBSCRIBE can do the filtering at all. But Redis additionally treats […] as a character class and \ as an escape, while a Nika pattern treats all three as ordinary characters.

Handing an untranslated pattern to PSUBSCRIBE would silently change its meaning: item[1] would stop matching the literal subject item[1] and start matching item1. So [, ] and \ are escaped on the way to the broker and */? pass through, which makes a pattern mean exactly the same thing at the broker as it does in microservice.Pattern.Match.

reply: is a reserved namespace — it is where request/reply inboxes live — so a handler pattern may not start with it. That is what stops a handler subscription from straddling another client's reply inbox.

Overlapping subscriptions are collapsed for you

Redis delivers a message once per matching subscription. A service registering both user_created and user_* would get the literal message twice: once as a message from SUBSCRIBE and once as a pmessage from PSUBSCRIBE. Two overlapping globs produce two pmessages.

The transport assigns each channel exactly one owning subscription and accepts only that delivery, so a handler runs once. The exact channel wins when there is one, mirroring the Router's "exact beats wildcard" rule; otherwise the first matching glob wins, and because patterns arrive in specificity order that is the same glob whose handler the Router would pick. You do not have to make your handlers idempotent to compensate for a doubled delivery — but on an at-most-once transport they should be idempotent anyway, because a retrying publisher is your only recovery mechanism.

A saturated consumer loses messages

Concurrency bounds how many messages this transport dispatches at once. Reaching the cap pauses reads from the subscription channel, which go-redis buffers — and if that buffer stays full for a minute, go-redis drops messages. A permanently saturated consumer loses traffic rather than queueing it.

This is the same failure as everywhere else on this transport: there is no backpressure toward the publisher, so the only outcomes are "keep up" and "lose messages". Size Concurrency for your throughput, watch for the drop, and if you find yourself tuning around it you have outgrown pub/sub.

An undecodable payload is logged and skipped rather than fatal, so one publisher writing garbage — a different service on the same prefix, a stray redis-cli PUBLISH — cannot tear down a subscription serving everyone else.

Testing

Handlers do not need Redis. nikatest.NewMicroservice(t) runs the whole message stack over the in-memory transport:

ms := nikatest.NewMicroservice(t)
ms.LoadModule(src.NewAppModule())

ms.Send("user_created", CreateUserDto{Name: "Ada"}).
    ExpectStatus(201).
    ExpectJSONPath("data.name", "Ada")

See Testing.

The transport's own integration suite needs a real server and is excluded from a default go test ./... by a build tag:

REDISMQ_TEST_URL=redis://localhost:6379/15 \
  go test -tags redis_integration -race ./common/microservice/transport/redismq/

Use a throwaway database. The tests publish on a random prefix so they do not collide with each other, but pub/sub is instance-wide and a noisy instance makes them flaky.

When to use it, and when not to

Use Redis when you already run Redis, the traffic is events rather than commands, and a missed message is acceptable because the next one supersedes it: cache invalidation, presence, live dashboards, config reload fan-out. Broadcast is the natural shape — every subscriber gets every matching message, so scaling out multiplies the work rather than dividing it.

Do not use it when a message must survive a consumer restart, when work needs to be load-balanced across replicas, or when a lost message would need to be reconciled by hand. RabbitMQ gives you at-least-once delivery with a durable queue and per-replica work sharing; Kafka gives you a replayable log; NATS gives you the same at-most-once model as Redis but with native request/reply, queue groups for load balancing, and JetStream when you need durability.