const server = await NoexServer.start({
  store,
  rules,
  port: 8080,
  auth: { validate: verifyToken },
});

noex ecosystem

noex-server

Name: noex-server
Author: noex

Real-time WebSocket Server

JSON-based protocol over WebSocket with GenServer per-connection isolation, reactive store subscriptions, rules engine proxy, pluggable authentication, and built-in backpressure management.

View on GitHub

Key Features

Everything you need for real-time WebSocket communication in Node.js

GenServer per Connection

Each WebSocket connection runs in its own GenServer actor, supervised with simple_one_for_one strategy. If one connection crashes, others continue unaffected.

Full Store Proxy

Complete CRUD operations, reactive query subscriptions with automatic push updates, cursor-based pagination, aggregations, and multi-bucket ACID transactions over WebSocket.

Rules Engine Proxy

Event emission, fact management, pattern-based wildcard queries, and real-time event subscriptions — all proxied through the WebSocket connection.

Authentication & Authorization

Pluggable token validation with per-connection sessions. Role-based permission checks on every operation. Session expiration with automatic enforcement.

Rate Limiting

Sliding window rate limiter with configurable max requests and window duration. Per-user for authenticated or per-IP for anonymous connections.

Heartbeat Ping/Pong

Automatic dead connection detection with configurable intervals (default 30s) and timeout (default 10s). Connections closed with code 4001 on timeout.

Write-Buffer Backpressure

Protection against slow clients. When WebSocket write buffer exceeds the high water mark (default 80% of 1 MB), push messages are dropped to prevent memory exhaustion.

Graceful Shutdown

Clients receive a system shutdown notification with grace period. New connections rejected while existing clients have time to disconnect cleanly.

Protocol & Messages

JSON over WebSocket, protocol version 1.0.0. Request-response with async push notifications.

Message Types

Client → Request

{ "id": 1, "type": "store.get", "bucket": "users", "key": "abc" }

← Server Response

{ "id": 1, "type": "result", "data": { "id": "abc", "name": "Alice" } }

← Server Push

{ "type": "push", "channel": "subscription", "subscriptionId": "sub_1", "data": [...] }

← Server Heartbeat

{ "type": "ping", "timestamp": 1706000000 }

store.insertstore.getstore.updatestore.deletestore.allstore.wherestore.findOnestore.countstore.firststore.laststore.paginatestore.clearstore.sumstore.avgstore.minstore.maxstore.subscribestore.unsubscribestore.transactionstore.bucketsstore.stats

Connection Lifecycle

WebSocket connect

Server sends welcome message with protocol version

Client authenticates (if auth required)

Client sends requests, server responds

Server pushes subscription updates

Client or server closes connection

Supervision Architecture

GenServer per connection, supervised with simple_one_for_one strategy. Crashed connections are cleaned up automatically.

NoexServer

HTTP Server

ConnectionSupervisor

ConnectionRegistry

RateLimiter opt

ConnectionServer #1

ConnectionServer #2

ConnectionServer #N

Each WebSocket connection runs in its own GenServer — full process isolation, sequential message processing, independent subscription state and session.

Request pipeline: JSON parse → Auth check → Rate limit → Route to store/rules/auth proxy → Serialize response. Push messages flow from store/rules subscriptions through the connection GenServer.

See It in Action

Real examples showing server startup, client CRUD, reactive subscriptions, and transactions

server.ts

import { NoexServer } from '@hamicek/noex-server';
import { Store } from '@hamicek/noex-store';
import { RuleEngine } from '@hamicek/noex-rules';

const store = await Store.start();
await store.defineBucket('users', {
  key: 'id',
  schema: {
    id:   { type: 'string', generated: 'uuid' },
    name: { type: 'string', required: true },
  },
});

const rules = await RuleEngine.start();

const server = await NoexServer.start({
  store,
  rules,
  port: 8080,
  auth: {
    validate: async (token) => {
      // Return session or null
      return { userId: 'user_1', roles: ['admin'] };
    },
  },
  heartbeat: { intervalMs: 30_000, timeoutMs: 10_000 },
  backpressure: { maxBufferedBytes: 1_048_576, highWaterMark: 0.8 },
});

console.log(`Server listening on port ${server.port}`);

How It Compares

noex-server vs popular real-time WebSocket solutions

Feature	noex-server	Socket.IO	Supabase Realtime	Firebase RTDB	Ably	Pusher
Protocol	JSON over WS	Custom protocol	Postgres CDC	Custom binary	Custom protocol	Custom protocol
Per-connection Isolation	GenServer actor	—	—	—	—	—
Reactive Queries	Convex-style subscriptions	Manual rooms	Postgres changes	Realtime sync	Pub/sub	Channels
ACID Transactions	Multi-bucket over WS	—	Postgres transactions	—	—	—
Built-in Rule Engine	✓	—	—	—	—	—
Backpressure Management	Write-buffer based	—	—	—	Server-side	—
Heartbeat / Dead Conn Detection	✓	✓	✓	✓	✓	✓
Supervision Tree	OTP simple_one_for_one	—	—	—	—	—
Self-hosted	✓	✓	—	—	—	—
Authentication	Pluggable token validation	Middleware	JWT / RLS	Firebase Auth	Token-based	Token-based
Graceful Shutdown	Client notification + grace period	—	Managed	Managed	Managed	Managed
Status	Active	Active	Active	Active	Active	Active

What Makes noex-server Unique

GenServer per Connection

Each WebSocket connection is a supervised GenServer actor. Sequential message processing eliminates race conditions, and crash isolation prevents one bad connection from affecting others.

Integrated noex-store Reactivity

Convex-style reactive query subscriptions are proxied directly over WebSocket. Clients receive automatic push updates when underlying data changes.

Built-in Rule Engine Proxy

The only WebSocket server with integrated rule engine access. Emit events, manage facts, and subscribe to pattern-matched rule events in real-time.

Write-Buffer Backpressure

Protects against slow clients by monitoring WebSocket write buffer. When buffer exceeds the high water mark, push messages are safely dropped to prevent memory exhaustion.

ACID Transactions over WebSocket

Multi-bucket atomic transactions with optimistic locking, sent as a single WebSocket message. Read-your-own-writes and automatic rollback on conflict.

Start building real-time applications

Add noex-server to your project in seconds

npm install @hamicek/noex-server

$ npm install @hamicek/noex-server

Read the Docs Star on GitHub

Back to noex

Support the Project

Love noex? Help us keep building amazing tools

Bitcoin