Go Relay

Go Relay is a distributed, type-safe background job processing library for Go.

It acts as a bridge between your application logic and your distributed infrastructure (Warp Mesh, Redis, etc.), providing a clean, generic-based API for handling async tasks.

Key Features

• Type-Safe: No more any casting. Payload types are checked at compile time.
  
• Backend Agnostic: Switch from In-Memory to Redis or P2P Mesh without changing your code.
  
• Zero-Config: Starts with a sensible In-Memory default for immediate productivity.
  

Documentation

• Getting Started: Your first Job in 30 seconds.
  
• Architecture: How Relay works under the hood.
  
• Transports: Configure Memory, Redis, or Warp Mesh backends.
  

Quick Example

type Notification struct {
    ReqID string
}

// Register
relay.Register(r, "notify", func(ctx context.Context, n Notification) error {
    return sendPush(n.ReqID)
})

// Enqueue
relay.Enqueue(ctx, r, "notify", Notification{ReqID: "123"})

Brokers

Memory (default)

No dependencies. Suitable for single-process workloads. Supports manager-level retries with exponential backoff.

r := manager.New(manager.WithMaxRetries(3))

Redis Streams

Distributed, durable competing consumers via Redis Streams. Failed messages beyond MaxRetries are moved to a {topic}.dead stream. Stale messages from dead workers are automatically reclaimed on startup.

import (
    "github.com/mirkobrombin/go-relay/v2/pkg/broker"
    "github.com/redis/go-redis/v9"
)

rdb := redis.NewClient(&redis.Options{Addr: "localhost:6379"})
r := manager.New(
    manager.WithBroker(broker.NewRedisBroker(rdb,
        broker.WithGroup("my-workers"),
        broker.WithRedisMaxRetries(5),
        broker.WithClaimTimeout(60*time.Second),
    )),
)

NATS JetStream

Distributed competing consumers via NATS JetStream. Streams are created automatically. NATS handles redelivery and dead-letter advisories natively.

import (
    "github.com/mirkobrombin/go-relay/v2/pkg/broker"
    "github.com/nats-io/nats.go"
    "github.com/nats-io/nats.go/jetstream"
)

nc, _ := nats.Connect(nats.DefaultURL)
js, _ := jetstream.New(nc)
r := manager.New(
    manager.WithBroker(broker.NewNATSBroker(js,
        broker.WithNATSGroup("my-workers"),
        broker.WithMaxDeliver(5),
        broker.WithAckWait(45*time.Second),
    )),
)

License

MIT License.