DEV Community: Sohaib Alqasem

RabbitMQ Topic Routing: Event Names vs Routing Keys

Sohaib Alqasem — Fri, 26 Jun 2026 20:49:24 +0000

RabbitMQ topic routing is powerful, but it is also one of the easiest parts to misunderstand.

The confusion usually starts with this question:

Is order.* the routing key I publish with, or the pattern my queue binds with?

In most topic-exchange designs, values like order.* and # are binding patterns.

The message itself is usually published with a concrete routing key like:

order.created

That difference matters.

If you mix up event names, publish routing keys, and binding patterns, messages can route in surprising ways.

This post explains the difference and shows how Rabbit Relay handles it while still keeping RabbitMQ concepts explicit.

The basic RabbitMQ routing model

A simple RabbitMQ flow looks like this:

producer -> exchange -> binding -> queue -> consumer

The producer does not publish directly to a queue.

It publishes a message to an exchange.

The exchange then decides which queues should receive the message based on bindings.

For a topic exchange, the important pieces are:

publish routing key
binding routing pattern
queue

Example:

message routing key: order.created
binding pattern:     order.*
queue:               orders.q

The message matches the binding pattern, so RabbitMQ routes the message to the queue.

Concrete routing keys

A concrete routing key describes the message being published.

Examples:

order.created
order.cancelled
payment.processed
invoice.generated
user.registered

These are usually event-like names.

They describe what happened.

For example:

const orderCreated = event("order.created", "v1").of<{
  orderId: string;
  amount: number;
}>();

When this event is published, a natural routing key is:

order.created

That is concrete.

It does not contain wildcards.

Topic binding patterns

Topic exchanges support wildcard patterns when queues bind to exchanges.

The two special wildcards are:

* = exactly one word
# = zero or more words

So these bindings behave differently:

order.*       matches order.created and order.cancelled
order.#       matches order.created, order.payment.failed, and order
#.created     matches order.created and invoice.created
#             matches everything

These are useful when a queue wants to receive a group of related events.

Example:

queue: orders.q
binding pattern: order.*

That queue receives:

order.created
order.cancelled

But not:

payment.processed
order.payment.failed

because order.payment.failed has more words than order.* allows.

The common mistake

The mistake is treating the binding pattern as the publish routing key.

For example:

binding pattern: order.*
publish key:     order.*

That is usually not what you want.

If you publish a message with routing key order.*, RabbitMQ treats order.* as the actual routing key string for that message.

It does not mean “publish this message to all order events.”

The wildcard behavior belongs to the binding pattern.

So this is usually better:

binding pattern: order.*
publish key:     order.created

Now the exchange can compare:

order.created matches order.*

and route the message correctly.

Event name vs routing key

In many event-driven systems, the event name and routing key are the same.

Example:

event name:   order.created
routing key:  order.created

That is simple and predictable.

But they do not have to be the same.

You may choose a different publish routing key for infrastructure reasons:

event name:   order.created
routing key:  internal.orders.created

That can be valid.

The important thing is to keep the difference clear:

event name = what happened
routing key = how RabbitMQ routes the message
binding pattern = what a queue wants to receive

How this looks in Rabbit Relay

Rabbit Relay keeps the RabbitMQ model visible.

A publisher may look like this:

import { RabbitMQBroker, event } from "@bitspacerlabs/rabbit-relay";

type OrderCreated = {
  orderId: string;
  amount: number;
};

const orderCreated = event("order.created", "v1").of<OrderCreated>();

const broker = new RabbitMQBroker("orders.publisher");

const pub = await broker
  .queue("orders.publisher.q")
  .exchange("orders.ex", {
    exchangeType: "topic",
    publisherConfirms: true,
  });

await pub.produce(
  orderCreated({
    orderId: "o-1",
    amount: 42,
  })
);

await broker.close();

By default, Rabbit Relay publishes using the event name as the routing key:

order.created

That works naturally with topic bindings like:

order.*

Binding a consumer with a pattern

A consumer can bind to a topic pattern:

import { RabbitMQBroker, type EventEnvelope } from "@bitspacerlabs/rabbit-relay";

type OrderCreated = {
  orderId: string;
  amount: number;
};

const broker = new RabbitMQBroker("orders.consumer");

const sub = await broker
  .queue("orders.q")
  .exchange<{
    "order.created": EventEnvelope<OrderCreated>;
  }>("orders.ex", {
    exchangeType: "topic",
    routingKey: "order.*",
  });

sub.handle("order.created", async (_id, ev) => {
  console.log(ev.data.orderId);
});

await sub.consume({
  prefetch: 10,
  concurrency: 5,
});

Here:

orders.ex = exchange
orders.q = queue
order.* = binding pattern
order.created = event name and publish routing key

The queue subscribes to a pattern.

The message is still published with a concrete event-like key.

What about `#`?

A binding pattern of # means:

match everything

This is common for logging, debugging, audit, or demo consumers.

