From 48cefad7acd54287a75f4aa776267e4dc6fe2584 Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Thu, 17 Apr 2025 15:28:24 -0300 Subject: [PATCH 1/5] Make REC* language more consistent For conditional things, consistently say "if it's x, determined by y", and don't use conditional language for non-conditional REC1b4. --- textile/features.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/textile/features.textile b/textile/features.textile index d5c61a7e..dc7a0f70 100644 --- a/textile/features.textile +++ b/textile/features.textile @@ -76,8 +76,8 @@ h2(#endpoint-configuration). Client library endpoint configuration ** @(REC1b)@ If the @endpoint@ option is specified then: *** @(REC1b1)@ If any one of the deprecated options @environment@, @restHost@, @realtimeHost@ or @fallbackHostsUseDefault@ are also specified then the options as a set are invalid. *** @(REC1b2)@ If the @endpoint@ option is a domain name, determined by it containing at least one period (@.@) then the @primary domain@ is the value of the @endpoint@ option. -*** @(REC1b3)@ Otherwise, if the @endpoint@ option is a non-production routing policy name of the form @nonprod:[name]@ then the @primary domain@ is @[name].realtime.ably-nonprod.net@. -*** @(REC1b4)@ Otherwise, if the @endpoint@ option is a production routing policy name of the form @[name]@ then the @primary domain@ is @[name].realtime.ably.net@. +*** @(REC1b3)@ Otherwise, if the @endpoint@ option is a non-production routing policy name, determined by it having the form @nonprod:[name]@, then the @primary domain@ is @[name].realtime.ably-nonprod.net@. +*** @(REC1b4)@ Otherwise, the @endpoint@ option is a production routing policy name of the form @[name]@, and the @primary domain@ is @[name].realtime.ably.net@. ** @(REC1c)@ If the deprecated @environment@ option is specified then it defines a production routing policy name @[name]@: *** @(REC1c1)@ If any one of the deprecated options @restHost@, @realtimeHost@ are also specified then the options as a set are invalid. *** @(REC1c2)@ Otherwise, the primary domain is @[name].realtime.ably.net@. From 4374210b6dc86b3ff98335c6ab5caf84f81cb7ba Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Thu, 17 Apr 2025 15:30:52 -0300 Subject: [PATCH 2/5] Fix fallback hosts predicate language The existing language implies that the primary domain equals the routing policy name, which is not what the referenced spec points say. --- textile/features.textile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/textile/features.textile b/textile/features.textile index dc7a0f70..6fa0b793 100644 --- a/textile/features.textile +++ b/textile/features.textile @@ -93,9 +93,9 @@ h2(#endpoint-configuration). Client library endpoint configuration ** @(REC2c)@ Otherwise, the set of @fallback domains@ is defined implicitly by the options used to define the @primary domain@ as specified in @(REC1)@: *** @(REC2c1)@ If the @primary domain@ is determined to be the default via @(REC1a)@ then the set of @fallback domains@ is the default @main.a.fallback.ably-realtime.com@, @main.b.fallback.ably-realtime.com@, @main.c.fallback.ably-realtime.com@, @main.d.fallback.ably-realtime.com@, and @main.e.fallback.ably-realtime.com@. *** @(REC2c2)@ Otherwise, if the @primary domain@ is determined to be an explicit domain name via @(REC1b2)@ then the set of @fallback domains@ is empty. -*** @(REC2c3)@ Otherwise, if the @primary domain@ is determined to be a non-production routing policy name via @(REC1b3)@ then the set of @fallback domains@ is @[name].a.fallback.ably-realtime-nonprod.com@, @[name].b.fallback.ably-realtime-nonprod.com@, @[name].c.fallback.ably-realtime-nonprod.com@, @[name].d.fallback.ably-realtime-nonprod.com@, @[name].e.fallback.ably-realtime-nonprod.com@. -*** @(REC2c4)@ Otherwise, if the @primary domain@ is determined to be a production routing policy name via @(REC1b4)@ then the set of @fallback domains@ is @[name].a.fallback.ably-realtime.com@, @[name].b.fallback.ably-realtime.com@, @[name].c.fallback.ably-realtime.com@, @[name].d.fallback.ably-realtime.com@, @[name].e.fallback.ably-realtime.com@. -*** @(REC2c5)@ Otherwise, if the @primary domain@ is determined to be a routing policy name via @(REC1c2)@ then the set of @fallback domains@ is @[name].a.fallback.ably-realtime.com@, @[name].b.fallback.ably-realtime.com@, @[name].c.fallback.ably-realtime.com@, @[name].d.fallback.ably-realtime.com@, @[name].e.fallback.ably-realtime.com@. +*** @(REC2c3)@ Otherwise, if the @primary domain@ is determined by a non-production routing policy name via @(REC1b3)@ then the set of @fallback domains@ is @[name].a.fallback.ably-realtime-nonprod.com@, @[name].b.fallback.ably-realtime-nonprod.com@, @[name].c.fallback.ably-realtime-nonprod.com@, @[name].d.fallback.ably-realtime-nonprod.com@, @[name].e.fallback.ably-realtime-nonprod.com@. +*** @(REC2c4)@ Otherwise, if the @primary domain@ is determined by a production routing policy name via @(REC1b4)@ then the set of @fallback domains@ is @[name].a.fallback.ably-realtime.com@, @[name].b.fallback.ably-realtime.com@, @[name].c.fallback.ably-realtime.com@, @[name].d.fallback.ably-realtime.com@, @[name].e.fallback.ably-realtime.com@. +*** @(REC2c5)@ Otherwise, if the @primary domain@ is determined by a routing policy name via @(REC1c2)@ then the set of @fallback domains@ is @[name].a.fallback.ably-realtime.com@, @[name].b.fallback.ably-realtime.com@, @[name].c.fallback.ably-realtime.com@, @[name].d.fallback.ably-realtime.com@, @[name].e.fallback.ably-realtime.com@. *** @(REC2c6)@ Otherwise, if the @primary domain@ is determined by the deprecated @restHost@ or @realtimeHost@ option via @(REC1d)@ then the set of fallback domains is empty. * @(REC3)@ Client options determine a @connectivity check URL@. From 273735812254fa9be4653b083d33439f3b22c063 Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Thu, 24 Apr 2025 09:22:48 -0300 Subject: [PATCH 3/5] Add "production" to REC2c5 For consistency with REC2c4. --- textile/features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/features.textile b/textile/features.textile index 6fa0b793..ae80f415 100644 --- a/textile/features.textile +++ b/textile/features.textile @@ -95,7 +95,7 @@ h2(#endpoint-configuration). Client library endpoint configuration *** @(REC2c2)@ Otherwise, if the @primary domain@ is determined to be an explicit domain name via @(REC1b2)@ then the set of @fallback domains@ is empty. *** @(REC2c3)@ Otherwise, if the @primary domain@ is determined by a non-production routing policy name via @(REC1b3)@ then the set of @fallback domains@ is @[name].a.fallback.ably-realtime-nonprod.com@, @[name].b.fallback.ably-realtime-nonprod.com@, @[name].c.fallback.ably-realtime-nonprod.com@, @[name].d.fallback.ably-realtime-nonprod.com@, @[name].e.fallback.ably-realtime-nonprod.com@. *** @(REC2c4)@ Otherwise, if the @primary domain@ is determined by a production routing policy name via @(REC1b4)@ then the set of @fallback domains@ is @[name].a.fallback.ably-realtime.com@, @[name].b.fallback.ably-realtime.com@, @[name].c.fallback.ably-realtime.com@, @[name].d.fallback.ably-realtime.com@, @[name].e.fallback.ably-realtime.com@. -*** @(REC2c5)@ Otherwise, if the @primary domain@ is determined by a routing policy name via @(REC1c2)@ then the set of @fallback domains@ is @[name].a.fallback.ably-realtime.com@, @[name].b.fallback.ably-realtime.com@, @[name].c.fallback.ably-realtime.com@, @[name].d.fallback.ably-realtime.com@, @[name].e.fallback.ably-realtime.com@. +*** @(REC2c5)@ Otherwise, if the @primary domain@ is determined by a production routing policy name via @(REC1c2)@ then the set of @fallback domains@ is @[name].a.fallback.ably-realtime.com@, @[name].b.fallback.ably-realtime.com@, @[name].c.fallback.ably-realtime.com@, @[name].d.fallback.ably-realtime.com@, @[name].e.fallback.ably-realtime.com@. *** @(REC2c6)@ Otherwise, if the @primary domain@ is determined by the deprecated @restHost@ or @realtimeHost@ option via @(REC1d)@ then the set of fallback domains is empty. * @(REC3)@ Client options determine a @connectivity check URL@. From d87dc79a9a09a49b40e416bd3f0e3d0d80225e91 Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Thu, 17 Apr 2025 15:38:54 -0300 Subject: [PATCH 4/5] Disambiguate the word "name" when talking about routing policies It was being used in two different ways in REC1b3. Per Laura ([1] and [2]) there is no such thing as a "routing policy name", and the term for the subcomponent is the "routing policy ID". [1] https://ably-real-time.slack.com/archives/CURL4U2FP/p1744878569805559 [2] https://github.com/ably/specification/pull/301#discussion_r2056761031 --- textile/features.textile | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/textile/features.textile b/textile/features.textile index ae80f415..0216b4e5 100644 --- a/textile/features.textile +++ b/textile/features.textile @@ -76,11 +76,11 @@ h2(#endpoint-configuration). Client library endpoint configuration ** @(REC1b)@ If the @endpoint@ option is specified then: *** @(REC1b1)@ If any one of the deprecated options @environment@, @restHost@, @realtimeHost@ or @fallbackHostsUseDefault@ are also specified then the options as a set are invalid. *** @(REC1b2)@ If the @endpoint@ option is a domain name, determined by it containing at least one period (@.@) then the @primary domain@ is the value of the @endpoint@ option. -*** @(REC1b3)@ Otherwise, if the @endpoint@ option is a non-production routing policy name, determined by it having the form @nonprod:[name]@, then the @primary domain@ is @[name].realtime.ably-nonprod.net@. -*** @(REC1b4)@ Otherwise, the @endpoint@ option is a production routing policy name of the form @[name]@, and the @primary domain@ is @[name].realtime.ably.net@. -** @(REC1c)@ If the deprecated @environment@ option is specified then it defines a production routing policy name @[name]@: +*** @(REC1b3)@ Otherwise, if the @endpoint@ option specifies a non-production routing policy ID, determined by it having the form @nonprod:[id]@, then the @primary domain@ is @[id].realtime.ably-nonprod.net@. +*** @(REC1b4)@ Otherwise, the @endpoint@ option is a production routing policy ID of the form @[id]@, and the @primary domain@ is @[id].realtime.ably.net@. +** @(REC1c)@ If the deprecated @environment@ option is specified then it defines a production routing policy ID @[id]@: *** @(REC1c1)@ If any one of the deprecated options @restHost@, @realtimeHost@ are also specified then the options as a set are invalid. -*** @(REC1c2)@ Otherwise, the primary domain is @[name].realtime.ably.net@. +*** @(REC1c2)@ Otherwise, the primary domain is @[id].realtime.ably.net@. ** @(REC1d)@ If either the @restHost@ or @realtimeHost@ option is specified then: *** @(REC1d1)@ If the @restHost@ option is specified the @primary domain@ is the value of the @restHost@ option. *** @(REC1d2)@ Otherwise, if the @realtimeHost@ option is specified the @primary domain@ is the value of the @realtimeHost@ option. @@ -93,9 +93,9 @@ h2(#endpoint-configuration). Client library endpoint configuration ** @(REC2c)@ Otherwise, the set of @fallback domains@ is defined implicitly by the options used to define the @primary domain@ as specified in @(REC1)@: *** @(REC2c1)@ If the @primary domain@ is determined to be the default via @(REC1a)@ then the set of @fallback domains@ is the default @main.a.fallback.ably-realtime.com@, @main.b.fallback.ably-realtime.com@, @main.c.fallback.ably-realtime.com@, @main.d.fallback.ably-realtime.com@, and @main.e.fallback.ably-realtime.com@. *** @(REC2c2)@ Otherwise, if the @primary domain@ is determined to be an explicit domain name via @(REC1b2)@ then the set of @fallback domains@ is empty. -*** @(REC2c3)@ Otherwise, if the @primary domain@ is determined by a non-production routing policy name via @(REC1b3)@ then the set of @fallback domains@ is @[name].a.fallback.ably-realtime-nonprod.com@, @[name].b.fallback.ably-realtime-nonprod.com@, @[name].c.fallback.ably-realtime-nonprod.com@, @[name].d.fallback.ably-realtime-nonprod.com@, @[name].e.fallback.ably-realtime-nonprod.com@. -*** @(REC2c4)@ Otherwise, if the @primary domain@ is determined by a production routing policy name via @(REC1b4)@ then the set of @fallback domains@ is @[name].a.fallback.ably-realtime.com@, @[name].b.fallback.ably-realtime.com@, @[name].c.fallback.ably-realtime.com@, @[name].d.fallback.ably-realtime.com@, @[name].e.fallback.ably-realtime.com@. -*** @(REC2c5)@ Otherwise, if the @primary domain@ is determined by a production routing policy name via @(REC1c2)@ then the set of @fallback domains@ is @[name].a.fallback.ably-realtime.com@, @[name].b.fallback.ably-realtime.com@, @[name].c.fallback.ably-realtime.com@, @[name].d.fallback.ably-realtime.com@, @[name].e.fallback.ably-realtime.com@. +*** @(REC2c3)@ Otherwise, if the @primary domain@ is determined by a non-production routing policy ID via @(REC1b3)@ then the set of @fallback domains@ is @[id].a.fallback.ably-realtime-nonprod.com@, @[id].b.fallback.ably-realtime-nonprod.com@, @[id].c.fallback.ably-realtime-nonprod.com@, @[id].d.fallback.ably-realtime-nonprod.com@, @[id].e.fallback.ably-realtime-nonprod.com@. +*** @(REC2c4)@ Otherwise, if the @primary domain@ is determined by a production routing policy ID via @(REC1b4)@ then the set of @fallback domains@ is @[id].a.fallback.ably-realtime.com@, @[id].b.fallback.ably-realtime.com@, @[id].c.fallback.ably-realtime.com@, @[id].d.fallback.ably-realtime.com@, @[id].e.fallback.ably-realtime.com@. +*** @(REC2c5)@ Otherwise, if the @primary domain@ is determined by a production routing policy ID via @(REC1c2)@ then the set of @fallback domains@ is @[id].a.fallback.ably-realtime.com@, @[id].b.fallback.ably-realtime.com@, @[id].c.fallback.ably-realtime.com@, @[id].d.fallback.ably-realtime.com@, @[id].e.fallback.ably-realtime.com@. *** @(REC2c6)@ Otherwise, if the @primary domain@ is determined by the deprecated @restHost@ or @realtimeHost@ option via @(REC1d)@ then the set of fallback domains is empty. * @(REC3)@ Client options determine a @connectivity check URL@. From cbe7c83e843722da2a93ac74eb3fe06c406773cb Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Thu, 17 Apr 2025 16:12:17 -0300 Subject: [PATCH 5/5] Make `endpoint` special-case `localhost` and IP addresses I believe it's quite common (e.g. for Realtime devs) to want to point to a local Realtime. Or, for example in the SDK team, to want to point to a local reverse proxy for interception. Turns out that it's already special-cased in ably-go [1], so let's add to spec. Since ably-go is the only place that the `endpoint` functionality has been implemented so far, I'm just changing the existing spec point and will update ably-go to reflect. [1] https://github.com/ably/ably-go/blob/17f6575773b28a146ac04bfaf3b8de44ce1ff162/ably/options.go#L506-L510 --- textile/features.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/textile/features.textile b/textile/features.textile index 0216b4e5..3314cf92 100644 --- a/textile/features.textile +++ b/textile/features.textile @@ -75,7 +75,7 @@ h2(#endpoint-configuration). Client library endpoint configuration ** @(REC1a)@ The @primary domain@ is @main.realtime.ably.net@ unless overridden by specifying an @endpoint@ option or any of the deprecated options @environment@, @restHost@, @realtimeHost@. ** @(REC1b)@ If the @endpoint@ option is specified then: *** @(REC1b1)@ If any one of the deprecated options @environment@, @restHost@, @realtimeHost@ or @fallbackHostsUseDefault@ are also specified then the options as a set are invalid. -*** @(REC1b2)@ If the @endpoint@ option is a domain name, determined by it containing at least one period (@.@) then the @primary domain@ is the value of the @endpoint@ option. +*** @(REC1b2)@ If the @endpoint@ option is a hostname, determined by it containing at least one period (@.@), or containing at least one instance of the string @::@, or being equal to the string @localhost@, then the @primary domain@ is the value of the @endpoint@ option. *** @(REC1b3)@ Otherwise, if the @endpoint@ option specifies a non-production routing policy ID, determined by it having the form @nonprod:[id]@, then the @primary domain@ is @[id].realtime.ably-nonprod.net@. *** @(REC1b4)@ Otherwise, the @endpoint@ option is a production routing policy ID of the form @[id]@, and the @primary domain@ is @[id].realtime.ably.net@. ** @(REC1c)@ If the deprecated @environment@ option is specified then it defines a production routing policy ID @[id]@: @@ -92,7 +92,7 @@ h2(#endpoint-configuration). Client library endpoint configuration ** @(REC2b)@ Otherwise, if the deprecated @fallbackHostsUseDefault@ option is specified then the set of @fallback domains@ is the default set defined in @(REC2c1)@. ** @(REC2c)@ Otherwise, the set of @fallback domains@ is defined implicitly by the options used to define the @primary domain@ as specified in @(REC1)@: *** @(REC2c1)@ If the @primary domain@ is determined to be the default via @(REC1a)@ then the set of @fallback domains@ is the default @main.a.fallback.ably-realtime.com@, @main.b.fallback.ably-realtime.com@, @main.c.fallback.ably-realtime.com@, @main.d.fallback.ably-realtime.com@, and @main.e.fallback.ably-realtime.com@. -*** @(REC2c2)@ Otherwise, if the @primary domain@ is determined to be an explicit domain name via @(REC1b2)@ then the set of @fallback domains@ is empty. +*** @(REC2c2)@ Otherwise, if the @primary domain@ is determined to be an explicit hostname via @(REC1b2)@ then the set of @fallback domains@ is empty. *** @(REC2c3)@ Otherwise, if the @primary domain@ is determined by a non-production routing policy ID via @(REC1b3)@ then the set of @fallback domains@ is @[id].a.fallback.ably-realtime-nonprod.com@, @[id].b.fallback.ably-realtime-nonprod.com@, @[id].c.fallback.ably-realtime-nonprod.com@, @[id].d.fallback.ably-realtime-nonprod.com@, @[id].e.fallback.ably-realtime-nonprod.com@. *** @(REC2c4)@ Otherwise, if the @primary domain@ is determined by a production routing policy ID via @(REC1b4)@ then the set of @fallback domains@ is @[id].a.fallback.ably-realtime.com@, @[id].b.fallback.ably-realtime.com@, @[id].c.fallback.ably-realtime.com@, @[id].d.fallback.ably-realtime.com@, @[id].e.fallback.ably-realtime.com@. *** @(REC2c5)@ Otherwise, if the @primary domain@ is determined by a production routing policy ID via @(REC1c2)@ then the set of @fallback domains@ is @[id].a.fallback.ably-realtime.com@, @[id].b.fallback.ably-realtime.com@, @[id].c.fallback.ably-realtime.com@, @[id].d.fallback.ably-realtime.com@, @[id].e.fallback.ably-realtime.com@.