43d4ace13c
- Introduce new Tai SDK tests in the GitHub workflows, requiring a Tai container with Docker socket mount for execution. - Update the Makefile to include a dedicated target for running Tai SDK tests, enhancing test coverage for the Tai integration. - Modify the Go module dependencies to include the pierrec/lz4 package, ensuring compatibility with the new tests. - Adjust test folder selection logic in the Makefile to exclude additional directories, streamlining the testing process.
128 lines
3.7 KiB
Markdown
128 lines
3.7 KiB
Markdown
# Tai Go SDK
|
|
|
|
Go client library for [Tai](https://github.com/yaoapp/tai) — the universal runtime bridge for Yao Sandbox.
|
|
|
|
## Overview
|
|
|
|
Provides a unified API for container lifecycle, filesystem operations, HTTP proxy, and VNC access.
|
|
Supports two modes via a single entry point:
|
|
|
|
- **Local** (`docker://` or `""`) — direct Docker daemon connection
|
|
- **Remote** (`tai://host`) — via Tai Server proxy
|
|
|
|
All sub-packages follow the same pattern: **interface + Remote/Local implementations**.
|
|
|
|
## Package Layout
|
|
|
|
```
|
|
yao/tai/
|
|
├── tai.go # Client, New(), Option, Close()
|
|
├── volume/ # Volume IO + Sync
|
|
├── workspace/ # Go fs.FS wrapper over volume.Volume
|
|
├── sandbox/ # Container lifecycle (Create/Start/Stop/Exec/Remove)
|
|
├── proxy/ # HTTP reverse proxy URL resolution
|
|
└── vnc/ # VNC WebSocket URL resolution
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```go
|
|
import "github.com/yaoapp/yao/tai"
|
|
|
|
// Local — default Docker socket
|
|
c, _ := tai.New("")
|
|
|
|
// Local — explicit address
|
|
c, _ := tai.New("docker:///var/run/docker.sock")
|
|
c, _ := tai.New("docker://192.168.1.50:2375")
|
|
|
|
// Remote — via Tai Server (Docker runtime, default)
|
|
c, _ := tai.New("tai://192.168.1.100")
|
|
|
|
// Remote — via Tai Server (K8s runtime)
|
|
c, _ := tai.New("tai://10.0.0.5", tai.K8s)
|
|
|
|
defer c.Close()
|
|
|
|
// Container lifecycle
|
|
id, _ := c.Sandbox().Create(ctx, sandbox.CreateOptions{
|
|
Image: "node:20",
|
|
Cmd: []string{"sleep", "infinity"},
|
|
})
|
|
c.Sandbox().Start(ctx, id)
|
|
|
|
// Filesystem
|
|
ws := c.Workspace("session-1")
|
|
ws.WriteFile("app.js", []byte("console.log('hi')"), 0644)
|
|
data, _ := ws.ReadFile("app.js")
|
|
|
|
// HTTP proxy URL
|
|
url, _ := c.Proxy().URL(ctx, id, 3000, "/api/health")
|
|
|
|
// VNC URL
|
|
vncURL, _ := c.VNC().URL(ctx, id)
|
|
```
|
|
|
|
## Address Protocol
|
|
|
|
| Prefix | Mode | Description |
|
|
|--------|------|-------------|
|
|
| `""` | Local | Platform default Docker socket |
|
|
| `docker://...` | Local | Direct Docker daemon (socket or TCP) |
|
|
| `tai://host` | Remote | Via Tai Server, all services proxied |
|
|
|
|
## Sub-Package Interfaces
|
|
|
|
### volume.Volume
|
|
|
|
File IO and directory sync between Yao and the container workspace.
|
|
|
|
- `ReadFile`, `WriteFile`, `Stat`, `ListDir`, `Remove`, `Rename`, `MkdirAll`
|
|
- `SyncPush` (Yao → Tai), `SyncPull` (Tai → Yao)
|
|
- **Remote**: gRPC to Tai `:9100`
|
|
- **Local**: direct disk IO under `dataDir/{sessionID}/`
|
|
|
|
### workspace.FS
|
|
|
|
Go `fs.FS`-compatible interface wrapping `volume.Volume`, adding write operations.
|
|
|
|
### sandbox.Sandbox
|
|
|
|
Container lifecycle: `Create`, `Start`, `Stop`, `Remove`, `Exec`, `Inspect`, `List`.
|
|
|
|
- **Local**: direct Docker socket, handles VNC port mapping and capabilities
|
|
- **Docker**: via Tai `:2375`
|
|
- **Containerd**: via Tai `:2376` (Phase 2)
|
|
- **K8s**: via Tai `:6443` (Phase 2)
|
|
|
|
### proxy.Proxy
|
|
|
|
HTTP service URL resolution: `URL(ctx, containerID, port, path)`.
|
|
|
|
- **Remote**: `http://tai-host:8080/{id}:{port}/{path}`
|
|
- **Local**: `http://127.0.0.1:{hostPort}/{path}` via `sandbox.Inspect`
|
|
|
|
### vnc.VNC
|
|
|
|
VNC WebSocket URL resolution: `URL(ctx, containerID)`.
|
|
|
|
- **Remote**: `ws://tai-host:6080/vnc/{id}/ws`
|
|
- **Local**: `ws://127.0.0.1:{vncHostPort}/ws` via `sandbox.Inspect`
|
|
|
|
## Options
|
|
|
|
```go
|
|
tai.Docker // default runtime (can omit)
|
|
tai.Containerd // containerd runtime
|
|
tai.K8s // Kubernetes runtime
|
|
tai.WithPorts(Ports{}) // custom port mapping
|
|
tai.WithHTTPClient(hc) // custom HTTP client
|
|
tai.WithDataDir(dir) // workspace root (Local mode)
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
- `github.com/yaoapp/tai/volume/pb` — gRPC proto types
|
|
- `google.golang.org/grpc`
|
|
- `github.com/pierrec/lz4/v4` — sync compression
|
|
- `github.com/docker/docker` — Docker SDK
|