DEV Community: Ken C. Demanawa

Redis Isn't PostgreSQL: Building a Hybrid Change Data Capture Runtime in Ruby

Ken C. Demanawa — Sat, 27 Jun 2026 02:26:37 +0000

I Built Commercial Redis CDC Source Drivers for Ruby — Here's What I Learned

For the past couple of years I've been building a Change Data Capture (CDC) ecosystem for Ruby.

Like many CDC projects, it started with PostgreSQL. PostgreSQL's Write-Ahead Log (WAL) is an excellent source of truth: durable, ordered, replayable, and well understood. It provides exactly the properties you want when you're building reliable event pipelines.

But the deeper I went into distributed systems, the more I realized something important.

Many systems don't observe change from PostgreSQL first.

They observe it from Redis.

Redis often sits at the front of modern architectures:

Redis Streams carry application events.
Pub/Sub distributes transient state changes.
Keyspace notifications react to cache invalidation and key expiry.
Redis Cluster routes events across multiple primaries.

In many systems, Redis sees a change before PostgreSQL ever commits it.

That raised an interesting question:

Can Redis become a first-class Change Data Capture source?

The obvious answer is "yes."

The interesting answer is "yes—but not in the same way PostgreSQL does."

That distinction eventually became cdc-redis-pro, a commercial Redis source driver for the Ruby CDC ecosystem.

This article isn't a product announcement.

It's an engineering write-up about the architectural decisions behind the project, the tradeoffs Redis forces you to make, and the execution model that ultimately emerged.

Redis Doesn't Have One CDC Interface

One misconception I frequently encounter is the assumption that Redis has an equivalent of PostgreSQL's WAL.

It doesn't.

Instead, Redis exposes several completely different mechanisms for observing change.

Source	Delivery	Replay
Streams	At-least-once	Yes
Pub/Sub	At-most-once	No
Sharded Pub/Sub	At-most-once	No
Keyspace Notifications	At-most-once	No

At first glance they all look like "events."

Operationally they're completely different systems.

Streams are durable.

Pub/Sub isn't.

Keyspace notifications exist primarily as operational signals.

Sharded Pub/Sub introduces routing constraints that don't exist elsewhere.

Treating them all as the same abstraction inevitably hides important guarantees—and hidden guarantees eventually become production incidents.

Instead of pretending every Redis source behaves identically, I wanted the API to expose those differences explicitly.

If a source cannot replay missed messages, the API should say so.

If a reconnect creates a loss window, operators should know exactly when it happened.

Infrastructure software shouldn't hide reality.

It should make reality easier to reason about.

Redis and PostgreSQL Solve Different Problems

A common question is:

"If Redis can generate change events, why not replace PostgreSQL CDC entirely?"

Because they solve different problems.

PostgreSQL's WAL is the durable history of your system.

Redis is often the earliest signal that something is happening.

One tells you what committed.

The other tells you what is happening right now.

They're complementary.

Not competing.

Conceptually, I think about them like this:

                    PostgreSQL WAL
                          │
                          ▼
                 Durable Record of Truth

Redis Streams / PubSub / Keyspace
              │
              ▼
        Fast Operational Signal

The goal isn't choosing one over the other.

The goal is allowing both to participate in the same downstream processing pipeline.

That required another architectural boundary.

A Common Language for Change Events

One of the design goals of the broader CDC ecosystem is that downstream processors shouldn't care where an event originated.

Whether a change comes from PostgreSQL logical replication or Redis Streams, the downstream processing model should remain identical.

That boundary is CDC::Core::ChangeEvent.

Instead of exposing PostgreSQL-specific or Redis-specific payloads to processors, each source is normalized into a common event model.

Conceptually the pipeline looks like this:

                PostgreSQL WAL
                     │                     
                pgoutput-client
                     │
                     ▼
                 ChangeEvent
                       ▲
                       │
                 cdc-redis-pro
                       │
        Streams / PubSub / Keyspace

Everything downstream consumes the same normalized event.

A webhook processor doesn't need to know whether the event came from WAL or Redis.

A search indexing pipeline doesn't care.

An audit sink doesn't care.

Even the execution runtime doesn't care.

That separation between source acquisition and event processing became one of the defining architectural decisions of the ecosystem.

As the project grew, it became clear that acquiring events efficiently and processing them efficiently are two different problems—and they scale independently.

That realization eventually led to a separate execution engine: cdc-orchestrator-pro.

We'll come back to that shortly.

First, let's look at what makes each Redis source fundamentally different.

Redis Isn't One Event System. It's Four.

The first surprise when building a Redis CDC source is that there isn't a single Redis change stream.

There are four.

Each has different delivery guarantees.

Each behaves differently during failures.

Each recovers differently after reconnects.

And each answers a different operational question.

Treating them as interchangeable would have made the implementation simpler—but it also would have hidden the exact information operators need during production incidents.

Instead, cdc-redis-pro embraces those differences.

Redis Streams: The Durable Path

Redis Streams is the closest thing Redis has to a traditional CDC source.

Messages are persisted.

Consumers maintain checkpoints.

Consumer groups coordinate work.

Failed consumers leave pending entries behind for recovery.

In many ways, Streams feels familiar to anyone coming from Kafka or PostgreSQL logical replication.

That made it the natural foundation for the recoverable side of the driver.

The Streams implementation supports:

XREAD
XREADGROUP
Consumer Groups
Pending-entry inspection
XAUTOCLAIM
Duplicate suppression
Optional dead-letter streams

Operationally, Streams is the only Redis source that provides genuine replay.

If a downstream worker crashes halfway through a batch, processing resumes from the last committed checkpoint rather than silently dropping work.

Conceptually, it looks like this:


             Producer
                │
                ▼
          Redis Stream
                │
          Consumer Group
                │
                ▼
          cdc-redis-pro
                │
           ChangeEvent
                │
                ▼
         Downstream Runtime

This is the strongest consistency story Redis offers.

It isn't PostgreSQL's WAL—but it isn't trying to be.

It's a durable event log designed for application-level workflows.

Pub/Sub: Fast, But Ephemeral

Pub/Sub solves a completely different problem.

Messages exist only while subscribers are connected.

Disconnect for five seconds.

Those five seconds are gone forever.

That isn't a bug.

It's the contract.

Many libraries attempt to hide this by automatically reconnecting.

