pubsub: add device and server packages

[lmars]

Introduce per-side pubsub packages, so applications declare whether they are running on an end-user device or a server by their choice of package. Additive and shippable in a minor release.

Packages

• pubsub/device — NewClient, returning a Client (= ably.Realtime)
• pubsub/server — NewHTTPClient and NewRealtimeClient, returning an HTTPClient (= ably.REST) and a RealtimeClient (= ably.Realtime)

The constructors return type aliases of today's clients rather than wrapper types: the side is the package and constructor choice plus the agent declaration, not a type distinction.

Agent declaration

Each constructor appends a side-declaring agent (ably-go-pubsub-device / ably-go-pubsub-server) to the Ably-Agent header, which is what monthly-active-user classification keys on.

WithAgents now merges its entries into any agents already configured instead of replacing them, so the side agent appended by the constructors and a user-supplied WithAgents coexist regardless of option order.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added dedicated device-side client creation for Ably Pub/Sub connections.
  • Added server-side HTTP and realtime client constructors.
  • Client requests now identify whether they originate from a device or server.
  • Custom agent information is preserved and combined with these client identifiers.

• Tests

  • Added coverage verifying device and server client identification and custom agent merging.

[coderabbitai]

Walkthrough

The PR merges successive Ably agent options and adds device- and server-scoped Pub/Sub client constructors that attach corresponding agent identifiers. Tests verify generated Ably-Agent headers and preservation of user-provided agents.

Changes

Pub/Sub agent classification

Layer / File(s)	Summary
Preserve and merge agent options ably/options.go	WithAgents now retains existing entries and applies newly provided entries, with later values taking precedence.
Device client constructor and agent header pubsub/device/device.go, pubsub/device/device_test.go	Adds a realtime device client alias and constructor that sets the device agent, with an HTTP header test.
Server client constructors and agent preservation pubsub/server/server.go, pubsub/server/server_test.go	Adds REST and realtime server client constructors and tests server-agent tagging alongside user-provided agents.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant PubSubConstructor
  participant AblyClient
  participant HTTPServer
  Caller->>PubSubConstructor: provide client options
  PubSubConstructor->>AblyClient: create client with scoped agent
  AblyClient->>HTTPServer: send request with Ably-Agent
  HTTPServer-->>Caller: captured agent header

Loading

Poem

A rabbit hops through options bright,
Merging agents left and right.
Device hops, server follows near,
Headers carry labels clear.
Tests twitch noses: all is right!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change by adding the new pubsub device and server packages.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch pubsub-device-server-packages

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

pubsub/server/server_test.go (1)

36-56: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Cover NewRealtimeClient as well.

The new public realtime constructor has a separate code path, but these tests exercise only NewHTTPClient. Add equivalent agent and user-agent assertions for server.NewRealtimeClient (with auto-connect disabled) so regressions in realtime option propagation are detected.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@pubsub/server/server_test.go` around lines 36 - 56, Extend the constructor
agent tests to cover server.NewRealtimeClient using auto-connect disabled. Add
equivalent assertions for the ably-go-pubsub-server agent and merged user agent,
alongside the existing NewHTTPClient tests, so realtime option propagation is
verified.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@pubsub/server/server_test.go`:
- Around line 36-56: Extend the constructor agent tests to cover
server.NewRealtimeClient using auto-connect disabled. Add equivalent assertions
for the ably-go-pubsub-server agent and merged user agent, alongside the
existing NewHTTPClient tests, so realtime option propagation is verified.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6d9d83b2-18e5-48c6-a8b2-cfa394cd41fe

📥 Commits

Reviewing files that changed from the base of the PR and between 26cb171 and 07bb6d5.

📒 Files selected for processing (5)

• ably/options.go
• pubsub/device/device.go
• pubsub/device/device_test.go
• pubsub/server/server.go
• pubsub/server/server_test.go

[ttypic]

probably should be ably-pubsub-device-go

[lmars]

Based on our internal decision record, the agent entry needs to end in -device or -server.

[paddybyers]

Do we expect there to be go devices?

[lmars]

@paddybyers I think there was a recent discussion where it was suggested that the Go SDK could be used to build a desktop or CLI app, in which case it would be in a device context.