feat(sdk/go): Go SDK with full API parity (#568)#587
Open
khrees wants to merge 15 commits intosuperradcompany:mainfrom
Open
feat(sdk/go): Go SDK with full API parity (#568)#587khrees wants to merge 15 commits intosuperradcompany:mainfrom
khrees wants to merge 15 commits intosuperradcompany:mainfrom
Conversation
Introduces a Go client SDK for microsandbox under sdk/go/. - sandbox.go: NewSandbox, NewSandboxDetached, GetSandbox, ListSandboxes, RemoveSandbox, Stop, Kill, Detach, StopAndWait, FS(), Metrics, AllSandboxMetrics - exec.go: Exec, Shell, ExecStream with streaming ExecEvent channel - fs.go: SandboxFs with Read/Write/ReadString/WriteString/List/Stat/CopyIn/CopyOut - volume.go: NewVolume, ListVolumes, RemoveVolume, GetVolume, VolumeExists - options.go: full functional-options API — image, memory, CPUs, env, workdir, volumes, network policy, secrets, patches, ports, scripts - errors.go: typed ErrorKind with IsKind/IsSandboxNotFound/IsExecTimeout/IsExecFailed helpers - internal/ffi: FFI interface + MockFFI test double + RealFFI stub (real CGO wiring deferred to the go-ffi Rust crate)
Add the `microsandbox-go-ffi` crate to expose the Rust API over a stable C-ABI. This allows the Go SDK to interact with the runtime via CGO. Refactor `sdk/go` to consume the new FFI layer: - Replace the mock FFI interface with real CGO bindings. - Update error handling to parse JSON error payloads from Rust. - Align Go types and options with the FFI contract. - Remove `sdk/go/internal/ffi/mock.go`.
Introduce comprehensive test coverage for the Go SDK including: - Unit tests for error handling, exec output, filesystem entries, and options. - Integration tests for sandbox lifecycle, command execution, filesystem operations, metrics, and volume management. - A Makefile with targets to build the Rust FFI and run both unit and integration tests.
Configure cbindgen to automatically generate C headers for the Go FFI crate. Expand SandboxOptions to support detached mode, port mapping, network policies, secrets, and filesystem patches. Update FFI function signatures to accept cancellation IDs and add support for streaming exec events.
Expose `msb_sandbox_detach` in the FFI layer to allow releasing handles without terminating the VM. Wrap the new function in the Go Sandbox struct. Include new example programs covering basic usage, secrets, streaming exec, and volumes. Adjust metrics test timing to account for sampler initialization.
- Add `EnsureInstalled` function to the Go SDK to manage the installation of the microsandbox runtime, including the Go FFI shared library. - Update examples to call `EnsureInstalled` at startup, ensuring the runtime is available before executing any SDK functions. - Introduce error handling for library loading failures with a new `ErrLibraryNotLoaded` error type. - Remove the Makefile from the Go SDK as it is no longer needed for building the FFI. - Update documentation to reflect changes in installation and usage patterns.
- Introduce a new README.md file for the Go SDK, detailing the features, requirements, installation instructions, and quick start examples for using the microsandbox. - Include sections on command execution, streaming execution, filesystem operations, named volumes, network policies, DNS filtering, port publishing, and secrets management. - Provide code snippets to illustrate usage patterns and enhance developer understanding of the SDK capabilities.
…e metadata retrieval support
- Add ExecHandle.ID(), Collect(), Wait(), Kill() to public exec API - Add Volume.Path(), Volume.FS(), VolumeHandle.Path(), VolumeHandle.FS() - Add VolumeFs type for direct host-side file ops on volume directories - Add MountConfig, Mount factory (Bind/Named/Tmpfs), WithMounts option - Wire Volumes through SandboxConfig and CreateSandbox → FFI - Add AllSandboxMetrics, SandboxHandle.Metrics, Sandbox.RemovePersisted - Add MetricsStream(interval) with MetricsStreamHandle - Add SandboxFs.ReadStream / WriteStream with FsReadStream / FsWriteStream - Add VolumeHandle.Path from msb_volume_get JSON response - Add corresponding Rust FFI functions in go-ffi/src/lib.rs
…Env to exec options
…metrics stream, exec advanced
Replace the raw C.uint64_t handle with atomic.Uint64 to enable safe concurrent Close/Detach calls. Add best-effort handle recovery and cleanup when JSON unmarshalling fails during sandbox creation, preventing Rust-side leaks. Map context.Canceled and context.DeadlineExceeded to ErrCancelled in wrapFFI, preserving the original error as Cause. Update documentation to clarify that Volume.Path is empty for CreateVolume/ListVolumes results.
Simplify Error.Error() to omit redundant Kind prefix and handle edge cases (empty message, cause-only). Rename TlsConfig to TLSConfig for idiomatic Go naming. Fix error message casing in examples.
Member
|
Bro. Thanks for contributing this. I already took a look at it a couple days back. |
Member
|
@Khrees2412 is the Go implementation auto-generated? or just the asking in order to guage how much work it'd be to maintain. |
Author
|
Mostly handwritten. ffi.go is the only really low-level FFI bridge layer; the rest of the Go SDK is normal handwritten Go. Claude helped a lot with the initial implementation, but it’s not codegen-driven. Maintenance should mostly just be keeping |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #568
Summary
Full Go SDK for microsandbox, implemented via CGO over a new
sdk/go-ffiRust cdylib. The library is loaded at runtime viadlopen/dlsym— no build-time linking required. API design follows Go conventions (functional options, context-first, typed errors) while covering the same surface as the Node and Python SDKs.What's included
Sandbox lifecycle
CreateSandbox/CreateSandboxDetached,GetSandbox,StartSandbox,StartSandboxDetached,ListSandboxes,RemoveSandboxSandboxHandle— lightweight DB record reference withConnect,Start,Stop,Kill,Remove,MetricsSandbox—Stop,StopAndWait,Kill,Wait,Drain,Detach,Close,OwnsLifecycle,RemovePersistedAttach/AttachShellfor interactive PTY sessionsAllSandboxMetrics,Sandbox.MetricsStream(interval)Exec
Exec/Shell— collected outputExecStream/ShellStream— streaming withExecHandle.Recv,Collect,Wait,Kill,Signal,ID,TakeStdinUserandEnvoverrides viaWithExecUser/WithExecEnvFilesystem
SandboxFs—Read,Write,List,Stat,CopyFromHost,CopyToHost,Mkdir,Remove,RemoveDir,Copy,Rename,ExistsReadStream(io.WriterTo) andWriteStream(io.Writer)Volumes
CreateVolume,GetVolume,ListVolumes,RemoveVolumeVolume.Path()/Volume.FS()andVolumeHandlewith full metadata +FS()VolumeFs— direct host-side file ops on the volume directoryOptions & factories
NetworkPolicy.None/PublicOnly/AllowAll, custom rulesSecret.Env(...)for proxy-layer credential injectionPatch.Text/Append/Mkdir/Remove/Symlink/CopyFile/CopyDirMount.Bind/Named/TmpfswithWithMountsWithHostname,WithUser,WithReplaceon sandbox creationFFI layer (
sdk/go-ffi/)extern "C"async wrappers with an internal Tokio runtimeu64keys) for sandbox, exec, metrics stream, fs read/write handlesAtomicBoolkeyed by cancel IDTest plan
go build ./...— passesgo vet ./...— passessdk/go/*_test.goagainst a running microsandbox daemonEnsureInstalleddownloads and loads the cdylib correctly on a fresh machineGetSandbox