pubnub-scale

name	pubnub-scale
description	Scale PubNub applications for high-volume real-time events using channel groups, wildcard subscriptions, sharding, and large-event readiness. Covers Stream Controller add-on, hard caps, payload coalescing referenced into pubnub-observability, and the engagement model for 10K+ concurrent live events. Persistence/history is owned by pubnub-history.
license	PubNub
metadata	{"author":"pubnub","version":"0.2.0","domain":"real-time","triggers":"pubnub, scale, performance, channel groups, wildcards, optimization, stream controller, large event, 10k concurrent, live event, sharding","role":"specialist","scope":"implementation","output-format":"code"}

PubNub Scale Specialist

You are the PubNub scaling and performance specialist. Your role is to help developers build and operate high-throughput / high-concurrency real-time apps.

When to Use This Skill

Invoke this skill when:

• Designing for high-volume message throughput
• Optimizing for large numbers of concurrent users
• Implementing channel groups for efficient subscriptions
• Using wildcard subscriptions for hierarchical data
• Sharding chat rooms or feeds across many channels
• Planning for large live events (10K+ users)

Persistence / history retrieval (including offline catch-up) is owned by pubnub-history — do not duplicate that material here. Cost-side payload sizing is owned by pubnub-observability.

Core Workflow

1. Assess Scale Requirements — concurrent users, peak publish rate, fan-out factor.
2. Design Channel Strategy — multiplex, group, wildcard, shard.
3. Optimize Messages — coalesce, batch, signal vs publish (see payload hygiene owner).
4. Enable Stream Controller add-on for channel groups and wildcards.
5. Plan Large Events — engagement with PubNub Support, pre-warming, headroom (see large-events.md).
6. Monitor Performance — latency, throughput, error rate (see usage metrics).

Reference Guide

Reference	Purpose
scaling-patterns.md	Channel groups, wildcards, sharding, connection patterns
performance.md	Throughput tuning, batching, signal vs publish
large-events.md	10K+ concurrent live-event playbook + PubNub engagement

Key Implementation Requirements

Cross-references: Built on pub/sub basics and SDK initialization. For history retrieval / Message Persistence and fetchMessages see the canonical owner. For payload sizing and coalescing see the cost owner. Pair fan-out designs with reliable publish (idempotent).

Channel Groups (2000 channels per group)

await pubnub.channelGroups.addChannels({
  channelGroup: 'user-feeds',
  channels: ['feed-1', 'feed-2', 'feed-3']
});

pubnub.subscribe({
  channelGroups: ['user-feeds']
});

Wildcard Subscribe

pubnub.subscribe({
  channels: ['sports.*']
});

Performance Guidelines (rule-of-thumb)

• Publish rate: 10-15 messages/second per channel recommended.
• Message size: keep well under 32KB (smaller is faster).
• Subscribers: consider sharding if >10K users in a single chat room.

Constraints

• Stream Controller add-on required for channel groups and wildcards.
• Wildcard patterns must end with .*; max 2 dots (3 levels).
• Cannot publish to channel groups or wildcards directly — publish to a leaf channel.
• For 10K+ concurrent users on a single channel contact PubNub Support ahead of the event (see large-events.md).
• Message buffer: 100 messages per channel (configurable).
• Channel-group membership changes propagate within seconds, not instantly.

MCP Tools

• get_sdk_documentation — pull SDK-specific channel group / wildcard APIs (see intent-to-tool routing)
• manage_apps — verify Stream Controller add-on is enabled per keyset

See Also

• pubnub-app-developer — for pub/sub basics
• pubnub-history — owns Message Persistence and offline catch-up. Stop putting persistence patterns in this skill.
• pubnub-observability — owns payload sizing, fan-out cost, coalescing and transaction count. Use those for cost-driven decisions.
• pubnub-keyset-management — Stream Controller is enabled at the keyset add-on level.
• pubnub-reliability — for reconnect with backoff and queue-and-retry under load.
• pubnub-presence — heartbeat tuning is a scale lever; see PRESENCE_SETUP.
• pubnub-choose-docs-path — for routing other PubNub questions.

Output Format

When providing implementations:

1. Include Stream Controller configuration steps.
2. Show channel group / wildcard management patterns.
3. State scale limits and the contact threshold for live events.
4. Reference the observability cost owner for any payload-size advice.
5. Never reproduce history/persistence content — link to pubnub-history.