Channel concepts
Channels are used to separate messages into different topics. They are the building block of creating a realtime application using the publish-subscribe pattern. Channels are also the unit of security and scalability. Clients should only ever be provided the capabilities for channels that they should have access to.
Messages contain the data that a client is communicating, such as the contents of an individual chat message, or an event that has occurred, such as updated financial information.
With basic Pub/Sub you create a channel, subscribe to it, and then publish messages to it. Most other Ably features utilize channels, or a group of channels, to provide additional functionality to your realtime applications.
Use a channel
To get started with implementing any feature, a client must first create or retrieve an instance of a channel. A channel is created, or an existing channel is retrieved from the Channels collection. You can only connect to one channel in a single operation.
Channels are identified by their unique name. The following restrictions apply to when naming a channel:
- Channel names are case sensitive
- They can't start with
[or: - They can't be empty
- They can't contain newline characters
While Ably doesn't limit the length of channel names, keeping them under 2048 characters is recommended, since some older browsers have trouble with long URLs.
Use the get() method to create or retrieve a channel instance:
1
const channel = realtime.channels.get('axe-art-ill');Publishing and subscribing
Clients subscribe to a channel to receive the messages published to it. Clients can subscribe to all messages, or only messages identified by specific names.
Publishing messages to a channel is how clients communicate with one another. Any subscribers will receive published messages as long as they are subscribed and have the subscribe capability for that channel.
Channel options
Channel options are used to customize the functionality of channels. This includes enabling features such as encryption and deltas, or for a client to retrieve messages published prior to it attaching to a channel using rewind.
Channel metadata
Metadata provides additional information about your apps and channels. It includes uses such as enabling clients to be aware of how many other clients are attached to a channel without the need to use presence, Examples of channel metadata available include the status and occupancy of specific channels.
Rules
Rules are used to enforce settings for the channels selected by a match expression. They can be broadly categorized into three different types:
- For message storage
- For client security and identification
- To enable features for a set of channels
The rules related to message storage are:
| Rule | Description |
|---|---|
| Persist last message | If enabled, the very last message published on a channel will be stored for a year. This message is retrievable using rewind by attaching to the channel with rewind=1. If you send multiple messages in a single protocol message, for example calling publish() with an array of messages, you would receive all of them as one message. Be aware that presence messages are not stored and that messages stored in this manner are not accessible using history. Note that for each message stored using this rule, an additional message is deducted from your monthly allocation. |
| Persist all messages | If enabled, all messages published on a channel will be stored according to the storage rules for your account. This is 24 hours for free accounts and 72 hours for paid accounts. Messages stored in this manner are accessible using history. Note that for each message stored using this rule, an additional message is deducted from your monthly allocation. |
The rules related to security and client identity are:
| Rule | Description |
|---|---|
| Identified | If enabled, clients will not be permitted to use (including to attach, publish, or subscribe) matching channels unless they are identified (they have an assigned client ID). Anonymous clients are not permitted to join these channels. Find out more about authenticated and identified clients. |
| TLS only | If enabled, only clients who have connected to Ably over TLS will be allowed to use matching channels. By default all of Ably's client libraries use TLS when communicating with Ably over REST or when using Realtime transports such as Websockets. |
The rules related to enabling features are:
| Rule | Description |
|---|---|
| Push notifications enabled | If checked, publishing messages with a push payload in the extras field is permitted. This triggers the delivery of a Push Notification to devices registered for push on the channel. |
| Server-side batching | If enabled, messages are grouped into batches before being sent to subscribers. Server-side batching reduces the overall message count, lowers costs, and mitigates the risk of hitting rate limits during high-throughput scenarios. |
| Message conflation | If enabled, messages are aggregated over a set period of time and evaluated against a conflation key. All but the latest message for each conflation key value will be discarded, and the resulting message, or messages, will be delivered to subscribers as a single batch once the period of time elapses. Message conflation reduces costs in high-throughput scenarios by removing redundant and outdated messages. |
| Message annotations, updates, deletes, and appends | If enabled, allows message annotations to be used, as well as updates, deletes, and appends to be published to messages. Note that these features are currently in public preview. When this feature is enabled, messages will be persisted (necessary in order from them later be annotated or updated), and continuous history features will not work. |
To set a rule:
In your app settings:
- Click Create rule.
- Enter the match expression selecting the channels to apply the rules to.
- Check the required rules.
- Click Create rule to save.
Match expressions
A rule's id is a match expression selecting the channels it applies to. An expression is one or more segments delimited by colons (:), where each segment is either literal text or a single wildcard (*):
- A non-trailing
*matches exactly one segment. - A trailing
*matches one segment or more, but never zero. - An expression with no wildcard matches only the channel with exactly that name.
| Expression | Matches | Does not match |
|---|---|---|
foo | foo | foo:bar |
foo:* | foo:bar, foo:bar:baz | foo |
* | foo, foo:bar (any channel) | — |
*:sub | foo:sub | foo:bar:sub |
foo:*:baz | foo:bar:baz | foo:baz |
The wildcard rules are the same as those for a capability resource expression, so if you already know one you know the other. The set of things you can name differs, though: a rule id is always a normal channel; unlike a capability resource it cannot address a queue or metachannel.
A trailing * needs at least one segment, so foo:* does not cover a channel just named foo. The only expressions that match that channel would be foo or *.
Each segment must be non-empty, and a segment containing a wildcard alongside other characters is rejected, eg foo* and foo:ba*r, to avoid confusion caused by using asterisks which wouldn't work as wildcards because they're not in their own colon-delimited segment.
Which rule applies
Where several rules match a channel, exactly one of them applies: the most specific. Rules are not merged.
Specificity is decided by comparing expressions segment by segment from the left:
- At the first segment where one rule has a literal and the other has
*, the rule with the literal wins. - If the two agree as far as both extend, the rule with more segments wins.
Because segments are compared from the left, an earlier literal decides the contest outright, however many segments the other expression pins down later, so chat:* beats *:room:42:msgs in matching chat:room:42:msgs.
Rules created before match expressions (see older channel rules) win over a match-expression rule.
Older channel rules (namespaces)
Rules created before match expressions were introduced were known as channel namespaces, and match on the first segment of a channel name: the rule's id (the namespace) matches the channel with exactly that name, plus every channel beneath id:. A rule with the id batching matches batching, batching:chat and batching:order:update — equivalent to the two expressions batching and batching:* together. These rules will keep working unchanged, and can have their attributes edited, but any new rules you create will need to use match expressions. To convert a rule to use match expressions, just create it as a new rule and delete the old one.
Channel history
Channel history enables clients to retrieve messages that have been previously published on the channel. Messages can be retrieved from history for up to 72 hours in the past, depending on the persistence configured for the channel.
Presence
The presence feature enables clients to be aware of other clients that are 'present' on the channel. Client status is updated as they enter or leave the presence set. Clients can also provide an optional payload describing their status or attributes, and trigger an update event at any time.
Channel groups
Ably does not support channel groups, a concept used by some other providers where channels are placed into groups to work around limitations in dynamically subscribing or unsubscribing from channels.
Why Ably doesn't need channel groups:
- With Ably client libraries, you can add or remove subscriptions to channels dynamically at any time.
- All channels operate over a single efficient connection.
- Channel rules already provide grouping functionality for configuration purposes, applying settings to whole sets of channels at once.
Instead of channel groups, simply subscribe to the specific channels your client needs access to. The efficient multiplexing ensures optimal performance regardless of the number of channels.