Skip to content

Add spec points to describe the Objects plugin #332

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
VeskeR merged 1 commit into from
Jul 4, 2025
Merged

Add spec points to describe the Objects plugin #332

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions textile/features.textile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ jump_to:
- Channels#realtime-channels
- RealtimeChannel#realtime-channel
- RealtimePresence#realtime-presence
- RealtimeObjects#realtime-objects
- EventEmitter#eventemitter
- Forwards compatibility#realtime-compatibility
- State conditions and operations#state-conditions-and-operations
Expand Down Expand Up @@ -385,13 +386,15 @@ h3(#plugins). Plugins
* @(PC2)@ No generic plugin interface is specified, and therefore there is no common API exposed by all plugins. However, for type-safety, the opaque interface @Plugin@ should be used in strongly-typed languages as the type of the @ClientOptions.plugins@ collection as per "TO3o":#TO3o.
* @(PC3)@ A plugin provided with the @PluginType@ enum key value of @vcdiff@ should be capable of decoding "vcdiff"-encoded messages. It must implement the @VCDiffDecoder@ interface and the client library must be able to use it by casting it to this interface.
** @(PC3a)@ The base argument of the @VCDiffDecoder.decode@ method should receive the stored base payload of the last message on a channel as specified by "RTL19":#RTL19. If the base payload is a string it should be encoded to binary using UTF-8 before being passed as base argument of the @VCDiffDecoder.decode@ method.
* @(PC5)@ A plugin provided with the @PluginType@ enum key value of @Objects@ should provide the "RealtimeObjects":#RTO1 feature functionality for realtime channels ("RTL27":#RTL27). The plugin object itself is not expected to provide a public API. The type of the plugin object, and how it enables the Objects feature for a realtime channel, are left for individual implementations to decide.
* @(PC4)@ A client library is allowed to accept plugins other than those specified in this specification, through the use of additional @ClientOptions.plugins@ keys defined by that library. The library is responsible for defining the interface of these plugins, and for making sure that these keys do not clash with the keys defined in this specification.

h3(#plugin-type). PluginType

* @(PT1)@ @PluginType@ is an enum describing the different types of plugins that the library supports. See the @ClientOptions#plugins@ property ("TO3o":#TO3o).
* @(PT2)@ @PluginType@ takes one of the following values:
** @(PT2a)@ @vcdiff@ – see "PC3":#PC3.
** @(PT2b)@ @Objects@ – see "PC5":#PC5.

h3(#vcdiff-decoder). VCDiffDecoder

Expand Down Expand Up @@ -775,6 +778,9 @@ h3(#realtime-channel). RealtimeChannel
** @(RTL8b)@ Unsubscribe with a name argument and a listener argument unsubscribes the provided listener if previously subscribed with a name-specific subscription
* @(RTL9)@ @RealtimeChannel#presence@ attribute:
** @(RTL9a)@ Returns the @RealtimePresence@ object for this channel
* @(RTL27)@ @RealtimeChannel#objects@ attribute:
** @(RTL27a)@ Returns the @RealtimeObjects@ object for this channel "RTO1":#RTO1
** @(RTL27b)@ It is a programmer error to access this property without first providing the @Objects@ plugin ("PC5":#PC5) in the client options. This programmer error should be handled in an idiomatic fashion; if this means accessing the property should throw an error, then the error should be an @ErrorInfo@ with @statusCode@ 400 and @code@ 40019.
* @(RTL10)@ @RealtimeChannel#history@ function:
** @(RTL10a)@ Supports all the same params as @RestChannel#history@
** @(RTL10b)@ Additionally supports the param @untilAttach@, which if true, will only retrieve messages prior to the moment that the channel was attached or emitted an @UPDATE@ indicating loss of continuity. This bound is specified by passing the querystring param @fromSerial@ with the @RealtimeChannel#properties.attachSerial@ assigned to the channel in the @ATTACHED@ @ProtocolMessage@ (see "RTL15a":#RTL15a). If the @untilAttach@ param is specified when the channel is not attached, it results in an error
Expand Down Expand Up @@ -930,9 +936,9 @@ then the @enter@ request results in an error immediately.
** @(RTP15e)@ Implicitly attaches the @RealtimeChannel@ if the channel is in the @INITIALIZED@ state. However, if the channel is in or enters the @DETACHED@ or @FAILED@ state before the operation succeeds, it will result in an error
** @(RTP15f)@ If the client is identified and has a valid @clientId@, and the @clientId@ argument does not match the client's @clientId@, then it should indicate an error. The connection and channel remain available for further operations

h3(#objects). Objects
h3(#realtime-objects). RealtimeObjects
Copy link
Collaborator

@sacOO7 sacOO7 Jun 13, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
h3(#realtime-objects). RealtimeObjects
h3(#realtime-objects). LiveObjects

It seems like we're currently using two different terms for the same feature.
To avoid confusion, calling this as LiveObjects would be more consistent naming wdyt?
Unless, LiveObjects is already being used elsewhere and could cause a naming conflict.

Copy link
Contributor Author

@VeskeR VeskeR Jun 13, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the name of the feature is Objects, and it must not be called LiveObjects in the client library imlpementation at all, see https://ably.atlassian.net/wiki/spaces/LOB/pages/3819896841/LODR-033+Isolating+API+naming+from+Product+naming+Renaming+state+and+liveobjects+to+objects+in+APIs.

The spec change from Objects to RealtimeObjects this PR adds is explained in commit message ccc5329, but essentially it's to keep consistency with RealtimeChannels, RealtimePresence, and allow us to add RestObjects in the future.
This change only relates to the name of the public class exposed to the end-user. It does not change the property found on a channel: channel.objects returns a RealtimeObjects instance, just like channel.presence returns RealtimePresence

Copy link
Collaborator

@sacOO7 sacOO7 Jun 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, will take a look at LODR 👍


Reserved for @Objects@ feature specification. Reserved spec points: @OBJ@, @LM@, @LC@
Reserved for @RealtimeObjects@ feature specification. Reserved spec points: @RTO@, @RTLO@, @RTLC@, @RTLM@

h3(#realtime-annotations). RealtimeAnnotations

Expand Down Expand Up @@ -2314,6 +2320,7 @@ class RealtimeChannel: // RTL*
state: ChannelState // RTL2b
whenState(ChannelState, (ChannelStateChange?) ->) // RTL25
presence: RealtimePresence // RTL9
objects: RealtimeObjects // RTL27
properties: ChannelProperties // RTL15
// Only on platforms that support receiving push notifications:
push: PushChannel // RSH7
Expand Down Expand Up @@ -2853,6 +2860,7 @@ class Plugin // PC2

enum PluginType // PT*
"vcdiff" // PT2a
"Objects" // PT2b

class VCDiffDecoder // VD*
decode([byte] delta, [byte] base) -> [byte] // VD2a, PC3a
Expand Down
Loading