Channels and Segments

1. Choose a channel reference

A channel reference names a communication space inside your Celeris app, such as orders or room-42. You do not create it in the dashboard first.

In the JavaScript SDK, a channel handle represents one connection:

// Continue after creating client in the Quickstart.
const channel = client.channel("room-42");

Creating a handle does not connect. await channel.connect() opens the socket. Calling client.channel("room-42") twice creates two separate handles; connecting both opens two sockets, even though their reference is the same.

Every successful connection automatically joins the channel's default segment. You do not need to create it or call subscribe() to join it. Access it through channel.defaultSegment(), which is equivalent to channel.segment("default"). Obtaining that handle does not connect by itself.

Channel references contain 1 to 255 ASCII letters, digits, hyphens, or underscores.

2. Divide the connection into segments

A segment is a named stream inside the channel. Use segments for related updates that share a connection but have different subscribers or permissions.

If your channel needs only one stream, use default:

const updates = channel.defaultSegment();

updates is a handle to the stream you automatically join when channel.connect() succeeds. You can receive messages with updates.onMessage() and send them with updates.publish(). No updates.subscribe() call is needed. Your credentials must still grant the appropriate read/write permissions for default.

Add named segments only when you need separate streams:

const chat = channel.segment("chat");
const typing = channel.segment("typing");

Both handles use the same channel socket. Obtaining a segment handle does not perform network work. Joining a segment is a real server operation, not just a local filter.

Names are not security boundaries by themselves. Your trusted server must sign the allowed channel references and segment read/write permissions.

3. Listen and subscribe

A listener is your local callback. A subscription tells the SDK to maintain interest in the segment's messages. For an additional named segment such as chat, register both. For default, register the listener; connection setup already supplies the membership.

import { readText } from "@useceleris/client";

const stopUpdates = updates.onMessage((payload) => {
  console.log("Default stream:", readText(payload));
});

const stopListening = chat.onMessage((payload) => {
  console.log(readText(payload));
});
const membership = chat.subscribe();
await channel.connect();

Registering before connecting lets the SDK restore your interests as part of connection setup. A subscription is not a server acknowledgement: permission errors arrive separately.

For a default-only setup, keep updates and its listener, and omit the chat listener and subscription. Connect the channel once in either case. The Quickstart credentials allow only demo-room / chat; authorize room-42 and the segments you use on your server before running these examples.

A message reaches permitted members of its own segment, not every connection in the channel.

4. Understand automatic membership

Connecting automatically joins the "default" segment. channel.defaultSegment() is shorthand for channel.segment("default"). Read permission is still required to receive messages, and automatic membership does not subscribe to presence.

The default segment is not a wildcard. A message published to chat does not also appear in default, and a message published to default does not reach every named segment. See the default-segment example for publishing and receiving without an explicit subscription.

Publishing joins that segment server-side. Subscribing to presence also joins it for messages, and cancelling presence alone does not leave that message membership.

Multiple handles for the same segment share the channel's listeners and interest counts. Cancelling one subscription does not cancel another caller's interest. The default segment is never remotely unsubscribed.

5. Release what you own

stopUpdates(); // Remove the default stream's callback.
stopListening(); // Remove this callback.
membership.cancel(); // Release this subscription.
await channel.close(); // Finish with the whole connection.

close() also closes every segment handle on that channel. Create a new channel if you need a connection after closing.

With the default-only setup, cleanup is just stopUpdates() and await channel.close(); there is no subscription handle to cancel.

Next: Messaging in JavaScript, or Reconnection and Recovery to understand how subscriptions survive an outage.