Example:

binding pattern: #
publish key:     demo.tick

The queue receives demo.tick because # matches everything.

But you usually do not want to publish messages with # as the routing key.

The message should still have a real routing key like:

demo.tick

Explicit routing key overrides

Sometimes you really do want to publish with a custom routing key.

Rabbit Relay allows that explicitly:

await pub.publish(eventEnvelope, {
  routingKey: "internal.orders.created",
});

This is useful when the event name and the infrastructure routing key are intentionally different.

The important word is intentionally.

The override should be obvious in code.

Why Rabbit Relay treats wildcards carefully

In Rabbit Relay 1.0.0, routing-key behavior is designed around this distinction:

concrete configured routingKey values can be used when publishing
topic wildcard patterns like # and order.* are treated as binding patterns
explicit publish options still override the routing key

That means this binding stays safe:

.exchange("orders.ex", {
  exchangeType: "topic",
  routingKey: "order.*",
});

Rabbit Relay does not publish messages with order.* just because the binding pattern is order.*.

It continues publishing event messages with concrete event names like:

order.created

This avoids turning binding patterns into publish routing keys by accident.

A simple rule of thumb

Use this mental model:

event name:
  what happened

publish routing key:
  how this message enters RabbitMQ routing

binding pattern:
  what this queue wants to receive

In many apps:

event name = publish routing key

Example:

order.created

And queues bind with patterns:

order.*

That is a simple and maintainable default.

Final thought

RabbitMQ topic routing is not complicated once the roles are clear.

The main thing is to avoid mixing up these three ideas:

event name
publish routing key
binding pattern

A concrete event like:

order.created

is a good publish routing key.

A pattern like:

order.*

is usually a good binding pattern.

Keeping that distinction clear makes RabbitMQ systems easier to reason about, easier to debug, and safer to operate.

That is also the philosophy behind Rabbit Relay:

Keep RabbitMQ explicit, but make it safer and cleaner to use in TypeScript services.

Install

npm i @bitspacerlabs/rabbit-relay

GitHub:

https://github.com/bitspacerlabs/rabbit-relay

Docs:

https://bitspacerlabs.github.io/rabbit-relay/

Launch post:

https://bitspacerlabs.github.io/rabbit-relay/docs/blog/rabbit-relay-1-0

Rabbit Relay v1.0.0: Type-safe RabbitMQ for Node.js without hiding RabbitMQ

Sohaib Alqasem — Thu, 25 Jun 2026 06:12:47 +0000

I just released Rabbit Relay 1.0.0, the first stable release of a TypeScript-first RabbitMQ framework for Node.js.

Rabbit Relay is built on top of amqplib.

The main idea is simple:

Keep RabbitMQ explicit, but make it safer and cleaner to use in TypeScript services.

It keeps real RabbitMQ concepts visible:

exchanges
queues
bindings
routing keys
acknowledgements
retries
dead-letter queues
publisher confirms
topology ownership

It is not trying to turn RabbitMQ into magic function calls.

It is trying to make RabbitMQ easier to use correctly.

Why I built it

amqplib is powerful, but it is low-level.

In real services, teams often repeat the same boilerplate again and again:

create connection
create channel
assert exchanges
assert queues
bind queues
serialize messages
publish messages
consume messages
ACK/NACK messages
handle retries
configure DLQs
add correlation IDs
add health checks
decide who owns topology

That logic can become inconsistent across services.

One service handles retries one way.

Another forgets publisher confirms.

Another requeues forever.

Another uses routing keys differently.

Rabbit Relay is my attempt to make this layer consistent without hiding the RabbitMQ model.

A typed event

import { RabbitMQBroker, event } from "@bitspacerlabs/rabbit-relay";

type OrderCreated = {
  orderId: string;
  amount: number;
};

const orderCreated = event("order.created", "v1").of<OrderCreated>();

const broker = new RabbitMQBroker("orders.publisher");

const pub = await broker
  .queue("orders.publisher.q")
  .exchange("orders.ex", {
    exchangeType: "topic",
    publisherConfirms: true,
  });

await pub.produce(
  orderCreated({
    orderId: "o-1",
    amount: 42,
  })
);

await broker.close();

The RabbitMQ concepts are still visible:

orders.ex = exchange
orders.publisher.q = queue
topic = exchange type
publisherConfirms = wait for RabbitMQ broker acknowledgement

Rabbit Relay just gives this a cleaner TypeScript API.

Typed event contracts

Messaging systems often fail when message contracts become tribal knowledge.

Someone knows order.created has an orderId.

Someone else knows payment.processed has a transactionId.

But unless those contracts are visible in code, they are easy to break.

Rabbit Relay event factories make the event name, version, and payload type explicit:

const paymentProcessed = event("payment.processed", "v1").of<{
  orderId: string;
  transactionId: string;
  status: "paid";
}>();

Then publishing is type-checked:

