uts: add ProxyManager and ProxySession for integration tests

[ttypic]

• Introduced ProxyManager to manage the uts-proxy binary lifecycle, including downloading, verification, and process control.
• Added ProxySession for managing proxy sessions with rules, actions, event logging, and cleanup.
• Included KDoc documentation for clear usage guidelines in integration tests.

Summary by CodeRabbit

Release Notes

• New Features

  • Added proxy-driven integration testing support, including proxy session/rule/action helpers and typed inspection of proxy traffic logs.

• Tests

  • Added sandbox app provisioning/teardown helpers.
  • Added pollUntil for real-time, wall-clock polling assertions.
  • Added a programmable-proxy re-authentication integration test.
  • Updated test dependencies and added configurable uts.proxy.localPath for forked test JVMs.

• Documentation

  • Extended UTS-to-Kotlin translation with a dedicated “Proxy integration tests” flow and guidance.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ab3f4b15-95f7-47a9-a3e0-11177af08e8f

📥 Commits

Reviewing files that changed from the base of the PR and between de0feb2 and 18f4a68.

📒 Files selected for processing (4)

• .claude/skills/uts-to-kotlin/SKILL.md
• uts/build.gradle.kts
• uts/src/test/kotlin/io/ably/lib/realtime/integration/proxy/AuthReauthTest.kt
• uts/src/test/kotlin/io/ably/lib/test/helper/ProxyManager.kt

🚧 Files skipped from review as they are similar to previous changes (3)

• uts/build.gradle.kts
• uts/src/test/kotlin/io/ably/lib/realtime/integration/proxy/AuthReauthTest.kt
• .claude/skills/uts-to-kotlin/SKILL.md

---

Walkthrough

Adds sandbox and proxy test helpers, a polling utility, and a proxy-driven integration test for re-authentication. The build gains Ktor test dependencies and proxy path wiring. Translation guidance in SKILL.md is updated for proxy-based integration specs.

Changes

Proxy Integration Test Infrastructure

Layer / File(s)	Summary
Build deps and SandboxApp provisioning helper uts/build.gradle.kts, uts/src/test/kotlin/io/ably/lib/test/helper/SandboxApp.kt	Adds Ktor client test dependencies and proxy path JVM property passthrough, then introduces SandboxApp which provisions a sandbox app from a shared JSON payload and tears it down with authorized deletion.
ProxySession types and rule factories uts/src/test/kotlin/io/ably/lib/test/helper/ProxySession.kt	Defines the proxy rule alias and event model, then adds websocket and HTTP rule factory helpers for connect attempts, frames, and requests with optional match constraints and auto-removal counts.
ProxySession control API client and connectThroughProxy uts/src/test/kotlin/io/ably/lib/test/helper/ProxySession.kt	Implements ProxySession session creation, rule updates, action triggering, log retrieval, and cleanup against the proxy control API, and adds connectThroughProxy to retarget realtime and REST client settings through the local proxy port.
pollUntil utility and AuthReauthTest integration test uts/src/test/kotlin/io/ably/lib/Utils.kt, uts/src/test/kotlin/io/ably/lib/realtime/integration/proxy/AuthReauthTest.kt	Adds pollUntil as a suspend polling helper, then uses it in AuthReauthTest to connect through the proxy, inject protocol action 17, observe a single additional auth callback, keep the connection state connected, preserve the connection id, and verify the proxy log entry.
SKILL.md proxy translation guidance .claude/skills/uts-to-kotlin/SKILL.md	Updates the realtime integration spec output-path mapping and adds proxy integration translation guidance covering helper usage, lifecycle patterns, proxy rules, auth callbacks, log inspection, and sandbox execution notes.

Sequence Diagram(s)

sequenceDiagram
  participant AuthReauthTest
  participant ProxySession
  participant RealtimeClient
  participant AuthCallback

  AuthReauthTest->>ProxySession: create()
  AuthReauthTest->>RealtimeClient: connectThroughProxy(session)
  AuthReauthTest->>RealtimeClient: set authCallback
  AuthReauthTest->>RealtimeClient: connect()
  RealtimeClient->>AuthCallback: token request
  AuthCallback-->>RealtimeClient: signed TokenRequest
  AuthReauthTest->>ProxySession: triggerAction(action=17)
  ProxySession->>RealtimeClient: inject_to_client
  RealtimeClient->>AuthCallback: re-auth
  AuthReauthTest->>AuthReauthTest: pollUntil(callbackCount++)
  AuthReauthTest->>ProxySession: getLog()
  AuthReauthTest->>AuthReauthTest: assert connected, same connId, auth frame present

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐇 I hopped through proxy tunnels bright,
With sandbox apps and logs in sight.
I polled, I pounced, I watched auth glow,
Then waved at action seventeen below.
The connId stayed, the tests held true—
A nifty rabbit trick for you!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 69.57% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change by naming the new proxy test helpers and their integration-test purpose.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 AIT-767/proxy-support

