Admission Control

Two-tier admission keeps a saturated cluster from amplifying load.

The handshake tier protects the listen socket; the message tier protects expensive code paths once a connection is open.

Setup

import { createAdmissionControl } from 'svelte-adapter-uws-extensions/admission';
import { createPublishRateAggregator } from 'svelte-adapter-uws-extensions/redis/publish-rate';

const rates = await createPublishRateAggregator(redis);

const admission = createAdmissionControl({
  rules: {
    'expensive-rpc': ['MEMORY', 'PUBLISH_RATE'],
    'cluster-broadcast': { clusterTopPublisher: { rates, threshold: 1000 } },
    'admin-only': (className, platform) => platform.connections < 1000
  }
});

Usage

import { createMessage, LiveError } from 'svelte-realtime/server';

export const message = createMessage({
  async beforeExecute(ws, rpcPath) {
    const className = classOf(rpcPath);
    if (!await admission.shouldAccept(className, platform)) {
      throw new LiveError('OVERLOADED', 'Server is shedding load');
    }
  }
});

Rule shapes

A rule is one of:

• Array of pressure reasons - ['MEMORY', 'PUBLISH_RATE', 'SUBSCRIBERS']. Reject if platform.pressure.reason is any of the listed reasons.
• Predicate - (className, platform) => boolean | Promise<boolean>. Custom logic.
• clusterTopPublisher - { rates, threshold }. Reject if the calling user is in the top-N publishers across the cluster (use with createPublishRateAggregator).

Metrics

Cluster-wide publish-rate aggregator

createPublishRateAggregator(redis, options?) exposes a cluster-wide top-publisher view that powers the clusterTopPublisher admission rule. Each instance broadcasts its own platform.pressure.topPublishers slice on a Redis pub/sub channel; every instance maintains a sliding-window view of all instances’ slices and merges them into a cluster-wide top-N. No leader election - each instance is its own aggregator. Storage cost is O(instances * topN) per instance, bounded and small.

// src/lib/server/publish-rate.js
import { redis } from './redis.js';
import { createPublishRateAggregator } from 'svelte-adapter-uws-extensions/redis/publish-rate';

export const aggregator = createPublishRateAggregator(redis, {
  publishInterval: 5_000,
  staleAfter: 12_000,
  topN: 20
});

// In your open hook (or any startup path with a platform reference):
export async function open(ws, { platform }) {
  await aggregator.activate(platform);
}

API

Options

Pairing with the sharded bus (cluster subscriber counts)

The aggregator’s subjects option is the channel for cluster-wide subscriber counts. Wire the sharded bus’s localSubjects(platform) helper as the contributor; the bus exposes a matching bus.subscribers(topic) that delegates to aggregator.subscribersOf(topic):

import { createShardedBus } from 'svelte-adapter-uws-extensions/redis/sharded-pubsub';
import { createPublishRateAggregator } from 'svelte-adapter-uws-extensions/redis/publish-rate';

const bus = createShardedBus(redis);
const aggregator = createPublishRateAggregator(redis, {
  subjects: () => bus.localSubjects(platform)
});

// Also pass subscribersAggregator into the bus so bus.subscribers(topic)
// returns the cluster-wide count rather than just the local one:
const busWithCluster = createShardedBus(redis, { subscribersAggregator: aggregator });

await bus.activate(platform);
await aggregator.activate(platform);

const cluster = busWithCluster.subscribers('chat:room-7');
// Local count + sum from non-stale remote instances.

Without an aggregator wired, bus.subscribers(topic) returns the local count only. Eventually-consistent within publishInterval for the remote contribution; the local read is always live. For exact counts (audit log, billing), track a Redis SET cluster-wide on subscribe / unsubscribe and SCARD it.

The unsharded createPubSubBus does not track per-topic state (it forwards every topic through a single Redis channel), so it does not expose localSubjects / subscribers. Apps that need cluster-wide subscriber counts on the unsharded bus thread their own per-topic state into the aggregator’s subjects callback.

Wire envelope

Channel: {channel}                    (default: 'uws:pressure:rates')
Payload: {
  instanceId, ts,
  slice: [{topic, messagesPerSec, bytesPerSec}, ...],
  subs?: [{topic, count}, ...]
}

Receivers merge into a per-instanceId map keyed on the broadcasting instance; entries older than staleAfter are dropped on the next merge. The subs field is omitted when no subjects callback is configured. Aggregators on either side of a version skew tolerate envelopes with or without subs (forward- and backward-compatible).

Metrics

Wire to Prometheus via wireClusterPublishRateMetrics(aggregator, metrics, { topN }). Per-instance metrics via wirePublishRateMetrics(platform, metrics). Both can be active simultaneously - local view shows hot-shard pressure, cluster view shows global capacity. See Metrics.

See also

• Adapter upgradeAdmission - handshake-tier cap.
• Adapter platform.pressure - per-worker backpressure source.