The problem is that reconnecting doesn't recover missed messages.

It only resumes receiving future ones.

Pretending otherwise creates false confidence.

Instead, cdc-redis-pro treats Pub/Sub as an explicitly at-most-once source.

Reconnects are measured.

Loss windows are reported.

Operators can immediately see:

when the disconnect occurred,
how long the subscriber was offline,
and exactly where message loss became possible.

That distinction matters.

Infrastructure software shouldn't promise guarantees the underlying system doesn't provide.

Sharded Pub/Sub Changes the Topology

Redis Cluster introduces another variation.

Sharded Pub/Sub distributes channels across multiple primaries.

That improves scalability, but it also means subscriptions become topology-aware.

A reconnect isn't always reconnecting to the same node.

During resharding, ownership of a channel may move entirely.

Handling that correctly requires continuously tracking cluster topology rather than assuming a fixed server layout.

The driver automatically discovers topology through CLUSTER SHARDS and transparently rebinds subscriptions as ownership changes.

To downstream processors, events continue arriving normally.

To operators, topology changes remain observable.

Keyspace Notifications Aren't Really CDC

Keyspace notifications are probably the easiest Redis feature to misunderstand.

They're incredibly useful.

They're also incredibly easy to misuse.

Keyspace notifications exist to announce that Redis itself performed an operation:

a key expired,
a value changed,
a key was deleted,
a hash was updated.

They're operational signals.

They're not durable history.

They're not replayable.

And by the time you receive an expiration notification, the value may already be gone.

That's simply how Redis works.

Rather than pretending every notification contains complete information, the driver offers optional best-effort value enrichment whenever the value still exists.

If it doesn't, the event still proceeds.

The guarantee remains explicit.

Delivery Guarantees Should Stay Visible

One design principle shaped almost every API in the project.

I didn't want to normalize away delivery semantics.

Instead, I wanted them to remain visible all the way to the operator.

Think of it like a database transaction.

You wouldn't want a library to silently convert an eventually-consistent operation into something that merely looks transactional.

The same idea applies here.

Different Redis sources have different operational characteristics.

The API should preserve them.

That philosophy can be summarized like this:

Source	Replay	Delivery	Typical Use
Streams	✓	At-least-once	Durable workflows
Pub/Sub	✗	At-most-once	Live events
Sharded Pub/Sub	✗	At-most-once	Cluster-scale broadcasts
Keyspace Notifications	✗	At-most-once	Operational signals

None of these are "better."

They're simply optimized for different workloads.

Topology Matters More Than Features

Supporting Redis isn't just about supporting commands.

It's about supporting deployments.

A surprising amount of complexity came not from Streams or Pub/Sub themselves, but from the environments they run in.

The driver currently supports:

Standalone Redis
Redis Sentinel
Redis Cluster
TLS
ACL authentication

Cluster support turned out to be particularly interesting.

Streams must remain within a single hash slot.

Cross-slot reads fail.

Pub/Sub subscriptions migrate during resharding.

Connections disappear during primary failover.

Those aren't edge cases.

They're normal operating conditions in production.

Every supported topology is continuously exercised using Docker-based integration tests covering failover, node restarts, resharding, authentication, and TLS.

I wanted the implementation to reflect how Redis is actually deployed—not just how it behaves on a laptop.

Acquiring Events Is Only Half the Problem

By this point, the source layer was capable of reliably acquiring events from every major Redis deployment model.

The next question became much harder.

How do you process them efficiently?

One worker?

Ten workers?

Hundreds?

How do you preserve ordering where it's required while still exploiting modern Ruby's parallelism?

It turned out that reading events from Redis wasn't the difficult part.

Scheduling what happened after they were read became the real engineering challenge.

That challenge eventually became HybridRuntime, the execution engine inside cdc-orchestrator-pro.

And surprisingly, the solution wasn't built around threads.

It was built around ownership.

The Architecture I'm Most Proud Of

Surprisingly, reading events from Redis wasn't the hardest part of the project.

Scheduling what happened after those events arrived was.

Modern Ruby gives us two powerful concurrency primitives:

Ractors for parallel CPU execution
Fibers for concurrent I/O

Most systems choose one.

I wanted both.

That eventually became HybridRuntime, the execution engine inside cdc-orchestrator-pro.

Its job isn't tied to Redis.

Redis simply happened to be the workload that exposed the problem first.

Event Acquisition and Event Processing Are Different Problems

One architectural realization changed the direction of the project.

Reading events from a source and processing those events are two completely different concerns.

They're limited by different bottlenecks.

They scale independently.

A PostgreSQL logical replication connection is fundamentally serial.

A Redis Stream consumer is similarly constrained.

But once an event has been acquired and normalized into a CDC::Core::ChangeEvent, downstream processing becomes embarrassingly parallel.

That naturally separates the pipeline into two halves.

                    Source Layer
                         │
         PostgreSQL WAL / Redis Streams
                         │
                         ▼
                CDC::Core::ChangeEvent
                         │
                         ▼
                  Execution Layer

Once an event reaches the execution layer, its origin no longer matters.

Redis.

PostgreSQL.

A future Kafka adapter.

A future S3 replay.

The runtime simply processes ChangeEvent.

That separation turned out to be one of the most valuable architectural decisions in the ecosystem.

HybridRuntime

HybridRuntime combines two existing execution engines from the CDC ecosystem.

cdc-parallel provides pools of prewarmed Ractors for true CPU parallelism.
cdc-concurrent provides asynchronous Fiber pools for overlapping I/O within each Ractor.

Together they form a nested execution model.

                 HybridRuntime
                        │
        ┌───────────────┴───────────────┐
        ▼                               ▼
  Ractor Pool                    Ractor Pool
        │                               │
        ▼                               ▼
   Fiber Pool                     Fiber Pool
        │                               │
        ▼                               ▼
Redis Connections              Redis Connections

The interesting observation is that parallelism and concurrency solve different problems.

Ractors increase throughput by executing work simultaneously.

Fibers increase throughput by avoiding idle time while waiting for I/O.

The runtime deliberately uses both.

The Inception Pool

As the architecture evolved, I noticed something amusing.

Every layer owned another pool.

The runtime owns a pool of Ractors.

Each Ractor owns a LocalResourcePool.

