Skip to content
Wisps

Go SDK

The Go SDK is the Wisps API for Go programs, It is its own module with one dependency (a WebSocket library), and it builds on Linux, macOS and Windows. See the API reference for request and response fields.

Have ready

Section titled “Have ready”

Steps

Section titled “Steps”

  1. Add the module. Your provider must give you access to its SDK distribution. If the source module is private, the command requires repository access.

    Terminal window
    go get github.com/akramh/wisps/sdk/go

  2. Connect. The package is wisps.

    import "github.com/akramh/wisps/sdk/go/wisps"
    

    c := wisps.New("https://api.example.com", os.Getenv("WISPS_TOKEN"))

  3. Create, use and delete a wisp as in the quickstart.

Check

Section titled “Check”
Terminal window
go vet ./...

It builds without errors.

Everyday calls

Section titled “Everyday calls”
Task Call
Create an ephemeral sandbox c.Create(ctx, "", wisps.CreateOptions{})
Create a workspace that persists (person token) c.Create(ctx, "dev", wisps.CreateOptions{Mode: wisps.ModeOnDemand})
Run a command to completion w.Run(ctx, wisps.RunOptions{Script: "make test"})
Run with output as it arrives w.RunStream(ctx, opts, func(stderr bool, p []byte) {...})
Interactive or long command w.Command("sh") (like exec.Cmd), or w.Exec with Detachable and later w.Attach
Files w.WriteFile, w.ReadFile, w.Upload, w.Open, w.ReadDir, w.Mkdir, w.Remove
A port inside the wisp w.DialPort(ctx, 8080) returns a net.Conn
Find wisps c.ListMatching(ctx, wisps.ListOptions{Labels: ...})
Change mode, clocks or labels w.Update(ctx, wisps.UpdateOptions{...}); Mode: wisps.ModeOnDemand keeps an ephemeral wisp
Checkpoint and restore w.PrepareVersion then w.ApplyVersion, safe to resend after a disconnect

Run and RunStream are not cut off by the client’s general request timeout; the command’s own TimeoutSeconds (default 60, at most 900 on a standard host) and your context bound them.

Errors

Section titled “Errors”
Case How to tell
The API refused the request *wisps.APIError with Status and Message
No such wisp (or another team’s) wisps.IsNotFound(err)
Deleted automatically wisps.IsGone(err): the message says why; create a new one
An ephemeral wisp’s lifetime is over Status 409 from start and work requests; switch it to ModeOnDemand to use it again
An API token asked for a persistent mode Status 403
The command failed Not an error: RunResult.ExitCode, TimedOut, StdoutTruncated