rabbit-sock-relay

A lightweight and efficient bridge to connect a RabbitMQ instance (via AMQP) to frontend applications using a simple WebSocket interface. This package allows you to relay messages from RabbitMQ queues and exchanges directly to your web clients in real-time.

Features

• Type-safe: Built with TypeScript and Effect for robust error handling
• Modular architecture: Composable services using Effect layers
• Real-time messaging: WebSocket server for instant message delivery
• Message flow management: Handles message ordering and event flows
• Authentication: JWT-based authentication with middleware support
• Logging: Comprehensive logging with in-memory log storage and viewer
• Health monitoring: Built-in health checks and diagnostics endpoints
• Test utilities: Includes WebSocket test clients and diagnostic tools

Framework Compatibility

This package is designed to work with multiple JavaScript frameworks and environments:

✅ Effect-based Applications (Native)

For applications already using Effect, use the native API:

import { startRelay, createDefaultConfig } from 'rabbit-sock-relay';

const { server, relay } = await startRelay();

✅ Express.js Applications

Use the Express middleware for seamless integration:

const { createExpressMiddleware } = require('rabbit-sock-relay');

const relayMiddleware = createExpressMiddleware({
  server: { port: 3000 },
  rabbitMQ: { url: "amqp://localhost:5672" }
});

app.use(relayMiddleware.middleware);

✅ Next.js Applications

Use the Next.js API handler:

import { createNextJSHandler } from 'rabbit-sock-relay';

const relayHandler = createNextJSHandler({
  server: { port: 3000 },
  rabbitMQ: { url: process.env.RABBITMQ_URL }
});

export default relayHandler.handler;

✅ Pure Node.js Applications

Use the adapter class for full control:

const { RabbitSockRelayAdapter } = require('rabbit-sock-relay');

const relay = new RabbitSockRelayAdapter({
  server: { port: 3000 },
  rabbitMQ: { url: "amqp://localhost:5672" }
});

const server = await relay.start();

✅ Simple Function-based Usage

For quick prototyping and simple applications:

const { createSimpleRelay } = require('rabbit-sock-relay');

const relay = await createSimpleRelay({
  server: { port: 3000 },
  rabbitMQ: { url: "amqp://localhost:5672" }
});

✅ Other Frameworks

The package works with any framework that supports Node.js HTTP servers:

• Fastify: Use the RabbitSockRelayAdapter class
• Koa: Use the RabbitSockRelayAdapter class
• Hapi: Use the RabbitSockRelayAdapter class
• Custom servers: Use the RabbitSockRelayAdapter class

See FRAMEWORK_EXAMPLES.md for detailed examples.

Installation

npm install rabbit-sock-relay

Quick Start

import { startRelay, createDefaultConfig } from 'rabbit-sock-relay';

// Start with default configuration
const { server, relay } = await startRelay();

// Or customize the configuration
const config = createDefaultConfig({
  server: { port: 8080 },
  rabbitMQ: { url: "amqp://localhost:5672" },
  auth: { enabled: true, secretKey: "your-secret-key" }
});

const { server, relay } = await startRelay(config);

Configuration

The package supports comprehensive configuration options:

interface RelayConfig {
  rabbitMQ: {
    url: string;
    exchangeName: string;
    queueName: string;
    heartbeatInterval: number;
    reconnectInterval: number;
  };
  webSocket: {
    path: string;
    pingInterval: number;
    maxConnections: number;
  };
  auth: {
    enabled: boolean;
    secretKey?: string;
    expiresIn?: string;
  };
  server: {
    port: number;
    host: string;
    cors: CorsOptions;
  };
  logLevel: "debug" | "info" | "warn" | "error";
}

Available Endpoints

• GET /health - Health check endpoint
• GET /diagnostics - Detailed system diagnostics
• GET /logs - HTML log viewer
• DELETE /logs - Clear logs
• GET /ws-test - WebSocket test client
• WS /ws - WebSocket connection endpoint

Effect-based Architecture

This package is built using the Effect library for functional programming with:

• Composable services: Each component is a separate Effect service
• Dependency injection: Services are provided through Effect layers
• Type-safe error handling: Structured error types and handling
• Resource management: Automatic cleanup and resource disposal

Services

• RelayService: Main application service
• RabbitMQService: AMQP connection and message handling
• WebSocketService: WebSocket server and client management
• EventFlowManager: Message ordering and flow control
• LoggerService: Structured logging
• LogService: In-memory log storage and retrieval
• AuthService: JWT authentication and middleware

Development

# Build the project
npm run build

# Run tests
npm test

# Watch mode for development
npm run dev

License

MIT