Each LocalResourcePool owns a pool of Fibers.

Each Fiber owns a live Redis connection.

It looked like this:

HybridRuntime
     │
     ▼
Prewarmed Ractor Pool
     │
     ▼
LocalResourcePool
     │
     ▼
Fiber Pool
     │
     ▼
Redis Connections

Internally I started calling it the Inception Pool.

A pool containing pools containing pools.

The name stuck.

Ownership Instead of Synchronization

Most concurrent systems solve shared state by protecting it.

Threads
  │
  ▼
Mutex
  │
  ▼
Shared Connection Pool

The more workers you add, the more frequently they compete for the same resources.

Locks become unavoidable.

HybridRuntime takes a different approach.

Instead of synchronizing ownership...

...it avoids sharing ownership entirely.

Every Redis client is created inside the Ractor that will use it.

It never leaves that Ractor.

Nothing is borrowed.

Nothing is shared.

Nothing requires a mutex.

Conceptually it looks like this.

Ractor 1
   │
   ├── Redis Connection A
   ├── Redis Connection B
   └── Fiber Scheduler

Ractor 2
   │
   ├── Redis Connection A
   ├── Redis Connection B
   └── Fiber Scheduler

The only thing that crosses a Ractor boundary is an immutable ChangeEvent.

Everything else remains local.

This aligns naturally with Ruby's ownership model.

Mutable state belongs somewhere.

Rather than fighting that constraint, the runtime embraces it.

Why LocalResourcePool Exists

That ownership model eventually led to another component:
CDC::Orchestrator::Pro::LocalResourcePool.

Unlike traditional connection pools, a LocalResourcePool isn't shared across Ractors.

The pool itself is shared as an immutable coordinator.

The live resources are not.

Instead, every Ractor lazily creates and owns its own resource pool the first time it needs one.

             LocalResourcePool
                    │
      ┌─────────────┴─────────────┐
      ▼                           ▼
  Ractor A                   Ractor B
      │                           │
 Resource Pool               Resource Pool
      │                           │
 Redis Connections          Redis Connections

Each Ractor owns its resources for their entire lifetime.

Nothing crosses a Ractor boundary.

Nothing requires synchronization.

The work moves.

The connections don't.

This turns out to be a natural fit for long-lived resources such as:

Redis clients
PostgreSQL connections
HTTP clients
Elasticsearch clients
S3 clients

Every Ractor operates independently using resources it owns locally.

Rather than coordinating access to a shared pool, the runtime coordinates immutable ChangeEvents while leaving the underlying resources exactly where they were created.

The result is a simpler ownership model, reduced contention, and an execution architecture that scales naturally with additional Ractors.

Two Independent Scaling Axes

Another consequence of this architecture is that acquisition and processing no longer have to scale together.

Suppose a Redis deployment only needs three acquisition workers.

That says nothing about how many processing workers you need.

You might run:

Acquisition

3 Ractors
5 Fibers each

↓

Processing

7 Ractors
20 Fibers each

Each side can be tuned independently.

Adding more downstream workers doesn't require opening additional Redis Streams.

Adding more source readers doesn't require changing the execution topology.

The two halves of the pipeline evolve independently.

That separation proved invaluable during benchmarking because it exposed where the real bottlenecks actually lived.

Beyond Redis

One realization surprised me.

HybridRuntime wasn't solving a Redis problem.

It was solving an event-processing problem.

Redis happened to be the first source.

The same execution model works for:

PostgreSQL logical replication
Redis Streams
Webhook delivery
Search indexing
Object storage sinks
Future Kafka adapters
Future message brokers

Anything capable of producing a CDC::Core::ChangeEvent automatically inherits the same execution engine.

That ultimately justified extracting the runtime into its own commercial component: cdc-orchestrator-pro.

Originally it lived inside another project.

Eventually it became obvious that it wasn't a Redis runtime.

It wasn't a Sidekiq runtime.

It wasn't even a PostgreSQL runtime.

It was an execution fabric for normalized change events.

Redis simply happened to be the benchmark that inspired it.

Parallelism Isn't Free

One thing the benchmarks made very clear is that parallelism isn't magic.

Adding more Ractors doesn't produce linear speedups.

It introduces coordination costs.

Partition routing.

Mailbox communication.

Ordering constraints.

Preserving correctness means accepting those costs.

Understanding where those tradeoffs appear became just as interesting as the throughput numbers themselves.

Let's look at what those benchmarks actually measured.

Where This Actually Fits

After spending so much time discussing architecture, it's worth asking a simple question.

Who actually needs this?

The honest answer is:

Not every Rails application.

If Redis is simply a cache sitting beside your database, this project is probably unnecessary.

Likewise, if every important state transition already commits to PostgreSQL before anything else happens, PostgreSQL logical replication alone may be all the CDC infrastructure you need.

cdc-redis-pro exists for a much narrower class of systems.

Systems where Redis is part of the application's event architecture rather than merely its cache.

Redis Streams as an Event Bus

This is probably the most natural fit.

Many distributed systems already use Redis Streams as their internal event bus.

Order Service
    │
    ▼
Redis Stream
    │
    ▼
Consumers

Once Redis becomes the place where work is coordinated, durability suddenly matters.

Consumers crash.

Deployments restart.

Networks partition.

A consumer needs to know where to resume.

Redis Streams already provides those building blocks.

Consumer Groups.

Pending Entries.

Checkpoint IDs.

XAUTOCLAIM.

The job of cdc-redis-pro isn't replacing those mechanisms.

It's integrating them into a larger event-processing pipeline while preserving their semantics.

Fast Signals Before Durable State

Many systems generate transient events before anything reaches PostgreSQL.

Examples include:

inventory availability
market data
IoT telemetry
collaborative editing
multiplayer game state

These events often exist for milliseconds.

Some are never intended to become permanent records.

Waiting for a database commit before reacting introduces unnecessary latency.

Redis already has the signal.

The application simply needs a reliable way to observe it.

That's exactly where Redis becomes a valuable CDC source.

Not because it replaces the database.

Because it observes change sooner.

Redis and PostgreSQL Together

The architecture becomes much more interesting when both sources exist simultaneously.

Imagine an order-processing pipeline.

Customer clicks Buy
       │
       ▼
Redis Stream
       │
 Immediate downstream processing
        │
 PostgreSQL Transaction
        │
        ▼
 Logical Replication

