rexec

package module
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 3, 2026 License: MIT Imports: 10 Imported by: 0

README

Rexec Go SDK

Official Go SDK for Rexec - Terminal as a Service.

Installation

go get github.com/PipeOpsHQ/rexec-go

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    rexec "github.com/PipeOpsHQ/rexec-go"
)

func main() {
    // Create client
    client := rexec.NewClient("https://your-rexec-instance.com", "your-api-token")

    ctx := context.Background()

    // Create a container
    container, err := client.Containers.Create(ctx, &rexec.CreateContainerRequest{
        Image: "ubuntu",
        Name:  "my-sandbox",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Created container: %s\n", container.ID)

    // Connect to terminal
    term, err := client.Terminal.Connect(ctx, container.ID)
    if err != nil {
        log.Fatal(err)
    }
    defer term.Close()

    // Send a command
    term.Write([]byte("echo 'Hello from Rexec!'\n"))

    // Read output
    output, _ := term.Read()
    fmt.Printf("Output: %s\n", output)

    // Clean up
    client.Containers.Delete(ctx, container.ID)
}

API Reference

Client
// Create a new client
client := rexec.NewClient(baseURL, apiToken)

// Use custom HTTP client
client.SetHTTPClient(&http.Client{Timeout: 60 * time.Second})
Containers
// List all containers
containers, err := client.Containers.List(ctx)

// Get a specific container
container, err := client.Containers.Get(ctx, containerID)

// Create a container
container, err := client.Containers.Create(ctx, &rexec.CreateContainerRequest{
    Image: "ubuntu",
    Name:  "my-container",
    Environment: map[string]string{
        "MY_VAR": "value",
    },
})

// Start a container
err := client.Containers.Start(ctx, containerID)

// Stop a container
err := client.Containers.Stop(ctx, containerID)

// Delete a container
err := client.Containers.Delete(ctx, containerID)
Files
// List files in a directory
files, err := client.Files.List(ctx, containerID, "/home")

// Download a file
data, err := client.Files.Download(ctx, containerID, "/home/file.txt")

// Create a directory
err := client.Files.Mkdir(ctx, containerID, "/home/newdir")
Terminal
// Connect to terminal
term, err := client.Terminal.Connect(ctx, containerID)
defer term.Close()

// Send input
term.Write([]byte("ls -la\n"))

// Read output
output, err := term.Read()

// Resize terminal
term.Resize(120, 40)

Examples

Run a Script
func runScript(client *rexec.Client, containerID, script string) error {
    ctx := context.Background()
    
    term, err := client.Terminal.Connect(ctx, containerID)
    if err != nil {
        return err
    }
    defer term.Close()

    // Write script
    term.Write([]byte(script + "\n"))
    
    // Read output
    for {
        output, err := term.Read()
        if err != nil {
            break
        }
        fmt.Print(string(output))
    }
    
    return nil
}
Interactive Session
func interactiveSession(client *rexec.Client, containerID string) error {
    ctx := context.Background()
    
    term, err := client.Terminal.Connect(ctx, containerID)
    if err != nil {
        return err
    }
    defer term.Close()

    // Handle terminal resize
    term.Resize(80, 24)

    // Read from stdin and write to terminal
    go func() {
        buf := make([]byte, 1024)
        for {
            n, _ := os.Stdin.Read(buf)
            term.Write(buf[:n])
        }
    }()

    // Read from terminal and write to stdout
    for {
        output, err := term.Read()
        if err != nil {
            break
        }
        os.Stdout.Write(output)
    }
    
    return nil
}

License

MIT License - see LICENSE for details.

Documentation

Overview

Package rexec provides a Go SDK for interacting with Rexec - Terminal as a Service.

The SDK allows you to programmatically create, manage, and interact with sandboxed Linux environments through the Rexec API.

Basic usage: 

client := rexec.NewClient("https://rexec.sh", "your-api-token")

// Create a sandbox (preferred)
sandbox, err := client.Sandboxes.Create(ctx, &rexec.CreateSandboxRequest{
    Image: "ubuntu",
    Name:  "my-sandbox",
})
// Legacy: client.Containers is the same service

term, err := client.Terminal.Connect(ctx, sandbox.ID)
term.Write([]byte("echo hello\n"))

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	StatusCode int
	Message    string
}

APIError represents an API error.

func (*APIError) Error 

func (e *APIError) Error() string

type Client 

type Client struct {

	// Sandboxes is the preferred accessor for sandbox lifecycle APIs.
	Sandboxes *SandboxService
	// Containers is a deprecated alias for Sandboxes (same pointer). Prefer Sandboxes.
	Containers *SandboxService
	Files      *FileService
	Terminal   *TerminalService
	// contains filtered or unexported fields
}

Client is the main Rexec API client.

func NewClient 

func NewClient(baseURL, token string) *Client

NewClient creates a new Rexec client.

func (*Client) SetHTTPClient 

func (c *Client) SetHTTPClient(httpClient *http.Client)

SetHTTPClient sets a custom HTTP client.

type Container 

type Container = Sandbox

Container is a deprecated alias for Sandbox. Deprecated: use Sandbox.

type ContainerService 

type ContainerService = SandboxService

ContainerService is a deprecated alias for SandboxService. Deprecated: use SandboxService.

type CreateContainerRequest 

type CreateContainerRequest = CreateSandboxRequest

CreateContainerRequest is a deprecated alias for CreateSandboxRequest. Deprecated: use CreateSandboxRequest.

type CreateSandboxRequest added in v1.1.0 

type CreateSandboxRequest struct {
	Name        string            `json:"name,omitempty"`
	Image       string            `json:"image"`
	Environment map[string]string `json:"environment,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
}

CreateSandboxRequest represents a request to create a sandbox. Prefer image aliases such as "ubuntu".

type ErrorResponse 

type ErrorResponse struct {
	Error string `json:"error"`
}

ErrorResponse represents an API error response.

type FileInfo 

type FileInfo struct {
	Name    string    `json:"name"`
	Path    string    `json:"path"`
	Size    int64     `json:"size"`
	Mode    string    `json:"mode"`
	ModTime time.Time `json:"mod_time"`
	IsDir   bool      `json:"is_dir"`
}

FileInfo represents file metadata.

type FileService 

type FileService struct {
	// contains filtered or unexported fields
}

FileService handles file operations.

func (*FileService) Download 

func (s *FileService) Download(ctx context.Context, containerID, path string) ([]byte, error)

Download downloads a file from a container.

func (*FileService) List 

func (s *FileService) List(ctx context.Context, containerID, path string) ([]FileInfo, error)

List lists files in a container directory.

func (*FileService) Mkdir 

func (s *FileService) Mkdir(ctx context.Context, containerID, path string) error

Mkdir creates a directory in a container.

type Sandbox added in v1.1.0 

type Sandbox struct {
	ID          string            `json:"id"`
	Name        string            `json:"name"`
	Image       string            `json:"image"`
	Status      string            `json:"status"`
	CreatedAt   time.Time         `json:"created_at"`
	StartedAt   *time.Time        `json:"started_at,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
	Environment map[string]string `json:"environment,omitempty"`
}

Sandbox represents a Rexec sandbox (isolated Linux environment). Wire protocol still uses the /api/containers resource.

type SandboxService added in v1.1.0 

type SandboxService struct {
	// contains filtered or unexported fields
}

SandboxService handles sandbox lifecycle operations. HTTP paths remain /api/containers for backend compatibility.

func (*SandboxService) Create added in v1.1.0 

func (s *SandboxService) Create(ctx context.Context, req *CreateSandboxRequest) (*Sandbox, error)

Create creates a new sandbox.

func (*SandboxService) Delete added in v1.1.0 

func (s *SandboxService) Delete(ctx context.Context, id string) error

Delete deletes a sandbox.

func (*SandboxService) Get added in v1.1.0 

func (s *SandboxService) Get(ctx context.Context, id string) (*Sandbox, error)

Get returns a sandbox by ID.

func (*SandboxService) List added in v1.1.0 

func (s *SandboxService) List(ctx context.Context) ([]Sandbox, error)

List returns all sandboxes for the authenticated user.

func (*SandboxService) Start added in v1.1.0 

func (s *SandboxService) Start(ctx context.Context, id string) error

Start starts a stopped sandbox.

func (*SandboxService) Stop added in v1.1.0 

func (s *SandboxService) Stop(ctx context.Context, id string) error

Stop stops a running sandbox.

type Terminal 

type Terminal struct {
	// contains filtered or unexported fields
}

Terminal represents a WebSocket terminal connection.

func (*Terminal) Close 

func (t *Terminal) Close() error

Close closes the terminal connection.

func (*Terminal) Read 

func (t *Terminal) Read() ([]byte, error)

Read reads data from the terminal.

func (*Terminal) Resize 

func (t *Terminal) Resize(cols, rows int) error

Resize resizes the terminal.

func (*Terminal) Write 

func (t *Terminal) Write(data []byte) error

Write sends data to the terminal.

type TerminalService 

type TerminalService struct {
	// contains filtered or unexported fields
}

TerminalService handles terminal connections.

func (*TerminalService) Connect 

func (s *TerminalService) Connect(ctx context.Context, containerID string) (*Terminal, error)

Connect establishes a WebSocket terminal connection to a container.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.