🚇 Tunnel Protocol

Ring's Multi-Transport Real-Time Communication

Tunnel Protocol is Ring Platform's intelligent real-time communication system - the Ring analog to Firebase Realtime Database. It provides unified real-time messaging across WebSocket, Server-Sent Events (SSE), Supabase Realtime, and Long-Polling transports with automatic fallback and Edge Runtime compatibility.

v1.6.0: lib/tunnel/disconnected-tunnel-context.ts preserves UX when the tunnel is offline; pair with Push notifications FCM for mobile alerts.

🎯 Why Tunnel Protocol?

The Problem with Firebase RTDB

Firebase Realtime Database provides excellent real-time features but creates vendor lock-in:

• ❌ Vendor Lock-in: Tied to Firebase infrastructure
• ❌ Edge Runtime Incompatible: Cannot run on Vercel Edge
• ❌ Cost Scaling: Pay-per-operation pricing
• ❌ Limited Control: Cannot optimize for specific use cases
• ❌ Single Transport: WebSocket only

The Ring Solution: Tunnel Protocol

✅ Transport Abstraction: Unified API across 5+ transports
✅ Edge Runtime Compatible: SSE support for Vercel Edge
✅ Zero Vendor Lock-in: Use any backend (PostgreSQL, Supabase, Firebase)
✅ Intelligent Fallback: Automatic cascade on transport failures ✅ : Self-hosted options, pay only for infrastructure ✅ : Real-time features for unauthenticated users

🚇 Tunnel Protocol

Ring's Multi-Transport Real-Time Communication

Tunnel Protocol is Ring Platform's intelligent real-time communication system - the Ring analog to Firebase Realtime Database. It provides unified real-time messaging across WebSocket, Server-Sent Events (SSE), Supabase Realtime, and Long-Polling transports with automatic fallback and Edge Runtime compatibility.

v1.6.0: lib/tunnel/disconnected-tunnel-context.ts preserves UX when the tunnel is offline; pair with Push notifications FCM for mobile alerts.

🎯 Why Tunnel Protocol?

The Problem with Firebase RTDB

Firebase Realtime Database provides excellent real-time features but creates vendor lock-in:

• ❌ Vendor Lock-in: Tied to Firebase infrastructure
• ❌ Edge Runtime Incompatible: Cannot run on Vercel Edge
• ❌ Cost Scaling: Pay-per-operation pricing
• ❌ Limited Control: Cannot optimize for specific use cases
• ❌ Single Transport: WebSocket only

The Ring Solution: Tunnel Protocol

✅ Transport Abstraction: Unified API across 5+ transports
✅ Edge Runtime Compatible: SSE support for Vercel Edge
✅ Zero Vendor Lock-in: Use any backend (PostgreSQL, Supabase, Firebase)
✅ Intelligent Fallback: Automatic cascade on transport failures ✅ : Self-hosted options, pay only for infrastructure ✅ : Real-time features for unauthenticated users

🚇 Tunnel Protocol

Ring's Multi-Transport Real-Time Communication

Tunnel Protocol is Ring Platform's intelligent real-time communication system - the Ring analog to Firebase Realtime Database. It provides unified real-time messaging across WebSocket, Server-Sent Events (SSE), Supabase Realtime, and Long-Polling transports with automatic fallback and Edge Runtime compatibility.

v1.6.0: lib/tunnel/disconnected-tunnel-context.ts preserves UX when the tunnel is offline; pair with Push notifications FCM for mobile alerts.

🎯 Why Tunnel Protocol?

The Problem with Firebase RTDB

Firebase Realtime Database provides excellent real-time features but creates vendor lock-in:

• ❌ Vendor Lock-in: Tied to Firebase infrastructure
• ❌ Edge Runtime Incompatible: Cannot run on Vercel Edge
• ❌ Cost Scaling: Pay-per-operation pricing
• ❌ Limited Control: Cannot optimize for specific use cases
• ❌ Single Transport: WebSocket only

The Ring Solution: Tunnel Protocol

