USPs for Pub/Sub

src/components/Layout/mdx/Admonition.tsx

@@ -3,7 +3,7 @@ import cn from '@ably/ui/core/utils/cn';
 import Aside from 'src/components/blocks/dividers/Aside';
 import { HtmlComponentPropsData } from 'src/components/html-component-props';
 
-const LEGACY_ADMONITION_TYPES = ['new', 'updated', 'experimental'];
+const LEGACY_ADMONITION_TYPES = ['new', 'updated', 'experimental', 'see-evidence'];
 
 type AdmonitionVariant = 'neutral' | 'note' | 'further-reading' | 'important' | 'warning';
 

src/components/blocks/dividers/Aside.tsx

@@ -3,6 +3,7 @@ import Html from '../Html';
 import Icon from '@ably/ui/core/Icon';
 import { isArray } from 'lodash';
 import HtmlDataTypes from '../../../../data/types/html';
+import * as styles from './dividers.module.css';
 import {
   inlineGridParagraph,
   inlineContentContainer,
@@ -46,6 +47,14 @@ const Aside = ({ data, attribs }: HtmlComponentProps<'div'>) => {
             <span className="ui-text-p2 font-bold text-neutral-1300 mb-12">Further Reading</span>
           </strong>
         </>
+      ) : attribs && attribs[`data-type`] === `see-evidence` ? (
+        <>
+          <span className={`${leftSideElement} ${styles['see-evidence-element']}`}>&nbsp;</span>
+          <strong className={tipTitleElement}>
+            <span className="mr-3 text-3xl">🔎</span>
+            <span className="ui-text-p2 font-bold text-neutral-1300 mb-12">See evidence</span>
+          </strong>
+        </>
       ) : attribs && isVersioningInfo ? (
         <>
           <span

src/components/blocks/dividers/dividers.module.css

@@ -21,6 +21,9 @@ span.left-side-element {
 .further-reading-element {
   background-color: #08fe13;
 }
+.see-evidence-element {
+  background-color: #14b8a6;
+}
 
 strong.tip-title-element {
   margin-left: var(--spacing-16);

src/pages/docs/channels/options/deltas.mdx

@@ -31,6 +31,10 @@ As delta compression is specified by a subscriber, the publisher has no control
 
 There is no constraint on how many publishers or subscribers there are. If there are multiple publishers, then deltas can still be generated, and they will be determined based on the order of messages. Deltas are calculated strictly based on the message ordering in that channel, with the effectiveness being dependent on the level of similarity between successive payloads.
 
+<Aside data-type='see-evidence'>
+Messages published using Realtime have consistent ordering for all subscribers, with each message assigned a unique serial number to preserve its place. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/message-ordering)
+</Aside>
+
 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.
 
 <If lang="javascript,nodejs">

src/pages/docs/connect/index.mdx

@@ -151,6 +151,10 @@ A connection ID is a unique identifier given to a connection, allowing for ident
 
 An active connection ID is guaranteed to be unique in the Ably system whilst it is active, i.e. no other connection will share that connection ID. However, Ably reserves the right to generate a new connection ID later that may be the same as a previously discarded connection ID (once the connection is closed). Therefore customers are advised to not use the connection ID as a perpetual unique identifier as it is possible that a connection ID may be used many times.
 
+<Aside data-type='see-evidence'>
+If a client reconnects within two minutes, full connection recovery with exactly-once delivery is guaranteed. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/idempotency#connection-recovery-and-exactly-once-delivery)
+</Aside>
+
 ### Connection metachannels <a id="metachannels"/>
 
 [Metachannels](/docs/metadata-stats/metadata/subscribe) are a namespace of channels beginning with the [meta] qualifier, distinguishing them from regular channels. For connections there is a specific `[meta]connection.lifecycle` channel that publishes messages about the lifecycle of realtime connections. The connection lifecycle consists of a number of [connection states](/docs/connect/states#available-connection-states) that can be observed and interacted with using methods available on the connection object.
@@ -222,6 +226,10 @@ By default, the Ably Pub/Sub JavaScript SDK adds a listener for the `beforeunloa
 
 If a connection to Ably is not explicitly closed when there is a page unload event, then the connection state is preserved by Ably for 2 minutes. Preserving connection state for 2 minutes when there is an unexpectedly dropped connection provides the opportunity for the client to reconnect and resume the connection without losing any messages.
 
+<Aside data-type='see-evidence'>
+Ably's SDKs automatically resolve edge network failures within 30 seconds, keeping your users connected even during infrastructure issues. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/edge-network)
+</Aside>
+
 ### Reliability considerations
 The `beforeunload` event can be unreliable and is not guaranteed to fire under certain circumstances:
 * The event may fire but the page is subsequently not disposed of (navigation can be cancelled).

src/pages/docs/connect/states.mdx

@@ -7,6 +7,10 @@ Connections to Ably will transition through multiple states throughout their lif
 
 Although connection state is temporary, Ably provides continuity of message delivery between a client and the service provided that a dropped connection is re-established by the client within a limited interval (typically around two minutes). After that time the connection becomes stale and the system will not attempt to recover the connection state.
 
+<Aside data-type='see-evidence'>
+Failed connections automatically try up to 5 alternative endpoints worldwide, maximizing reconnection success. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/edge-network)
+</Aside>
+
 An Ably SDK is responsible for managing a connection. This includes:
 
 * Selecting a transport, when multiple transports are available.

src/pages/docs/messages/index.mdx

@@ -44,6 +44,10 @@ Ensure a message was successfully published by checking the [history](/docs/stor
 
 Ably does not store per-message delivery logs, nor logs of who is subscribed to a channel at any point in time. This means it is not possible to check which users have received messages retroactively.
 
+<Aside data-type='see-evidence'>
+Applications maintain their state during disruptions - all messages are received in correct order with zero message loss. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/connection-recovery)
+</Aside>
+
 ## Message conflation <a id="conflation"/>
 
 Use message conflation to ensure that clients only ever receive the most up-to-date message, by removing redundant and outdated messages. Message conflation will aggregate published messages for a set period of time and evaluate all messages against a [conflation key](#routing). 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.

src/pages/docs/metadata-stats/metadata/subscribe.mdx

@@ -62,6 +62,10 @@ Seeing `channel.region.inactive` events in your [Dev Console](/docs/platform/acc
 
 A `channel.region.inactive` event indicates that a channel no longer has any clients in that specific region, or that the channel is shutting down altogether. This is part of Ably's normal operation to efficiently manage resources across its global infrastructure.
 
+<Aside data-type='see-evidence'>
+With 50% capacity headroom built in, Ably instantly absorbs traffic spikes without degradation or pre-provisioning. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/infrastructure-operations#resource-implications)
+</Aside>
+
 The following is an example of subscribing to all `[meta]channel.lifecycle` events:
 
 <Code>

src/pages/docs/metadata-stats/stats.mdx

@@ -18,6 +18,10 @@ redirect_from:
 
 Ably provides statistics at one minute intervals. They are aggregated by minute, hour, day and month. The most recent statistics can be delayed by up to six seconds.
 
+<Aside data-type='see-evidence'>
+Ably delivers over 500 billion messages monthly, demonstrating massive throughput capability. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/scalability)
+</Aside>
+
 Statistics are available as:
 
 * [Account statistics](#account) covering all applications in your account

src/pages/docs/presence-occupancy/index.mdx

@@ -14,3 +14,7 @@ Presence is a feature that tracks the membership of a presence set for a channel
 Occupancy provides metrics for a channel. It is a feature that counts how many of a thing are attached to a channel, such as the number of connections. It does not provide any information that can identify individual connections or clients attached to the channel.
 
 Take a chat application containing multiple chat rooms as an example. Occupancy would be a more lightweight method for displaying the popularity of rooms, by displaying the number of connections to each channel. Presence could be utilized in each channel to indicate which users are online, and to notify other members when someone leaves the room.
+
+<Aside data-type='see-evidence'>
+Ably's tiered fanout architecture allows it to scale to handle millions of subscribers per channel. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/platform-scalability#handling-high-scale-fanout)
+</Aside>

src/pages/docs/presence-occupancy/occupancy.mdx

@@ -8,6 +8,10 @@ redirect_from:
 
 Occupancy provides high level metrics about the clients attached to a channel. This includes the number of [connections](/docs/connect) currently attached to a channel, and the number of connections attached that are permitted to publish and subscribe to the channel.
 
+<Aside data-type='see-evidence'>
+Whether there are many lightly-loaded channels or fewer heavily-loaded ones, scaling and placement strategies ensure capacity is added as required and load is effectively distributed. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/platform-scalability#how-ably-achieves-scalability)
+</Aside>
+
 ## Occupancy metric categories <a id="occupancy-metrics"/>
 
 The following are the metric categories that occupancy reports:

src/pages/docs/presence-occupancy/presence.mdx

@@ -32,6 +32,11 @@ The following presence events are emitted:
 |-------|-------------|
 | Enter | A new member has entered the channel |
 | Leave | A member who was present has now left the channel. This may be a result of an explicit request to leave or implicitly when detaching from the channel. Alternatively, if a member's connection is abruptly disconnected and they do not resume their connection within a minute, Ably treats this as a leave event as the client is no longer present |
+
+<Aside data-type='see-evidence'>
+Ably's edge network bypasses DNS entirely when clients can't reach primary endpoints. SDKs automatically reconnect to backup endpoints instead of waiting several minutes for DNS to make changes. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/edge-network)
+</Aside>
+
 | Update | An already present member has updated their [member data](#member-data). Being notified of member data updates can be useful, for example, it can be used to update the status of a user when they are typing a message |
 | Present | When subscribing to presence events on a channel that already has members present, this event is emitted for every member already present on the channel before the subscribe listener was registered |
 

src/pages/docs/protocols/index.mdx

@@ -15,6 +15,10 @@ Ably helps customers migrate from other data streaming networks including PubNub
 
 Protocol adapters ensure interoperability between different protocols. For example, you can publish sensor data from an MQTT device, subscribe to that data using a Pusher client library for dashboard display, support mobile apps using Ably SDKs, and process data using AMQP worker queues - all within the same system.
 
+<Aside data-type='see-evidence'>
+Direct site-to-site distribution means that messages are delivered to all subscribers in the minimum time. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/message-ordering#multi-region)
+</Aside>
+
 Migration times typically range from a few hours (using protocol adapters) to a week, depending on your migration strategy and whether you choose to adopt Ably's native SDKs immediately or transition gradually.
 
 A full list of Ably SDKs can be found on the [SDK page](/docs/sdks).

src/pages/docs/protocols/mqtt.mdx

@@ -26,6 +26,10 @@ Using the MQTT adapter will be a little slower than using an Ably SDK, as an ada
 
 While the adapter can be useful for devices which need to use MQTT, there are many benefits to using an Ably SDK, such as continuity guarantees, fallback host support, history and presence. As a result, if an Ably SDK is available for your platform, it is recommended you consider using it instead of the protocol adapter.
 
+<Aside data-type='see-evidence'>
+Users in the same region will have a consistent experience with all subscribers observing messages in the same order. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/message-ordering#practical-implications-of-dual-ordering)
+</Aside>
+
 Our MQTT adapter only supports features supported by both the MQTT protocol and the Ably platform:
 
 * Only supports MQTT 3.1.1 clients only, connection attempts using earlier protocol versions will be rejected

src/pages/docs/protocols/pubnub.mdx

@@ -10,6 +10,10 @@ Ably enables migration from PubNub to Ably using its PubNub Adapter. The protoco
 
 Using an adapter introduces some latency and is slower than using an Ably SDK. The PubNub adapter can have more variable latency than other adapters because PubNub's protocol is inherently long-polling based, which creates an impedance mismatch with Ably's WebSocket-based architecture. Some operations are quick with PubNub, but slower or impossible with Ably, and vice versa.
 
+<Aside data-type='see-evidence'>
+Ably delivers messages globally with a median latency of 37ms, validated by over 6 million daily measurements across its infrastructure. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/latency#latency)
+</Aside>
+
 Many of the advantages associated with using Ably, such as the use of WebSockets rather than long polling, [continuity guarantees](https://ably.com/four-pillars-of-dependability), and fallback host support are only available when using an Ably SDK. If an [Ably SDK](/docs/sdks) is available in your chosen platform, it is recommended you use that, or plan to transition to it eventually.
 
 You can use PuBNub and and an Ably SDK side-by-side as they are interoperable, with the exception of a few features.

src/pages/docs/protocols/pusher.mdx

@@ -9,6 +9,10 @@ Ably enables migration from Pusher to Ably using its Pusher Adapter. The protoco
 
 Using an adapter introduces some latency and is slower than using an Ably SDK, however the impact is typically 1-10ms. It will also be slightly slower than using Pusher natively, but only if you are close to whichever Pusher data center used. If you aren't close to the Pusher data center you've chosen, then the extra latency from using the adapter should be more than compensated for by being able to use a data center that is close to you. This is because Ably automatically connects clients to the data center closest to them.
 
+<Aside data-type='see-evidence'>
+Ably delivers messages globally with a median latency of 37ms, validated by over 6 million daily measurements across its infrastructure. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/latency#latency)
+</Aside>
+
 The Pusher Adapter provides some of the advantages of Ably, such as inter-regional message federation, however others, such as [continuity guarantees](https://ably.com/four-pillars-of-dependability), fallback host support, and [message history](/docs/storage-history/history) are only available when using an Ably SDK. If an [Ably SDK](/docs/sdks) is available in your chosen platform, it is recommended you use that, or plan to transition to it eventually.
 
 ## Supported features <a id="features"/>

src/pages/docs/protocols/sse.mdx

@@ -35,6 +35,11 @@ SSE is an excellent alternative to Ably SDK in memory-limited environments.
 ### Advantages of Ably SDKs and Realtime Protocol <a id="Advantages-of-Ably-SDKs-and-Realtime-Protocol"/>
 
 * Assured high service quality and resilience, particularly in DNS (Domain Name System) disruptions or network partitioning scenarios.
+
+<Aside data-type='see-evidence'>
+In catastrophic datacenter failures, Ably automatically reroutes all traffic in under 2 minutes, maintaining service continuity. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/edge-network)
+</Aside>
+
 * Access to a comprehensive range of features including, but not limited to, [publishing](/docs/push/publish), [presence](/docs/presence-occupancy/presence), [history](/docs/storage-history/history), [push notifications](/docs/push), [automatic payload encoding](/docs/channels/options/encryption), and [symmetric encryption](/docs/channels/options/encryption).
 * Optimal compatibility with browsers via the WebSocket protocol.
 

src/pages/docs/pub-sub/advanced.mdx

@@ -388,6 +388,10 @@ Subscribing to events server-side using the pub-sub pattern can be disadvantageo
 
 [Message queues](/docs/platform/integrations/queues) are more appropriate to use in this instance, as multiple worker servers enable Ably to distribute the load of messages received. This ensures that each message is only processed once, by any one of your worker servers.
 
+<Aside data-type='see-evidence'>
+Ably delivers messages globally with a median latency of 37ms, validated by over 6 million daily measurements across its infrastructure. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/latency#latency)
+</Aside>
+
 ### Subscription filters <a id="subscription-filters"/>
 
 Subscription filters enable you to subscribe to a channel and only receive messages that satisfy a filter expression.

src/pages/docs/pub-sub/index.mdx

@@ -7,6 +7,10 @@ Ably Pub/Sub enables you to implement the publish-subscribe (pub-sub) pattern. A
 
 [Channels](/docs/channels) are used to separate messages into different topics. [Messages](/docs/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. Whilst billions of messages may be delivered by Ably, clients receive only the messages on the channels they subscribe to.
 
+<Aside data-type='see-evidence'>
+Ably delivers messages globally with a median latency of 37ms, validated by over 6 million daily measurements across its infrastructure. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/latency#latency)
+</Aside>
+
 To get started with sending and receiving messages, all you need to do is:
 
 * [Use a channel](#use)

src/pages/docs/push/index.mdx

@@ -23,6 +23,10 @@ Publishing directly sends push notifications to specific devices or browsers ide
 
 Publishing via channels uses a [Pub/Sub](/docs/channels/messages) model. Messages are sent to channels to which multiple devices or browsers can subscribe. When a message is published to a channel, all devices or browsers subscribed to that channel receive the notification. This approach is particularly powerful for simultaneously publishing messages to multiple users.
 
+<Aside data-type='see-evidence'>
+Ably's infrastructure serves billions of devices each month, handling enterprise-scale traffic reliably and quickly. [Click here for evidence 🔬](https://ably.com/docs/platform/architecture/scalability)
+</Aside>
+
 <Aside data-type="note">
 Push subscriptions do not count toward your connection limit since devices don't need to maintain an active connection to receive push notifications. However, publishing push notifications via channels does activate those channels, so your concurrent peak channel count will equal the number of channels you publish to simultaneously.
 </Aside>