@devries-cameron20 / t3code-1 / commits / c8e240771b
Fork 0

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 },