Redis carries the operational signal.

PostgreSQL records the durable history.

Eventually both become the same normalized object.

Redis Streams
        │
        ▼
   ChangeEvent
        ▲
        │
PostgreSQL WAL

Once normalized, downstream processing becomes identical.

That separation allows each technology to do what it does best.

Redis optimizes for responsiveness.

PostgreSQL optimizes for durability.

Neither replaces the other.

Event Processing Shouldn't Care About the Source

One of the design goals of the CDC ecosystem is that processors shouldn't know—or care—where an event originated.

A webhook dispatcher shouldn't behave differently because the event came from Redis instead of PostgreSQL.

Neither should:

search indexing
audit sinks
analytics
cache invalidation
AI pipelines
object storage
future message brokers

Every processor consumes exactly the same event model.

Redis
   │
   ▼
 ChangeEvent
       ▲
       │
 PostgreSQL
      │
      ▼
 Processor
        │
 ┌──────┼────────┬────────┬────────┐
 ▼      ▼        ▼        ▼        ▼

Webhook Search  Audit   Redis   Future...

That separation is what allows the runtime to remain completely source-agnostic.

Ordered Workloads

Not every workload benefits equally from parallelism.

Suppose an application updates customer balances.

+100
-20
+15

Processing those out of order would produce incorrect state.

Ordering matters.

Other workloads don't have that constraint.

Search indexing.

Webhook fan-out.

Telemetry aggregation.

Independent cache updates.

Those can often execute concurrently.

One of the runtime's responsibilities is recognizing that not every processor requires the same ordering guarantees.

Correctness always comes first.

Throughput comes second.

Why Not Just Use Sidekiq?

This is probably the question Ruby developers ask most often.

After all, Sidekiq already provides a robust distributed job system.

The answer is that jobs and change streams solve different scheduling problems.

A job queue answers:

"What work should execute next?"

A CDC runtime answers:

"How should related events flow through the system while preserving their correctness?"

Those are similar questions.

They're not the same question.

Jobs are independent.

Change events frequently aren't.

Ordering.

Checkpoints.

Replay.

Transaction boundaries.

Partition routing.

Those become first-class concerns in CDC systems.

Rather than replacing Sidekiq, the runtime sits at a different layer.

Sidekiq remains an excellent execution engine for background jobs.

HybridRuntime focuses on ordered event pipelines.

The two complement one another rather than compete.

Lessons Learned

Building cdc-redis-pro changed how I think about event-driven systems.

A few observations kept appearing throughout development.

Redis isn't PostgreSQL.

Trying to force Redis into a WAL-shaped abstraction usually hides important operational behavior.

Delivery guarantees matter more than APIs.

Two systems exposing similar methods may have completely different recovery characteristics.

Ownership scales better than synchronization.

Keeping mutable resources inside a single Ractor proved simpler than sharing them across many workers.

Acquisition and processing are independent problems.

The bottleneck for reading events is rarely the same bottleneck for processing them.

Treating those concerns separately made both architectures significantly cleaner.

Most importantly...

Infrastructure shouldn't hide tradeoffs.

It should make them explicit.

That's the philosophy behind the entire project.

The benchmark results ended up reflecting exactly those design decisions.

What the Benchmarks Actually Mean

Benchmark numbers are easy to misunderstand.

They're also surprisingly easy to exaggerate.

I wanted to avoid both.

Rather than publishing a single headline number, I built a benchmark matrix that explored how the runtime behaves under different execution strategies.

The goal wasn't to find the biggest number.

The goal was to understand where the architecture stops scaling—and why.

Measuring Different Parts of the Pipeline

Not every benchmark measures the same thing.

Some benchmarks measure source acquisition.

Others measure downstream execution.

Others measure the orchestration layer itself.

Treating those numbers as interchangeable would be misleading.

I ended up thinking about the benchmarks as three different phases.

Redis Source
      │
      ▼
ChangeEvent Acquisition
      │
      ▼
HybridRuntime
      │
      ▼
Downstream Sink

Each phase has different bottlenecks.

Acquisition is constrained by Redis.

Processing is constrained by CPU, I/O latency, ordering requirements, and scheduling overhead.

Understanding which phase you're measuring is more important than the final throughput number.

The Synthetic Benchmark

The largest number observed was approximately 54,500 events per second.

That's intentionally not presented as an end-to-end Redis benchmark.

It measures the execution capacity of the orchestration layer after events have already been acquired.

In other words:

ChangeEvent
      │
      ▼
HybridRuntime
      │
      ▼
Processor

This benchmark answers a very specific question:

"How quickly can the runtime schedule and execute already-available work?"

That's useful.

It just isn't the same as measuring an entire Redis pipeline.

End-to-End Pipelines

Real systems spend time doing real work.

Reading from Redis.

Writing to PostgreSQL.

Calling HTTP services.

Updating search indexes.

Those operations introduce latency that no scheduler can eliminate.

When measured end-to-end, the results naturally become lower.

Current peak observations include:

Redis Streams → Runtime: approximately 17,600 events/sec
PostgreSQL WAL → Redis: approximately 20,000 events/sec

Those numbers include actual I/O rather than isolated scheduling.

Personally, I find them more interesting than the synthetic benchmark because they reflect complete pipelines.

Scaling Isn't Linear

One result immediately stood out.

Adding more Ractors did not produce proportional speedups.

That's exactly what I expected.

Parallelism always introduces coordination costs.

Events must be routed.

Partitions must remain consistent.

Workers communicate through Ractor mailboxes.

Ordering constraints occasionally delay otherwise-complete work.

The runtime spends part of its time doing useful work...

...and part of its time coordinating that work.

That coordination isn't overhead to eliminate.

It's the cost of preserving correctness.

The benchmark matrix made those tradeoffs visible.

Rather than chasing perfect scaling, the goal became identifying the point where additional parallelism stopped producing meaningful throughput gains.

For the current implementation, that sweet spot consistently appeared around:

3 prewarmed Ractors
5 Redis connections per Ractor
50 Fibers

That balance delivered high throughput without introducing excessive scheduling overhead.

Ordering Has a Cost

One benchmark compared ordered and unordered execution.

The difference wasn't dramatic.

Ordered execution consistently performed slightly slower.

That's expected.