✅ Transport Abstraction: Unified API across 5+ transports
✅ Edge Runtime Compatible: SSE support for Vercel Edge
✅ Zero Vendor Lock-in: Use any backend (PostgreSQL, Supabase, Firebase)
✅ Intelligent Fallback: Automatic cascade on transport failures ✅ : Self-hosted options, pay only for infrastructure ✅ : Real-time features for unauthenticated users

🏗️ Architecture Overview

Unified Transport API

🏗️ Architecture Overview

Unified Transport API

🏗️ Architecture Overview

Unified Transport API

// Single API works across ALL transports
import { publishToTunnel, subscribeToTunnel } from '@/lib/tunnel/publisher'

// Publish message (works on any transport)
await publishToTunnel(channel, eventType, data)

// Subscribe to updates (works on any transport)
const unsubscribe = subscribeToTunnel(channel, (message) => {
  console

// Single API works across ALL transports
import { publishToTunnel, subscribeToTunnel } from '@/lib/tunnel/publisher'

// Publish message (works on any transport)
await publishToTunnel(channel, eventType, data)

// Subscribe to updates (works on any transport)
const unsubscribe = subscribeToTunnel(channel, (message) => {
  console

// Single API works across ALL transports
import { publishToTunnel, subscribeToTunnel } from '@/lib/tunnel/publisher'

// Publish message (works on any transport)
await publishToTunnel(channel, eventType, data)

// Subscribe to updates (works on any transport)
const unsubscribe = subscribeToTunnel(channel, (message) => {
  console

Supported Transports

Supported Transports

Supported Transports

🚀 Quick Start

Publishing Real-Time Updates

Replace Firebase RTDB calls with Tunnel:

Before (Firebase RTDB):

🚀 Quick Start

Publishing Real-Time Updates

Replace Firebase RTDB calls with Tunnel:

Before (Firebase RTDB):

🚀 Quick Start

Publishing Real-Time Updates

Replace Firebase RTDB calls with Tunnel:

Before (Firebase RTDB):

import { getAdminRtdb } from '@/lib/firebase-admin.server'

const rtdb = getAdminRtdb()
await rtdb.ref(`messages/${messageId}`).set(messageData)

import { getAdminRtdb } from '@/lib/firebase-admin.server'

const rtdb = getAdminRtdb()
await rtdb.ref(`messages/${messageId}`).set(messageData)

import { getAdminRtdb } from '@/lib/firebase-admin.server'

const rtdb = getAdminRtdb()
await rtdb.ref(`messages/${messageId}`).set(messageData)

After (Tunnel Protocol):

After (Tunnel Protocol):

After (Tunnel Protocol):

import { publishToTunnel } from '@/lib/tunnel/publisher'

await publishToTunnel(`conversation:${conversationId}`, 'message:new', messageData)

import { publishToTunnel } from '@/lib/tunnel/publisher'

await publishToTunnel(`conversation:${conversationId}`, 'message:new', messageData)

import { publishToTunnel } from '@/lib/tunnel/publisher'

await publishToTunnel(`conversation:${conversationId}`, 'message:new', messageData)

Subscribing to Updates

Before (Firebase RTDB):

Subscribing to Updates

Before (Firebase RTDB):

Subscribing to Updates

Before (Firebase RTDB):

const ref = rtdb.ref(`messages/${messageId}`)
ref.on('value', (snapshot) => {
  const data = snapshot.val()
  handleUpdate(data)
})

const ref = rtdb.ref(`messages/${messageId}`)
ref.on('value', (snapshot) => {
  const data = snapshot.val()
  handleUpdate(data)
})

const ref = rtdb.ref(`messages/${messageId}`)
ref.on('value', (snapshot) => {
  const data = snapshot.val()
  handleUpdate(data)
})

After (Tunnel Protocol):

After (Tunnel Protocol):

After (Tunnel Protocol):

import { subscribeToTunnel } from '@/lib/tunnel/client'

const unsubscribe = subscribeToTunnel(`conversation:${conversationId}`, (message) => {
  if (message.type === 'message:new') {
    handleUpdate(message.payload)

import { subscribeToTunnel } from '@/lib/tunnel/client'

const unsubscribe = subscribeToTunnel(`conversation:${conversationId}`, (message) => {
  if (message.type === 'message:new') {
    handleUpdate(message.payload)

import { subscribeToTunnel } from '@/lib/tunnel/client'

const unsubscribe = subscribeToTunnel(`conversation:${conversationId}`, (message) => {
  if (message.type === 'message:new') {
    handleUpdate(message.payload)

💡 Real-World Examples

Example 1: Chat Messages

Server-side (publish):

💡 Real-World Examples

Example 1: Chat Messages

Server-side (publish):

💡 Real-World Examples

Example 1: Chat Messages

Server-side (publish):

'use server'

import { initializeDatabase, getDatabaseService } from '@/lib/database/DatabaseService'
import { publishToTunnel } from '@/lib/tunnel/publisher'
import { revalidatePath } from 'next/cache'

export async function sendMessage(conversationId: string, content: string

'use server'

import { initializeDatabase, getDatabaseService } from '@/lib/database/DatabaseService'
import { publishToTunnel } from '@/lib/tunnel/publisher'
import { revalidatePath } from 'next/cache'

export async function sendMessage(conversationId: string, content: string

'use server'

import { initializeDatabase, getDatabaseService } from '@/lib/database/DatabaseService'
import { publishToTunnel } from '@/lib/tunnel/publisher'
import { revalidatePath } from 'next/cache'

export async function sendMessage(conversationId: string, content: string

Client-side (subscribe):

Client-side (subscribe):

Client-side (subscribe):

'use client'

import { useEffect, useState } from 'react'
import { subscribeToTunnel } from '@/lib/tunnel/client'

export function ChatMessages({ conversationId }) {
  const [messages, setMessages] = useState([])
  
  useEffect

'use client'

import { useEffect, useState } from 'react'
import { subscribeToTunnel } from '@/lib/tunnel/client'

export function ChatMessages({ conversationId }) {
  const [messages, setMessages] = useState([])
  
  useEffect

'use client'

import { useEffect, useState } from 'react'
import { subscribeToTunnel } from '@/lib/tunnel/client'

export function ChatMessages({ conversationId }) {
  const [messages, setMessages] = useState([])
  
  useEffect

Example 2: Typing Indicators

Publish typing status:

Example 2: Typing Indicators

Publish typing status:

Example 2: Typing Indicators

Publish typing status:

await publishToTunnel(`conversation:${conversationId}`, 'typing:start', {
  userId,
  userName,
  timestamp: Date.now()
})

await publishToTunnel(`conversation:${conversationId}`, 'typing:start', {
  userId,
  userName,
  timestamp: Date.now()
})

await publishToTunnel(`conversation:${conversationId}`, 'typing:start', {
  userId,
  userName,
  timestamp: Date.now()
})

Subscribe to typing:

Subscribe to typing:

Subscribe to typing:

subscribeToTunnel(`conversation:${conversationId}`, (message) => {
  if (message.type === 'typing:start') {
    showTypingIndicator(message.payload.userName)
  }
})

subscribeToTunnel(`conversation:${conversationId}`, (message) => {
  if (message.type === 'typing:start') {
    showTypingIndicator(message.payload.userName)
  }
})

subscribeToTunnel(`conversation:${conversationId}`, (message) => {
  if (message.type === 'typing:start') {
    showTypingIndicator(message.payload.userName)
  }
})

Example 3: Like/Unlike Updates

Publish like update:

Example 3: Like/Unlike Updates

Publish like update:

Example 3: Like/Unlike Updates

Publish like update:

await publishToTunnel(`entity:${entityId}`, 'like:toggled', {
  likeCount: newCount,
  liked: true,
  userId
})

await publishToTunnel(`entity:${entityId}`, 'like:toggled', {
  likeCount: newCount,
  liked: true,
  userId
})

await publishToTunnel(`entity:${entityId}`, 'like:toggled', {
  likeCount: newCount,
  liked: true,
  userId
})

🎛️ Transport Selection

Tunnel automatically selects optimal transport based on deployment:

Kubernetes + PostgreSQL

// Detected: postgres.*.svc.cluster.local
// Selected: WebSocket (wss://)
// Fallback: Long-Polling

Vercel Edge Runtime

// Detected: VERCEL=1
// Selected: SSE (Edge compatible)
// Fallback: Long-Polling

Supabase Deployment

// Detected: SUPABASE_URL configured
// Selected: Supabase Realtime
// Fallback: SSE → Long-Polling

Firebase Mode

🎛️ Transport Selection

Tunnel automatically selects optimal transport based on deployment:

Kubernetes + PostgreSQL

// Detected: postgres.*.svc.cluster.local
// Selected: WebSocket (wss://)
// Fallback: Long-Polling

Vercel Edge Runtime

// Detected: VERCEL=1
// Selected: SSE (Edge compatible)
// Fallback: Long-Polling

Supabase Deployment

// Detected: SUPABASE_URL configured
// Selected: Supabase Realtime
// Fallback: SSE → Long-Polling

Firebase Mode

🎛️ Transport Selection

Tunnel automatically selects optimal transport based on deployment:

Kubernetes + PostgreSQL

// Detected: postgres.*.svc.cluster.local
// Selected: WebSocket (wss://)
// Fallback: Long-Polling

Vercel Edge Runtime

// Detected: VERCEL=1
// Selected: SSE (Edge compatible)
// Fallback: Long-Polling

Supabase Deployment

// Detected: SUPABASE_URL configured
// Selected: Supabase Realtime
// Fallback: SSE → Long-Polling

Firebase Mode

// Detected: DB_BACKEND_MODE=firebase-full
// Selected: Firebase Realtime
// Fallback: SSE → Long-Polling

🔧 Configuration

Environment Variables

// Detected: DB_BACKEND_MODE=firebase-full
// Selected: Firebase Realtime
// Fallback: SSE → Long-Polling

🔧 Configuration

Environment Variables

// Detected: DB_BACKEND_MODE=firebase-full
// Selected: Firebase Realtime
// Fallback: SSE → Long-Polling

🔧 Configuration

Environment Variables

# Transport selection (optional - auto-detected)
NEXT_PUBLIC_TUNNEL_TRANSPORT=websocket # or sse, supabase, firebase

# WebSocket configuration
TUNNEL_WEBSOCKET_URL=wss://your-domain.com/api/tunnel/ws

# SSE configuration (Edge Runtime)
TUNNEL_SSE_URL=https://your-domain.com/api/tunnel/sse

# Fallback settings
TUNNEL_ENABLE_FALLBACK=true
TUNNEL_FALLBACK_TIMEOUT=5000 # 5 seconds

# Transport selection (optional - auto-detected)
NEXT_PUBLIC_TUNNEL_TRANSPORT=websocket # or sse, supabase, firebase

# WebSocket configuration
TUNNEL_WEBSOCKET_URL=wss://your-domain.com/api/tunnel/ws

# SSE configuration (Edge Runtime)
TUNNEL_SSE_URL=https://your-domain.com/api/tunnel/sse

# Fallback settings
TUNNEL_ENABLE_FALLBACK=true
TUNNEL_FALLBACK_TIMEOUT=5000 # 5 seconds

# Transport selection (optional - auto-detected)
NEXT_PUBLIC_TUNNEL_TRANSPORT=websocket # or sse, supabase, firebase

# WebSocket configuration
TUNNEL_WEBSOCKET_URL=wss://your-domain.com/api/tunnel/ws

# SSE configuration (Edge Runtime)
TUNNEL_SSE_URL=https://your-domain.com/api/tunnel/sse

# Fallback settings
TUNNEL_ENABLE_FALLBACK=true
TUNNEL_FALLBACK_TIMEOUT=5000 # 5 seconds

Backend Mode Integration

Tunnel respects your database backend mode:

Backend Mode Integration

Tunnel respects your database backend mode:

Backend Mode Integration

Tunnel respects your database backend mode:

// lib/database/backend-mode-config.ts
export const BACKEND_MODES = {
  'k8s-postgres-fcm': {
    tunnel: 'websocket' // Primary transport
  },
  'firebase-full': {
    tunnel: 'firebase' // Use Firebase Realtime
  },
  'supabase-fcm': {

// lib/database/backend-mode-config.ts
export const BACKEND_MODES = {
  'k8s-postgres-fcm': {
    tunnel: 'websocket' // Primary transport
  },
  'firebase-full': {
    tunnel: 'firebase' // Use Firebase Realtime
  },
  'supabase-fcm': {

// lib/database/backend-mode-config.ts
export const BACKEND_MODES = {
  'k8s-postgres-fcm': {
    tunnel: 'websocket' // Primary transport
  },
  'firebase-full': {
    tunnel: 'firebase' // Use Firebase Realtime
  },
  'supabase-fcm': {

📊 Performance Characteristics

Latency Comparison

📊 Performance Characteristics

Latency Comparison

📊 Performance Characteristics

Latency Comparison

WebSocket:          <50ms   // Best for self-hosted
SSE:                <100ms  // Best for Edge Runtime
Supabase Realtime:  <50ms   // Best for Supabase deployments
Firebase Realtime:  <200ms  // When using Firebase mode
Long-Polling:       500ms-2s // Universal fallback

WebSocket:          <50ms   // Best for self-hosted
SSE:                <100ms  // Best for Edge Runtime
Supabase Realtime:  <50ms   // Best for Supabase deployments
Firebase Realtime:  <200ms  // When using Firebase mode
Long-Polling:       500ms-2s // Universal fallback

WebSocket:          <50ms   // Best for self-hosted
SSE:                <100ms  // Best for Edge Runtime
Supabase Realtime:  <50ms   // Best for Supabase deployments
Firebase Realtime:  <200ms  // When using Firebase mode
Long-Polling:       500ms-2s // Universal fallback

Throughput Comparison

Throughput Comparison

Throughput Comparison

WebSocket:          10,000 messages/second
SSE:                1,000 messages/second
Supabase Realtime:  5,000 messages/second
Firebase Realtime:  1,000 messages/second
Long-Polling:       100 messages/second

WebSocket:          10,000 messages/second
SSE:                1,000 messages/second
Supabase Realtime:  5,000 messages/second
Firebase Realtime:  1,000 messages/second
Long-Polling:       100 messages/second

WebSocket:          10,000 messages/second
SSE:                1,000 messages/second
Supabase Realtime:  5,000 messages/second
Firebase Realtime:  1,000 messages/second
Long-Polling:       100 messages/second

🛡️ Security Features

Encrypted Channels

All transports support encryption:

🛡️ Security Features

Encrypted Channels

All transports support encryption:

🛡️ Security Features

Encrypted Channels

All transports support encryption:

await publishToTunnel(`secure:${userId}`, 'sensitive:data', {
  encrypted: true,
  data: encryptedPayload
})

await publishToTunnel(`secure:${userId}`, 'sensitive:data', {
  encrypted: true,
  data: encryptedPayload
})

await publishToTunnel(`secure:${userId}`, 'sensitive:data', {
  encrypted: true,
  data: encryptedPayload
})

Rate Limiting

Built-in protection against abuse:

Rate Limiting

Built-in protection against abuse:

Rate Limiting

Built-in protection against abuse:

// Automatic rate limiting per user/IP
Max 100 messages/minute per user
Max 1000 messages/minute per IP

// Automatic rate limiting per user/IP
Max 100 messages/minute per user
Max 1000 messages/minute per IP

// Automatic rate limiting per user/IP
Max 100 messages/minute per user
Max 1000 messages/minute per IP

DDoS Protection

Transport-level protection:

• Connection limits per IP
• Message size limits
• Automatic ban for abusive patterns

🎯 Migration Guide

From Firebase RTDB

DDoS Protection

Transport-level protection:

• Connection limits per IP
• Message size limits
• Automatic ban for abusive patterns

🎯 Migration Guide

From Firebase RTDB

DDoS Protection

Transport-level protection:

• Connection limits per IP
• Message size limits
• Automatic ban for abusive patterns

🎯 Migration Guide

From Firebase RTDB

Code Example

Before:

Code Example

Before:

Code Example

Before:

const rtdb = getAdminRtdb()
await rtdb.ref(`typing/${conversationId}/${userId}`).set(typingData)
await rtdb.ref(`typing/${conversationId}/${userId}`).

const rtdb = getAdminRtdb()
await rtdb.ref(`typing/${conversationId}/${userId}`).set(typingData)
await rtdb.ref(`typing/${conversationId}/${userId}`).

const rtdb = getAdminRtdb()
await rtdb.ref(`typing/${conversationId}/${userId}`).set(typingData)
await rtdb.ref(`typing/${conversationId}/${userId}`).

After:

After:

After:

await publishToTunnel(`conversation:${conversationId}`, 'typing:start', {
  userId,
  userName,
  timestamp: Date.now()
})
// Disconnect handling automatic in Tunnel transport layer

await publishToTunnel(`conversation:${conversationId}`, 'typing:start', {
  userId,
  userName,
  timestamp: Date.now()
})
// Disconnect handling automatic in Tunnel transport layer

await publishToTunnel(`conversation:${conversationId}`, 'typing:start', {
  userId,
  userName,
  timestamp: Date.now()
})
// Disconnect handling automatic in Tunnel transport layer

🔥 Advanced Features

Message Types

Tunnel supports typed messages:

🔥 Advanced Features

Message Types

Tunnel supports typed messages:

🔥 Advanced Features

Message Types

Tunnel supports typed messages:

type TunnelMessageType = 
  | 'DATA'          // Generic data
  | 'NOTIFICATION'  // Push notifications
  | 'MESSAGE'       // Chat messages
  | 'PRESENCE'      // User presence/typing
  | 'HEARTBEAT'     // Keep-alive
  | 'ACK'           // Acknowledgments
  | '

type TunnelMessageType = 
  | 'DATA'          // Generic data
  | 'NOTIFICATION'  // Push notifications
  | 'MESSAGE'       // Chat messages
  | 'PRESENCE'      // User presence/typing
  | 'HEARTBEAT'     // Keep-alive
  | 'ACK'           // Acknowledgments
  | '

type TunnelMessageType = 
  | 'DATA'          // Generic data
  | 'NOTIFICATION'  // Push notifications
  | 'MESSAGE'       // Chat messages
  | 'PRESENCE'      // User presence/typing
  | 'HEARTBEAT'     // Keep-alive
  | 'ACK'           // Acknowledgments
  | '

Channel Patterns

Organize channels by feature:

Channel Patterns

Organize channels by feature:

Channel Patterns

Organize channels by feature:

`conversation:${id}`     // Chat conversations
`entity:${id}`           // Entity updates
`opportunity:${id}`      // Opportunity updates
`user:${id}`             // User-specific channel
`typing:${conversationId}` // Typing indicators
`presence:${

`conversation:${id}`     // Chat conversations
`entity:${id}`           // Entity updates
`opportunity:${id}`      // Opportunity updates
`user:${id}`             // User-specific channel
`typing:${conversationId}` // Typing indicators
`presence:${

`conversation:${id}`     // Chat conversations
`entity:${id}`           // Entity updates
`opportunity:${id}`      // Opportunity updates
`user:${id}`             // User-specific channel
`typing:${conversationId}` // Typing indicators
`presence:${

🎖️ Best Practices Summary

🎖️ Best Practices Summary

🎖️ Best Practices Summary

Built by Legiox Commander for Emperor Ray
Ring analog to Firebase RTDB - Zero vendor lock-in - Maximum flexibility
🔥⚔️👑

Built by Legiox Commander for Emperor Ray
Ring analog to Firebase RTDB - Zero vendor lock-in - Maximum flexibility
🔥⚔️👑

Built by Legiox Commander for Emperor Ray
Ring analog to Firebase RTDB - Zero vendor lock-in - Maximum flexibility
🔥⚔️👑