await pub.produce(
  paymentProcessed({
    orderId: "o-1",
    transactionId: "txn-123",
    status: "paid",
  })
);

This does not replace schema validation or contract testing.

But it makes the common TypeScript workflow much safer.

A typed publish API

Rabbit Relay can also build a small typed publish API from event factories:

const send = event("send", "v1").of<{ message: string }>();

const api = pub.with({ send });

await api.send({
  message: "hello world",
});

The generated methods create the event and publish it.

So they are async publish methods and should be awaited.

Routing keys stay explicit

RabbitMQ topic routing is powerful, but easy to confuse.

In topic exchanges, values like order.* or # are usually binding patterns.

They are useful when binding a queue.

But they are usually not what you want to publish as the message routing key.

Rabbit Relay keeps this behavior explicit.

By default, Rabbit Relay publishes with the event name as the routing key:

const makeOrderCreated = event("order.created", "v1").of<OrderCreated>();

await pub.produce(
  makeOrderCreated({
    orderId: "o-1",
    amount: 42,
  })
); // routing key: "order.created"

If a concrete routing key is configured, Rabbit Relay can use it when publishing.

But if the configured routing key is a topic wildcard pattern like # or order.*, Rabbit Relay treats it as a binding pattern and continues publishing with the event name.

You can still override the publish routing key explicitly:

await pub.publish(eventEnvelope, {
  routingKey: "custom.key",
});

Consuming events

import { RabbitMQBroker, type EventEnvelope } from "@bitspacerlabs/rabbit-relay";

type OrderCreated = {
  orderId: string;
  amount: number;
};

const broker = new RabbitMQBroker("orders.consumer");

const sub = await broker
  .queue("orders.q")
  .exchange<{
    "order.created": EventEnvelope<OrderCreated>;
  }>("orders.ex", {
    exchangeType: "topic",
    routingKey: "order.*",
  });

sub.handle("order.created", async (_id, ev) => {
  console.log(ev.data.orderId);
});

await sub.consume({
  prefetch: 10,
  concurrency: 5,
});

The mental model stays the same:

producer -> exchange -> binding -> queue -> consumer

Production failure handling

The happy path is not enough.

Consumers fail.

Downstream services go down.

Databases timeout.

Messages can be delivered more than once.

Poison messages can block processing if failure handling is not designed carefully.

Rabbit Relay supports:

ACK on success
NACK and requeue
NACK and dead-letter
bounded retry
delayed retry
DLQ redrive

Example:

await sub.consume({
  prefetch: 10,
  concurrency: 5,
  onError: "retry",
  retry: {
    attempts: 3,
    delayMs: 5000,
    then: "dead-letter",
  },
});

This avoids two dangerous patterns:

Losing failed messages silently.
Requeueing forever and creating an infinite failure loop.

Operations features

Rabbit Relay 1.0.0 also includes:

lifecycle hooks
health checks
OpenTelemetry adapter
topology planning
topology validation
DLQ redrive

For example:

const plan = broker.planTopology();

console.log(plan);

Topology validation can passively check existing RabbitMQ infrastructure without modifying it.

That is useful when infrastructure owns the RabbitMQ topology and applications should only validate that required exchanges and queues exist.

Why not hide RabbitMQ?

Some libraries try to make messaging look like normal function calls.

That can be nice at first, but it often hides important operational details.

RabbitMQ concepts matter:

exchange type matters
routing key matters
queue durability matters
prefetch matters
ACK/NACK behavior matters
DLQs matter
publisher confirms matter
topology ownership matters

Rabbit Relay is designed around the idea that developers should understand these concepts, not avoid them.

The library should reduce boilerplate, not remove the mental model.

Install

npm i @bitspacerlabs/rabbit-relay

GitHub: github.com/bitspacerlabs/rabbit-relay

Docs: bitspacerlabs.github.io/rabbit-relay

npm: @bitspacerlabs/rabbit-relay

Final thought

RabbitMQ is already powerful.

Rabbit Relay is not trying to replace it.

It is trying to make RabbitMQ easier to use correctly in Node.js and TypeScript services, while keeping the real messaging concepts visible.

That is the core idea:

Type-safe RabbitMQ for Node.js, without hiding RabbitMQ.

DEV Community: Sohaib Alqasem

RabbitMQ Topic Routing: Event Names vs Routing Keys

The basic RabbitMQ routing model

Concrete routing keys

Topic binding patterns

The common mistake

Event name vs routing key

How this looks in Rabbit Relay

Binding a consumer with a pattern

What about #?

Explicit routing key overrides

Why Rabbit Relay treats wildcards carefully

A simple rule of thumb

Final thought

Install

Rabbit Relay v1.0.0: Type-safe RabbitMQ for Node.js without hiding RabbitMQ

Why I built it

A typed event

Typed event contracts

A typed publish API

Routing keys stay explicit

Consuming events

Production failure handling

Operations features

Why not hide RabbitMQ?

Install

Final thought

What about `#`?