src/vs/platform/agentHost/common/tunnelAgentHost.ts
276 LOC · 255 covered · 21 uncovered · 2 ranges · 6 concepts · 1 introducers · 4 tests
File neighbourhood
The centred file is linked to every concept that introduces one of its ranges, every test that runs code from the file, and the gray connector concepts standing between those tests and the file's own introducer concepts. Undirected links join concepts to every file where they introduce source and concepts to the tests they introduce; arrows show specialization between the displayed concepts and bridge only concepts omitted from this view. Concept colors match the source ranges below; connector concepts have no source color and are shown in gray.
Focused file, its introducer and connector concepts, their introduced files, and tests that run code from the file
In the embedded map, ordinary wheel input scrolls the page; use the visible controls to zoom and drag to pan. Open the full-screen map for canvas navigation: wheel pans, Ctrl/Command plus wheel zooms, and arrow keys pan when this region is focused. On touch screens, open the full-screen map to pan or pinch. If JavaScript or WebGL is unavailable, use the related-file, concept, and source links on this page.
Graph controls are ready.
Interactive rendering requires JavaScript and WebGL. Use the related-file, concept, and source links on this page while the interactive map is unavailable.
1
>
/*---------------------------------------------------------------------------------------------
tunnelAgentHostService.ts ×14
2
>
* Copyright (c) Microsoft Corporation. All rights reserved.
3
>
* Licensed under the MIT License. See License.txt in the project root for license information.
4
>
*--------------------------------------------------------------------------------------------*/
5
>
6
>
import { Event } from '../../../base/common/event.js';
7
>
import { createDecorator } from '../../instantiation/common/instantiation.js';
8
>
import type { IAgentHostSocketInfo } from './agentService.js';
9
>
10
>
export const ITunnelAgentHostService = createDecorator<ITunnelAgentHostService>('tunnelAgentHostService');
11
>
12
>
/**
13
>
* IPC channel name for the shared-process tunnel service.
14
>
*/
15
>
export const TUNNEL_AGENT_HOST_CHANNEL = 'tunnelAgentHost';
16
>
17
>
/** Configuration key for the list of manually configured tunnel names. */
18
>
export const TunnelAgentHostsSettingId = 'chat.remoteAgentTunnels';
19
>
20
>
/** Minimum protocol version required for agent host connections. */
21
>
export const TUNNEL_MIN_PROTOCOL_VERSION = 5;
22
>
23
>
/** Well-known port for the agent host on tunnel machines. */
24
>
export const TUNNEL_AGENT_HOST_PORT = 31546;
25
>
26
>
/** Label used to identify VS Code server launcher tunnels. */
27
>
export const TUNNEL_LAUNCHER_LABEL = 'vscode-server-launcher';
28
>
29
>
/** Address prefix for tunnel-backed connections (e.g. `tunnel:myTunnelId`). */
30
>
export const TUNNEL_ADDRESS_PREFIX = 'tunnel:';
31
>
32
>
/** Prefix for protocol version tags. */
33
>
export const PROTOCOL_VERSION_TAG_PREFIX = 'protocolv';
34
>
35
>
/**
36
>
* Parse tunnel tags to extract display name and protocol version.
37
>
* Follows the convention from the vscode-remote-tunnels SDK: the
38
>
* first label that is not `vscode-server-launcher`, does not start
39
>
* with `_`, and is not a `protocolvN` tag is the display name.
40
>
*/
41
>
export class TunnelTags {
42
>
public readonly protocolVersion: number = 2;
43
>
public readonly name: string | undefined;
44
>
45
>
constructor(readonly value: readonly string[] | undefined) {
46
if (value) {
47
let protocolVersion: number | undefined;
48
let name: string | undefined;
49
for (const tag of value) {
50
if (tag.startsWith(PROTOCOL_VERSION_TAG_PREFIX)) {
51
const parsed = Number(tag.slice(PROTOCOL_VERSION_TAG_PREFIX.length));
52
if (!isNaN(parsed)) {
53
protocolVersion = parsed;
54
}
55
} else if (!tag.startsWith('_') && tag !== TUNNEL_LAUNCHER_LABEL && !name) {
56
name = tag;
57
}
58
}
59
if (protocolVersion !== undefined) {
60
this.protocolVersion = protocolVersion;
61
}
62
if (name !== undefined) {
63
this.name = name;
64
}
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
>
}