Open History to see the last commit
1import { EnvironmentId, type ExecutionEnvironmentDescriptor } from "@t3tools/contracts";
2import { RelayEnvironmentEndpointFailure } from "@t3tools/contracts/relay";
3import * as Schema from "effect/Schema";
4
5const ConnectionTargetBase = {
6 environmentId: EnvironmentId,
7 label: Schema.String,
8};
9
10export class PrimaryConnectionTarget extends Schema.TaggedClass<PrimaryConnectionTarget>()(
11 "PrimaryConnectionTarget",
12 {
13 ...ConnectionTargetBase,
14 httpBaseUrl: Schema.String,
15 wsBaseUrl: Schema.String,
16 },
17) {}
18
19export class BearerConnectionTarget extends Schema.TaggedClass<BearerConnectionTarget>()(
20 "BearerConnectionTarget",
21 {
22 ...ConnectionTargetBase,
23 connectionId: Schema.String,
24 },
25) {}
26
27export class RelayConnectionTarget extends Schema.TaggedClass<RelayConnectionTarget>()(
28 "RelayConnectionTarget",
29 {
30 ...ConnectionTargetBase,
31 },
32) {}
33
34export class SshConnectionTarget extends Schema.TaggedClass<SshConnectionTarget>()(
35 "SshConnectionTarget",
36 {
37 ...ConnectionTargetBase,
38 connectionId: Schema.String,
39 },
40) {}
41
42export const ConnectionTarget = Schema.Union([
43 PrimaryConnectionTarget,
44 BearerConnectionTarget,
45 RelayConnectionTarget,
46 SshConnectionTarget,
47]);
48export type ConnectionTarget = typeof ConnectionTarget.Type;
49
50export const PersistedConnectionTarget = Schema.Union([
51 BearerConnectionTarget,
52 RelayConnectionTarget,
53 SshConnectionTarget,
54]);
55export type PersistedConnectionTarget = typeof PersistedConnectionTarget.Type;
56
57export type NetworkStatus = "unknown" | "offline" | "online";
58
59export const ConnectionTransientReason = Schema.Literals([
60 "network",
61 "timeout",
62 "transport",
63 "endpoint-unavailable",
64 "relay-unavailable",
65 "remote-unavailable",
66 "session-pending",
67]);
68export type ConnectionTransientReason = typeof ConnectionTransientReason.Type;
69
70export const ConnectionBlockedReason = Schema.Literals([
71 "authentication",
72 "configuration",
73 "permission",
74 "unsupported",
75]);
76export type ConnectionBlockedReason = typeof ConnectionBlockedReason.Type;
77
78/** A part of the path to an environment: this device, T3 Connect, the host's tunnel, or T3 Code on the host. */
79export const ConnectionHop = Schema.Literals(["device", "relay", "tunnel", "server"]);
80export type ConnectionHop = typeof ConnectionHop.Type;
81
82/** The relay's endpoint failures plus the causes the client can name from other errors. */
83export const ConnectionFailureCause = Schema.Literals([
84 ...RelayEnvironmentEndpointFailure.literals,
85 "clock_skew",
86 "not_linked",
87 "relay_error",
88 "tunnel_pending",
89 "tunnel_not_enabled",
90]);
91export type ConnectionFailureCause = typeof ConnectionFailureCause.Type;
92
93/**
94 * Where and why a failure happened, when the code that saw it knows. See
95 * `presentConnectionDiagnosis`. `via` names the route when the hop alone does
96 * not: T3 Code on the host can fail behind the tunnel or on a direct route.
97 */
98const ConnectionFailureFields = {
99 hop: Schema.optionalKey(ConnectionHop),
100 via: Schema.optionalKey(Schema.Literals(["relay", "direct"])),
101 failureCause: Schema.optionalKey(ConnectionFailureCause),
102 httpStatus: Schema.optionalKey(Schema.Number),
103};
104
105export class ConnectionTransientError extends Schema.TaggedError<ConnectionTransientError>()(
106 "ConnectionTransientError",
107 {
108 reason: ConnectionTransientReason,
109 detail: Schema.String,
110 traceId: Schema.optionalKey(Schema.String),
111 ...ConnectionFailureFields,
112 },
113) {
114 override get message(): string {
115 return this.detail;
116 }
117}
118
119export class ConnectionBlockedError extends Schema.TaggedError<ConnectionBlockedError>()(
120 "ConnectionBlockedError",
121 {
122 reason: ConnectionBlockedReason,
123 detail: Schema.String,
124 traceId: Schema.optionalKey(Schema.String),
125 ...ConnectionFailureFields,
126
127 serverUpdateRequired: Schema.optionalKey(Schema.Boolean),
128 },
129) {
130 override get message(): string {
131 return this.detail;
132 }
133}
134
135export type ConnectionAttemptError = ConnectionTransientError | ConnectionBlockedError;
136
137export const DPOP_ACCESS_TOKEN_REFRESH_SKEW_MS = 60_000;
138
139export type PreparedHttpAuthorization =
140 | {
141 readonly _tag: "Bearer";
142 readonly token: string;
143 }
144 | {
145 readonly _tag: "Dpop";
146 readonly accessToken: string;
147 readonly expiresAtEpochMs: number;
148 };
149
150export interface PreparedConnection {
151 readonly environmentId: EnvironmentId;
152 readonly label: string;
153 readonly httpBaseUrl: string;
154 readonly socketUrl: string;
155 readonly httpAuthorization: PreparedHttpAuthorization | null;
156 readonly target: ConnectionTarget;
157 /** What the server said about itself while this connection was prepared. */
158 readonly descriptor?: ExecutionEnvironmentDescriptor;
159}
160
161export type SupervisorConnectionPhase =
162 | "available"
163 | "offline"
164 | "connecting"
165 | "backoff"
166 | "connected"
167 | "blocked";
168
169export type ConnectionAttemptStage = "preparing" | "opening" | "synchronizing";
170
171export interface SupervisorConnectionState {
172 readonly desired: boolean;
173 readonly network: NetworkStatus;
174 readonly phase: SupervisorConnectionPhase;
175 readonly stage: ConnectionAttemptStage | null;
176 readonly attempt: number;
177 readonly generation: number;
178 readonly lastFailure: ConnectionAttemptError | null;
179 readonly retryAt: number | null;
180}
181
182export type ConnectionProjectionPhase = "disconnected" | "synchronizing" | "ready";
183
184export function connectionProjectionPhase(
185 state: SupervisorConnectionState,
186): ConnectionProjectionPhase {
187 switch (state.phase) {
188 case "connecting":
189 return "synchronizing";
190 case "connected":
191 return "ready";
192 case "available":
193 case "offline":
194 case "backoff":
195 case "blocked":
196 return "disconnected";
197 }
198}
199
200export const AVAILABLE_CONNECTION_STATE: SupervisorConnectionState = Object.freeze({
201 desired: false,
202 network: "unknown",
203 phase: "available",
204 stage: null,
205 attempt: 0,
206 generation: 0,
207 lastFailure: null,
208 retryAt: null,
209});