Realtime Client Library API

Rewind

Overview

The rewind parameter allows you to specify, at the time of attaching to a channel, where to start the attachment from.

You can specify either:

  • A given number of messages.
  • A point in time in the past, as a time interval.

The parameter relates to the initial attachment of a connection to a channel, and expresses the intent to attach to the channel at a position, or a point in time, in the past (that is, effectively “rewinding” the channel for the purposes of the present attachment).

The rewind parameter is specified using channel parameters.

Examples

Rewind example with an Ably client library

A rewind value that is a number n (eg rewind=1) is a request to attach to the channel at a position n messages before the present position. If the attachment is successful, and one or more messages exist on the channel prior to the present position, then those messages will be delivered to the subscriber immediately after the attachment has completed, and before any subsequent messages that arise in real time.

If fewer than the requested number of messages exists on the channel (including the case that there are no prior messages), then the available messages are sent; this does not constitute an error.

To subscribe to a channel, getting the most recent message if available:

var realtime = new Ably.Realtime('xVLyHw.wL8nxw:92Ve6fxsjr2cqyZH');
realtime.channels.get('axe-dog-arc', {
  params: {rewind: '1'}
}).subscribe(msg => console.log("Received message: ", msg));
var realtime = new Ably.Realtime('xVLyHw.wL8nxw:92Ve6fxsjr2cqyZH');
realtime.channels.get('axe-dog-arc', {
  params: {rewind: '1'}
}).subscribe(msg => console.log("Received message: ", msg));
final Map<String, String> params = new HashMap<>();
params.put("rewind", "1");
final ChannelOptions options = new ChannelOptions();
options.params = params;
final Channel channel = ably.channels.get("axe-dog-arc", options);

channel.subscribe(new MessageListener() {
  @Override
  public void onMessage(Message message) {
    System.out.println("Received `" + message.name + "` message with data: " + message.data);
  }
});
let options = ARTClientOptions(key: "xVLyHw.wL8nxw:92Ve6fxsjr2cqyZH")
let client = ARTRealtime(options: options)
let channelOptions = ARTRealtimeChannelOptions()
channelOptions.params = [
  "rewind": "1"
]

let channel = client.channels.get(channelName, options: channelOptions)
var clientOptions = new ClientOptions();
clientOptions.Key = "xVLyHw.wL8nxw:92Ve6fxsjr2cqyZH";
clientOptions.Environment = AblyEnvironment;
var ably = new AblyRealtime(clientOptions);

var channelParams = new ChannelParams();
channelParams.Add("rewind", "1");
var channelOptions = new ChannelOptions();
channelOptions.Params = channelParams;
var channel = ably.Channels.Get("axe-dog-arc", channelOptions);

channel.Subscribe(message => {
    Console.WriteLine(message.Data.ToString());
});

A rewind value can also be a string that is a time interval specifier. Supported specifier values express an integral number of seconds (eg 15s) or minutes (eg 2m). If that attachment is successful, and one or more messages exist on the channel in the given time interval prior to the present time, then those messages will be delivered to the subscriber immediately after the attachment has completed, and before any subsequent messages that arise in real time.

If you wish to use a time interval rewind but additionally specify a limit on the number of messages to be returned, you can use the rewindLimit channel parameter. For example, to request up to 10 messages in a window 5m before the present time, specify a channel parameter string of rewind=5m&rewindLimit=10. If fewer than the requested number of messages exists on the channel in that interval (including the case that there are no messages), then the available messages are sent; this does not constitute an error.

Rewind example with SSE

To subscribe to a channel, getting the most recent message if available:

var querystring = 'v=1.2&channels=axe-dog-arc&rewind=1&key=xVLyHw.wL8nxw:92Ve6fxsjr2cqyZH';
var eventSource = new EventSource('https://realtime.ably.io/event-stream?' + querystring);

Rewind example with MQTT

var mqtt = require('mqtt');
var options = {
  keepalive: 30,
  username: 'xVLyHw.wL8nxw', /* API key's name */
  password: '92Ve6fxsjr2cqyZH', /* API key's secret */
  port: 8883
};
var client = mqtt.connect('mqtts:mqtt.ably.io', options);
client.on('connect', () => {
  client.subscribe('[?rewind=1]axe-dog-arc');
});
client.on('message', (topic, message) => {
  ...
});

Additional information

At most 100 messages will be sent in a rewind request. If the number of messages within the specified interval is greater than that limit, then only the most recent messages up to that limit are sent. The attachment succeeds, but truncation of the message backlog is indicated as a non-fatal error in the attachment response.

Rewind by time (rewind=30s) can only get messages at most 2 minutes old. So, if you specify rewind=3m, you will only get the last 2 minutes of history upon attaching. For now, it’s not possible to reach into persisted history using time-based parameters.

Rewind by a certain number of messages (rewind=20) is restricted by the channel’s persistence period. If you’ve not enabled persisted history, this will be 2 minutes. If you have persistence enabled, this’ll be 24 hours for free accounts, and 72 hours for paid accounts.

The channel position expressed by a rewind parameter only has an effect on an initial channel attachment. Any subsequent reattachment of the same channel on the same connection, in order to resume the connection, will attempt to resume with continuity from the point at which the connection dropped. (There are a few exceptions to this: in particular, client libraries earlier than v1.2 that have been disconnected for over two minutes, and all clients when using recover mode ; in both cases the previous attachment state is not preserved).

Any rewind parameter value that cannot be parsed either as a number or a time specifier will cause the attachment request to fail and return an error.

API Reference

ChannelOptions ObjectARTChannelOptionsio.ably.lib.types.ChannelOptionsIO.Ably.Realtime.ChannelOptions

Channel options are used for setting channel parameters and configuring encryption.

ChannelOptions, a plain Javascript object, may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options. The following attributes can be defined on the object:

ChannelOptions, a Hash object, may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options. The following key symbol values can be added to the Hash:

ChannelOptions, an Associative Array, may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options. The following named keys and values can be added to the Associated Array:

ARTio.ably.lib.types.ChannelOptions may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options.

IO.Ably.ChannelOptions may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options.

PropertiesMembersAttributes

:cipherCipherParamscipher
Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See an example
Type: CipherParams or an options objecta Param[] listan options hashan Associative Array containing at a minimum a key
paramsParams
Optional parameters which specify behaviour of the channel.
Type: Map<String, String>JSON Object
cipherCipherParams
Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See an example
Type: CipherParams or an options objecta Param[] listan options hashan Associative Array containing at a minimum a key

Static methods

withCipherKey

static ChannelOptions.withCipherKey(Byte[] or String key)

A helper method to generate a ChannelOptions for the simple case where you only specify a key.

Parameters

key
A binary Byte[] array or a base64-encoded String.

Returns

On success, the method returns a complete ChannelOptions object. Failure will raise an AblyException.


API reference
Documentation