aboutsummaryrefslogtreecommitdiff
path: root/internal/colab/kernel.go
diff options
context:
space:
mode:
authorOnur Gündüz <ogunduz@gmail.com>2026-06-28 07:24:36 +0200
committerOnur Gündüz <ogunduz@gmail.com>2026-06-28 07:24:36 +0200
commit4ff7975b497da3877ac24172d47e7b009b949cae (patch)
tree8ebc8d06b58b2dd1a330806614c15beeda06d830 /internal/colab/kernel.go
parentbc940168825da277f5897c89a5591d6fab2315c5 (diff)
downloadcolabctl-4ff7975b497da3877ac24172d47e7b009b949cae.tar.gz
colabctl-4ff7975b497da3877ac24172d47e7b009b949cae.zip
Add colab client package
Diffstat (limited to 'internal/colab/kernel.go')
-rw-r--r--internal/colab/kernel.go541
1 files changed, 541 insertions, 0 deletions
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()
+}