1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
|
// Package colab provides a client for the Google Colab runtime API and the
// Jupyter kernel protocol that Colab exposes over WebSocket.
package colab
import (
"context"
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
"strings"
)
const (
baseURL = "https://colab.research.google.com"
tunEndpoint = "/tun/m"
xssiPrefix = ")]}'\n"
)
// RuntimeProxyInfo holds the short-lived token and base URL returned by the
// assign endpoint. These are used to connect to the Jupyter kernel — they are
// NOT the OAuth2 bearer token.
type RuntimeProxyInfo struct {
Token string `json:"token"`
TokenExpiresInSecs int `json:"tokenExpiresInSeconds"`
URL string `json:"url"`
}
// AssignmentInfo is what Assign returns after a successful runtime allocation.
type AssignmentInfo struct {
Endpoint string
RuntimeProxyInfo RuntimeProxyInfo
}
// getAssignmentResponse is the first-step response: contains an XSRF token
// that must be echoed back in the POST.
type getAssignmentResponse struct {
Acc string `json:"acc"`
Nbh string `json:"nbh"`
Token string `json:"token"`
Variant string `json:"variant"`
}
// postAssignmentResponse is the second-step response: contains the actual
// runtime proxy info.
type postAssignmentResponse struct {
Accelerator string `json:"accelerator"`
Endpoint string `json:"endpoint"`
RuntimeProxyInfo RuntimeProxyInfo `json:"runtimeProxyInfo"`
Variant int `json:"variant"`
}
// existingAssignment is returned by the GET when a runtime is already live for
// this notebook hash.
type existingAssignment struct {
Endpoint string `json:"endpoint"`
RuntimeProxyInfo RuntimeProxyInfo `json:"runtimeProxyInfo"`
}
// Client interacts with the Colab backend API.
type Client struct {
http *http.Client
}
// New creates a Colab client backed by the given authenticated HTTP client.
func New(httpClient *http.Client) *Client {
return &Client{http: httpClient}
}
// Assign allocates (or re-uses) a Colab runtime. notebookHash is an opaque
// identifier for the notebook — pass a random UUID hex string for new
// one-shot sessions. variant and accelerator are optional ("" for defaults).
//
// The flow mirrors the official google-colab-cli:
// 1. GET /tun/m/assign?nbh=<hash>&authuser=0
// → either an existing assignment (done) or an XSRF token for step 2
// 2. POST /tun/m/assign?nbh=<hash>&authuser=0 with X-Goog-Colab-Token
// → new assignment with runtime proxy info
func (c *Client) Assign(ctx context.Context, notebookHash, variant, accelerator string) (*AssignmentInfo, error) {
assignURL := c.buildAssignURL(notebookHash, variant, accelerator)
// Step 1: GET — check for an existing assignment or obtain the XSRF token.
body, err := c.issueRequest(ctx, http.MethodGet, assignURL, nil)
if err != nil {
return nil, fmt.Errorf("assign GET: %w", err)
}
// Try to decode as an existing assignment first (has "endpoint" field).
var existing existingAssignment
if err := json.Unmarshal(body, &existing); err == nil && existing.Endpoint != "" {
return &AssignmentInfo{
Endpoint: existing.Endpoint,
RuntimeProxyInfo: existing.RuntimeProxyInfo,
}, nil
}
// Otherwise it should be a first-step response with an XSRF token.
var step1 getAssignmentResponse
if err := json.Unmarshal(body, &step1); err != nil || step1.Token == "" {
return nil, fmt.Errorf("assign GET: unexpected response body: %s", string(body))
}
// Step 2: POST — send the XSRF token back to claim the assignment.
extraHeaders := map[string]string{
"X-Goog-Colab-Token": step1.Token,
}
body, err = c.issueRequest(ctx, http.MethodPost, assignURL, extraHeaders)
if err != nil {
// HTTP 412 means the account has reached the maximum number of
// concurrent runtimes. Surface a clear message instead of raw HTML.
if strings.Contains(err.Error(), "HTTP 412") {
return nil, fmt.Errorf("too many active Colab runtimes on this account — " +
"go to https://colab.research.google.com and stop an existing runtime, then retry")
}
if strings.Contains(err.Error(), "HTTP 400") {
return nil, fmt.Errorf("backend rejected the requested accelerator — " +
"you may not have quota for it on this account; try a different accelerator or omit --accelerator for CPU")
}
return nil, fmt.Errorf("assign POST: %w", err)
}
var step2 postAssignmentResponse
if err := json.Unmarshal(body, &step2); err != nil || step2.Endpoint == "" {
return nil, fmt.Errorf("assign POST: unexpected response body: %s", string(body))
}
return &AssignmentInfo{
Endpoint: step2.Endpoint,
RuntimeProxyInfo: step2.RuntimeProxyInfo,
}, nil
}
// ActiveRuntime describes one running Colab assignment returned by
// ListAssignments.
type ActiveRuntime struct {
Endpoint string
Accelerator string
URL string
ProxyToken string
}
// ListAssignments returns all currently active runtimes for the account.
func (c *Client) ListAssignments(ctx context.Context) ([]*ActiveRuntime, error) {
url := fmt.Sprintf("%s%s/assignments?authuser=0", baseURL, tunEndpoint)
body, err := c.issueRequest(ctx, http.MethodGet, url, nil)
if err != nil {
return nil, fmt.Errorf("list assignments: %w", err)
}
var resp struct {
Assignments []struct {
Endpoint string `json:"endpoint"`
Accelerator string `json:"accelerator"`
RuntimeProxyInfo RuntimeProxyInfo `json:"runtimeProxyInfo"`
} `json:"assignments"`
}
if err := json.Unmarshal(body, &resp); err != nil {
return nil, fmt.Errorf("parse assignments: %w", err)
}
out := make([]*ActiveRuntime, 0, len(resp.Assignments))
for _, a := range resp.Assignments {
out = append(out, &ActiveRuntime{
Endpoint: a.Endpoint,
Accelerator: a.Accelerator,
URL: a.RuntimeProxyInfo.URL,
ProxyToken: a.RuntimeProxyInfo.Token,
})
}
return out, nil
}
// AssignmentFromEndpoint looks up an existing runtime by endpoint ID and
// returns an AssignmentInfo so it can be used with CreateAndConnectKernel.
func (c *Client) AssignmentFromEndpoint(ctx context.Context, endpoint string) (*AssignmentInfo, error) {
runtimes, err := c.ListAssignments(ctx)
if err != nil {
return nil, err
}
for _, r := range runtimes {
if r.Endpoint == endpoint {
return &AssignmentInfo{
Endpoint: r.Endpoint,
RuntimeProxyInfo: RuntimeProxyInfo{
Token: r.ProxyToken,
URL: r.URL,
},
}, nil
}
}
return nil, fmt.Errorf("no active runtime found with endpoint %q — run 'colab sessions' to list active runtimes", endpoint)
}
// Unassign releases a runtime by its endpoint identifier.
func (c *Client) Unassign(ctx context.Context, endpoint string) error {
getURL := fmt.Sprintf("%s%s/unassign/%s?authuser=0", baseURL, tunEndpoint, endpoint)
body, err := c.issueRequest(ctx, http.MethodGet, getURL, nil)
if err != nil {
return fmt.Errorf("unassign GET: %w", err)
}
var tokenResp struct {
Token string `json:"token"`
}
if err := json.Unmarshal(body, &tokenResp); err != nil || tokenResp.Token == "" {
return fmt.Errorf("unassign GET: unexpected response: %s", string(body))
}
postURL := fmt.Sprintf("%s%s/unassign/%s?authuser=0", baseURL, tunEndpoint, endpoint)
_, err = c.issueRequest(ctx, http.MethodPost, postURL, map[string]string{
"X-Goog-Colab-Token": tokenResp.Token,
})
return err
}
// KeepAlive pings the runtime tunnel to reset its idle timer.
func (c *Client) KeepAlive(ctx context.Context, endpoint string) error {
keepAliveURL := fmt.Sprintf("%s%s/%s/keep-alive/?authuser=0", baseURL, tunEndpoint, endpoint)
_, err := c.issueRequest(ctx, http.MethodGet, keepAliveURL, map[string]string{
"X-Colab-Tunnel": "Google",
})
return err
}
// KernelWebSocketURL returns the WebSocket URL for the Jupyter kernel channel.
// kernelID is the UUID returned when a kernel was created via the Jupyter API.
// sessionID is a random hex UUID that identifies this client session; it is
// required by the Colab tunnel and must also be embedded in every message header.
func (info *AssignmentInfo) KernelWebSocketURL(kernelID, sessionID string) string {
base := strings.TrimRight(info.RuntimeProxyInfo.URL, "/")
// Convert https:// to wss://.
base = strings.Replace(base, "https://", "wss://", 1)
base = strings.Replace(base, "http://", "ws://", 1)
token := url.QueryEscape(info.RuntimeProxyInfo.Token)
sid := url.QueryEscape(sessionID)
// session_id must come first; the Colab tunnel uses it to multiplex channels.
return fmt.Sprintf("%s/api/kernels/%s/channels?session_id=%s&token=%s&colab-runtime-proxy-token=%s",
base, kernelID, sid, token, token)
}
// JupyterBaseURL returns the http(s) base URL for Jupyter REST calls.
func (info *AssignmentInfo) JupyterBaseURL() string {
return strings.TrimRight(info.RuntimeProxyInfo.URL, "/")
}
// buildAssignURL constructs the assign endpoint URL with optional variant /
// accelerator query parameters.
//
// accelerator is a case-insensitive GPU/TPU name (T4, L4, A100, H100, G4,
// V5E1, V6E1) or "" for CPU. variant is inferred automatically when blank:
// GPU accelerators → "GPU", TPU accelerators → "TPU", CPU → "DEFAULT".
// The official CLI always sends both parameters together.
func (c *Client) buildAssignURL(notebookHash, variant, accelerator string) string {
// Normalise accelerator to the API's expected casing.
accelUpper := strings.ToUpper(strings.TrimSpace(accelerator))
// Map user-friendly names to API values.
accelMap := map[string]string{
"T4": "T4", "L4": "L4", "A100": "A100", "H100": "H100", "G4": "G4",
"A100-80GB": "A100", // alias
"V5E1": "V5E1", "V6E1": "V6E1",
}
apiAccel := "NONE"
if v, ok := accelMap[accelUpper]; ok {
apiAccel = v
}
// Derive variant when not explicitly overridden.
apiVariant := variant
if apiVariant == "" {
switch accelUpper {
case "T4", "L4", "A100", "A100-80GB", "H100", "G4":
apiVariant = "GPU"
case "V5E1", "V6E1":
apiVariant = "TPU"
default:
apiVariant = "DEFAULT"
}
}
return fmt.Sprintf("%s%s/assign?nbh=%s&authuser=0&variant=%s&accelerator=%s",
baseURL, tunEndpoint,
url.QueryEscape(notebookHash),
url.QueryEscape(apiVariant),
url.QueryEscape(apiAccel),
)
}
// issueRequest performs an HTTP request with the standard Colab headers and
// strips the XSSI prefix from the response body.
func (c *Client) issueRequest(ctx context.Context, method, endpoint string, extraHeaders map[string]string) ([]byte, error) {
req, err := http.NewRequestWithContext(ctx, method, endpoint, nil)
if err != nil {
return nil, err
}
req.Header.Set("Accept", "application/json")
req.Header.Set("X-Colab-Client-Agent", "colab-cli")
for k, v := range extraHeaders {
req.Header.Set(k, v)
}
resp, err := c.http.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
raw, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
if err != nil {
return nil, err
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, string(raw))
}
// Strip the XSSI prefix that Google APIs prepend to JSON responses.
body := strings.TrimPrefix(string(raw), xssiPrefix)
return []byte(body), nil
}
|