65
}
66
}
68
>
69
>
/** A recently used tunnel cached in storage. */
70
>
export interface ICachedTunnel {
71
>
readonly tunnelId: string;
72
>
readonly clusterId: string;
73
>
readonly name: string;
74
>
readonly authProvider?: 'github' | 'microsoft';
75
>
}
76
>
77
>
/** Information about a discovered dev tunnel with an agent host. */
78
>
export interface ITunnelInfo {
79
>
/** The tunnel's unique identifier. */
80
>
readonly tunnelId: string;
81
>
/** The cluster region where the tunnel is hosted. */
82
>
readonly clusterId: string;
83
>
/** Display name derived from tunnel tags or tunnel name. */
84
>
readonly name: string;
85
>
/** All tags/labels on the tunnel. */
86
>
readonly tags: readonly string[];
87
>
/** Parsed protocol version from tags. */
88
>
readonly protocolVersion: number;
89
>
/** Number of hosts currently accepting connections (0 = offline). */
90
>
readonly hostConnectionCount: number;
91
>
}
92
>
93
>
/**
94
>
* Serializable result from a successful tunnel connect operation.
95
>
* Returned over IPC from the shared process.
96
>
*/
97
>
export interface ITunnelConnectResult {
98
>
/** Unique identifier for this connection's relay channel. */
99
>
readonly connectionId: string;
100
>
/** Display-friendly address (e.g. "tunnel:myTunnel"). */
101
>
readonly address: string;
102
>
/** Display name for the tunnel. */
103
>
readonly name: string;
104
>
/** Connection token derived from the tunnel ID. */
105
>
readonly connectionToken: string;
106
>
}
107
>
108
>
/**
109
>
* A message relayed from a remote agent host through the tunnel.
110
>
* The shared process acts as a WebSocket proxy, forwarding JSON
111
>
* messages bidirectionally between the tunnel and the renderer via IPC.
112
>
*/
113
>
export interface ITunnelRelayMessage {
114
>
readonly connectionId: string;
115
>
readonly data: string;
116
>
}
117
>
118
>
/**
119
>
* Main-process (shared process) service that manages dev tunnel
120
>
* connections. The renderer calls this over IPC and handles registration
121
>
* with {@link IRemoteAgentHostService} locally.
122
>
*/
123
>
export const ITunnelAgentHostMainService = createDecorator<ITunnelAgentHostMainService>('tunnelAgentHostMainService');
124
>
125
>
export interface ITunnelAgentHostMainService {
126
>
readonly _serviceBrand: undefined;
127
>
128
>
/** Fires when a message is received from a remote agent host via the tunnel relay. */
129
>
readonly onDidRelayMessage: Event<ITunnelRelayMessage>;
130
>
131
>
/** Fires when a relay connection to a remote agent host closes. */
132
>
readonly onDidRelayClose: Event<string /* connectionId */>;
133
>
134
>
/**
135
>
* List dev tunnels associated with the user's account that have
136
>
* the `vscode-server-launcher` label and a protocol version tag
137
>
* of at least {@link TUNNEL_MIN_PROTOCOL_VERSION}.
138
>
*
139
>
* @param token The user's access token (GitHub or Microsoft).
140
>
* @param authProvider The auth provider that issued the token.
141
>
* @param additionalTunnelNames Optional tunnel names to look up
142
>
* in addition to the account-wide enumeration.
143
>
*/
144
>
listTunnels(token: string, authProvider: 'github' | 'microsoft', additionalTunnelNames?: string[]): Promise<ITunnelInfo[]>;
145
>
146
>
/**
147
>
* Connect to a tunnel's agent host via the dev tunnels relay and
148
>
* begin relaying WebSocket messages through IPC.
149
>
*
150
>
* @param token The user's access token (GitHub or Microsoft).
151
>
* @param authProvider The auth provider that issued the token.
152
>
* @param tunnelId The tunnel ID to connect to.
153
>
* @param clusterId The cluster region of the tunnel.
154
>
*/
155
>
connect(token: string, authProvider: 'github' | 'microsoft', tunnelId: string, clusterId: string): Promise<ITunnelConnectResult>;
156
>
157
>
/**
158
>
* Send a message to a remote agent host through the tunnel relay.
159
>
*/
160
>
relaySend(connectionId: string, message: string): Promise<void>;
161
>
162
>
/**
163
>
* Disconnect a tunnel relay connection.
164
>
*/
165
>
disconnect(connectionId: string): Promise<void>;
166
>
}
167
>
168
>
/**
169
>
* Renderer-side service that manages dev tunnel agent host connections.
170
>
* Uses the shared-process {@link ITunnelAgentHostMainService} for
171
>
* actual tunnel SDK operations and registers connections with
172
>
* {@link IRemoteAgentHostService}.
173
>
*/
174
>
export interface ITunnelAgentHostService {
175
>
readonly _serviceBrand: undefined;
176
>
177
>
/** Fires when the set of available tunnels changes. */
178
>
readonly onDidChangeTunnels: Event<void>;
179
>
180
>
/**
181
>
* Enumerate available dev tunnels with agent host support.
182
>
* When {@link options.silent} is `true`, uses cached tokens without
183
>
* prompting the user. Returns an empty array if no cached token.
184
>
*/
185
>
listTunnels(options?: { silent?: boolean }): Promise<ITunnelInfo[]>;
186
>
187
>
/**
188
>
* Connect to a tunnel's agent host and register the connection
189
>
* with {@link IRemoteAgentHostService}.
190
>
*
191
>
* @param tunnel The tunnel to connect to.
192
>
* @param authProvider Optional auth provider to use. If omitted, uses cached/last known.
193
>
*/
194
>
connect(tunnel: ITunnelInfo, authProvider?: 'github' | 'microsoft'): Promise<void>;
195
>
196
>
/**
197
>
* Disconnect from a tunnel agent host.
198
>
*/
199
>
disconnect(address: string): Promise<void>;
200
>
201
>
/** Get the list of recently used (cached) tunnels. */
202
>
getCachedTunnels(): ICachedTunnel[];
203
>
204
>
/** Cache a tunnel as recently used. */
205
>
cacheTunnel(tunnel: ITunnelInfo, authProvider?: 'github' | 'microsoft'): void;
206
>
207
>
/** Remove a tunnel from the cache. */
208
>
removeCachedTunnel(tunnelId: string): void;
209
>
210
>
/** Whether startup/background auto-connect should skip this tunnel because the user disconnected it. */
211
>
isAutoConnectSuppressed(tunnelId: string): boolean;
212
>
213
>
/** Remember that the user explicitly disconnected this tunnel, so startup/background auto-connect skips it. */
214
>
suppressAutoConnect(tunnelId: string): void;
215
>
216
>
/** Clear a previous user-disconnect marker after the user explicitly reconnects this tunnel. */
217
>
clearAutoConnectSuppression(tunnelId: string): void;
218
>
219
>
/**
220
>
* Determine which auth provider has an existing cached session.
221
>
* When {@link silent} is true, does not prompt the user.
222
>
* Returns `undefined` if no cached session is available.
223
>
*/
224
>
getAuthProvider(options?: { silent?: boolean }): Promise<'github' | 'microsoft' | undefined>;
225
>
}
226
>
227
>
// ---- Tunnel hosting (exposing the local agent host to remote clients) --------
228
>
229
>
/** IPC channel name for the tunnel host service. */
230
>
export const TUNNEL_HOST_CHANNEL = 'tunnelHost';
231
>
232
>
/** Output channel ID for the tunnel host logs. */
233
>
export const TUNNEL_HOST_LOG_ID = 'tunnelHostService';
234
>
235
>
/** Information about an actively hosted tunnel. */
236
>
export interface ITunnelHostInfo {
237
>
readonly tunnelName: string;
238
>
readonly tunnelId: string;
239
>
readonly clusterId: string;
240
>
readonly domain: string;
241
>
}
242
>
243
>
/** Status of the tunnel host. */
244
>
export type TunnelHostStatus =
245
>
| { readonly active: false }
246
>
| { readonly active: true; readonly info: ITunnelHostInfo };
247
>
248
>
/**
249
>
* Shared-process service that hosts a dev tunnel using `TunnelRelayTunnelHost`
250
>
* and pipes incoming connections to the local agent host.
251
>
*/
252
>
export const ITunnelAgentHostHostingService = createDecorator<ITunnelAgentHostHostingService>('tunnelAgentHostHostingService');
253
>
254
>
export interface ITunnelAgentHostHostingService {
255
>
readonly _serviceBrand: undefined;
256
>
257
>
/** Fires when the hosting status changes. */
258
>
readonly onDidChangeStatus: Event<TunnelHostStatus>;
259
>
260
>
/**
261
>
* Start hosting a dev tunnel that forwards connections to the local
262
>
* agent host. Creates a tunnel with the appropriate labels and port
263
>
* configuration, then connects a `TunnelRelayTunnelHost`.
264
>
*
265
>
* @param token The user's access token.
266
>
* @param authProvider The auth provider that issued the token.
267
>
* @param socketInfo Socket path for the local agent host.
268
>
*/
269
>
startHosting(token: string, authProvider: 'github' | 'microsoft', socketInfo: IAgentHostSocketInfo): Promise<ITunnelHostInfo>;
270
>
271
>
/** Stop hosting and clean up the tunnel. */
272
>
stopHosting(): Promise<void>;
273
>
274
>
/** Get the current hosting status. */
275
>
getStatus(): Promise<TunnelHostStatus>;
276
>
}