Skip to content

Commit 77a6677

Browse files
authored
Merge pull request #1235 from ably/integration/split-4-uts-side-modes
[Split 4/4] Run the UTS through the server door's builders
2 parents bf00ff4 + fb91b48 commit 77a6677

10 files changed

Lines changed: 284 additions & 15 deletions

File tree

‎.github/workflows/check.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,13 @@ jobs:
2525
uses: gradle/actions/setup-gradle@d9c87d481d55275bb5441eef3fe0e46805f9ef70 # v3
2626
- run: ./gradlew checkWithCodenarc checkstyleMain checkstyleTest runUnitTests runLiveObjectsUnitTests :uts:runUtsUnitTests
2727

28+
# A second UTS leg through the server door's builders (see the uts.side handling in
29+
# uts/.../ClientFactories.kt): the builders stamp a side-declaring agent entry and pass
30+
# everything else through, so conformance must be identical on both legs; SideModesTest
31+
# fails a leg whose stamp does not match. There is no device leg on the JVM — the device
32+
# door is an Android artifact, covered by the instrumentation tests in emulate.yml.
33+
- run: ./gradlew :uts:runUtsUnitTests -Duts.side=server
34+
2835
# Continuously proves the release pre-flight and that every published module
2936
# builds a publishable artifact set, so version/coordinate regressions surface
3037
# on PRs rather than on release day.

‎.github/workflows/integration-test.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -144,3 +144,7 @@ jobs:
144144
uses: gradle/actions/setup-gradle@d9c87d481d55275bb5441eef3fe0e46805f9ef70 # v3
145145

146146
- run: ./gradlew :uts:runUtsIntegrationTests
147+
148+
# A second leg through the server door's builders — see the uts.side handling in
149+
# uts/.../ClientFactories.kt and the matching leg in check.yml.
150+
- run: ./gradlew :uts:runUtsIntegrationTests -Duts.side=server

‎lib/src/main/java/io/ably/lib/debug/DebugOptions.java‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,10 @@ public DebugOptions copy() {
8787
copied.authParams = authParams;
8888
copied.queryTime = queryTime;
8989
copied.useTokenAuth = useTokenAuth;
90+
copied.headers = headers;
91+
copied.fallbackHosts = fallbackHosts;
92+
copied.transportParams = transportParams;
93+
copied.agents = agents;
9094
return copied;
9195
}
9296
}

‎uts/README.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -792,6 +792,42 @@ RUN_DEVIATIONS=1 ./gradlew :uts:runUtsUnitTests --tests "*ConnectionRecoveryTest
792792
`runLiveObjectsUnitTests`); `runUtsIntegrationTests` runs in the `check-uts` job of
793793
`integration-test.yml` (alongside `check-liveobjects`).
794794

