ably-cocoa allows users to pass in Ably-authored plugins via the ARTClientOptions.plugins property. These plugins extend the functionality of the SDK.
ably-cocoa and its plugins depend on a library called _AblyPluginSupportPrivate, which is a target of this package (found in _AblyPluginSupportPrivate; it was previously in the separate ably-cocoa-plugin-support repository). This provides an API that plugins can use to access ably-cocoa's internals, and which ably-cocoa can use to communicate with its plugins.
I will expand on this documentation once this mechanism is more mature. ADR-128: Plugins for ably-cocoa SDK describes the original design, but is now outdated in some important ways: it is centred on the plugin living in a separate repository so as not to be bound by ably-cocoa's OS version requirements, a constraint that turned out not to exist (per-declaration @available annotations let a single package host components with different OS requirements, and the plugin now lives in this repository), and _AblyPluginSupportPrivate (called AblyPlugin in the ADR) is a standalone library rather than part of the SDK's own module.
Currently, our only plugin is for adding LiveObjects functionality. This plugin can be found in this repository's LiveObjects/ directory, and is vended as this package's AblyLiveObjects product.
- Everything in ably-cocoa that depends on
_AblyPluginSupportPrivateis gated behind#ifdef ABLY_SUPPORTS_PLUGINS.Package.swiftdefines that macro for theAblyPubSubDevicetarget, so plugin support is compiled into every build of this package. The gate is what letsSourcecompile at all without_AblyPluginSupportPrivate, which is a target of this package rather than a library a build can pick up from anywhere else. - ably-cocoa provides an implementation of
_AblyPluginSupportPrivate'sAPPluginAPIprotocol, which is the interface that plugins use to access ably-cocoa's internals. On library initialization, it registers this implementation withAPDependencyStore, from where plugins can subsequetly fetch it. - There are some tests for the
APPluginAPIimplementation inPluginAPITests.swift(with only partial coverage at the moment). - Currently, the plan is to test all the LiveObjects functionality within the plugin's own test suite (
LiveObjects/Tests), so the ably-cocoa tests do not import the LiveObjects plugin. - The underscore and
Privateare to reduce the chances of the user accidentally importing it into their project. _AblyPluginSupportPrivatecan not refer to any of ably-cocoa's types (since SPM forbids circular dependencies) and so it contains various types that duplicate ably-cocoa's public types. These fall into two categories:- enums e.g.
APRealtimeChannelState, which are an exact copy of the corresponding ably-cocoa enum (in this example,ARTRealtimeChannelState) - marker protocols e.g.
APPublicRealtimeChannelwhich are empty protocols whose instances can always be safely casted to and from their corresponding ably-cocoa type (in this example,ARTRealtimeChannel)
- enums e.g.
- Do not add instance methods to types such as
APLoggerandAPRealtimeChannel(instead, favour adding methods toAPPluginAPI), so that ably-cocoa can make its internalARTInternalLogandARTRealtimeChannelInternaltypes conform to these protocols without having to worry about return or parameter type clashes due to the enum divergence described in the previous point.
- Make good use of
NS_SWIFT_NAMEto make_AblyPluginSupportPrivatenicer to use from Swift (e.g. to remove theAPprefix from class names).