aboutsummaryrefslogtreecommitdiff
path: root/internal
diff options
context:
space:
mode:
Diffstat (limited to 'internal')
-rw-r--r--internal/colab/contents.go159
-rw-r--r--internal/colab/kernel.go541
-rw-r--r--internal/colab/session.go322
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
+}