From a05606aa55a4aa56ee09b8190c06ee4462b62680 Mon Sep 17 00:00:00 2001 From: Greg Holmes Date: Thu, 21 Aug 2025 11:43:11 +0100 Subject: [PATCH 1/2] Remove root directory files --- .../partials/types/_client_options.textile | 2 +- content/partials/types/_token_params.textile | 2 +- content/root/glossary.textile | 250 ------------------ content/root/ids-and-keys.textile | 85 ------ content/root/key-concepts.textile | 168 ------------ content/root/tools.textile | 68 ----- index.textile | 2 +- 7 files changed, 3 insertions(+), 574 deletions(-) delete mode 100644 content/root/glossary.textile delete mode 100644 content/root/ids-and-keys.textile delete mode 100644 content/root/key-concepts.textile delete mode 100644 content/root/tools.textile diff --git a/content/partials/types/_client_options.textile b/content/partials/types/_client_options.textile index a5e6fc0417..943c723fa2 100644 --- a/content/partials/types/_client_options.textile +++ b/content/partials/types/_client_options.textile @@ -12,7 +12,7 @@ h4. - tlsTls:tls := _true_ A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. "Find out more about TLS":https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls
__Type: @Boolean@__ -- clientIdClientIdclient_id:client_id := A client ID, used for identifying this client when publishing messages or for presence purposes. The @clientId@@client_id@@ClientId@ can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a @clientId@@client_id@@ClientId@ may also be implicit in a token used to instantiate the library; an error will be raised if a @clientId@@client_id@ specified here conflicts with the @clientId@@client_id@@ClientId@ implicit in the token. "Find out more about client identities":/docs/key-concepts#client-identity
__Type: @String@__ +- clientIdClientIdclient_id:client_id := A client ID, used for identifying this client when publishing messages or for presence purposes. The @clientId@@client_id@@ClientId@ can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a @clientId@@client_id@@ClientId@ may also be implicit in a token used to instantiate the library; an error will be raised if a @clientId@@client_id@ specified here conflicts with the @clientId@@client_id@@ClientId@ implicit in the token. "Find out more about client identities":/docs/auth/identified-clients
__Type: @String@__ - useTokenAuthUseTokenAuthuse_token_auth:use_token_auth := _false_ When true, forces "Token authentication":/docs/auth/token to be used by the library. Please note that if a @client_id@@clientId@ is not specified in the "@ClientOptions@":/docs/api/realtime-sdk/types#client-options or "@TokenParams@":/docs/api/realtime-sdk/types#token-params, then the Ably Token issued will be "anonymous":https://faqs.ably.com/authenticated-and-identified-clients.
__Type: @Boolean@__ diff --git a/content/partials/types/_token_params.textile b/content/partials/types/_token_params.textile index ab3035218f..4ae27b1499 100644 --- a/content/partials/types/_token_params.textile +++ b/content/partials/types/_token_params.textile @@ -24,7 +24,7 @@ h4. - capabilityCapability:capability := JSON stringified capability of the "Ably Token":/docs/api/realtime-sdk/authentication#token-details. If the "Ably Token":/docs/api/realtime-sdk/authentication#token-details request is successful, the capability of the returned "Ably Token":/docs/api/realtime-sdk/authentication#token-details will be the intersection of this capability with the capability of the issuing key. "Find our more about how to use capabilities to manage access privileges for clients":/docs/auth/capabilities. __Type: @String@@Capability@__ -- clientIdClientIdclient_id:client_id := A client ID, used for identifying this client when publishing messages or for presence purposes. The @clientId@@client_id@@ClientId@ can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a @clientId@@client_id@@ClientId@ may also be implicit in a token used to instantiate the library; an error will be raised if a @clientId@@client_id@@ClientId@ specified here conflicts with the @clientId@@client_id@@ClientId@ implicit in the token. "Find out more about client identities":/docs/key-concepts#client-identity
__Type: @String@__ +- clientIdClientIdclient_id:client_id := A client ID, used for identifying this client when publishing messages or for presence purposes. The @clientId@@client_id@@ClientId@ can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a @clientId@@client_id@@ClientId@ may also be implicit in a token used to instantiate the library; an error will be raised if a @clientId@@client_id@@ClientId@ specified here conflicts with the @clientId@@client_id@@ClientId@ implicit in the token. "Find out more about client identities":/docs/auth/identified-clients
__Type: @String@__ - nonceNonce:nonce := An optional opaque nonce string of at least 16 characters to ensure uniqueness of this request. Any subsequent request using the same nonce will be rejected.
__Type: @String@__ diff --git a/content/root/glossary.textile b/content/root/glossary.textile deleted file mode 100644 index 7b7f0eed73..0000000000 --- a/content/root/glossary.textile +++ /dev/null @@ -1,250 +0,0 @@ ---- -title: Glossary -meta_description: "A glossary of common terms used in Ably products and the Ably documentation." -meta_keywords: "glossary, terms, descriptions" -section: root -index: 50 -jump_to: ---- - -h2(#amqp). AMQP - -Advanced Message Queuing Protocol (AMQP) is a protocol that can be used to retrieve messages from a queue. - -See the "queues documentation":/docs/integrations/queues and "Wikipedia":https://en.wikipedia.org/wiki/Advanced_Message_Queuing_Protocol for further information. - -h2(#api-key). API key - -Ably uses API keys for authentication, either directly ("basic authentication":/docs/auth/basic) or for generating tokens ("token authentication":/docs/auth/token). Each application will have at least one API key and each key can confer different rights for access to channels and other resources within its associated application. - -API keys contain three parts: the public app ID and public app key ID (which, combined, form the API key ID) and the API key secret. API keys should be kept secret and only shared with trusted parties. - -h2(#apps). Apps - -An app (or application) in the context of Ably is a grouping of channels, queues and other resources that are managed as a collection. An app defines a namespace for its channels and queues so that they are unique to that application. An Ably account can contain multiple apps, with each app having its own set of API keys to limit client access to its resources. Access can then be further limited to a subset of channels and queues within an app and the permissions on those resources, such as whether a client can publish or subscribe to them. - -h2(#atm). ATM - -Active Traffic Management (ATM) is an "Enterprise-only":https://ably.com/pricing service that allows Ably engineers to manage the endpoints that customers connect to. This allows Ably to proactively route customer traffic to specific data centers or regions, ensuring service availability in the event of an incident. - -h2(#batch-requests). Batch requests - -Batch requests enable multiple queries to be made in parallel as part of a single HTTP request. Examples include publishing a message to multiple channels and retrieving the presence state of multiple channels. - -See the "batch request documentation":/docs/messages/batch#batch-publish for further information. - -h2(#capability). Capability - -A capability represents a collection of resources, each with a set of permitted operations. For example, a capability can grant permission to subscribe to the @finance:@ channel namespace. Capabilities are used to define the rights associated with an authentication credential such as an API key or token, although the rights expressed by a capability for a token cannot exceed those of its associated API key. - -See the "capabilities documentation":/docs/auth/capabilities for further information. - -h2(#channels). Channels - -Channels are used to logically separate messages into different topics. Clients subscribe to channels for topics they are interested in, to receive all messages sent on those channels. When a publisher sends a message on a channel, all subscribers receive that message. - -See the "channels documentation":/docs/channels for further information. - -h2(#channel-namespaces). Channel namespaces - -Channel namespaces provide a way for certain properties (such as persistence) to be assigned to a group of channels, rather than requiring them to be assigned to individual channels. The namespace is the first colon-delimited segment of a channel name, or the channel name itself if no colon exists. For example, the channels @finance@ and @finance:approvals@ would both be considered part of the @finance@ namespace. - -See the "channel namespace documentation":/docs/channels#namespaces for further information. - -h2(#connection). Connection - -A connection to Ably must be established and maintained for realtime communication. A connection goes through several different connection states throughout its lifecycle, such as @connecting@, @connected@ and @suspended@. - -See the "connection documentation":/docs/connect for further information. - -h2(#control). Control API - -The Control API is a REST API that enables an Ably account to be managed programmatically. This includes the creation and management of resources such as "Ably apps":#apps, "API keys":#api-key and "queues":#queues. - -See the "Control API documentation":/docs/platform/account/control-api for further information. - -h2(#dashboard). Dashboard - -The Ably dashboard is the user interface for managing applications, viewing statistics, creating API keys and setting up integrations and channel rules. - -Once you have "registered":https://ably.com/sign-up for an account, you can "sign in":https://ably.com/login to view your dashboard. - -h2(#dead-letter). Dead letter queue - -Dead letter queues store messages that were intended to be delivered to a queue, but have failed to be processed correctly. They are created when a queue is provisioned, with one dead letter queue per application, not per queue. - -See the "dead letter queue documentation":/docs/integrations/queues#deadletter for further information. - -h2(#delta-compression). Delta compression - -Delta compression is a feature that enables a subscriber to only receive the difference between the payload of the current message and the one sent previously. It is used when there is a degree of similarity between successive messages. - -See the "delta compression documentation":/docs/channels/options/deltas for further information. - -h2(#deltas). Deltas - -See "delta compression.":#delta-compression - -h2(#firehose). Firehose - -Firehose is a feature that enables the realtime data published in Ably to be streamed directly into another streaming or queuing service such as "Amazon Kinesis":https://aws.amazon.com/kinesis/. - -See the "Firehose documentation":/docs/general/firehose for further information. - -h2(#idempotent). Idempotent - -An idempotent operation is one whose effect is the same whether it is performed once or multiple times. In the context of Ably, idempotence ensures that retried publish attempts, such as in response to a network failure, do not result in duplicate messages being published. - -See the "idempotent messages documentation":/docs/pub-sub/advanced#idempotency for further information. - -h2(#inband-occupancy). Inband channel occupancy - -The inband channel occupancy feature enables a client to subscribe to occupancy events related to a channel. The events are then delivered to that client as messages on the channel. - -See the "inband channel occupancy documentation":/docs/presence-occupancy/occupancy for further information. - -h2(#iot). IoT - -The Internet of Things (IoT) is a term used to describe a network of physical objects that use software or sensors to connect to the internet. Examples include smart meters, smart appliances and smart security systems. - -See "IoT at Ably":https://ably.com/solutions/iot-and-connected-devices and "Wikipedia":https://en.wikipedia.org/wiki/Internet_of_things for further information. - -h2(#jwt). JWT - -JSON Web Token (JWT) is an open standard for securely representing claims transmitted between parties. The claims and metadata of a JWT are in JSON format and can be verified by recipients because they are cryptographically signed. JWTs can be used for authenticating with Ably. - -See the "authentication documentation":/docs/auth/token#jwt for further information. - -h2(#kinesis). Kinesis - -Kinesis is serverless streaming data service for capturing, processing, and storing data streams provided by Amazon Web Services. You can use Ably's Firehose to set up a Kinesis rule to send data streams from Ably to Kinesis. - -See the "Kinesis rule documentation":/docs/integrations/streaming/kinesis for more information. - -h2(#lambda). Lambda - -Lambda is an event-driven serverless service provided by Amazon Web Services that allows users to easily run code when specified conditions are met. You can set up Ably "Webhooks":/docs/integrations/webhooks to trigger Lambda functions when events occur. - -See the "Lambda documentation":/docs/integrations/webhooks/lambda for more information. - -h2(#latency). Latency - -Latency is a measure of the delay between an operation being initiated and its effect. In the context of Ably, latency typically refers to the time elapsed between a message being published on a channel and being received by a channel subscriber on another connection. - -h2(#messages). Message - -A message is the unit of information sent using the Ably platform. Messages are sent by publishers on a channel and received by all subscribers to that channel. - -See the "messages documentation":/docs/channels/messages for further information. - -h2(#metachannels). Metachannel - -A metachannel is a channel that receives messages containing metadata or events relating to an application. Metachannels exist outside of regular channel namespaces and instead have their names qualified with @[meta]@, for example @[meta]log@ or @[meta]channel.lifecycle@. - -See the "metachannels documentation":/docs/metadata-stats/metadata/subscribe for further information. - -h2(#mqtt). MQTT - -Message Queuing Telemetry Transport (MQTT) is a lightweight publish-subscribe protocol for minimal code implementations, or low bandwidth networks. - -See "Wikipedia":https://en.wikipedia.org/wiki/MQTT for further information. - -h2(#mqtt-adapter). MQTT Adapter - -The Ably MQTT Adapter can translate between MQTT and the Ably protocol. - -See the "MQTT Adapter documentation":/docs/protocols/mqtt for further information. - -h2(#occupancy). Occupancy - -Occupancy is a feature that enables you to view the number of occupants attached to a channel and specific metrics about their connections. - -See the "occupancy documentation":/docs/presence-occupancy/occupancy for further information. - -h2(#persistence). Persistence - -Persistence (or persisted history) is a feature that enables messages on a channel to be stored on disk. The last message published on a channel can be stored for 365 days, or all messages on a channel can be stored from between 24 hours up to 365 days or longer, based on your account package. Persisted messages can be retrieved by API or replayed to clients using the "rewind":#rewind feature when they attach to a channel. - -See the "history documentation":/docs/storage-history/history for further information. - -h2(#presence). Presence - -The presence feature enables clients in a channel to be aware of other presence members in the same channel. Each client has a presence state, and that state is communicated to all presence subscribers on the channel when a client enters or leaves. - -See the "presence documentation":/docs/presence-occupancy/presence for further information. - -h2(#pub-sub). Pub/Sub - -Publish-subscribe (or pub/sub) is a pattern of information exchange where a publisher does not need to interact directly with, or even know the existence or identities of, any subscribers. Conversely, a subscriber can gain access to published information without interacting directly with the publisher. - -h2(#publisher). Publisher - -A publisher is an entity that sends messages on one or more channels. - -See the "channels documentation":/docs/channels for further information. - -h2(#push-notification). Push notifications - -Push notifications are messages that are pushed to a device's user interface such as a visual notification. Ably can deliver push notifications using platforms such as "Apple's Push Notification service":https://developer.apple.com/documentation/usernotifications or "Google's Firebase Cloud Messaging service":https://firebase.google.com/docs/cloud-messaging. - -See the "push notification documentation":/docs/push for further information. - -h2(#queues). Queues - -Ably Queues provide a service that distributes messages between subscribers, so that each message is only received by one subscriber. This model is referred to as "competing consumers" and is different to the pub/sub model where each message is delivered to every subscriber. Ably uses integration rules to publish messages received in a channel into a queue. - -See the "queues documentation":/docs/integrations/queues for further information. - -h2(#realtime). Realtime interface - -The realtime interface of an Ably SDK is implemented using an Ably-defined protocol, with communication primarily over WebSockets. It enables devices and browsers to maintain a persistent connection to Ably. SDKs are available in various languages and platforms, such as JavaScript, Ruby and Android. - -See the "available SDKs":/docs/sdks for further information on the realtime interface and the languages and platforms supported by the SDKs. - -h2(#rest). REST interface - -The REST interface of an Ably SDK communicates with the Ably service using the HTTP protocol and is effectively stateless. The REST interface provides a convenient way to access the "REST HTTP API":/docs/api/rest-api and is intended to be used by clients that don't require realtime updates. - -See the "available SDKs":/docs/sdks for further information on the REST interface and the languages and platforms supported by the SDKs. - -h2(#rewind). Rewind - -Rewind is a feature that enables a client to subscribe to a channel from a position earlier than the current point in time. @rewind@ is a channel parameter that can specify an earlier position as a time interval or set number of messages. When a client first attaches to a channel using rewind, all messages from that earlier position are replayed to them. - -See the "Rewind documentation":/docs/channels/options/rewind for further information. - -h2(#sqs). SQS - -Simple Queue Service (SQS) is an Amazon Web Service that allows you to send, store, and receive messages between systems. You can use Ably's "Firehose":/docs/general/firehose feature to set up a SQS rule for sending from Ably to SQS. - -See the "SQS rule documentation":/docs/integrations/streaming/sqs for more information. - -h2(#sse). SSE - -Server Sent Events (SSE) is an HTTP-based protocol for streaming events from a server to a client. In the context of Ably, SSE can be used to establish a realtime subscription to a set of channels. - -See the "SSE documentation":/docs/protocols/sse for further information on using SSE with Ably. - -h2(#stomp). STOMP - -Simple (or Streaming) Text Orientated Messaging Protocol (STOMP) is a protocol that can be used to retrieve messages from a queue. - -See the "queues documentation":/docs/integrations/queues and "Wikipedia":https://en.wikipedia.org/wiki/Streaming_Text_Oriented_Messaging_Protocol for further information. - -h2(#subscriber). Subscriber - -A subscriber is an entity that establishes a realtime connection to Ably in order to receive messages on one or more channels. - -See the "channels documentation":/docs/channels for further information. - -h2(#webhooks). Webhooks - -Webhooks are HTTP callbacks that are triggered by a specified event. Ably supports incoming and outbound webhooks. Incoming webhooks take data from an external application or service and publish it as messages on a channel. Outgoing webhooks notify an external application or service when a message or event is received. - -See the "incoming webhook documentation":/docs/integrations/inbound/webhooks and "outbound webhook documentation":/docs/integrations/webhooks for further information. - -h2(#websocket). WebSocket - -WebSocket is a communication protocol. A WebSocket connection is established with Ably when a client is instantiated using the realtime interface of an SDK. This connection is multiplexed, enabling multiple channels to share it. Messages can then be sent between Ably and the client in realtime. - -See the "websocket deep dive":https://ably.com/topic/websockets and "Wikipedia":https://en.wikipedia.org/wiki/WebSocket for further information. diff --git a/content/root/ids-and-keys.textile b/content/root/ids-and-keys.textile deleted file mode 100644 index 84f8aead9c..0000000000 --- a/content/root/ids-and-keys.textile +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Finding your Ably Account ID, App IDs, and API Keys -meta_description: "Guidance on how to find useful IDs and Keys" -meta_keywords: "Keys, ID, Account ID, App ID, API Key, Authentication" -section: root -index: 19 -jump_to: - Help with: - - Finding an Account ID#account-id - - Finding an App ID#app-id - - Finding an API Key#api-key ---- - -Ably uses IDs to specify which account or app an operation should affect, and API keys to authenticate these operations. - -This page covers how to find your: - -* "Account ID":#account-id -* "App ID":#app-id -* "API Key":#api-key - -h2(#account-id). Account ID - -Account IDs are used by operations that affect your entire account, such as listing the apps associated with a particular account. - -h3(#find-account-id). How to find your account ID - -In the "Ably dashboard":https://ably.com/accounts/any click the dropdown from the top right, then select 'Account settings': - - - Account settings - - -Note, if you have more than one account, you can change accounts from the top left dropdown. - -Your account settings are displayed and you can now find your account ID on this page: - - - Account ID - - -h2(#app-id). App ID - -App IDs are used by operations that affect individual apps, such as creating an API key. - -h3(#find-app-id). How to find your app ID - -In the "Ably dashboard":https://ably.com/accounts/any select the app you want to find the app ID for. Click on the 'Settings' tab: - - - App settings - - -The "App ID" is displayed under 'Application settings': - - - App ID - - -h2(#api-key). API key - -Ably uses API keys for authentication, either directly ("basic authentication":/docs/auth/basic) or for generating tokens ("token authentication":/docs/auth/token). Each application has at least one API key and each key can have different capabilities specified. - -API keys contain three parts: the public app ID and public app key ID (which, combined, form the API key ID) and the API key secret. An example API key is: @I2E_JQ.OqUdfg:EVKVTCBlzLBPYJiCZTsIW_pqylJ9WVRB5K9P19Ap1y0@, made up of: - -* @I2E_JQ.OqUdfg@ is the public API key ID (made from the public app ID and app key ID) -** @I2E_JQ@ is the public app ID (the part before the first period) -** @OqUdfg@ is the public app key ID (after the period and before the colon) -* @EVKVTCBlzLBPYJiCZTsIW_pqylJ9WVRB5K9P19Ap1y0@ is the API secret key (after the colon) - -API keys should be kept secret. - -h3(#find-api-key). How to find your API Key - -In the "Ably dashboard":https://ably.com/accounts/any select the app you want to find the API keys for. Click on the "API Keys" tab: - - - API keys - - -Your API keys are then individually displayed with only the public key segment showing, click 'show' to reveal your API secret key: - - - API key - diff --git a/content/root/key-concepts.textile b/content/root/key-concepts.textile deleted file mode 100644 index 3e4a8f03d2..0000000000 --- a/content/root/key-concepts.textile +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: Key concepts -meta_description: "An introduction to Ably and its key concepts." -meta_keywords: "introduction, channels, persistence, messages, presence, state recovery, redundancy" -section: root -index: 20 -jump_to: - Concepts: - - Channels - - Presence - - Integrations - - Authentication - - Global message routing - - Connection state recovery - - Redundancy - - Security and Encryption - - Any internet device -redirect_from: - - /docs/how-ably-works - - /docs/root/how-ably-works ---- - -Ably's realtime platform enables data to be streamed between Internet-connected devices such as browsers, phones, servers and IoT (Internet of Things) devices in milliseconds. The Ably platform provides developers with enterprise scale messaging by delivering a "highly-available service":https://faqs.ably.com/ablys-uptime-guarantee, "message delivery guarantees":https://faqs.ably.com/message-durability-and-qos-quality-of-service and low latency on a global basis. "Round trip latencies":https://faqs.ably.com/round-trip-latency-and-performance are typically less than 60ms. - -h2. Pub/Sub - -At its core, Ably is a cloud-based "pub/sub":https://ably.com/pub-sub-messaging Platform-as-a-Service ensuring any device publishing messages to Ably will be received in real time by any number of subscribing devices. But it is more than that. Ably makes it possible for developers to build apps and infrastructure that can communicate in realtime without the worries of managing scale, latency, data durability, integrity and storage, seamless connection recovery, device interoperability, network outages, encryption, security and authentication, throttling, and denial of service attacks, to name a few. Additionally, our platform supports both "pub/sub":https://ably.com/pub-sub-messaging and "message-queue":/docs/integrations/queues patterns. - -In order to understand how Ably works, and why "pub/sub":https://ably.com/pub-sub-messaging is only one part of the problem we solve for developers, we explain the key concepts in the following sections. - -h3(#channels). Channels - -The Ably service organizes the traffic within any application into named channels. Clients connected to Ably can either be publishers (they push messages with data to Ably), subscribers (they wait for messages to be pushed from Ably to them), or both. Messages are always published over a named channel. Channels are used to filter messages, so whilst billions of messages may be delivered by Ably, subscribers will only receive the messages on the channels they subscribe to. - -Channels are uniquely identified by a string specified when publishing to or attaching to a channel. Publishers and subscribers are completely decoupled: a publisher can publish a message without any subscribers on the channel; subscribers can listen on channels that don't yet have publishers; arbitrarily many subscribers can receive a single message published on a channel. In other words, Ably channels support one-to-many (fan-out), many-to-one (fan-in), and many-to-many. - -The following diagram illustrates a very simple use case for channels. The server and vehicle are publishing messages on channels without any knowledge of subscribers. One mobile device is both a subscriber and publisher and is publishing its location, but also subscribing for alerts. All other devices are subscribed to just one channel. - - - Channel concept diagram - - -h4. Message persistence - -All messages received by Ably are immediately stored in RAM in three separate physical locations for redundancy. They are then persisted as follows: - -* In server RAM for 2 minutes in every location that the channel is active -* On disk in three locations for 24 - 72 hours if the "channel is configured to persist messages":/docs/general/channel-rules-namespaces - -Whilst Ably is used primarily by clients to receive messages in real time, Ably provides a "history API":/docs/storage-history/history that allows clients to retrieve older messages from memory and/or disk. - -h3(#presence). Presence - -Presence provides awareness of other clients that are connected to Ably and present on a channel. Each member present on a channel has a unique client identifier and an optional payload that can be used to describe the member’s status or attributes. Presence allows you to quickly build apps such as chat rooms or multiplayer games as Ably will automatically keep track of who is present in real time across any device. Clients can also subscribe to the presence events and members on a channel without being present themselves. - -There are three presence operations, @enter@ for new members, @update@ allowing the payload data associated with a member to be updated and announced to everyone, and @leave@ for members that have requested to leave or who have left implicitly as a result of their connection being disconnected. - -The complete set of members present and their optional payload is stored by Ably in server RAM in at least three locations. Like messages, presence events such as @enter@ and @leave@ are persisted in RAM for 2 minutes, and optionally to disk in three locations for 24 - 72 hours if the "channel is configured to persist messages":/docs/general/channel-rules-namespaces - -h3(#integrations). Integrations - -Whilst pub/sub channels are well suited to fan-out, fan-in or one-to-one communication between servers and/or devices, they are less well suited to servers that want to consume realtime data and distribute that workload between server nodes. Consuming realtime data in a scalable, reliable and stateless way requires a different strategy, and our Ably Integrations deliver that through streams and message queues. - -Ably Integrations are powered by a rules engine that enables realtime data to be streamed into our "Ably Queue service":/docs/integrations/queues or any third party queue, streaming provider or endpoint. - - - Ably Integrations diagram - - -* **Message queues** allow you to distribute the message processing work between your servers to enable horizontal scaling and reliability for applications that need to respond to realtime data as it happens. "Find out more":/docs/integrations/queues -* **Firehose** allows you to stream realtime data published within the Ably core platform directly to another streaming or queueing service such as Amazon Kinesis or Amazon SQS. "Find out more":/docs/general/firehose -* **Webhooks** allow us to notify your servers over HTTP or trigger server-less functions in real time when devices become present, channels become active, or messages are published. "Find out more about Webhooks":/docs/general/webhooks - -h3(#authentication). Authentication - -Ably supports two forms of authentication described below. For an in-depth explanation, view the "authentication documentation":/docs/auth. - -h4. Basic Authentication - -Basic authentication is the simplest form of authentication, allowing clients to communicate with Ably by including the complete private API key within the URL or request headers. To mitigate the risks of sending a private key over the Internet, basic authentication is only permitted over an encrypted "TLS":https://en.wikipedia.org/wiki/Transport_Layer_Security connection. Private API keys and their capabilities (permissions) are managed within an "app's dashboard":https://ably.com/dashboard. In most cases, we do not recommend that basic authentication is used as it requires that you share your private API key with the client that is connecting to Ably. Our recommendation is to only use basic authentication on your trusted servers. - -h4. Token Authentication - -Token authentication provides a means for clients to connect to Ably without a private API key. Tokens have a time-to-live (they expire) ensuring that any compromise of a token will have a limited impact. Token authentication is also used to identify clients and provide fine-grained access control on a per-client basis. - -Most often, token authentication is implemented as follows: an "Ably TokenRequest":/docs/api/rest-sdk/authentication#token-request is generated by your server; it is signed using your private API key and then passed to the client; the realtime client uses this Ably TokenRequest to request an "Ably Token":/docs/api/realtime-sdk/authentication#tokens from Ably directly. This approach is recommended as at no point does your server need to communicate directly with Ably and ever communicate the secret API key. - - - Ably TokenRequest from your server concept diagram - - -An equally viable method is to generate a JSON Web Token (JWT) on your server; it is signed using your private API key and then passed to the client; the realtime client uses this JWT to authenticate with Ably. A JWT which has been constructed to be compatible with Ably is known as an "Ably JWT":/docs/api/realtime-sdk/authentication#ably-jwt. Any third party software can be used to generate this JWT using the Ably private API key to sign it. - - - Ably JWT from your server concept diagram - - -h5(#client-identity). Client identity and access control - -A client using token authentication is considered to either anonymous, or identified if a client ID exists in the token. All messages, presence state and connection state for "identified clients":/docs/auth/identified-clients contain the trusted client ID and are accessible by other clients. As a private key is needed to generate a token for a client with a client ID, the client ID can be trusted by other clients. Find out "more on identified clients":/docs/auth/identified-clients. - -Tokens are limited to the capabilities of the API key used to create the token. The capabilities of a token may be limited further using fine-grained permissions using a combination of the operation (such as publish, subscribe, presence) and the channel(s). Find out "more on token capabilities":/docs/auth/capabilities. - -h3(#global-message-routing). Global message routing - -The Ably service, running in "over 16 datacenters and 175+ edge acceleration points-of-presence globally":https://ably.com/network, provides a true mesh distributed system ensuring that there is both no single point of congestion and no single point of failure. Ably is designed to always route messages using the least number of network hops minimizing latency and ensuring maximum performance for clients no matter their location. - -The diagram below explains how Ably solves the challenge of efficient global routing at all times: - -* The publish only server located in New York is routed to the nearest datacenter (US East) using our latency based routing; @Msg A@ published to US East is routed directly to clients in US East, and once to every other datacenter with clients subscribed for messages; Clients in all other regions subscribed for messages receive @Msg A@ directly from the datacenter they are connected to -* Publish & subscribe client in London is routed to the nearest data (EU West) using our latency based routing; @Msg B@ published to EU West is routed directly to clients in EU West, and once to every other datacenter with clients subscribed for messages; Clients in all other regions subscribed for messages receive @Msg B@ directly from the datacenter they are connected to - - - Global routing diagram - - -h3(#connection-state-recovery). Connection state recovery - -It is common for devices to have constantly changing network conditions as a result of moving from a mobile data network to a WiFi network, being in a tunnel for a short period, or perhaps due to intermittent network issues. We believe that developers shouldn't have to worry about service continuity between brief connection loss. As such, Ably ensures that the connection state for a client is retained on our servers whenever a client is disconnected abruptly. By retaining a client's connection state on our servers, this allows us to replay all channel activity back to a client as soon as it reconnects. - -Ably provides the following assurances in regards to connection state recovery: - -* Any client that is able to reestablish a connection within 2 minutes will remain attached on all channels and will not lose any messages published by other clients whilst disconnected; -* All messages published on channels whilst the client was disconnected will be replayed to the recovered client in the order they were published; -* There is no upper limit in regards to the number of messages that are queued for disconnected clients, however if a threshold to ensure system stability is exceeded then an error is emitted; -* Connection state recovery provides certainty and is thus binary in its behavior - it either succeeds and all operations continue as if the connection was never disconnected, or it fails by detaching the channel or emitting an error on the channel so that the developer is made aware of the state loss and is able to respond accordingly - -h3(#redundancy). Redundancy - -The Ably global platform is designed to provide rigorous "uptime guarantees":https://faqs.ably.com/ablys-uptime-guarantee. This is possible because redundancy has been addressed in not just every area of our systems, but also within the client libraries used by our customers. Our redundancy is best depicted in the following diagram: - - - Ably redundancy diagram - - -h4. Jargon buster: - -- "Connection state recovery":https://faqs.ably.com/connection-state-recovery := ensures that clients disconnected abruptly from Ably can resume their connection -- "Proactive health checked DNS":https://faqs.ably.com/routing-around-network-and-dns-issues := our DNS TTL is kept very low allowing us to route traffic away from unhealthy datacenters in 60s once our monitoring systems detect an issue -- "Secondary domain endpoints":https://faqs.ably.com/routing-around-network-and-dns-issues := we operate a completely isolated backup domain that is used by our client libraries if the primary @ably.io@ endpoint is failing -- "Host fallback":https://faqs.ably.com/routing-around-network-and-dns-issues := clients that are unable to connect to their closest datacenter using the primary @ably.io@ domain will automatically fallback to an alternative datacenter using the secondary domain -- "Auto scaling":https://faqs.ably.com/are-you-able-to-scale-ably-indefinitely-to-meet-demand := as load on the system increases, more servers are automatically provisioned in every part of the system that requires additional capacity -- "Load balancers":https://faqs.ably.com/are-you-able-to-scale-ably-indefinitely-to-meet-demand := our load balancers are elastic and scale to meet demand, but are also responsible for intelligently routing traffic to existing and new frontends that are coming online -- "Stateless":https://en.wikipedia.org/wiki/Stateless_protocol := our frontends do not store any state thus ensuring that frontends can come online quickly and service new requests, but also go offline easily without data loss -- "Self-healing cluster":https://faqs.ably.com/self-healing-cluster := as problems are detected in the system, they are isolated or remedied by our automated health servers -- "Data replicas":https://faqs.ably.com/ablys-uptime-guarantee := all data is stored in at least three datacenters across at least two regions ensuring data availability through any imaginable failure -- "Multiple availability zones":https://ably.com/network := in every region our our data is replicated between servers in at least two independent datacenters ensuring outages in one datacenter cannot cause data loss -- "Multiple regions":https://ably.com/network := ensuring that data is always stored in at least two regions protects against complete region outage or network partitioning -- "Edge acceleration points-of-presence":https://ably.com/network := servers running in 175+ locations globally that accept connections close to where users are (reducing latency) and accelerate traffic to an Ably datacenter using dedicated network connections (not over the Internet) - - -h3(#security-and-encryption). Security and Encryption - -By default all of our client libraries use TLS when communicating with Ably over REST or via our Realtime transports such as "WebSockets":https://ably.com/topic/websockets. We do not charge customers for using TLS and actively encourage everyone to always use TLS as it provides a secure transport for communication with Ably with very little practical overhead. - -Whilst TLS encryption ensures that messages in transit to and from Ably cannot be intercepted, inspected, or tampered with, it does not ensure that the Ably service itself is unable to (in theory) inspect your messages and their content. If you want to ensure that all messages are encrypted and complete opaque and inaccessible to the Ably service, we provide built-in "private key symmetric encryption within our client libraries":https://faqs.ably.com/cross-platform-symmetric-encryption-offered-by-the-libraries. - - -h3(#any-internet-device). Any internet enabled device support - -Most of our client libraries use a "WebSocket":https://ably.com/topic/websockets to establish a realtime connection to Ably, and use a simple HTTP request for all other REST operations including authentication. - -However, client libraries such as our "JavaScript browser library":https://github.com/ably/ably-js are designed to choose the best transport available based on the browser and connection available. By starting from a base transport that has the highest likelihood of working and then attempting to upgrading the connection to use a websocket, Ably ensures that practically every browser in use today is able to establish a realtime connection to Ably. The following transports are currently supported by our "JavaScript browser library":https://github.com/ably/ably-js in order of best to worst performing: - -* "WebSockets":https://ably.com/topic/websockets ("supported by 94% of browsers globally as of Dec 2017":https://caniuse.com/#feat=websockets) -* XHR streaming -* XHR polling -* JSONP polling diff --git a/content/root/tools.textile b/content/root/tools.textile deleted file mode 100644 index fca278afd4..0000000000 --- a/content/root/tools.textile +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Tools -meta_description: "A list of Ably tools for increasingly productivity." -meta_keywords: "tools, automation, productivity, developers, tooling, debugging" -section: root -index: 15 -jump_to: - Help with: - - VSCode#vscode-plugin - - Terraform Provider#terraform-provider - - GitHub actions#github-actions - - Developer Console#developer-console - - React Hooks#react-hooks ---- - -This topic lists some developer resources and tools you can use to increase your productivity with Ably. - -h2(#vscode-plugin). Ably for Visual Studio Code - -Use the Ably for Visual Studio Code extension to manage your Ably apps directly in Visual Studio Code. - -The extension enables you to: - -* List all apps in your Ably account. -** View API keys, queues and integration rules for each app. -** Copy API keys to your clipboard. -* Create an Ably app. - -"Find it here.":https://github.com/ably-labs/vscode-ably - -h2(#terraform-provider). Ably Terraform provider - -Terraform provider for Ably enables you to manage your Ably account using Infrastructure-as-Code (IaC), including managing your applications, namespaces, keys, queues, rules and more. - -"Find it here.":https://github.com/ably/terraform-provider-ably - -h2(#github-actions). Ably Control API GitHub Action - -A GitHub Action to use the "Ably Control API":/docs/platform/account/control-api. You can use this action to: - -* Create an Ably application. -* Add an API key to an application, with a list of capabilities. - -"Find it here.":https://github.com/ably-labs/ably-control-api-action - -h2(#developer-console). Developer console - -The "Ably dashboard":https://ably.com/dashboard contains a developer console. In the developer console you can view connection events. The following screenshot illustrates an example connection: - - - Developer Console - - -You can attach to a specific channel to view messages. You can also publish messages directly in the console: - - - Developer Console - Channels - - -The developer console provides you with some REST API Curl command snippets that can help you test out Ably quickly: - - - Developer Console - REST API curl samples - - -Note, for convenience, the Curl commands have your Ably credentials already added. - -"Find it here.":https://ably.com/dashboard diff --git a/index.textile b/index.textile index d0389e856b..eed05448d5 100644 --- a/index.textile +++ b/index.textile @@ -18,7 +18,7 @@ h2. What's covered The Ably documentation is organized as follows: -* Getting started & key concepts: "Quick start guide":/docs/quick-start-guide and "key concepts":/docs/key-concepts +* "Getting started":/docs/getting-started * "Realtime client library API documentation":/docs/realtime/ * "REST client library API documentation":/docs/rest/ * "REST API documentation":/docs/rest-api/. Note, we recommend you use one of our REST client libraries instead of accessing the Ably REST API directly as the client libraries abstract away underlying complexity and provide a rich convenient feature set to developers. From 714a74e594379205f3f59891caf95dc6cd14299e Mon Sep 17 00:00:00 2001 From: Greg Holmes Date: Fri, 22 Aug 2025 17:01:03 +0100 Subject: [PATCH 2/2] Add redirect from /docs/ids-and-keys to /docs/auth --- src/pages/docs/auth/index.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/src/pages/docs/auth/index.mdx b/src/pages/docs/auth/index.mdx index cd18c3bd5b..171144ce70 100644 --- a/src/pages/docs/auth/index.mdx +++ b/src/pages/docs/auth/index.mdx @@ -17,6 +17,7 @@ redirect_from: - /docs/core-features/authentication.ably-jwt - /docs/general/authentication - /docs/general/_authentication_capabilities + - /docs/ids-and-keys --- Before a client or server can issue requests to Ably, such as subscribe to channels, or publish messages, it must authenticate with Ably. Authentication requires an Ably API key.