Cross-region messaging

Cross-region messaging lets channels span multiple npayload instances. Messages published in one region are automatically replicated to other regions with guaranteed delivery, enabling global applications while respecting data residency requirements.

How it works

When a channel is configured for cross-region messaging, npayload maintains a transmission queue between instances. Messages are published locally, queued for transmission, and delivered to remote instances with exactly-once guarantees.

Instance US-East                    Instance EU-West
┌──────────────────┐                ┌──────────────────┐
│  Channel: events │                │  Channel: events │
│                  │   Transmission │                  │
│  Publish here    │───────────────>│  Delivered here  │
│                  │   Queue        │                  │
│  Subscribe here  │<───────────────│  Publish here    │
└──────────────────┘                └──────────────────┘

Subscribers in each region receive messages from both local and remote publishers without any code changes.

Replication modes

Active-active

All instances both publish and receive messages. Subscribers in every region see the full stream.

const channel = await npayload.channels.create({
  name: 'global-events',
  replication: {
    mode: 'active-active',
    regions: ['us-east', 'eu-west', 'ap-south'],
  },
});

Active-passive

One region is the source. Other regions receive replicated messages but do not publish back.

const channel = await npayload.channels.create({
  name: 'config-updates',
  replication: {
    mode: 'active-passive',
    sourceRegion: 'us-east',
    replicaRegions: ['eu-west', 'ap-south'],
  },
});

Data residency

Cross-region messaging includes built-in data residency controls. Data does not flow to a region unless both the source and destination organisations have given explicit consent.

// Grant consent for data to flow to EU
await npayload.federation.grantConsent({
  channel: 'events',
  targetRegion: 'eu-west',
  dataClassification: 'standard', // or 'sensitive', 'restricted'
});

Data classification

Ordering guarantees

Latency considerations

Cross-region delivery adds network latency between instances. Plan for:

Local subscribers always receive messages at local speed. The added latency only applies to cross-region delivery.

Instance discovery

npayload instances automatically discover each other. When a new instance is provisioned, it registers with the network and becomes available for cross-region channels without manual configuration.

// List available instances and regions
const instances = await npayload.federation.listInstances();

instances.forEach(instance => {
  console.log(`${instance.region}: ${instance.status}`);
});

Use cases

Next steps

• Channels to understand channel types and cross-instance channels
• Marketplace to discover and share channels across organisations
• Architecture for an overview of the global network