Maintaining ordering means the runtime occasionally waits for earlier work to complete before later work can safely continue.

Event 1
Event 2
Event 3

cannot become:

Event 2
Event 3
Event 1

simply because Event 2 happened to finish first.

Preserving correctness sometimes requires sacrificing a little throughput.

That's a tradeoff I consider worthwhile.

Correctness scales better than debugging race conditions.

The Interesting Bottleneck

The benchmark wasn't really about Redis.

It was about coordination.

At low parallelism, workers spend most of their time processing events.

At high parallelism, workers spend increasingly more time coordinating with one another.

Eventually another Ractor contributes more scheduling overhead than useful work.

Finding that point was considerably more valuable than finding the largest throughput number.

It answered a much more practical question:

"How should I actually configure this in production?"

Chaos Matters More Than Throughput

Raw throughput is only one characteristic of an event pipeline.

Recovery behavior is arguably more important.

The benchmark suite includes failure scenarios covering:

Redis restarts
PostgreSQL restarts
connection interruption
checkpoint recovery
consumer recovery

Streams resumed processing from checkpoints.

Pub/Sub sources reported explicit loss windows.

Recovery behavior remained consistent with each source's documented guarantees.

That consistency mattered more to me than achieving another few thousand events per second.

Long-Running Stability

Short benchmarks rarely expose operational problems.

Memory leaks.

Connection exhaustion.

Scheduler starvation.

Queue growth.

Those usually appear over time.

The runtime was therefore exercised continuously using soak tests.

One representative run processed approximately 1.34 million events over five minutes.

No processing failures were observed.

Median throughput degraded by roughly 2% over the duration of the run.

That's encouraging, although much longer overnight and multi-day soak tests remain on my roadmap.

Operational confidence comes from sustained behavior—not just impressive graphs.

What I Learned

Perhaps the most surprising outcome of the benchmarking work was this:

The execution runtime wasn't the limiting factor.

The limiting factor was almost always the surrounding system.

Network latency.

Redis.

HTTP endpoints.

Disk.

Database writes.

The scheduler spent most of its time waiting for external systems.

That reinforced one of the central architectural decisions behind HybridRuntime.

Fibers overlap waiting.

Ractors overlap computation.

Neither attempts to eliminate latency.

They simply ensure latency in one part of the system doesn't unnecessarily stall everything else.

The result isn't infinite scalability.

It's predictable scalability.

And for infrastructure software, predictability is usually the more valuable property.

The complete benchmark reports—including raw CSV data, SVG charts, chaos-recovery artifacts, and soak-test results—are published alongside the documentation.

I'd much rather readers inspect the raw data than rely on a single headline number.

Benchmarks are most useful when they're reproducible.

What's Next

cdc-redis-pro is only one piece of a much larger ecosystem.

The long-term goal was never to build "yet another Redis client."

The goal was to build a source-agnostic Change Data Capture platform for Ruby.

Today, PostgreSQL logical replication and Redis happen to be the two primary sources.

Tomorrow, that could just as easily include:

Kafka
NATS
Amazon SQS
Webhooks
Object storage
Search indexes
Other databases

The important observation is that the runtime doesn't need to change.

As long as a source can be normalized into a CDC::Core::ChangeEvent, everything downstream already knows how to process it.

That was the motivation behind separating source acquisition from execution.

        Source
           │
           ▼
   CDC::Core::ChangeEvent
           │
           ▼
    cdc-orchestrator-pro
           │
           ▼
        Processors

Every new source becomes an adapter.

Not a new runtime.

Why Split the Runtime?

One architectural decision deserves a brief explanation.

Originally the execution engine lived inside another project.

As the ecosystem evolved, I realized something important.

The runtime wasn't solving a Redis problem.

It wasn't solving a PostgreSQL problem.

It wasn't even solving a Sidekiq problem.

It was solving an event-processing problem.

That realization led to extracting the execution engine into its own commercial component:

cdc-orchestrator-pro

Today it powers Redis CDC.

Tomorrow it can power any source capable of producing normalized change events.

Separating those concerns keeps both halves of the system simpler.

Source adapters acquire events.

HybridRuntime processes them.

Each evolves independently.

Open Source First

Although cdc-redis-pro and cdc-orchestrator-pro are commercial products, the ecosystem they're built upon remains open source.

That includes:

cdc-core
cdc-parallel
cdc-concurrent
pgoutput-client
pgoutput-parser
pgoutput-decoder
pgoutput-source-adapter
Mammoth

Those projects define the common event model, execution primitives, and PostgreSQL integration that everything else builds upon.

The commercial components focus on operational capabilities rather than replacing the open-source foundation.

That separation is intentional.

I believe infrastructure ecosystems become valuable through adoption and trust—not artificial feature restrictions.

Looking Ahead

Redis replication remains one of the larger pieces still on the roadmap.

Today, cdc-redis-pro consumes Redis event sources such as Streams, Pub/Sub, and Keyspace Notifications.

A future version will move further upstream by treating Redis itself as a replication source.

That's a significantly more ambitious problem.

I'd rather stabilize the current architecture before expanding its scope.

There are also areas where I think the execution engine itself can continue to improve.

Adaptive scheduling.

Smarter partition routing.

Better observability.

Long-running soak tests.

More topology-aware execution.

Those improvements belong to the runtime rather than any particular source adapter—which is exactly why separating acquisition from execution turned out to be such a useful architectural boundary.

Final Thoughts

I started this project thinking I was building Redis CDC.

Somewhere along the way I realized I was really building an execution model.

Redis happened to expose the problem first.

PostgreSQL reinforced it.

Future source adapters will probably validate it again.

The most interesting lesson wasn't about Redis at all.

It was this:

Acquiring events and processing events are different problems.

They have different bottlenecks.

They scale differently.

They deserve different architectures.

Once those responsibilities are separated, the rest of the system becomes remarkably composable.

Redis becomes another source.

PostgreSQL becomes another source.

Tomorrow's adapters become just that—adapters.

The runtime stays the same.

For me, that's the most exciting part of the entire project.

Not because it produced the largest benchmark numbers.

Not because it uses Ractors or Fibers.

But because it led to an architecture that's easier to reason about, easier to extend, and honest about the tradeoffs of the systems it builds upon.

The benchmark reports are public.

The documentation is public.