795+
### Per-side package modes
796+
797+
The suite constructs its clients through a single seam (`TestRealtimeClient` / `TestRestClient`
798+
in `infra/unit/ClientFactories.kt`), selected by the `uts.side` system property (or the
799+
`UTS_SIDE` environment variable):
800+
801+
```bash
802+
./gradlew :uts:runUtsUnitTests # core (default): the core constructors
803+
./gradlew :uts:runUtsUnitTests -Duts.side=server # io.ably.pubsub:server — the PubSubServer builders
804+
```
805+
806+
The server builders only stamp the side-declaring agent entry (a versionless flag, per
807+
ably/ably-common#361) and pass everything else through — `DebugOptions` included, whose `copy()`
808+
override keeps the mock hooks — so every mode must pass identically. `SideModesTest` asserts each
809+
mode's stamp so a broken seam cannot silently degrade the server leg into a duplicate core run.
810+
CI runs both modes (`check.yml` and `integration-test.yml`).
811+
812+
Unlike ably-js's UTS there is no `device` mode: `io.ably.pubsub:device` is an Android artifact,
813+
so its door cannot run on the JVM this suite uses. Its stamping contract is covered by the
814+
instrumentation tests in the `device` module (`emulate.yml`).
815+
816+
**Token auth on the server leg.** Realtime rejects a token-authenticated connection that
817+
declares the server side through the agent entry alone (error 40167: on token auth the side
818+
must come from a signed `x-ably-clientType` token claim). The suite handles this per token
819+
format, with nothing skipped:
820+
821+
- **JWTs** can carry the claim already: tests that authenticate the client under test with a
822+
token mint one via `AblyJwt` (HS256, JDK crypto), adding `x-ably-clientType=server` on the
823+
server leg (see `AuthReauthTest`).
824+
- **Native tokens** cannot carry the claim yet, so a client may not authenticate *itself* with
825+
one while declaring the server side. `TokenRequestTest` therefore splits its clients across
826+
the seam, matching how the feature is really used: the **minting** client (the
827+
`createTokenRequest` surface under test) goes through the door on every leg, and the
828+
**consuming** client — modelling the device the token was minted for — is always a plain
829+
core client.
830+
795831
Notes:
796832
- `ProxyManager` **advises** running proxy suites single-fork (`maxParallelForks = 1`) because they
797833
share the control port (10100). This is not currently set in `uts/build.gradle.kts`; it isn't

‎uts/build.gradle.kts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ plugins {
66

77
dependencies {
88
testImplementation(project(":core"))
9+
// The server door package, so the suite can run through its side-stamping builders
10+
// (`-Duts.side=server`) as well as the core constructors. See ClientFactories.kt.
11+
testImplementation(project(":server"))
912
testImplementation(project(":network-client-core"))
1013
// Runtime-only so compile-time stays decoupled from the plugin internals; the LiveObjects test
1114
// helpers reach the internal wire/message classes (e.g. for build_public_object_message) by reflection.
@@ -39,6 +42,16 @@ tasks.withType<Test>().configureEach {
3942
.orElse(providers.environmentVariable("UTS_PROXY_LOCAL_PATH"))
4043
.getOrElse(""),
4144
)
45+
46+
// Which package's entry points the suite constructs clients through: `core` (default) or
47+
// `server` (the io.ably.pubsub:server builders). Forwarded explicitly for the same reason
48+
// as uts.proxy.localPath above. See ClientFactories.kt.
49+
systemProperty(
50+
"uts.side",
51+
providers.systemProperty("uts.side")
52+
.orElse(providers.environmentVariable("UTS_SIDE"))
53+
.getOrElse("core"),
54+
)
4255
}
4356

4457
tasks.register<Test>("runUtsUnitTests") {
Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
package io.ably.lib.uts.infra.integration
2+
3+
import java.util.Base64
4+
import javax.crypto.Mac
5+
import javax.crypto.spec.SecretKeySpec
6+
7+
/**
8+
* Minimal HS256 Ably JWT signer, built on JDK crypto only (no external JWT library).
9+
*
10+
* Exists for tests that need token claims the native Ably token format cannot carry —
11+
* notably `x-ably-clientType=server`: on token auth the realtime service accepts a
12+
* server-side declaration only from that signed claim (a `-server` agent entry alone is
13+
* rejected with error 40167), and the native token format cannot carry the claim yet. So a
14+
* JWT is the one way a token-authenticated client can declare the server side, which lets
15+
* JWT-based tests run on the server UTS leg. (Native-token tests instead keep their
16+
* token-consuming client on the core constructors, modelling the device the token was minted
17+
* for — see TokenRequestTest.)
18+
*/
19+
object AblyJwt {
20+
/**
21+
* Signs a JWT with the given Ably API key (`keyName:keySecret`), valid for [ttlSeconds],
22+
* with wildcard capability, and the optional Ably claims.
23+
*/
24+
fun sign(
25+
keyStr: String,
26+
clientId: String? = null,
27+
clientType: String? = null,
28+
ttlSeconds: Long = 3600,
29+
): String {
30+
val keyName = keyStr.substringBefore(':')
31+
val keySecret = keyStr.substringAfter(':')
32+
val now = System.currentTimeMillis() / 1000
33+
val header = """{"typ":"JWT","alg":"HS256","kid":"$keyName"}"""
34+
val claims = buildString {
35+
append("""{"iat":$now,"exp":${now + ttlSeconds},"x-ably-capability":"{\"*\":[\"*\"]}"""")
36+
if (clientId != null) append(""","x-ably-clientId":"$clientId"""")
37+
if (clientType != null) append(""","x-ably-clientType":"$clientType"""")
38+
append("}")
39+
}
40+
val enc = Base64.getUrlEncoder().withoutPadding()
41+
val signingInput = enc.encodeToString(header.toByteArray(Charsets.UTF_8)) + "." +
42+
enc.encodeToString(claims.toByteArray(Charsets.UTF_8))
43+
val mac = Mac.getInstance("HmacSHA256").apply {
44+
init(SecretKeySpec(keySecret.toByteArray(Charsets.UTF_8), "HmacSHA256"))
45+
}
46+
val signature = enc.encodeToString(mac.doFinal(signingInput.toByteArray(Charsets.UTF_8)))
47+
return "$signingInput.$signature"
48+
}
49+
}

‎uts/src/test/kotlin/io/ably/lib/uts/infra/unit/ClientFactories.kt‎

Lines changed: 36 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ package io.ably.lib.uts.infra.unit
33
import io.ably.lib.debug.DebugOptions
44
import io.ably.lib.realtime.AblyRealtime
55
import io.ably.lib.rest.AblyRest
6+
import io.ably.pubsub.server.PubSubServer
67

78
class ClientOptionsBuilder : DebugOptions("appId.keyId:keySecret") {
89
init {
@@ -17,8 +18,39 @@ class ClientOptionsBuilder : DebugOptions("appId.keyId:keySecret") {
1718
}
1819
}
1920

20-
fun TestRealtimeClient(block: ClientOptionsBuilder.() -> Unit): AblyRealtime =
21-
AblyRealtime(ClientOptionsBuilder().apply(block))
21+
/**
22+
* Which package's entry points the suite constructs clients through, selected by the
23+
* `uts.side` system property (uts/build.gradle.kts forwards it to the test JVM):
24+
*
25+
* - `core` (default): the core constructors, the entry shape of today's package.
26+
* - `server`: `io.ably.pubsub:server` — both client kinds via its side-stamping builders.
27+
*
28+
* There is no `device` mode, unlike ably-js's UTS: `io.ably.pubsub:device` is an Android
29+
* artifact, so its door cannot run on the JVM this suite uses; its stamping contract is
30+
* covered by the instrumentation tests in the device module instead.
31+
*
32+
* The builders only stamp the side-declaring agent entry and pass every other option
33+
* through — [DebugOptions] included: its `copy()` override keeps the mock hooks the suite
34+
* installs — so conformance must be identical whichever door constructed the client.
35+
* `SideModesTest` asserts each mode's stamp, so a broken seam cannot silently degrade the
36+
* server CI leg into a duplicate of the core leg.
37+
*/
38+
val utsSide: String = System.getProperty("uts.side").let { if (it.isNullOrEmpty()) "core" else it }
2239

23-
fun TestRestClient(block: ClientOptionsBuilder.() -> Unit): AblyRest =
24-
AblyRest(ClientOptionsBuilder().apply(block))
40+
fun TestRealtimeClient(block: ClientOptionsBuilder.() -> Unit): AblyRealtime {
41+
val options = ClientOptionsBuilder().apply(block)
42+
return when (utsSide) {
43+
"core" -> AblyRealtime(options)
44+
"server" -> PubSubServer.realtimeClientBuilder(options).build()
45+
else -> throw IllegalArgumentException("Unknown uts.side '$utsSide': use 'core' or 'server'")
46+
}
47+
}
48+
49+
fun TestRestClient(block: ClientOptionsBuilder.() -> Unit): AblyRest {
50+
val options = ClientOptionsBuilder().apply(block)
51+
return when (utsSide) {
52+
"core" -> AblyRest(options)
53+
"server" -> PubSubServer.httpClientBuilder(options).build()
54+
else -> throw IllegalArgumentException("Unknown uts.side '$utsSide': use 'core' or 'server'")
55+
}
56+
}

‎uts/src/test/kotlin/io/ably/lib/uts/integration/proxy/realtime/AuthReauthTest.kt‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,16 @@
11
package io.ably.lib.uts.integration.proxy.realtime
22

33
import io.ably.lib.realtime.ConnectionState
4-
import io.ably.lib.rest.AblyRest
54
import io.ably.lib.rest.Auth
65
import io.ably.lib.uts.infra.awaitState
6+
import io.ably.lib.uts.infra.integration.AblyJwt
77
import io.ably.lib.uts.infra.integration.SandboxApp
88
import io.ably.lib.uts.infra.integration.proxy.ProxyManager
99
import io.ably.lib.uts.infra.integration.proxy.ProxySession
1010
import io.ably.lib.uts.infra.integration.proxy.connectThroughProxy
1111
import io.ably.lib.uts.infra.pollUntil
1212
import io.ably.lib.uts.infra.unit.TestRealtimeClient
13+
import io.ably.lib.uts.infra.unit.utsSide
1314
import kotlinx.coroutines.runBlocking
1415
import kotlinx.coroutines.test.runTest
1516
import org.junit.jupiter.api.AfterAll
@@ -59,14 +60,19 @@ class AuthReauthTest {
5960
val session = ProxySession.create(rules = emptyList())
6061

6162
// Re-authentication is observed via an authCallback. The spec generates a JWT from the
62-
// sandbox key parts; the idiomatic ably-java equivalent is a locally-signed TokenRequest
63-
// produced from the same key — no external JWT library required. The realtime client then
64-
// exchanges it for a token (through the proxy), satisfying RTC8a.
65-
val tokenSigner = AblyRest(app.defaultKey)
63+
// sandbox key parts, and so does this test (AblyJwt: HS256 via JDK crypto, no external
64+
// library). A JWT rather than a native TokenRequest is load-bearing on the server UTS
65+
// leg: a token-authenticated client may declare the server side only via the signed
66+
// x-ably-clientType claim, which the native token format cannot carry yet — so the JWT
67+
// carries the claim on the server leg, and this test runs on every leg.
6668
val authCallbackCount = AtomicInteger(0)
6769
val authCallback = Auth.TokenCallback { params ->
6870
authCallbackCount.incrementAndGet()
69-
tokenSigner.auth.createTokenRequest(params, null)
71+
AblyJwt.sign(
72+
app.defaultKey,
73+
clientId = params.clientId,
74+
clientType = if (utsSide == "server") "server" else null,
75+
)
7076
}
7177

7278
// Keep the JSON protocol (ClientOptionsBuilder default): the proxy injects/inspects frames
@@ -128,13 +134,12 @@ class AuthReauthTest {
128134
"Expected at least one client-to-server AUTH frame carrying auth details",
129135
)
130136
} finally {
131-
// Nest teardown so session/tokenSigner are always cleaned up even if close-wait times out.
137+
// Nest teardown so the session is always cleaned up even if close-wait times out.
132138
try {
133139
client.close()
134140
awaitState(client, ConnectionState.closed, 10.seconds)
135141
} finally {
136142
session.close()
137-
runCatching { tokenSigner.close() }
138143
}
139144
}
140145
}

‎uts/src/test/kotlin/io/ably/lib/uts/integration/standard/realtime/TokenRequestTest.kt‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
package io.ably.lib.uts.integration.standard.realtime
22

3+
import io.ably.lib.realtime.AblyRealtime
34
import io.ably.lib.realtime.ConnectionState
45
import io.ably.lib.rest.Auth
56
import io.ably.lib.uts.infra.awaitState
67
import io.ably.lib.uts.infra.integration.SandboxApp
7-
import io.ably.lib.uts.infra.unit.TestRealtimeClient
8+
import io.ably.lib.uts.infra.unit.ClientOptionsBuilder
89
import io.ably.lib.uts.infra.unit.TestRestClient
910
import kotlinx.coroutines.runBlocking
1011
import kotlinx.coroutines.test.runTest
@@ -29,6 +30,14 @@ import kotlin.time.Duration.Companion.seconds
2930
* server. A REST client signs the TokenRequest; a separate realtime client exchanges it (through
3031
* its `authCallback`) for a token and connects, proving the server accepted it.
3132
*
33+
* The two clients deliberately sit on different sides of the seam. The **minting** client — the
34+
* RSA9 surface under test — goes through [TestRestClient], so on the server UTS leg it exercises
35+
* `createTokenRequest` through the server door, the shape a real server has: mint native tokens
36+
* for others. The **consuming** client models the device those tokens are minted for, so it is
37+
* always a plain core client: a client may not authenticate *itself* with a native token while
38+
* declaring the server side (realtime rejects that with 40167 — on token auth the side must come
39+
* from the signed x-ably-clientType claim, which the native token format cannot carry).
40+
*
3241
* Spec points: RSA9, RSA9a, RSA9g. Source spec: `realtime/integration/auth/token_request_test.md`.
3342
*/
3443
@TestInstance(TestInstance.Lifecycle.PER_CLASS)
@@ -46,6 +55,10 @@ class TokenRequestTest {
4655
if (::app.isInitialized) app.delete()
4756
}
4857

58+
/** The token-consuming client — a plain core client on every leg; see the class doc. */
59+
private fun tokenConsumingClient(block: ClientOptionsBuilder.() -> Unit): AblyRealtime =
60+
AblyRealtime(ClientOptionsBuilder().apply(block))
61+
4962
/**
5063
* @UTS realtime/integration/RSA9a/token-request-server-accepted-0
5164
* @UTS realtime/integration/RSA9g/token-request-server-accepted-0
@@ -59,7 +72,7 @@ class TokenRequestTest {
5972
}
6073

6174
// Client B connects using a TokenRequest produced by client A.
62-
val client = TestRealtimeClient {
75+
val client = tokenConsumingClient {
6376
authCallback = Auth.TokenCallback { params -> creator.auth.createTokenRequest(params, null) }
6477
realtimeHost = SandboxApp.sandboxHost
6578
restHost = SandboxApp.sandboxHost
@@ -94,7 +107,7 @@ class TokenRequestTest {
94107

95108
// The TokenRequest is signed with the specific clientId, producing a token that
96109
// authenticates the client with that identity.
97-
val client = TestRealtimeClient {
110+
val client = tokenConsumingClient {
98111
authCallback = Auth.TokenCallback { params ->
99112
params.clientId = testClientId
100113
creator.auth.createTokenRequest(params, null)

0 commit comments

Comments
 (0)