Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ ably-cocoa is the Ably pub/sub SDK for iOS, macOS, and tvOS. It is written in Ob

**ably-cocoa is device-side only**: it serves apps running on an end user's device. Per [PDR-091](https://ably.atlassian.net/wiki/spaces/product/pages/5220106242), such a client declares that to Ably, which is what determines how its traffic counts toward an account's monthly active users. The decision records cover all nine Pub/Sub SDKs and describe a device/server pair, but the server half belongs to the server-capable SDKs; do not add a server package, a server factory, or the `ably-pubsub-server` agent identifier here, and do not document this SDK as a choice between two sides. Server-side Swift is tracked separately as `ably-swift`.

The SPM products are **`AblyPubSubCore`** (the core SDK, an internal implementation product for Ably's own packages rather than for direct use by applications) and `AblyLiveObjects`. The core's **module is `Ably` and its class prefix is `ART`**, independently of the product name — do not rename ObjC symbols, headers or the module.
The SPM products are **`AblyPubSubDevice`** (what applications depend on: `PubSubDevice.createClient(options:)`, which declares the device runtime), **`AblyPubSubCore`** (the core SDK, an internal implementation product for Ably's own packages rather than for direct use by applications) and `AblyLiveObjects`. The core's **module is `Ably` and its class prefix is `ART`**, independently of the product name — do not rename ObjC symbols, headers or the module.

## Build and Test

Expand Down
18 changes: 10 additions & 8 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@ Changes made to dependencies in the [Cartfile](Cartfile) need to be reflected in

## Adding new Objective-C files to the SDK

The steps below are for the core SDK — the `Ably` target, whose sources live in `Source/`. The `AblyPubSubDevice` target (`PubSubDevice/`) is laid out differently: its public headers go in `PubSubDevice/include/AblyPubSubDevice/` and its implementations directly in `PubSubDevice/`, there is no umbrella header to add an `#import` to, and it is absent from `Ably.xcodeproj`. SwiftPM globs the directory and generates the module map, so a new file there needs no other change.

### Public header (`.h`) files

These are the header files that form the public interface of the SDK.
Expand Down Expand Up @@ -127,19 +129,19 @@ If you add another `xcodebuild`-based path that compiles a test target linking `

### Distribution

`AblyLiveObjects` is available **via Swift Package Manager only**. CocoaPods and Carthage consumers receive the core SDK alone, so a release tag does not deliver the same set of products to every channel:
`AblyPubSubDevice` and `AblyLiveObjects` are available **via Swift Package Manager only**. CocoaPods and Carthage consumers receive the core SDK alone, so a release tag does not deliver the same set of products to every channel:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[MINOR] Release-notes bullet later in this file omits AblyPubSubDevice
Finding: This section now correctly establishes AblyPubSubDevice as SPM-only, but the Versioning section's release-notes bullet (line 191, just outside this diff) still reads "A release whose only change is to LiveObjects is a no-op for them" — naming only LiveObjects when explaining what CocoaPods/Carthage consumers don't receive.
Why it matters: With this PR, the pod/Carthage no-op reasoning applies equally to AblyPubSubDevice: a release whose only change is to the device product delivers nothing to those channels either. As written, the bullet could lead a release author to write inaccurate release notes for such a release. (This echoes an outstanding CodeRabbit nit.)
Suggested action: Extend the line-191 bullet to also name AblyPubSubDevice, e.g. "A release whose only change is to AblyPubSubDevice or LiveObjects is a no-op for them".

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Stale now — that bullet is gone. #2282 drops CocoaPods and Carthage from 2.x, so CONTRIBUTING.md no longer reasons about what those channels do or do not receive; the Distribution section says they stay on the 1.x line. Nothing left to extend.


| Channel | `AblyPubSubCore` | `AblyLiveObjects` |
| --- | --- | --- |
| Swift Package Manager | yes | yes |
| CocoaPods | yes (as the `Ably` pod) | no |
| Carthage | yes | no |
| Channel | `AblyPubSubCore` | `AblyPubSubDevice` | `AblyLiveObjects` |
| --- | --- | --- | --- |
| Swift Package Manager | yes | yes | yes |
| CocoaPods | yes (as the `Ably` pod) | no | no |
| Carthage | yes | no | no |

> The `AblyPubSubCore` product's module is named `Ably` and its classes carry the `ART` prefix, so
> consumers reach the core as `import Ably` / `#import <Ably/…>` whichever channel they install it
> from — which is why the CocoaPods pod and the Carthage framework are both named `Ably`.

This is a deliberate decision rather than an omission. Four separate things would each have to change to lift it:
The two are SPM-only for different reasons. Nothing about `AblyPubSubDevice` resists the other channels: it is a plain Objective-C target over the core, with the same platform floor and no plugin machinery, so shipping it as a pod would mean adding a podspec and Carthage targets rather than removing an obstacle. `AblyLiveObjects` is the constrained one, and deliberately so rather than by omission — four separate things would each have to change to lift it:

- [`Ably.podspec`](Ably.podspec)'s `source_files` covers `Source/` only, so neither `LiveObjects/` nor `_AblyPluginSupportPrivate/` ships in the pod; and `Ably.xcodeproj`, which Carthage builds, contains no LiveObjects or plugin-support targets.
- `ABLY_SUPPORTS_PLUGINS` is defined only in `Package.swift`. Without it the plugin hook points — `ARTClientOptions.plugins` and the plumbing in `ARTRealtimeChannel.m`, `ARTRealtime.m` and `ARTJsonLikeEncoder.m` — are compiled out. It is a compile-time define on the core target, so enabling it would enable it for every CocoaPods and Carthage consumer, in a configuration that has never been built or tested.
Expand Down Expand Up @@ -209,4 +211,4 @@ For each release, the following needs to be done:
* Checkout `main` locally, pulling in changes using `git checkout main && git pull`. Make sure the new tag you need was created on publish
* Release an update for CocoaPods using `pod trunk push Ably.podspec --allow-warnings`. Details on this command, as well as instructions for adding other contributors as maintainers, are at [Getting setup with Trunk](https://guides.cocoapods.org/making/getting-setup-with-trunk.html) in the [CocoaPods Guides](https://guides.cocoapods.org/). This publishes the core SDK only — there is no LiveObjects pod
* Test the integration of the library in a Xcode project using Carthage and CocoaPods using the [installation guide](https://github.com/ably/ably-cocoa#installation-guide)
* Test that Swift Package Manager resolves the new tag, selecting both the `AblyPubSubCore` and `AblyLiveObjects` products
* Test that Swift Package Manager resolves the new tag, selecting the `AblyPubSubCore`, `AblyPubSubDevice` and `AblyLiveObjects` products
3 changes: 2 additions & 1 deletion Examples/SPM/Package.swift
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@ let package = Package(
dependencies: [
// `package:` is the dependency's identity, which for a path
// dependency is the directory name, not the manifest's `name`.
.product(name: "AblyPubSubCore", package: "ably-cocoa")
.product(name: "AblyPubSubCore", package: "ably-cocoa"),
.product(name: "AblyPubSubDevice", package: "ably-cocoa")

@sacOO7 sacOO7 Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[MINOR] Example target isn't device-only
Finding: This adds AblyPubSubDevice alongside the existing AblyPubSubCore dependency on the same SPMIntegration target. main.swift imports only AblyPubSubDevice and uses the factory, so the new product is exercised at source level — but the example does not prove that depending on AblyPubSubDevice alone is sufficient, because the core product is still linked into the same target.
Why it matters: A key promise of the new product is that import AblyPubSubDevice re-exports the core's types, so an app needs exactly one dependency. With AblyPubSubCore still on the target, a regression that broke that re-export (e.g. a header or module-map change) would slip past this example unnoticed — the core types would still resolve through the direct dependency.
Suggested action: Add a device-only example target, or drop the now-redundant AblyPubSubCore product dependency from SPMIntegration.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Also resolved by #2285, which removes the core product entirely: Examples/SPM/Package.swift now depends on AblyPubSubDevice alone, so the target does prove that one dependency suffices. The example's direct-construction check went too, since those initializers are internal in #2287 — what remains exercises PubSubDevice.createClient and names RealtimeClient as the return type.

],
swiftSettings: [
.unsafeFlags(["-warnings-as-errors"])
Expand Down
10 changes: 9 additions & 1 deletion Examples/SPM/Sources/SPMIntegration/main.swift
Original file line number Diff line number Diff line change
@@ -1 +1,9 @@
import Ably
import AblyPubSubDevice

// `import AblyPubSubDevice` alone reaches the core's types too.
let options = ARTClientOptions()
options.autoConnect = false
options.key = "xxxx:xxxx"
options.clientId = "me"

let _ = PubSubDevice.createClient(options: options)
8 changes: 8 additions & 0 deletions Examples/SPM/Tests/SPMTests/SPMTests.swift
Original file line number Diff line number Diff line change
@@ -1,10 +1,18 @@
import XCTest
import Ably
import AblyPubSubDevice

final class SPMTests: XCTestCase {
func ablyInitTest() {
let clientOptions = ARTClientOptions()
let _ = ARTRest(options: clientOptions)
let _ = ARTRealtime(options: clientOptions)
}

func pubSubDeviceInitTest() {
let clientOptions = ARTClientOptions()
let _ = PubSubDevice.createClient(options: clientOptions)
let _ = PubSubDevice.createClient(key: "xxxx:xxxx")
let _ = PubSubDevice.createClient(token: "xxxx")
}
}
18 changes: 18 additions & 0 deletions Package.swift
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,12 @@ let package = Package(
name: "AblyPubSubCore",
targets: ["Ably"]
),
// The entry point for apps: creates clients that declare they are
// running on an end user's device.
.library(
name: "AblyPubSubDevice",
targets: ["AblyPubSubDevice"]
),
.library(
name: "AblyLiveObjects",
targets: ["AblyLiveObjects"]
Expand Down Expand Up @@ -84,6 +90,16 @@ let package = Package(
name: "_AblyPluginSupportPrivate",
path: "_AblyPluginSupportPrivate"
),
// Creates clients that declare they are running on an end user's
// device, by stamping the agent entry Ably classifies on.
.target(
name: "AblyPubSubDevice",
dependencies: [
.target(name: "Ably"),
],
path: "PubSubDevice",
publicHeadersPath: "include"
),
// The core SDK. Vended as the AblyPubSubCore product; its module is
// named `Ably`.
.target(
Expand Down Expand Up @@ -120,6 +136,7 @@ let package = Package(
name: "AblyTests",
dependencies: [
.byName(name: "Ably"),
.target(name: "AblyPubSubDevice"),

@sacOO7 sacOO7 Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[MINOR] No separate AblyPubSubDeviceTests target — please confirm intentional
Finding: The new product's tests are folded into the existing AblyTests (Swift) and AblyTestsObjC (ObjC) targets, as here, rather than getting a dedicated AblyPubSubDeviceTests target and xctestplan entry as sketched for this step of the PubSub device/server split rollout (PDR-091b2).
Why it matters: This reads as a justified divergence rather than a defect: the helpers these tests need (TestProxyTransport, TestProxyHTTPExecutor, commonAppSetup) live in AblyTests rather than the shared AblyTesting target, and reusing the existing targets keeps the new tests running in every existing CI lane on all three platforms.
Suggested action: No code change requested — just a conscious sign-off here so the divergence stands as a recorded decision.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Intentional — your own reasoning is the reason. The helpers these tests need (TestProxyTransport, TestProxyHTTPExecutor, commonAppSetup) live in AblyTests rather than the shared AblyTesting target, and reusing the existing targets puts the new tests in every existing lane on all three platforms rather than requiring a new xctestplan entry.

It paid off again in #2291: the plugins test reuses PluginAPITests' mock plugin, which is only reachable because the tests share a target.

.byName(name: "AblyTesting"),
.byName(name: "AblyTestingObjC"),
.product(name: "Nimble", package: "nimble"),
Expand Down Expand Up @@ -167,6 +184,7 @@ let package = Package(
name: "AblyTestsObjC",
dependencies: [
.byName(name: "Ably"),
.target(name: "AblyPubSubDevice"),
.byName(name: "AblyTesting"),
.byName(name: "AblyTestingObjC"),
],
Expand Down
41 changes: 41 additions & 0 deletions PubSubDevice/ARTPubSubDevice.m
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
#import <AblyPubSubDevice/ARTPubSubDevice.h>

/**
* The agent entry that declares a client is running on an end user's device.
*
* Ably matches this exact string to classify a connection for monthly active user counting, so
* changing it reclassifies every client this package creates. It is sent without a version: it
* states which kind of runtime the client is on, and the SDK's own entry alongside it carries the
* version.
*/
static NSString *const ARTPubSubDeviceAgentName = @"ably-pubsub-device";

@implementation ARTPubSubDevice

/// Returns a copy of `options` carrying the device declaration.
///
/// The caller's options object and its `agents` dictionary are both left untouched. The
/// declaration is applied last, so it wins if the caller set an entry under the same name.
+ (ARTClientOptions *)optionsDeclaringDevice:(ARTClientOptions *)options {
ARTClientOptions *const newOptions = [options copy];

NSMutableDictionary<NSString *, NSString *> *const agents = options.agents ? [options.agents mutableCopy] : [NSMutableDictionary dictionary];
agents[ARTPubSubDeviceAgentName] = ARTClientInformationAgentNotVersioned;
newOptions.agents = agents;

return newOptions;
}

+ (ARTRealtime *)createClientWithOptions:(ARTClientOptions *)options {
return [[ARTRealtime alloc] initWithOptions:[self optionsDeclaringDevice:options]];
}

+ (ARTRealtime *)createClientWithKey:(NSString *)key {
return [self createClientWithOptions:[[ARTClientOptions alloc] initWithKey:key]];
}

+ (ARTRealtime *)createClientWithToken:(NSString *)token {
return [self createClientWithOptions:[[ARTClientOptions alloc] initWithToken:token]];
}

@end
58 changes: 58 additions & 0 deletions PubSubDevice/include/AblyPubSubDevice/ARTPubSubDevice.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
#import <Ably/Ably.h>

@sacOO7 sacOO7 Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[MINOR] Header layout: no AblyPubSubDevice.h umbrella, SPM-generated module map — please confirm intentional
Finding: The target ships a single public header, ARTPubSubDevice.h, which carries the #import <Ably/Ably.h> re-export itself, and publicHeadersPath: "include" lets SwiftPM auto-generate the umbrella header and module map. The layout agreed for this step of the PubSub device/server split rollout (PDR-091b2) had a dedicated AblyPubSubDevice.h umbrella header plus a hand-written module map instead.
Why it matters: Nothing is broken — Swift import AblyPubSubDevice and ObjC @import AblyPubSubDevice; both reach the core's types, and this is arguably simpler than the agreed layout (a hand-written module map would have been redundant with SPM's generation). But it is a silent divergence from a written rollout step, and unacknowledged divergences make the later steps of the rollout harder to audit.
Suggested action: No code change requested — just an explicit acknowledgement here that the simpler layout is intentional, so it stands as a recorded decision.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Overtaken rather than acknowledged: #2285 merges the core into the device target and lands on the layout you were comparing against — Source/include/AblyPubSubDevice/AblyPubSubDevice.h as the umbrella, plus a hand-written Source/include/module.modulemap that also declares the Private submodule. So the divergence closes on its own further up the stack.


NS_ASSUME_NONNULL_BEGIN

/**
* Creates Pub/Sub clients for apps running on an end user's device.
*
* A client created here tells Ably that it is running on an end user's device. That declaration
* determines how the connection is counted: on an account billed by monthly active users, device
* traffic counts toward the total, the connection must carry a `clientId`, and that `clientId` is
* subject to a concurrency limit.
*
* The returned object is an `ARTRealtime` and behaves exactly as one built with
* `-[ARTRealtime initWithOptions:]`, so all of the Ably Pub/Sub documentation applies to it
* unchanged.
*/
NS_SWIFT_NAME(PubSubDevice)
@interface ARTPubSubDevice : NSObject

- (instancetype)init NS_UNAVAILABLE;

/**
* Creates a client with the given options.
*
* The options are not modified; any `agents` entries they carry are preserved alongside the
* device declaration.
*
* @param options The client options. Set `clientId` on them, or use token authentication that
* supplies one.
*
* @return A realtime client that declares it is running on an end user's device.
*/
+ (ARTRealtime *)createClientWithOptions:(ARTClientOptions *)options NS_SWIFT_NAME(createClient(options:));

/**
* Creates a client that authenticates with an API key.
*
* Prefer token authentication in code that ships to a device; an API key embedded in an app is
* readable by anyone who has the app.
*
* @param key A full Ably API key.
*
* @return A realtime client that declares it is running on an end user's device.
*/
+ (ARTRealtime *)createClientWithKey:(NSString *)key NS_SWIFT_NAME(createClient(key:));

/**
* Creates a client that authenticates with an existing token.
*
* @param token An Ably authentication token.
*
* @return A realtime client that declares it is running on an end user's device.
*/
+ (ARTRealtime *)createClientWithToken:(NSString *)token NS_SWIFT_NAME(createClient(token:));

@end

NS_ASSUME_NONNULL_END
Loading
Loading