Delegate proxy port assignment to uts-proxy in all test specs

Remove client-side allocated_port/port_base patterns from all proxy
test specs and helper docs. Port is now auto-assigned by the proxy
when omitted from create_proxy_session(). Matches uts-proxy v0.2.0.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: paddybyers

uts/docs/integration-testing.md

@@ -157,7 +157,6 @@ Proxy tests additionally set up a proxy session per test or group of tests. See
 BEFORE EACH TEST:
   session = create_proxy_session(
     endpoint: "nonprod:sandbox",
-    port: allocated_port,
     rules: [ ...initial rules... ]
   )
 

uts/docs/writing-test-specs.md

@@ -344,7 +344,6 @@ Tests that [behaviour] when the proxy injects [fault].
 ```pseudo
 session = create_proxy_session(
   target: TargetConfig(realtimeHost: "sandbox.realtime.ably-nonprod.net", restHost: "sandbox.realtime.ably-nonprod.net"),
-  port: allocated_port,
   rules: [{
     "match": { ... },
     "action": { ... },

uts/objects/integration/proxy/objects_faults.md

@@ -80,7 +80,7 @@ channel_name = "objects-sync-interrupt-" + random_id()
 // Disconnect after first OBJECT_SYNC frame
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
+
   rules: [{
     "match": { "type": "ws_frame_to_client", "action": 20 },
     "action": { "type": "disconnect" },
@@ -163,7 +163,7 @@ AWAIT root_a.set("key1", "initial")
 // Client B: through proxy, will be disconnected
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
+
   rules: []
 )
 
@@ -242,7 +242,7 @@ channel_name = "objects-detach-resync-" + random_id()
 
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
+
   rules: []
 )
 
@@ -318,7 +318,7 @@ channel_name = "objects-publish-failed-" + random_id()
 
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
+
   rules: []
 )
 
@@ -403,7 +403,7 @@ AWAIT root_a.set("existing", "before")
 // Client B: through proxy with delayed OBJECT_SYNC
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
+
   rules: [{
     "match": { "type": "ws_frame_to_client", "action": 20 },
     "action": { "type": "delay", "delayMs": 3000 },

uts/realtime/integration/helpers/proxy.md

@@ -20,7 +20,6 @@ Proxy integration tests use this to verify fault-handling behaviour against the
 # 1. Create a proxy session with rules
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
   rules: [ ...rules... ]
 )
 
@@ -58,7 +57,7 @@ session.close()
 interface ProxySession:
   session_id: String
   proxy_host: String     # Always "localhost"
-  proxy_port: Int        # Assigned from port pool
+  proxy_port: Int        # Auto-assigned by proxy, or explicit if specified
 
   add_rules(rules: List<Rule>, position?: "append"|"prepend")
   trigger_action(action: ActionRequest)
@@ -67,7 +66,7 @@ interface ProxySession:
 
 function create_proxy_session(
   endpoint: String,       # e.g. "nonprod:sandbox" → resolves to sandbox.realtime.ably-nonprod.net
-  port: Int,
+  port?: Int,             # Optional; proxy auto-assigns a free port if omitted
   rules?: List<Rule>,
   timeoutMs?: Int         # Session auto-cleanup timeout (default 30000)
 ): ProxySession

uts/realtime/integration/proxy/auth_reauth.md

@@ -31,16 +31,6 @@ AFTER ALL TESTS:
     WITH Authorization: Basic {api_key}
 ```
 
-## Port Allocation
-
-Each test allocates a unique proxy port to avoid conflicts:
-
-```pseudo
-BEFORE ALL TESTS:
-  port_base = allocate_port_range(count: 1)
-  # Tests use port_base + 0
-```
-
 ---
 
 ## Test 26: RTN22/RTC8a -- Server-initiated re-authentication
@@ -63,7 +53,6 @@ Tests that when the proxy injects a server-initiated AUTH ProtocolMessage (actio
 ```pseudo
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: port_base + 0,
   rules: []
 )
 ```
@@ -83,7 +72,7 @@ auth_callback = FUNCTION(params, callback):
 client = Realtime(options: ClientOptions(
   authCallback: auth_callback,
   endpoint: "localhost",
-  port: port_base + 0,
+  port: session.proxy_port,
   tls: false,
   useBinaryProtocol: false,
   autoConnect: false

uts/realtime/integration/proxy/channel_faults.md

@@ -71,7 +71,7 @@ channel_name = "test-RTL4f-${random_id()}"
 # Create proxy session that suppresses ATTACH messages for our channel
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
+
   rules: [{
     "match": { "type": "ws_frame_to_server", "action": "ATTACH", "channel": channel_name },
     "action": { "type": "suppress" },
@@ -177,7 +177,7 @@ channel_name = "test-RTL14-error-on-attach-${random_id()}"
 # Create proxy session that replaces ATTACHED with channel ERROR
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
+
   rules: [{
     "match": { "type": "ws_frame_to_client", "action": "ATTACHED", "channel": channel_name },
     "action": {
@@ -274,7 +274,7 @@ channel_name = "test-RTL5f-${random_id()}"
 # Phase 1: Create proxy session with NO fault rules (clean passthrough)
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
+
   rules: []
 )
 
@@ -374,7 +374,7 @@ channel_name = "test-RTL13a-${random_id()}"
 # Create proxy session with clean passthrough (no fault rules initially)
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
+
   rules: []
 )
 
@@ -471,7 +471,7 @@ channel_name = "test-RTL14-${random_id()}"
 # Create proxy session with clean passthrough
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
+
   rules: []
 )
 
@@ -563,7 +563,7 @@ channel_name = "test-RTL12-${random_id()}"
 # Create proxy session with clean passthrough
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
+
   rules: []
 )
 
@@ -666,7 +666,7 @@ channel_b_name = "test-RTL3d-b-${random_id()}"
 # Create proxy session with clean passthrough
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
+
   rules: []
 )
 

uts/realtime/integration/proxy/connection_open_failures.md

@@ -66,7 +66,7 @@ Tests that when the server responds with a fatal ERROR (non-token error code) du
 # Create proxy session that replaces the first CONNECTED with a fatal ERROR
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
+
   rules: [{
     "match": { "type": "ws_frame_to_client", "action": "CONNECTED" },
     "action": {
@@ -151,7 +151,7 @@ auth_callback_count = 0
 # Create proxy session that injects token error on first CONNECTED only
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
+
   rules: [{
     "match": { "type": "ws_frame_to_client", "action": "CONNECTED" },
     "action": {
@@ -246,7 +246,7 @@ Tests that when the first WebSocket connection is refused at the transport level
 # Create proxy session that refuses the first WebSocket connection
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
+
   rules: [{
     "match": { "type": "ws_connect", "count": 1 },
     "action": { "type": "refuse_connection" },
@@ -325,7 +325,7 @@ Tests that when the server responds with a connection-level ERROR (no channel fi
 # Create proxy session that replaces the first CONNECTED with a server ERROR
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
+
   rules: [{
     "match": { "type": "ws_frame_to_client", "action": "CONNECTED" },
     "action": {
@@ -408,7 +408,7 @@ Tests that when the server accepts the WebSocket but never sends a CONNECTED mes
 # Create proxy session that suppresses all CONNECTED messages
 session = create_proxy_session(
   endpoint: "nonprod:sandbox",
-  port: allocated_port,
+
   rules: [{
     "match": { "type": "ws_frame_to_client", "action": "CONNECTED" },
     "action": { "type": "suppress" },