The best way to control Claude Code, Codex and more from any computer or phone
fix(relay): preserve provisioning failure stage in client errors (#14581)
Co-authored-by: Ennio Cuteri <enniocuteri@fluence-group.com> Co-authored-by: Julius Marminge <julius0216@outlook.com>
ECuteri committed
Oct 20, 2026 at 07:07 UTC
c8e240771b73f608be88b54226bda55731a215ac
6 files changed
+149
-4
infra/relay/src/http/Api.test.ts
+101
@@ -26,6 +26,7 @@ import * as Layer from "effect/Layer";
26
import * as Option from "effect/Option";
27
import * as Predicate from "effect/Predicate";
28
import * as Redacted from "effect/Redacted";
29
+import * as Schema from "effect/Schema";
30
import * as TestClock from "effect/testing/TestClock";
31
import * as Tracer from "effect/Tracer";
32
import * as Etag from "effect/http/Etag";
@@ -41,7 +42,10 @@ import {
42
RelayEnvironmentAuth,
43
RelayEnvironmentPrincipal,
44
RelayApi,
45
+ RelayEnvironmentLinkUnavailableError,
46
+ RelayEnvironmentLinkRequest,
47
} from "@t3tools/contracts/relay";
48
+import { relayProtectedErrorMessage } from "@t3tools/client-runtime/relay";
49
import { RELAY_MANAGED_TUNNEL_RECOVERY_TYP, signRelayJwt } from "@t3tools/shared/relayJwt";
50
51
import {
@@ -93,6 +97,103 @@ const relaySettings: RelayConfiguration.RelayConfiguration["Service"] = {
97
managedEndpointNamespace: undefined,
98
};
99
100
+const encodeLinkRequest = Schema.encodeEffect(Schema.fromJsonString(RelayEnvironmentLinkRequest));
101
+const decodeLinkUnavailableError = Schema.decodeUnknownEffect(RelayEnvironmentLinkUnavailableError);
102
+
103
+describe("managed endpoint provisioning errors", () => {
104
+ it.effect("returns the failed stage without exposing provider secrets through HTTP", () => {
105
+ let traceId = "";
106
+ const handlers = RelayHttpApi.layerClientApi.pipe(
107
+ HttpRouter.provideRequest(
108
+ Layer.mergeAll(
109
+ Layer.mock(EnvironmentCredentials.EnvironmentCredentials, {}),
110
+ Layer.mock(EnvironmentLinks.EnvironmentLinks, {}),
111
+ Layer.mock(ManagedEndpointProvider.ManagedEndpointProvider, {}),
112
+ Layer.mock(RelayDb.RelayTransactions, {}),
113
+ Layer.mock(HookInbox.HookInbox, {}),
114
+ ),
115
+ ),
116
+ Layer.provide(
117
+ Layer.mergeAll(
118
+ Layer.succeed(RelayConfiguration.RelayConfiguration, relaySettings),
119
+ NodeCryptoLayer.layer,
120
+ Layer.mock(RelayTokens.RelayTokens, { resolveDpopAccessTokenScopes: () => null }),
121
+ Layer.mock(EnvironmentLinker.EnvironmentLinker, {
122
+ link: () =>
123
+ Effect.gen(function* () {
124
+ traceId = (yield* Effect.currentSpan.pipe(Effect.orDie)).traceId;
125
+ return yield* new ManagedEndpointProvider.ManagedEndpointProvisioningFailed({
126
+ userId: "user-1",
127
+ environmentId: "environment-1",
128
+ stage: "ensure-tunnel",
129
+ tunnelId: "private-tunnel-id",
130
+ cause: new Error("private-provider-token"),
131
+ });
132
+ }),
133
+ }),
134
+ Layer.mock(EnvironmentLinks.EnvironmentLinks, {}),
135
+ Layer.mock(ManagedEndpointProvider.ManagedEndpointProvider, {}),
136
+ Layer.mock(Devices.Devices, {}),
137
+ ),
138
+ ),
139
+ Layer.provideMerge(
140
+ Layer.succeed(RelayClientAuth, {
141
+ clientBearer: (effect) =>
142
+ Effect.provideService(effect, RelayClientPrincipal, {
143
+ userId: "user-1",
144
+ token: "test-token",
145
+ }),
146
+ }),
147
+ ),
148
+ );
149
+ return Effect.gen(function* () {
150
+ const app = yield* Effect.acquireRelease(
151
+ Effect.sync(() =>
152
+ HttpRouter.toWebHandler(
153
+ HttpApiBuilder.layer(HttpApi.make("RelayApi").add(RelayApi.groups.client)).pipe(
154
+ Layer.provide(handlers),
155
+ Layer.provide(HttpServer.layerServices),
156
+ ),
157
+ { disableLogger: true },
158
+ ),
159
+ ),
160
+ (app) => Effect.promise(() => app.dispose()),
161
+ );
162
+ const payload = yield* encodeLinkRequest({
163
+ proof: "test-proof",
164
+ notificationsEnabled: false,
165
+ liveActivitiesEnabled: false,
166
+ managedTunnelsEnabled: true,
167
+ });
168
+ const response = yield* Effect.promise(() =>
169
+ app.handler(
170
+ new Request("https://relay.example.test/v1/client/environment-links", {
171
+ method: "POST",
172
+ headers: {
173
+ authorization: "Bearer test-token",
174
+ "content-type": "application/json",
175
+ },
176
+ body: payload,
177
+ }),
178
+ ),
179
+ );
180
+ expect(response.status).toBe(503);
181
+ const body = yield* Effect.promise(() => response.json());
182
+ expect(body).toEqual({
183
+ _tag: "RelayEnvironmentLinkUnavailableError",
184
+ code: "environment_link_unavailable",
185
+ reason: "managed_endpoint_provisioning_failed",
186
+ provisioningStage: "ensure-tunnel",
187
+ traceId,
188
+ });
189
+ const error = yield* decodeLinkUnavailableError(body);
190
+ expect(relayProtectedErrorMessage(error)).toBe(
191
+ "Relay cannot provision the managed endpoint (managed_endpoint_provisioning_failed). Failed stage: ensure-tunnel.",
192
+ );
193
+ }).pipe(Effect.scoped);
194
+ });
195
+});
196
+
197
describe("device listing compatibility", () => {
198
it.effect("keeps v1 iOS-only while v2 returns every platform for the same account", () => {
199
const iphone: RelayClientDeviceRecord = {
infra/relay/src/http/Api.ts
+2
-1
@@ -904,10 +904,11 @@ export const layerClientApi = HttpApiBuilder.group(
904
reason: "managed_endpoint_not_configured",
905
traceId,
906
}),
907
- ManagedEndpointProvisioningFailed: (_error, traceId) =>
907
+ ManagedEndpointProvisioningFailed: (error, traceId) =>
908
new RelayEnvironmentLinkUnavailableError({
909
code: "environment_link_unavailable",
910
reason: "managed_endpoint_provisioning_failed",
911
+ provisioningStage: error.stage,
912
traceId,
913
}),
914
ManagedEndpointOriginNotAllowed: (_error, traceId) =>
packages/client-runtime/src/relay/errorPresentation.test.ts
+21
-1
@@ -1,5 +1,9 @@
1
-import { RelayAuthInvalidError } from "@t3tools/contracts/relay";
1
+import {
2
+ RelayAuthInvalidError,
3
+ RelayEnvironmentLinkUnavailableError,
4
+} from "@t3tools/contracts/relay";
5
import { describe, expect, it } from "@effect/vitest";
6
+import * as Schema from "effect/Schema";
7
8
import {
9
DPOP_CLOCK_HINT,
@@ -8,7 +12,23 @@ import {
12
relayProtectedErrorMessage,
13
} from "./errorPresentation.ts";
14
15
+const decodeLinkUnavailableError = Schema.decodeUnknownSync(RelayEnvironmentLinkUnavailableError);
16
+
17
describe("relayProtectedErrorMessage", () => {
18
+ it("decodes older relay failures and preserves their reason-only message", () => {
19
+ const error = decodeLinkUnavailableError({
20
+ _tag: "RelayEnvironmentLinkUnavailableError",
21
+ code: "environment_link_unavailable",
22
+ reason: "managed_endpoint_provisioning_failed",
23
+ traceId: "trace-1",
24
+ });
25
+
26
+ expect(error.traceId).toBe("trace-1");
27
+ expect(relayProtectedErrorMessage(error)).toBe(
28
+ "Relay cannot provision the managed endpoint (managed_endpoint_provisioning_failed).",
29
+ );
30
+ });
31
+
32
it("presents clock skew as one possible cause when the relay omits the reason", () => {
33
const error = new RelayAuthInvalidError({
34
code: "auth_invalid",
packages/client-runtime/src/relay/errorPresentation.ts
+3
-1
@@ -59,7 +59,9 @@ export function relayProtectedErrorMessage(error: RelayProtectedError): string {
59
case "RelayEnvironmentLinkFailedError":
60
return `Relay could not link the environment (${error.reason}).`;
61
case "RelayEnvironmentLinkUnavailableError":
62
- return `Relay cannot provision the managed endpoint (${error.reason}).`;
62
+ return `Relay cannot provision the managed endpoint (${error.reason}).${
63
+ error.provisioningStage ? ` Failed stage: ${error.provisioningStage}.` : ""
64
+ }`;
65
case "RelayEnvironmentLinkLimitExceededError":
66
return `Relay refused the link: this account already has its maximum of ${error.maxTunnels} managed tunnels. Unlink an environment to free one up.`;
67
case "RelayAgentActivityPublishProofExpiredError":
packages/contracts/src/relay.test.ts
+21
-1
@@ -2,7 +2,13 @@ import { describe, expect, it } from "vite-plus/test";
2
import * as OpenApi from "effect/http-api/OpenApi";
3
import * as Schema from "effect/Schema";
4
5
-import { RelayApi, RelayDeviceRegistrationRequest } from "./relay.ts";
5
+import {
6
+ RelayApi,
7
+ RelayDeviceRegistrationRequest,
8
+ RelayEnvironmentLinkUnavailableError,
9
+} from "./relay.ts";
10
+
11
+const decodeLinkUnavailableError = Schema.decodeUnknownSync(RelayEnvironmentLinkUnavailableError);
12
13
const decodeDevice = Schema.decodeUnknownExit(RelayDeviceRegistrationRequest);
14
const device = {
@@ -48,6 +54,20 @@ describe("mobile device platforms", () => {
54
});
55
});
56
57
+describe("relay provisioning error compatibility", () => {
58
+ it("preserves a stage introduced by a newer relay", () => {
59
+ const error = {
60
+ _tag: "RelayEnvironmentLinkUnavailableError",
61
+ code: "environment_link_unavailable",
62
+ reason: "managed_endpoint_provisioning_failed",
63
+ provisioningStage: "future-provisioning-stage",
64
+ traceId: "trace-1",
65
+ };
66
+
67
+ expect(decodeLinkUnavailableError(error)).toMatchObject(error);
68
+ });
69
+});
70
+
71
describe("RelayApi security", () => {
72
it("describes DPoP access tokens using the HTTP DPoP authorization scheme", () => {
73
const document = OpenApi.fromApi(RelayApi);
packages/contracts/src/relay.ts
+1
@@ -523,6 +523,7 @@ export class RelayEnvironmentLinkUnavailableError extends Schema.TaggedError<Rel
523
{
524
code: Schema.Literal("environment_link_unavailable"),
525
reason: RelayEnvironmentLinkUnavailableReason,
526
+ provisioningStage: Schema.optionalKey(TrimmedNonEmptyString),
527
traceId: TrimmedNonEmptyString,
528
},
529
{ httpApiStatus: 503 },