---

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]

Actionable comments posted: 5

🤖 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.

Inline comments:
In @.claude/skills/uts-to-kotlin/SKILL.md:
- Line 531: The documentation example in the SKILL.md file shows AblyRest being
initialized with app.apiKey, but the actual SandboxApp object only exposes the
defaultKey property, not apiKey. Update the parameter in the AblyRest
constructor call at line 531 from app.apiKey to app.defaultKey to match both the
actual test implementation (AuthReauthTest) and the correct API exposed by the
SandboxApp object.
- Around line 573-581: Update the documentation statement for the getLog()
method to correctly state that it returns List<Event> instead of
List<Map<String, Any>>. Find and modify only the type description in the
documentation; the code example is already correct using dot notation and should
not be changed. Remove the note about Gson deserialization and .toInt() casting
since the Event data class has properly typed fields.

In
`@uts/src/test/kotlin/io/ably/lib/realtime/integration/proxy/AuthReauthTest.kt`:
- Around line 125-128: The session cleanup is not guaranteed because
session.close() is called after awaitState(...) which may throw an exception if
the wait times out. Wrap the awaitState(client, ConnectionState.closed,
10.seconds) call in its own try-catch or try-finally block to ensure that
session.close() is always invoked regardless of whether awaitState succeeds or
times out, guaranteeing the proxy session is properly cleaned up.

In `@uts/src/test/kotlin/io/ably/lib/test/helper/ProxySession.kt`:
- Line 18: The HttpClient initialization in ProxySession.kt at the client
variable declaration is missing explicit timeout configurations for request,
connect, and socket operations. Modify the HttpClient(CIO) instantiation to
include an engine configuration block that sets these three timeouts
(requestTimeoutMillis, connectTimeoutMillis, and socketTimeoutMillis) to
appropriate values to prevent indefinite hangs when the local proxy or control
endpoint becomes stalled during test execution.

In `@uts/src/test/kotlin/io/ably/lib/test/helper/SandboxApp.kt`:
- Around line 16-25: The HttpRequestRetry configuration is applying retry logic
to all HTTP methods including POST requests for app creation, which will cause
duplicate sandbox apps if a timeout occurs after the server successfully creates
the app. Modify the retryIf lambda in the install(HttpRequestRetry) block to
check the HTTP request method and only retry for idempotent requests (such as
GET, HEAD, OPTIONS). Exclude POST requests from being retried by adding a method
check that returns false when the request method is POST, ensuring that the POST
/apps endpoint is not retried on failure.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 67c0dd6c-8aad-455e-9007-71034d5268b6

📥 Commits

Reviewing files that changed from the base of the PR and between 0e5e684 and eded262.

📒 Files selected for processing (7)

• .claude/skills/uts-to-kotlin/SKILL.md
• uts/build.gradle.kts
• uts/src/test/kotlin/io/ably/lib/Utils.kt
• uts/src/test/kotlin/io/ably/lib/realtime/integration/proxy/AuthReauthTest.kt
• uts/src/test/kotlin/io/ably/lib/test/helper/ProxyManager.kt
• uts/src/test/kotlin/io/ably/lib/test/helper/ProxySession.kt
• uts/src/test/kotlin/io/ably/lib/test/helper/SandboxApp.kt

[Copilot]

Pull request overview

Adds programmable-proxy infrastructure to the UTS Kotlin integration tests, enabling tests to drive real Ably Sandbox traffic through uts-proxy with session-scoped fault injection and event logging.

Changes:

• Introduces ProxyManager to download/verify/cache and start a shared uts-proxy process for test suites.
• Adds ProxySession + rule factory helpers + client wiring (connectThroughProxy) for session-based proxy control and log inspection.
• Adds sandbox app provisioning/teardown helper (SandboxApp) and a first proxy-based integration test (AuthReauthTest), plus a polling utility for real-time waits.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
uts/src/test/kotlin/io/ably/lib/Utils.kt	Adds pollUntil utility for wall-clock polling in integration tests.
uts/src/test/kotlin/io/ably/lib/test/helper/SandboxApp.kt	Adds helper to provision/delete Ably sandbox apps for proxy suites.
uts/src/test/kotlin/io/ably/lib/test/helper/ProxySession.kt	Adds session API, rule factories, typed log events, and client proxy wiring.
uts/src/test/kotlin/io/ably/lib/test/helper/ProxyManager.kt	Adds proxy binary lifecycle management (download/verify/extract/start/health).
uts/src/test/kotlin/io/ably/lib/realtime/integration/proxy/AuthReauthTest.kt	Adds proxy integration test for server-initiated reauth (RTN22/RTC8a).
uts/build.gradle.kts	Adds Ktor client dependencies needed by the new test helpers.
.claude/skills/uts-to-kotlin/SKILL.md	Updates translation guidance to include proxy integration test flow and helpers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 7 comments.

[sacOO7]

LGTM