The implementation is commercial.

If you're building event-driven systems in Ruby—or you're wrestling with Redis and PostgreSQL in the same architecture—I'd genuinely love to hear how you're approaching those problems.

I'm convinced there's still a lot left to explore.

🛡️ RackJwtAegis: Rack Middleware for Multi-Tenant JWT Authentication (Part 1)

Ken C. Demanawa — Thu, 14 Aug 2025 06:53:45 +0000

Implementing middleware-level JWT authentication and authorization before requests reach your Rails application

TL;DR

RackJwtAegis is a Rack middleware that provides JWT authentication and authorization before requests reach your Rails or Rack application. It validates JWT claims at the middleware layer, enabling multi-tenancy and security without touching your application code. This is Part 1 of a 2-part series focusing on basic setup and multi-tenant configuration. Part 2 will cover advanced RBAC (Role-Based Access Control) and caching strategies.

🔗 Links:

RubyGems: rack_jwt_aegis
GitHub: RackJwtAegis Repository
Demo App: Multi-Tenant Demo (Proof-of-Concept)

Why Another JWT Middleware?

Most JWT gems handle basic authentication, but many applications need additional features:

Multi-tenant isolation with header-based tenant id and request host subdomain validation
Path-based authorization using company slugs from JWT payloads
Middleware-level validation that occurs before requests reach your application
Built-in caching strategies for performance optimization
Support for organizational hierarchies without application code changes

RackJwtAegis was built to handle these scenarios at the Rack middleware layer, intercepting and validating requests before they reach your Rails controllers.

🏗️ The Demo: Multi-Tenant Proof-of-Concept

To demonstrate RackJwtAegis features, I built a basic proof-of-concept application with a multi-tenant ERP structure:

⚠️ Note: This is an unfinished demo application that only returns success messages - no actual business logic is implemented. It exists solely to showcase middleware authentication patterns.

Architecture Overview

Company Group (Tenant)
├── Company A (Manufacturing)
├── Company B (Retail)
├── Company C (Logistics)
├── Company D (Technology)
└── Company E (Wholesale)

Each company has 7 ERP modules (demo structure only):
📊 Accounting 📦 Inventory 🛒 Procurement 💼 Sales
🏪 Retail 📍 Warehouse 🏭 Wholesale

Note: These are placeholder modules for demonstrating multi-tenant routing - no actual ERP features are implemented.

Demo Permission Matrix

The application demonstrates these access patterns (without actual business logic):

Super Admin: Full access across all companies and modules
Group CFO: Financial access across multiple companies
Company Admin: Full access within their assigned companies
Department Manager: Module-specific access (e.g., Sales Manager)
Employee: Limited access based on role and assignment

Note: All endpoints return simple success messages like {"message": "Reports retrieved successfully"} to demonstrate authentication flow.

⚡ Quick Setup & Configuration

1. Installation

# Gemfile
gem 'rack_jwt_aegis', '~> 1.1.0'

bundle install

2. Basic Configuration

# config/application.rb
config.middleware.insert_before 0, RackJwtAegis::Middleware, {
  jwt_secret: ENV['JWT_SECRET'],
  skip_paths: ['/api/v1/auth/login', '/health']
}

What this configuration enables:

JWT Token Validation: The middleware validates JWT signatures using your secret key before any request reaches your Rails API-only application
Authentication Layer: Automatically extracts and validates JWT tokens from the Authorization: Bearer <token> header for API endpoints
Public Endpoints: The skip_paths array allows specific API routes (like login and health checks) to bypass JWT validation
Middleware Positioning: insert_before 0 ensures JWT validation happens first, before any other middleware or Rails API routing
API-First Security: Perfect for Rails API-only applications that serve mobile apps, SPAs, or microservices

Result: Your Rails API-only application now has middleware-level JWT authentication. Invalid tokens are rejected with HTTP 401 before reaching your API controllers.

3. Multi-Tenant Configuration

# config/application.rb - Multi-tenant configuration
config.middleware.insert_before 0, RackJwtAegis::Middleware, {
  jwt_secret: ENV['JWT_SECRET'] || 'your-super-secret-jwt-key-for-development',
  tenant_id_header_name: 'X-Company-Group-Id',
  validate_tenant_id: true,
  validate_pathname_slug: true,
  validate_subdomain: true,
  skip_paths: ['/api/v1/auth/login', '/up', '/api/v1/health'],
  # Custom JWT payload mapping for multi-tenant access control
  payload_mapping: {
    user_id: :sub,
    tenant_id: :company_group_id,
    subdomain: :company_group_domain,
    pathname_slugs: :company_slugs,
    role_ids: :role_ids,
  },
}

What this advanced configuration enables:

Tenant Header Validation: The tenant_id_header_name setting requires API requests to include an X-Company-Group-Id header that must match the company_group_id in the JWT payload, preventing cross-tenant access
Subdomain Security: validate_subdomain: true ensures the request subdomain (e.g., acme-corp.localhost.local) matches the JWT's company_group_domain field for API-only applications
Path-Based Authorization: validate_pathname_slug: true validates that company slugs in API URLs (e.g., /api/v1/acme-manufacturing/...) exist in the JWT's company_slugs array
Custom Payload Mapping: The payload_mapping hash tells the middleware where to find tenant isolation data in your JWT structure for API-only authentication
Role Integration: Maps role_ids from JWT payload for downstream RBAC processing in API controllers
Multi-Tenant API Security: Ideal for Rails API-only applications serving multiple tenants through mobile apps, SPAs, or B2B integrations

Result: Three-layer middleware security validation (JWT → Tenant → Path) that enforces multi-tenant isolation before requests reach your Rails API-only application. Users can only access companies they're authorized for, and tenant isolation is guaranteed at the middleware level for all API endpoints.

🎯 Consuming Validated Data in Rails Controllers

After RackJwtAegis middleware validates the JWT and enforces multi-tenant security, your Rails API controllers can access the validated user context through RequestContext:

Basic Controller Usage

