diff options
| -rw-r--r-- | internal/colab/contents.go | 159 | ||||
| -rw-r--r-- | internal/colab/kernel.go | 541 | ||||
| -rw-r--r-- | internal/colab/session.go | 322 |
3 files changed, 1022 insertions, 0 deletions
diff --git a/internal/colab/contents.go b/internal/colab/contents.go new file mode 100644 index 0000000..faa1f77 --- /dev/null +++ b/internal/colab/contents.go @@ -0,0 +1,159 @@ +package colab + +import ( + "context" + "encoding/base64" + "encoding/json" + "fmt" + "io" + "net/http" + "net/url" + "strings" + "time" +) + +// FileContent is a file downloaded from a runtime via the Jupyter Contents API. +type FileContent struct { + Name string + Path string + Data []byte +} + +// FetchFile downloads a single file from the runtime identified by info, using +// the Jupyter Contents API over the runtime proxy. remotePath is interpreted +// relative to the Jupyter server root (an absolute path like /content/x works +// too). Directories are rejected with a hint to archive them first. +func (c *Client) FetchFile(ctx context.Context, info *AssignmentInfo, remotePath string) (*FileContent, error) { + base := info.JupyterBaseURL() + token := info.RuntimeProxyInfo.Token + + apiURL := fmt.Sprintf("%s/api/contents/%s?content=1&token=%s", + base, escapeContentsPath(remotePath), url.QueryEscape(token)) + + req, err := http.NewRequestWithContext(ctx, http.MethodGet, apiURL, nil) + if err != nil { + return nil, err + } + req.Header.Set("Authorization", "token "+token) + req.Header.Set("X-Colab-Client-Agent", "colab-cli") + req.Header.Set("X-Colab-Runtime-Proxy-Token", token) + + resp, err := (&http.Client{Timeout: 5 * time.Minute}).Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + + body, err := io.ReadAll(resp.Body) + if err != nil { + return nil, err + } + if resp.StatusCode != http.StatusOK { + if resp.StatusCode == http.StatusNotFound { + return nil, fmt.Errorf("remote path %q not found on the runtime", remotePath) + } + return nil, fmt.Errorf("contents API HTTP %d: %s", resp.StatusCode, truncateForError(body)) + } + + var cr struct { + Name string `json:"name"` + Path string `json:"path"` + Type string `json:"type"` + Format string `json:"format"` + Content json.RawMessage `json:"content"` + } + if err := json.Unmarshal(body, &cr); err != nil { + return nil, fmt.Errorf("parse contents response: %w", err) + } + + if cr.Type == "directory" { + return nil, fmt.Errorf("%q is a directory — archive it on the runtime first, "+ + "e.g. run `!tar czf /tmp/out.tgz -C %s .` then pull /tmp/out.tgz", remotePath, remotePath) + } + + var data []byte + switch cr.Format { + case "base64": + var s string + if err := json.Unmarshal(cr.Content, &s); err != nil { + return nil, err + } + // Jupyter may wrap the base64 payload across lines. + s = strings.ReplaceAll(s, "\n", "") + data, err = base64.StdEncoding.DecodeString(s) + if err != nil { + return nil, fmt.Errorf("decode base64 content: %w", err) + } + case "text": + var s string + if err := json.Unmarshal(cr.Content, &s); err != nil { + return nil, err + } + data = []byte(s) + case "json": + // Notebooks come back as a JSON object rather than a string. + data = []byte(cr.Content) + default: + return nil, fmt.Errorf("unsupported content format %q for %q", cr.Format, remotePath) + } + + return &FileContent{Name: cr.Name, Path: cr.Path, Data: data}, nil +} + +// PutFile uploads data to remotePath on the runtime identified by info via the +// Jupyter Contents API. The parent directory must already exist. +func (c *Client) PutFile(ctx context.Context, info *AssignmentInfo, remotePath string, data []byte) error { + base := info.JupyterBaseURL() + token := info.RuntimeProxyInfo.Token + + apiURL := fmt.Sprintf("%s/api/contents/%s?token=%s", + base, escapeContentsPath(remotePath), url.QueryEscape(token)) + + payload, err := json.Marshal(map[string]interface{}{ + "type": "file", + "format": "base64", + "content": base64.StdEncoding.EncodeToString(data), + }) + if err != nil { + return err + } + + req, err := http.NewRequestWithContext(ctx, http.MethodPut, apiURL, strings.NewReader(string(payload))) + if err != nil { + return err + } + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "token "+token) + req.Header.Set("X-Colab-Client-Agent", "colab-cli") + req.Header.Set("X-Colab-Runtime-Proxy-Token", token) + + resp, err := (&http.Client{Timeout: 5 * time.Minute}).Do(req) + if err != nil { + return err + } + defer resp.Body.Close() + body, _ := io.ReadAll(io.LimitReader(resp.Body, 64*1024)) + if resp.StatusCode != http.StatusCreated && resp.StatusCode != http.StatusOK { + return fmt.Errorf("contents API HTTP %d: %s", resp.StatusCode, truncateForError(body)) + } + return nil +} + +// escapeContentsPath URL-escapes each path segment while keeping the slashes +// that separate them, and drops any leading slash the API does not expect. +func escapeContentsPath(p string) string { + p = strings.TrimPrefix(p, "/") + parts := strings.Split(p, "/") + for i, s := range parts { + parts[i] = url.PathEscape(s) + } + return strings.Join(parts, "/") +} + +func truncateForError(b []byte) string { + const max = 300 + if len(b) > max { + return string(b[:max]) + } + return string(b) +} diff --git a/internal/colab/kernel.go b/internal/colab/kernel.go new file mode 100644 index 0000000..5387ce3 --- /dev/null +++ b/internal/colab/kernel.go @@ -0,0 +1,541 @@ +package colab + +import ( + "context" + "crypto/rand" + "encoding/base64" + "encoding/binary" + "encoding/hex" + "encoding/json" + "fmt" + "io" + "net/http" + "net/url" + "path/filepath" + "regexp" + "strings" + "time" + + "github.com/gorilla/websocket" +) + +type msgHeader struct { + MsgID string `json:"msg_id"` + Username string `json:"username"` + Session string `json:"session"` + Date string `json:"date"` + MsgType string `json:"msg_type"` + Version string `json:"version"` +} + +type jupyterMsg struct { + Header msgHeader `json:"header"` + ParentHeader msgHeader `json:"parent_header"` + Metadata map[string]interface{} `json:"metadata"` + Content map[string]interface{} `json:"content"` + Channel string `json:"channel"` + Buffers []interface{} `json:"buffers"` +} + +type OutputKind string + +const ( + OutputStdout OutputKind = "stdout" + OutputStderr OutputKind = "stderr" + OutputResult OutputKind = "result" + OutputDisplay OutputKind = "display" + OutputError OutputKind = "error" + OutputStatus OutputKind = "status" + OutputInputReq OutputKind = "input_request" +) + +type KernelOutput struct { + Kind OutputKind + Text string + MsgType string + Filename string // suggested name from display metadata, if any + BinaryData map[string][]byte // mime type → decoded bytes (images, audio, etc.) +} + +// Kernel holds a live WebSocket connection to a Jupyter kernel. +// A background goroutine continuously reads all frames so that server pings +// are answered even while the REPL is idle waiting for user input. +type Kernel struct { + conn *websocket.Conn + kernelID string + sessionID string + msgs chan jupyterMsg + done chan struct{} +} + +func CreateAndConnectKernel(ctx context.Context, info *AssignmentInfo) (*Kernel, error) { + proxyToken := info.RuntimeProxyInfo.Token + baseURL := info.JupyterBaseURL() + + kernelID, _, err := acquireKernel(ctx, baseURL, proxyToken) + if err != nil { + return nil, fmt.Errorf("acquire kernel: %w", err) + } + + sessionID, err := randomHex(16) + if err != nil { + return nil, err + } + + wsURL := info.KernelWebSocketURL(kernelID, sessionID) + + wsHeaders := http.Header{} + wsHeaders.Set("Origin", "https://colab.research.google.com") + wsHeaders.Set("X-Colab-Client-Agent", "colab-cli") + wsHeaders.Set("X-Colab-Runtime-Proxy-Token", proxyToken) + + conn, resp, err := websocket.DefaultDialer.DialContext(ctx, wsURL, wsHeaders) + if err != nil { + if resp != nil { + b, _ := io.ReadAll(io.LimitReader(resp.Body, 2048)) + return nil, fmt.Errorf("dial kernel ws (HTTP %d): %w — %s", resp.StatusCode, err, string(b)) + } + return nil, fmt.Errorf("dial kernel ws: %w", err) + } + + k := &Kernel{ + conn: conn, + kernelID: kernelID, + sessionID: sessionID, + msgs: make(chan jupyterMsg, 256), + done: make(chan struct{}), + } + + go k.readLoop() + + return k, nil +} + +// readLoop runs in a goroutine for the lifetime of the kernel connection. +// It reads every frame from the WebSocket (keeping pings answered) and +// forwards parsed messages to k.msgs. +func (k *Kernel) readLoop() { + defer close(k.msgs) + for { + select { + case <-k.done: + return + default: + } + k.conn.SetReadDeadline(time.Time{}) + msgType, raw, err := k.conn.ReadMessage() + if err != nil { + return + } + + var jsonBytes []byte + if msgType == websocket.TextMessage { + // Default protocol, no buffers: plain JSON text frame. + jsonBytes = raw + } else { + // Default protocol, binary frame: + // bytes 0-3: nbufs (big-endian uint32) + // bytes 4..4+4n-1: offsets[0..n-1] (big-endian uint32 each) + // offsets[0]: start of buffer[0] (JSON) + // offsets[1]: start of buffer[1] (= end of JSON) + if len(raw) < 8 { + continue + } + nbufs := binary.BigEndian.Uint32(raw[0:4]) + if nbufs < 2 { + continue + } + headerLen := 4 + 4*int(nbufs) + if len(raw) < headerLen { + continue + } + off0 := int(binary.BigEndian.Uint32(raw[4:8])) + off1 := int(binary.BigEndian.Uint32(raw[8:12])) + if off0 < 0 || off1 > len(raw) || off0 > off1 { + continue + } + jsonBytes = raw[off0:off1] + } + + var msg jupyterMsg + if err := json.Unmarshal(jsonBytes, &msg); err != nil { + continue + } + select { + case k.msgs <- msg: + case <-k.done: + return + } + } +} + +func (k *Kernel) waitReady(ctx context.Context) error { + msgID, err := randomHex(16) + if err != nil { + return err + } + + req := jupyterMsg{ + Header: msgHeader{ + MsgID: msgID, + Username: "colab-cli", + Session: k.sessionID, + Date: time.Now().UTC().Format(time.RFC3339), + MsgType: "kernel_info_request", + Version: "5.3", + }, + ParentHeader: msgHeader{}, + Metadata: map[string]interface{}{}, + Content: map[string]interface{}{}, + Channel: "shell", + Buffers: []interface{}{}, + } + data, err := json.Marshal(req) + if err != nil { + return err + } + if err := k.conn.WriteMessage(websocket.TextMessage, data); err != nil { + return err + } + + deadline := time.NewTimer(3 * time.Minute) + defer deadline.Stop() + + for { + select { + case <-ctx.Done(): + return ctx.Err() + case <-deadline.C: + return fmt.Errorf("timed out waiting for kernel_info_reply") + case msg, ok := <-k.msgs: + if !ok { + return fmt.Errorf("kernel connection closed while waiting for kernel_info_reply") + } + if msg.Header.MsgType == "kernel_info_reply" && msg.ParentHeader.MsgID == msgID { + return nil + } + } + } +} + +func (k *Kernel) Execute(ctx context.Context, code string) (<-chan KernelOutput, error) { + msgID, err := randomHex(16) + if err != nil { + return nil, err + } + + req := jupyterMsg{ + Header: msgHeader{ + MsgID: msgID, + Username: "colab-cli", + Session: k.sessionID, + Date: time.Now().UTC().Format(time.RFC3339), + MsgType: "execute_request", + Version: "5.3", + }, + ParentHeader: msgHeader{}, + Metadata: map[string]interface{}{}, + Content: map[string]interface{}{ + "code": code, + "silent": false, + "store_history": true, + "user_expressions": map[string]interface{}{}, + "allow_stdin": false, + "stop_on_error": true, + }, + Channel: "shell", + Buffers: []interface{}{}, + } + data, err := json.Marshal(req) + if err != nil { + return nil, err + } + if err := k.conn.WriteMessage(websocket.TextMessage, data); err != nil { + return nil, fmt.Errorf("send execute_request: %w", err) + } + + outCh := make(chan KernelOutput, 32) + + go func() { + defer close(outCh) + + const idleTimeout = 10 * time.Minute + timer := time.NewTimer(idleTimeout) + defer timer.Stop() + + resetTimer := func() { + if !timer.Stop() { + select { + case <-timer.C: + default: + } + } + timer.Reset(idleTimeout) + } + + for { + select { + case <-ctx.Done(): + return + case <-timer.C: + return + case msg, ok := <-k.msgs: + if !ok { + return + } + resetTimer() + if msg.ParentHeader.MsgID != msgID { + continue + } + switch msg.Header.MsgType { + case "stream": + text, _ := msg.Content["text"].(string) + kind := OutputStdout + if name, _ := msg.Content["name"].(string); name == "stderr" { + kind = OutputStderr + } + outCh <- KernelOutput{Kind: kind, Text: text, MsgType: msg.Header.MsgType} + case "execute_result": + if d, ok := msg.Content["data"].(map[string]interface{}); ok { + out := KernelOutput{Kind: OutputResult, MsgType: msg.Header.MsgType} + extractBinaryData(&out, d) + out.Filename = filenameFromMetadata(msg.Content["metadata"]) + if txt, ok := d["text/plain"].(string); ok { + out.Text = txt + } + outCh <- out + } + case "display_data": + if d, ok := msg.Content["data"].(map[string]interface{}); ok { + out := KernelOutput{Kind: OutputDisplay, MsgType: msg.Header.MsgType} + extractBinaryData(&out, d) + out.Filename = filenameFromMetadata(msg.Content["metadata"]) + if txt, ok := d["text/plain"].(string); ok { + out.Text = txt + } + outCh <- out + } + case "error": + ename, _ := msg.Content["ename"].(string) + evalue, _ := msg.Content["evalue"].(string) + text := ename + ": " + evalue + if tb, ok := msg.Content["traceback"].([]interface{}); ok { + lines := make([]string, 0, len(tb)) + for _, l := range tb { + if s, ok := l.(string); ok { + lines = append(lines, stripANSI(s)) + } + } + text += "\n" + strings.Join(lines, "\n") + } + outCh <- KernelOutput{Kind: OutputError, Text: text, MsgType: msg.Header.MsgType} + case "status": + state, _ := msg.Content["execution_state"].(string) + outCh <- KernelOutput{Kind: OutputStatus, Text: state, MsgType: msg.Header.MsgType} + if state == "idle" { + return + } + case "input_request": + prompt, _ := msg.Content["prompt"].(string) + outCh <- KernelOutput{Kind: OutputInputReq, Text: prompt, MsgType: msg.Header.MsgType} + case "execute_reply": + if status, _ := msg.Content["status"].(string); status == "error" { + ename, _ := msg.Content["ename"].(string) + evalue, _ := msg.Content["evalue"].(string) + outCh <- KernelOutput{ + Kind: OutputError, + Text: ename + ": " + evalue, + MsgType: msg.Header.MsgType, + } + } + } + } + } + }() + + return outCh, nil +} + +func (k *Kernel) Close() error { + close(k.done) + return k.conn.Close() +} + +func acquireKernel(ctx context.Context, baseURL, proxyToken string) (string, bool, error) { + ids, err := listKernels(ctx, baseURL, proxyToken) + if err == nil && len(ids) > 0 { + return ids[0], false, nil + } + id, err := createKernel(ctx, baseURL, proxyToken) + return id, true, err +} + +func listKernels(ctx context.Context, baseURL, proxyToken string) ([]string, error) { + u := fmt.Sprintf("%s/api/kernels?token=%s", baseURL, url.QueryEscape(proxyToken)) + req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil) + if err != nil { + return nil, err + } + req.Header.Set("Authorization", "token "+proxyToken) + req.Header.Set("X-Colab-Client-Agent", "colab-cli") + req.Header.Set("X-Colab-Runtime-Proxy-Token", proxyToken) + + resp, err := (&http.Client{Timeout: 30 * time.Second}).Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + body, _ := io.ReadAll(io.LimitReader(resp.Body, 64*1024)) + if resp.StatusCode != http.StatusOK { + return nil, fmt.Errorf("HTTP %d", resp.StatusCode) + } + var kernels []struct { + ID string `json:"id"` + } + if err := json.Unmarshal(body, &kernels); err != nil { + return nil, err + } + ids := make([]string, 0, len(kernels)) + for _, k := range kernels { + if k.ID != "" { + ids = append(ids, k.ID) + } + } + return ids, nil +} + +func createKernel(ctx context.Context, baseURL, proxyToken string) (string, error) { + u := fmt.Sprintf("%s/api/kernels?token=%s", baseURL, url.QueryEscape(proxyToken)) + req, err := http.NewRequestWithContext(ctx, http.MethodPost, u, strings.NewReader("{}")) + if err != nil { + return "", err + } + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "token "+proxyToken) + req.Header.Set("X-Colab-Client-Agent", "colab-cli") + req.Header.Set("X-Colab-Runtime-Proxy-Token", proxyToken) + + resp, err := (&http.Client{Timeout: 60 * time.Second}).Do(req) + if err != nil { + return "", err + } + defer resp.Body.Close() + body, _ := io.ReadAll(io.LimitReader(resp.Body, 64*1024)) + if resp.StatusCode != http.StatusCreated && resp.StatusCode != http.StatusOK { + return "", fmt.Errorf("HTTP %d: %s", resp.StatusCode, string(body)) + } + var kernel struct { + ID string `json:"id"` + } + if err := json.Unmarshal(body, &kernel); err != nil || kernel.ID == "" { + return "", fmt.Errorf("unexpected create kernel response: %s", string(body)) + } + return kernel.ID, nil +} + +// binaryMIMETypes lists MIME types whose values are base64-encoded binary data. +var binaryMIMETypes = []string{ + "image/png", + "image/jpeg", + "image/gif", + "image/svg+xml", + "audio/wav", + "audio/mpeg", + "audio/mp3", + "audio/ogg", +} + +// filenameFromMetadata pulls a caller-supplied name out of a display message's +// metadata. The convention is display(obj, metadata={"filename": "name.ext"}). +// A "colab_filename" key is also accepted. Only the base name is kept so the +// metadata cannot direct writes outside the chosen output directory. +func filenameFromMetadata(meta interface{}) string { + m, ok := meta.(map[string]interface{}) + if !ok { + return "" + } + for _, key := range []string{"filename", "colab_filename"} { + if name, ok := m[key].(string); ok && name != "" { + return filepath.Base(name) + } + } + return "" +} + +// dataURIPattern matches a base64 data URI such as the ones IPython embeds in +// HTML for Audio and Video widgets: data:audio/wav;base64,<payload>. +var dataURIPattern = regexp.MustCompile(`data:([a-zA-Z0-9.+-]+/[a-zA-Z0-9.+-]+);base64,([A-Za-z0-9+/=]+)`) + +// extractBinaryData decodes any base64-encoded binary fields from a Jupyter +// data dict (the "data" key of display_data / execute_result) into out.BinaryData. +func extractBinaryData(out *KernelOutput, data map[string]interface{}) { + store := func(mime string, b []byte) { + if out.BinaryData == nil { + out.BinaryData = make(map[string][]byte) + } + out.BinaryData[mime] = b + } + + for _, mime := range binaryMIMETypes { + raw, ok := data[mime].(string) + if !ok || raw == "" { + continue + } + b, err := base64.StdEncoding.DecodeString(raw) + if err != nil { + continue + } + store(mime, b) + } + + // Some rich displays (IPython.display.Audio and Video, for example) provide + // only an HTML representation with the media embedded as a base64 data URI, + // not a top-level binary MIME bundle. Pull those out so they can be saved. + html, ok := data["text/html"].(string) + if !ok || html == "" { + return + } + for _, m := range dataURIPattern.FindAllStringSubmatch(html, -1) { + mime, payload := m[1], m[2] + if !strings.HasPrefix(mime, "image/") && + !strings.HasPrefix(mime, "audio/") && + !strings.HasPrefix(mime, "video/") { + continue + } + // A top-level bundle for this MIME type is higher fidelity; keep it. + if _, exists := out.BinaryData[mime]; exists { + continue + } + b, err := base64.StdEncoding.DecodeString(payload) + if err != nil { + continue + } + store(mime, b) + } +} + +func randomHex(n int) (string, error) { + b := make([]byte, n) + if _, err := rand.Read(b); err != nil { + return "", err + } + return hex.EncodeToString(b), nil +} + +func stripANSI(s string) string { + var out strings.Builder + i := 0 + for i < len(s) { + if s[i] == '\x1b' && i+1 < len(s) && s[i+1] == '[' { + i += 2 + for i < len(s) && s[i] != 'm' { + i++ + } + i++ + continue + } + out.WriteByte(s[i]) + i++ + } + return out.String() +} diff --git a/internal/colab/session.go b/internal/colab/session.go new file mode 100644 index 0000000..aad71f0 --- /dev/null +++ b/internal/colab/session.go @@ -0,0 +1,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 +} |
