From 9de02ccfbb08809eed9f7a58fdbcda92a2707537 Mon Sep 17 00:00:00 2001 From: Francis Roberts <111994975+franrob-projects@users.noreply.github.com> Date: Mon, 7 Jul 2025 17:39:25 +0200 Subject: [PATCH 1/2] EDU-2000: Adds vcdiff to JS delta docs --- content/channels/options/deltas.textile | 155 ++++++++++++++++-------- 1 file changed, 103 insertions(+), 52 deletions(-) diff --git a/content/channels/options/deltas.textile b/content/channels/options/deltas.textile index 1421a0881d..65e6f56a92 100644 --- a/content/channels/options/deltas.textile +++ b/content/channels/options/deltas.textile @@ -44,6 +44,38 @@ There is no constraint on how many publishers or subscribers there are. If there If a delta is generated and it results in a difference that is not appreciably smaller than the original message, or is larger than the original message, for example if successive messages are completely different, then the delta will not be sent. Clients will receive the original, unprocessed message. +blang[javascript,nodejs]. + + h2(#vcdiff). Install vcdiff decoder + + A Vcdiff decoder written in pure JavaScript. The vcdiff decoder is a JavaScript library that decodes delta-compressed messages, allowing clients to reconstruct full messages from the small "diffs" sent by Ably to reduce bandwidth usage. + + h3(#install). Installation from npm for Node.js + + ```[bash] + npm install @ably/vcdiff-decoder + ``` + + and require as: + + ```[javascript] + const vcdiffPlugin = require('@ably/vcdiff-decoder'); + ``` + + ```[nodejs] + const vcdiffPlugin = require('@ably/vcdiff-decoder'); + ``` + + h3(#browsers). Script include for web browsers + + Include the library in your HTML from our CDN: + + ```[html] + + ``` + +blang[default]. + h2(#subscribe). Subscribe using delta Set the @delta@ property of @params@ to @vcdiff@ in order to enable deltas when subscribing to a channel. @@ -53,82 +85,101 @@ This will cause delta messages to be generated by the server and sent to the cli Note that in some SDKs, the @vcdiff@ delta decoding library is excluded from the default distribution in order to avoid increasing the size. In these cases, it is also necessary to supply the delta decoder plugin when instantiating Ably. ```[realtime_javascript] - /* Make sure to include in your head */ - const realtime = new Ably.Realtime({ +/* Make sure to include in your head */ +const Ably = require('ably'); +const vcdiffPlugin = require('@ably/vcdiff-decoder'); + +const realtime = new Ably.Realtime({ key: '{{API_KEY}}', plugins: { - vcdiff: vcdiffDecoder - } - }); - const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', { + vcdiff: vcdiffPlugin + }, + log: { level: 4 } // optional +}); + +const channel = realtime.channels.get('your-ably-channel', { params: { - delta: 'vcdiff' + delta: 'vcdiff' } - }); +}); - await channel.subscribe((message) => { - console.log('Received message: ', msg); - }); +channel.subscribe(msg => console.log("Received message: ", msg)); ``` ```[realtime_nodejs] - const vcdiffPlugin = require('@ably/vcdiff-decoder'); - const realtime = new Ably.Realtime({ +/* Make sure to include in your head */ +const Ably = require('ably'); +const vcdiffPlugin = require('@ably/vcdiff-decoder'); + +const realtime = new Ably.Realtime({ key: '{{API_KEY}}', plugins: { - vcdiff: vcdiffPlugin - } - }); - const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', { + vcdiff: vcdiffPlugin + }, + log: { level: 4 } // optional +}); + +const channel = realtime.channels.get('your-ably-channel', { params: { - delta: 'vcdiff' + delta: 'vcdiff' } - }); +}); - await channel.subscribe((message) => { - console.log('Received message: ', msg); - }); +channel.subscribe(msg => console.log("Received message: ", msg)); ``` ```[realtime_java] - AblyRealtime ably = new AblyRealtime("{{API_KEY}}") - Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}", new ChannelOptions{{params = Map.of("delta", "vcdiff")}}); - channel.subscribe(new MessageListener() { - @Override - public void onMessage(Message message) { - System.out.println("Received `" + message.name + "` message with data: " + message.data); - } - }); +AblyRealtime ably = new AblyRealtime("{{API_KEY}}") +Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}", new ChannelOptions{{params = Map.of("delta", "vcdiff")}}); +channel.subscribe(new MessageListener() { + @Override + public void onMessage(Message message) { + System.out.println("Received `" + message.name + "` message with data: " + message.data); + } +}); ``` ```[realtime_swift] - let options = ARTClientOptions(key: key) - let client = ARTRealtime(options: options) - let channelOptions = ARTRealtimeChannelOptions() - channelOptions.params = [ - "delta": "vcdiff" - ] - - let channel = client.channels.get(channelName, options: channelOptions) +let options = ARTClientOptions(key: key) +let client = ARTRealtime(options: options) +let channelOptions = ARTRealtimeChannelOptions() +channelOptions.params = [ + "delta": "vcdiff" +] + +let channel = client.channels.get(channelName, options: channelOptions) ``` ```[realtime_csharp] - var clientOptions = new ClientOptions(); - clientOptions.Key = "{{API_KEY}}"; - clientOptions.Environment = AblyEnvironment; - var ably = new AblyRealtime(clientOptions); - - var channelParams = new ChannelParams(); - channelParams.Add("delta", "vcdiff"); - var channelOptions = new ChannelOptions(); - channelOptions.Params = channelParams; - var channel = ably.Channels.Get("{{RANDOM_CHANNEL_NAME}}", channelOptions); - - channel.Subscribe(message => { - Console.WriteLine(message.Data.ToString()); - }); +var clientOptions = new ClientOptions(); +clientOptions.Key = "{{API_KEY}}"; +clientOptions.Environment = AblyEnvironment; +var ably = new AblyRealtime(clientOptions); + +var channelParams = new ChannelParams(); +channelParams.Add("delta", "vcdiff"); +var channelOptions = new ChannelOptions(); +channelOptions.Params = channelParams; +var channel = ably.Channels.Get("{{RANDOM_CHANNEL_NAME}}", channelOptions); + +channel.Subscribe(message => { + Console.WriteLine(message.Data.ToString()); +}); ``` + blang[javascript,nodejs]. + +h3(#exported). Exported functions + +The vcdiff decoder library exports the following function for manual delta decoding. + +@decode(delta, source)@ applies a vcdiff delta to a source message to return a "@Uint8Array@":https://nodejs.org/api/buffer.html#buffer containing the target message: + +* @delta@: The binary delta/diff data. +* @source@: The original message to apply the delta to. + +blang[default]. + h2(#limitations). Known limitations In principle, @vcdiff@ deltas can be applied to encrypted message payloads, but in practice this provides no benefit because there is no similarity between successive encrypted payloads even for identical or near-identical plaintext message payloads. From 40c0260b0c2838ccf68c636df0836618f1150c00 Mon Sep 17 00:00:00 2001 From: Francis Roberts <111994975+franrob-projects@users.noreply.github.com> Date: Wed, 9 Jul 2025 18:49:56 +0200 Subject: [PATCH 2/2] fixup! EDU-2000: Adds vcdiff to JS delta docs --- content/channels/options/deltas.textile | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/content/channels/options/deltas.textile b/content/channels/options/deltas.textile index 65e6f56a92..08e78a9fc1 100644 --- a/content/channels/options/deltas.textile +++ b/content/channels/options/deltas.textile @@ -48,7 +48,7 @@ blang[javascript,nodejs]. h2(#vcdiff). Install vcdiff decoder - A Vcdiff decoder written in pure JavaScript. The vcdiff decoder is a JavaScript library that decodes delta-compressed messages, allowing clients to reconstruct full messages from the small "diffs" sent by Ably to reduce bandwidth usage. + The vcdiff decoder is written in pure JavaScript and enables clients to reconstruct full messages from the small "diffs" sent by Ably. h3(#install). Installation from npm for Node.js @@ -74,6 +74,15 @@ blang[javascript,nodejs]. ``` + h3(#exported). Exported functions + + The vcdiff decoder library exports the following function for manual delta decoding. + + @decode(delta, source)@ applies a vcdiff delta to a source message to return a "@Uint8Array@":https://nodejs.org/api/buffer.html#buffer containing the target message: + + * @delta@: The binary delta/diff data. + * @source@: The original message to apply the delta to. + blang[default]. h2(#subscribe). Subscribe using delta @@ -167,19 +176,6 @@ channel.Subscribe(message => { }); ``` - blang[javascript,nodejs]. - -h3(#exported). Exported functions - -The vcdiff decoder library exports the following function for manual delta decoding. - -@decode(delta, source)@ applies a vcdiff delta to a source message to return a "@Uint8Array@":https://nodejs.org/api/buffer.html#buffer containing the target message: - -* @delta@: The binary delta/diff data. -* @source@: The original message to apply the delta to. - -blang[default]. - h2(#limitations). Known limitations In principle, @vcdiff@ deltas can be applied to encrypted message payloads, but in practice this provides no benefit because there is no similarity between successive encrypted payloads even for identical or near-identical plaintext message payloads.