# app/controllers/api/v1/accounting/reports_controller.rb
class Api::V1::Accounting::ReportsController < ApplicationController
  def index
    # Check if request passed middleware authentication
    return unauthorized unless RackJwtAegis::RequestContext.authenticated?(request.env)

    # Get validated user information from middleware
    user_id = RackJwtAegis::RequestContext.user_id(request.env)
    tenant_id = RackJwtAegis::RequestContext.tenant_id(request.env)

    # Access full JWT payload validated by middleware
    payload = RackJwtAegis::RequestContext.payload(request.env)
    user_roles = payload['role_ids']

    # Your Rails API business logic here
    reports = Report.where(company_group_id: tenant_id)
    render json: { message: "Reports retrieved successfully", count: reports.count }
  end
end

Multi-Tenant Context Access

# app/controllers/application_controller.rb
class ApplicationController < ActionController::API
  protected

  def current_user_id
    RackJwtAegis::RequestContext.current_user_id(request)
  end

  def current_tenant_id
    RackJwtAegis::RequestContext.current_tenant_id(request)
  end

  def accessible_companies
    RackJwtAegis::RequestContext.pathname_slugs(request.env)
  end

  def has_company_access?(company_slug)
    RackJwtAegis::RequestContext.has_pathname_slug_access?(request.env, company_slug)
  end

  def jwt_payload
    RackJwtAegis::RequestContext.payload(request.env)
  end
end

Available RequestContext Methods

authenticated?(env) - Check if middleware validated the request
payload(env) - Get full JWT payload hash validated by middleware
user_id(env) - Get authenticated user ID
tenant_id(env) - Get tenant/company group ID
subdomain(env) - Get subdomain from JWT
pathname_slugs(env) - Get array of accessible company slugs
current_user_id(request) - Helper for request objects
current_tenant_id(request) - Helper for request objects
has_pathname_slug_access?(env, slug) - Check company access

Key Benefits: Your Rails API controllers receive pre-validated data from the middleware layer, eliminating the need for JWT parsing or multi-tenant validation in your application code.

🚀 Building API Gateway-Like Protection

For production Rails API-only applications, combine RackJwtAegis with Rack::Attack for comprehensive API gateway-like middleware protection:

# config/application.rb - Production API security stack
config.middleware.insert_before 0, RackJwtAegis::Middleware, {
  jwt_secret: ENV['JWT_SECRET'],
  tenant_id_header_name: 'X-Company-Group-Id',
  validate_tenant_id: true,
  validate_pathname_slug: true,
  validate_subdomain: true,
  skip_paths: ['/api/v1/auth/login', '/up', '/api/v1/health']
}

# Add rate limiting and request filtering after JWT validation
config.middleware.insert_after RackJwtAegis::Middleware, Rack::Attack
# or config.middleware.insert_before RackJwtAegis::Middleware, Rack::Attack

Result: Your Rails API-only application now has enterprise-grade middleware protection:

Layer 1: JWT authentication and multi-tenant authorization (RackJwtAegis)
Layer 2: Rate limiting, IP blocking, and request filtering (Rack::Attack)
Layer 3: Your Rails API controllers with clean, validated data

This middleware stack provides API gateway-like security without the complexity of external infrastructure, perfect for Rails API applications serving mobile apps, SPAs, and microservices.

🔐 JWT Payload Design for Multi-Tenancy

The key to effective multi-tenant authentication is a well-structured JWT payload:

# app/models/user.rb
def jwt_payload_data
  {
    sub: id,  # Standard JWT subject claim
    email: email,
    first_name: first_name,
    last_name: last_name,
    company_group_id: company_group.id,           # Tenant isolation
    company_group_domain: company_group.domain_name, # Subdomain validation
    company_slugs: companies.pluck(:slug),        # Path-based authorization
    iat: Time.current.to_i,                       # Issued at
    exp: 24.hours.from_now.to_i                   # Expires at
  }
end

This payload structure enables three layers of validation:

Tenant ID validation via company_group_id
Subdomain validation via company_group_domain
Path-based authorization via company_slugs

🏢 Middleware-Level Multi-Tenant Authorization

RackJwtAegis operates at the Rack middleware layer, validating requests before they reach your application. This provides three layers of security validation:

URL Structure & Validation

Request: GET https://acme-corp.localhost.local:3000/api/v1/acme-manufacturing/accounting/reports
Headers: Authorization: Bearer <JWT_TOKEN>
         X-Company-Group-Id: 1

URL Components:
├── Subdomain: acme-corp (maps to company_group_domain in JWT)
├── Path Slug: acme-manufacturing (must be in company_slugs array)
└── Module: accounting (validated in Part 2: RBAC)

Middleware Security Validation

Before your Rails application receives the request, RackJwtAegis middleware validates:

JWT Token Validity ✓ - Signature and expiration check
Tenant Header Match ✓ - X-Company-Group-Id must match JWT company_group_id
Subdomain Validation ✓ - acme-corp.localhost.local must match JWT company_group_domain
Path Authorization ✓ - acme-manufacturing must exist in JWT company_slugs array

Only valid requests reach your Rails controllers - invalid requests are rejected at the middleware layer with appropriate HTTP status codes.

Development Setup

# Update /etc/hosts for subdomain testing
echo "127.0.0.1 acme-corp.localhost.local" >> /etc/hosts

# In config/environments/development.rb
config.hosts << '.localhost.local'

🔄 Complete Authentication Flow

1. User Login

curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
      "email": "owner@acme-corp.com",
      "password": "password123"
    }
  }'

Response:

{
  "message": "Login successful",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": 1,
    "email": "owner@acme-corp.com",
    "role": "super_admin",
    "accessible_companies": [
      "acme-manufacturing",
      "acme-retail",
      "acme-logistics",
      "acme-technology",
      "acme-wholesale"
    ]
  },
  "expires_at": "2025-08-15T00:36:15Z"
}

2. Multi-Tenant API Access

# ✅ SUCCESS: Valid token + tenant header + authorized company
curl -X GET http://localhost:3000/api/v1/acme-manufacturing/accounting/reports \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Company-Group-Id: 1"

# ❌ FORBIDDEN: Wrong tenant header
curl -X GET http://localhost:3000/api/v1/acme-manufacturing/accounting/reports \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Company-Group-Id: 999"

# ❌ FORBIDDEN: Unauthorized company slug
curl -X GET http://localhost:3000/api/v1/unauthorized-company/accounting/reports \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Company-Group-Id: 1"

🧪 Testing Middleware Security

The demo includes curl tests that demonstrate how the middleware rejects requests before they reach your Rails application:

JWT Token Validation

