rexec

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:24.04",
        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:24.04",
    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://your-rexec-instance.com", "your-api-token")

// Create a container
container, err := client.Containers.Create(ctx, &rexec.CreateContainerRequest{
    Image: "ubuntu:24.04",
    Name:  "my-sandbox",
})

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

Index

• type APIError
  • func (e *APIError) Error() string
• type Client
  • func NewClient(baseURL, token string) *Client
  • func (c *Client) SetHTTPClient(httpClient *http.Client)
• type Container
• type ContainerService
  • func (s *ContainerService) Create(ctx context.Context, req *CreateContainerRequest) (*Container, error)
  • func (s *ContainerService) Delete(ctx context.Context, id string) error
  • func (s *ContainerService) Get(ctx context.Context, id string) (*Container, error)
  • func (s *ContainerService) List(ctx context.Context) ([]Container, error)
  • func (s *ContainerService) Start(ctx context.Context, id string) error
  • func (s *ContainerService) Stop(ctx context.Context, id string) error
• type CreateContainerRequest
• type ErrorResponse
• type FileInfo
• type FileService
  • func (s *FileService) Download(ctx context.Context, containerID, path string) ([]byte, error)
  • func (s *FileService) List(ctx context.Context, containerID, path string) ([]FileInfo, error)
  • func (s *FileService) Mkdir(ctx context.Context, containerID, path string) error
• type Terminal
  • func (t *Terminal) Close() error
  • func (t *Terminal) Read() ([]byte, error)
  • func (t *Terminal) Resize(cols, rows int) error
  • func (t *Terminal) Write(data []byte) error
• type TerminalService
  • func (s *TerminalService) Connect(ctx context.Context, containerID string) (*Terminal, error)

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 {

	// Services
	Containers *ContainerService
	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 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"`
}

Container represents a Rexec container/sandbox.

type ContainerService

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

ContainerService handles container operations.

func (*ContainerService) Create

func (s *ContainerService) Create(ctx context.Context, req *CreateContainerRequest) (*Container, error)

Create creates a new container.

func (*ContainerService) Delete

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

Delete deletes a container.

func (*ContainerService) Get

func (s *ContainerService) Get(ctx context.Context, id string) (*Container, error)

Get returns a container by ID.

func (*ContainerService) List

func (s *ContainerService) List(ctx context.Context) ([]Container, error)

List returns all containers for the authenticated user.

func (*ContainerService) Start

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

Start starts a stopped container.

func (*ContainerService) Stop

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

Stop stops a running container.

type CreateContainerRequest

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

CreateContainerRequest represents a request to create a container.

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 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.