# ❌ No token provided
curl -X GET http://localhost:3000/api/v1/acme-retail/accounting/reports

# ❌ Invalid token
curl -X GET http://localhost:3000/api/v1/acme-retail/accounting/reports \
  -H "Authorization: Bearer invalid.jwt.token"

# ❌ Malformed token
curl -X GET http://localhost:3000/api/v1/acme-retail/accounting/reports \
  -H "Authorization: Bearer notjwttoken"

Tenant Isolation Tests

# ❌ Wrong tenant header
curl -X GET http://localhost:3000/api/v1/acme-retail/accounting/reports \
  -H "Authorization: Bearer $VALID_TOKEN" \
  -H "X-Company-Group-Id: 999"

# ❌ Missing tenant header
curl -X GET http://localhost:3000/api/v1/acme-retail/accounting/reports \
  -H "Authorization: Bearer $VALID_TOKEN"

Path-Based Authorization Tests

# ❌ Unauthorized company slug (not in JWT company_slugs array)
curl -X GET http://localhost:3000/api/v1/unauthorized-company/accounting/reports \
  -H "Authorization: Bearer $VALID_TOKEN" \
  -H "X-Company-Group-Id: 1"

# ✅ Authorized company slug (in JWT company_slugs array)
curl -X GET http://localhost:3000/api/v1/acme-manufacturing/accounting/reports \
  -H "Authorization: Bearer $VALID_TOKEN" \
  -H "X-Company-Group-Id: 1"

🎯 What's Coming in Part 2

Part 2 of this series will cover advanced RBAC and caching strategies:

Advanced Features Preview

🔐 Role-Based Access Control (RBAC): Complex permission hierarchies with role inheritance
⚡ Solid Cache Integration: High-performance permission caching strategies
📊 Permission Matrix: Role-based access patterns across modules and companies
🎛️ Dynamic Permissions: Runtime permission validation and caching
🔄 Cache Invalidation: Smart cache invalidation strategies for role changes

RBAC Permissions Hash Structure

# Coming in Part 2: Cached permissions hash
{
  "permissions" => {
    "last_update" => 1755141074,
    "1" => ["accounting/*:*", "inventory/*:*", "sales/*:*"],  # Owner role
    "11" => ["sales/leads:get", "sales/customers:get"],       # Sales Rep role
    "14" => ["procurement/*:*"]                               # Procurement Manager
  }
}

🎉 Key Features Covered in Part 1

✅ Middleware-Level Security Foundation

🔐 JWT Authentication: Token validation with HS256 algorithm at middleware layer
🏢 Multi-Tenancy: Header-based tenant isolation (X-Company-Group-Id) before Rails
🌐 Subdomain Validation: Request host validation against JWT claims
📍 Path Authorization: Company slug validation from JWT payload
🛡️ Pre-Application Security: Three-tier validation before requests reach controllers
🔧 Configurable: Custom payload mapping and skip paths
🧪 Tested: Curl test suite demonstrating middleware rejection patterns

🚀 Production-Ready Configuration

# Production multi-tenant setup
config.middleware.insert_before 0, RackJwtAegis::Middleware, {
  jwt_secret: ENV['JWT_SECRET'],                    # Strong secret required
  tenant_id_header_name: 'X-Company-Group-Id',     # Consistent header naming
  validate_tenant_id: true,                        # Enable tenant isolation
  validate_subdomain: true,                        # Enable subdomain validation
  validate_pathname_slug: true,                    # Enable path authorization
  skip_paths: ['/api/v1/auth/*', '/health'],      # Public endpoints
  debug: false                                      # Disable debug in production
}

🔍 Real-World Multi-Tenant Use Cases

The middleware-level authentication patterns covered in Part 1 work well for:

Enterprise SaaS Applications

Multi-tenant CRM/ERP systems with company isolation
Team collaboration platforms with workspace separation
Project management tools with client segregation
E-commerce marketplaces with vendor separation

API-First Applications

Microservices authentication with tenant-aware routing
Mobile app backends with organization-based access
Third-party integrations with client-specific endpoints
Multi-brand platforms with subdomain-based routing

🎯 Conclusion

In Part 1, we've covered middleware-level multi-tenant JWT authentication with RackJwtAegis. You now have:

✅ Three-layer middleware security validation (JWT → Tenant → Path)
✅ Pre-application request filtering that protects your Rails controllers
✅ Production-ready multi-tenant configuration
✅ Testing patterns that demonstrate middleware behavior

This middleware foundation provides security for multi-tenant applications before requests reach your application code, but enterprise applications need more sophisticated authorization patterns.

Part 2 will cover RBAC systems, caching strategies, and permission hierarchies for multi-organizational applications.

Try the Demo Today

Prerequisites: Ruby 3.3+, Rails 8.0+

# Clone and run the proof-of-concept demo
git clone https://github.com/kanutocd/rack-jwt-aegis-example
cd rack-jwt-aegis-example

# Install dependencies
bundle install

# Setup database with test users and permissions cache
rails db:setup

# Start the server
rails server

# Test multi-tenant authentication (returns demo success messages)
curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"auth": {"email": "owner@acme-corp.com", "password": "password123"}}'

# Use the returned JWT token to test middleware security
TOKEN="<paste-token-here>"
curl -X GET http://localhost:3000/api/v1/acme-manufacturing/accounting/reports \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Company-Group-Id: 1"

What you'll see:

Authentication endpoint returns a JWT token with multi-tenant claims
Protected endpoints return success messages like {"message": "Reports retrieved successfully"}
Invalid requests are rejected by middleware before reaching Rails controllers
Comprehensive test users with different permission levels (see CURL_TESTING_GUIDE.md)

Remember: This demo only returns success messages to show middleware authentication patterns - no actual ERP functionality is implemented.

👀 Watch for Part 2: Advanced RBAC and Caching Strategies with RackJwtAegis

📚 Resources

📦 RubyGems: rack_jwt_aegis
📖 GitHub Repository: RackJwtAegis
💻 Demo App: Multi-Tenant Demo (Proof-of-Concept)
🧪 Testing Guide: Complete curl Testing Suite

Found this helpful? Give it a ⭐ on GitHub and watch for Part 2!

Tags: #ruby #rails #jwt #authentication #middleware #multitenant #security #api #saas #enterprise