slicer

package module
v0.0.12 Latest Latest
Warning

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

 Go to latest Published: Dec 12, 2025 License: MIT Imports: 19 Imported by: 1

README

Golang SDK for Slicer

SDK for SlicerVM.com

Installation

go get github.com/slicervm/sdk@latest

Example usage

Create a new slicer config:

slicer new api \
    --count=0 \
    --graceful-shutdown=false \
    --ram 4 \
    --cpu 2 > api.yaml

Create a VM (node) in a host group with the default RAM/CPU settings as defined in the host group.

package main

import (
    "fmt"
    "os"
    sdk "github.com/slicervm/sdk"
)

func main() {
    // Typically you'd load these from environment variables
    baseURL := os.Getenv("SLICER_URL")      // API base URL
    token := os.Getenv("SLICER_TOKEN")      // Your API token
    userAgent := "my-microvm-client/1.0"
    hostGroup := "api"                       // Existing host group name

    client := sdk.NewSlicerClient(baseURL, token, userAgent, nil /* or &http.Client{} */)

    createReq := sdk.SlicerCreateNodeRequest{
        RAMGB:      4,
        CPUs:       2,
        Userdata: `#!/bin/bash
echo 'Bootstrapping...'
ping -c3 google.com

sudo reboot
`,
        SSHKeys: []string{"ssh-rsa AAAA..."}, // Optional: inject public SSH keys
        ImportUser: "alexellis", // Optional: Import GitHub keys for a specific user
    }

    res, err := client.CreateNode(hostGroup, createReq)
    if err != nil {
        panic(fmt.Errorf("failed to create node: %w", err))
    }

    fmt.Printf("Created VM: hostname=%s ip=%s created_at=%s\n", res.Hostname, res.IP, res.CreatedAt)
    fmt.Printf("Parsed IP only: %s\n", res.IPAddress())
}

Start Slicer:

sudo -E slicer up ./api.yaml

Run the program i.e. after running go build -o client main.go:

SLICER_URL=http://127.0.0.1:8080 SLICER_TOKEN="$(sudo cat /var/lib/slicer/auth/token)" ./client

You'll find the logs for the microVM at /var/log/slicer/HOSTNAME.txt, showing the userdata executing.

Notes:

  • The argument order for NewSlicerClient is (baseURL, token, userAgent, httpClient).
  • RAMGB, CPUs, and ImportUser should be set; Userdata and SSHKeys are optional.
  • Userdata runs on first boot; keep it idempotent.
  • Use a persistent http.Client (e.g. with timeout) in production instead of nil.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrSecretExists is an error returned when a secret with given name already exists.
	ErrSecretExists = errors.New("secret already exists")
)

Functions

func ExtractTarStream added in v0.0.10 

func ExtractTarStream(ctx context.Context, r io.Reader, extractDir string, uid, gid uint32) error

ExtractTarStream extracts a tar stream from r into extractDir. This is a streaming implementation that doesn't buffer entire files in memory. If uid or gid are non-zero, files will be chowned to that uid/gid after creation.

func ExtractTarToPath added in v0.0.10 

func ExtractTarToPath(ctx context.Context, r io.Reader, dest string, uid, gid uint32) error

ExtractTarToPath extracts a tar stream to a local path with proper renaming logic. This handles the cp-like behavior of renaming files/directories and moving contents into existing directories. If uid or gid are non-zero, files will be chowned to that uid/gid after creation.

func StreamTarArchive added in v0.0.10 

func StreamTarArchive(ctx context.Context, w io.Writer, parentDir, baseName string) error

StreamTarArchive streams a tar archive of the given path to w. This is a streaming implementation that doesn't buffer entire files in memory. parentDir and baseName are used to strip leading paths, making it more like cp.

func ValidRelPath added in v0.0.10 

func ValidRelPath(p string) bool

ValidRelPath validates that a path is a valid relative path and doesn't contain directory traversal attempts

Types

type CreateSecretRequest added in v0.0.6 

type CreateSecretRequest struct {
	// Name is the unique name of the secret
	Name string `json:"name"`
	// Data is the secret content
	Data string `json:"data"`
	// Permissions specifies the file permissions (defaults to system default)
	Permissions string `json:"permissions,omitempty"`

	// GID is the user ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	UID uint32 `json:"uid,omitempty"`

	// GID is the group ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	GID uint32 `json:"gid,omitempty"`
}

CreateSecretRequest is the payload for creating a new secret via the REST API.

type Secret added in v0.0.6 

type Secret struct {
	// Name is the unique name of the secret
	Name string `json:"name"`
	// Size is the size of the secret data in bytes
	Size int64 `json:"size"`
	// Permissions specifies the file permissions for the secret (e.g., "0600")
	Permissions string `json:"permissions"`

	// GID is the user ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	UID uint32 `json:"uid,omitempty"`

	// GID is the group ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	GID uint32 `json:"gid,omitempty"`

	// ModifiedAt is the time the secret was last modified
	ModifiedAt *time.Time `json:"modified_at,omitempty"`
}

Secret represents a secret stored in the slicer system. Secrets can be used to store sensitive configuration data, keys, or other private information that can be mounted into nodes or used by services.

type SlicerClient 

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

SlicerClient handles all HTTP communication with the Slicer API

func NewSlicerClient 

func NewSlicerClient(baseURL, token string, userAgent string, httpClient *http.Client) *SlicerClient

NewSlicerClient creates a new Slicer API client

func (*SlicerClient) CpFromVM added in v0.0.10 

func (c *SlicerClient) CpFromVM(ctx context.Context, vmName, vmPath, localPath string, uid, gid uint32) error

CpFromVM copies files from a VM path to a local path. The tar stream is received from the VM and extracted to localPath with proper renaming logic (supports renaming files/directories). If uid or gid are 0, the current user's UID/GID will be used. On Windows, chown operations are skipped (uid/gid are ignored).

func (*SlicerClient) CpToVM added in v0.0.10 

func (c *SlicerClient) CpToVM(ctx context.Context, vmName, localPath, vmPath string, uid, gid uint32) error

CpToVM copies files from a local path to a VM path. The localPath can be a file or directory. The tar stream is created internally and sent to the VM. uid and gid specify the ownership for extracted files (0 means use default).

func (*SlicerClient) CreateNode 

func (c *SlicerClient) CreateNode(ctx context.Context, groupName string, request SlicerCreateNodeRequest) (*SlicerCreateNodeResponse, error)

CreateNode creates a new node in the specified host group

func (*SlicerClient) CreateSecret added in v0.0.6 

func (c *SlicerClient) CreateSecret(ctx context.Context, request CreateSecretRequest) error

CreateSecret creates a new secret. Returns ErrSecretExists if a secret with the same name already exists. An error is returned if creation fails.

func (*SlicerClient) CreateVM added in v0.0.10 

func (c *SlicerClient) CreateVM(ctx context.Context, groupName string, request SlicerCreateVMRequest) (*SlicerCreateNodeResponse, error)

CreateVM creates a new VM in a host group

func (*SlicerClient) DeleteNode 

func (c *SlicerClient) DeleteNode(groupName, nodeName string) error

DeleteNode deletes a node from the specified host group

func (*SlicerClient) DeleteSecret added in v0.0.6 

func (c *SlicerClient) DeleteSecret(ctx context.Context, secretName string) error

DeleteSecret removes a secret. Returns an error if the secret doesn't exist or if the deletion fails.

func (*SlicerClient) DeleteVM added in v0.0.10 

func (c *SlicerClient) DeleteVM(ctx context.Context, groupName, hostname string) (*SlicerDeleteResponse, error)

DeleteVM deletes a VM from a host group

func (*SlicerClient) Exec added in v0.0.9 

func (c *SlicerClient) Exec(ctx context.Context, nodeName string, execReq SlicerExecRequest) (chan SlicerExecWriteResult, error)

Exec executes a command on the specified node and streams the output. The channel is unbuffered so the caller should read from it promptly to avoid blocking.

func (*SlicerClient) GetHostGroupNodes 

func (c *SlicerClient) GetHostGroupNodes(ctx context.Context, groupName string) ([]SlicerNode, error)

GetHostGroupNodes fetches nodes for a specific host group

func (*SlicerClient) GetHostGroups 

func (c *SlicerClient) GetHostGroups(ctx context.Context) ([]SlicerHostGroup, error)

GetHostGroups fetches all host groups from the API

func (*SlicerClient) GetVMLogs added in v0.0.10 

func (c *SlicerClient) GetVMLogs(ctx context.Context, hostname string, lines int) (*SlicerLogsResponse, error)

GetVMLogs fetches logs for a specific VM

func (*SlicerClient) GetVMStats added in v0.0.10 

func (c *SlicerClient) GetVMStats(ctx context.Context, hostname string) ([]SlicerNodeStat, error)

GetVMStats fetches stats for all VMs or a specific VM if hostname is provided. If hostname is empty, returns stats for all VMs.

func (*SlicerClient) ListSecrets added in v0.0.6 

func (c *SlicerClient) ListSecrets(ctx context.Context) ([]Secret, error)

ListSecrets retrieves all secrets. Note: The actual secret data is not returned for security reasons.

func (*SlicerClient) ListVMs added in v0.0.10 

func (c *SlicerClient) ListVMs(ctx context.Context) ([]SlicerNode, error)

ListVMs fetches all VMs (nodes)

func (*SlicerClient) PatchSecret added in v0.0.6 

func (c *SlicerClient) PatchSecret(ctx context.Context, secretName string, request UpdateSecretRequest) error

PatchSecret updates an existing secret with new data and/or metadata. Only the fields provided in the UpdateSecretRequest will be modified. Returns an error if the secret doesn't exist or if the update fails.

type SlicerCpRequest added in v0.0.10 

type SlicerCpRequest struct {
	VM   string // VM name
	Path string // Path on the VM
}

SlicerCpRequest contains parameters for copying files to/from a VM

type SlicerCreateNodeRequest 

type SlicerCreateNodeRequest struct {
	RamGB      int      `json:"ram_gb"`
	CPUs       int      `json:"cpus"`
	Tags       []string `json:"tags,omitempty"`
	ImportUser string   `json:"import_user"`
	Userdata   string   `json:"userdata,omitempty"`
	SSHKeys    []string `json:"ssh_keys,omitempty"`
	Secrets    []string `json:"secrets,omitempty"`
}

SlicerCreateNodeRequest is the payload for creating a node via the REST API.

type SlicerCreateNodeResponse 

type SlicerCreateNodeResponse struct {
	Hostname  string    `json:"hostname"`
	IP        string    `json:"ip"`
	CreatedAt time.Time `json:"created_at"`
	Arch      string    `json:"arch,omitempty"`
}

SlicerCreateNodeResponse is the response from the REST API when creating a node.

func (*SlicerCreateNodeResponse) IPAddress 

func (n *SlicerCreateNodeResponse) IPAddress() net.IP

type SlicerCreateVMRequest added in v0.0.10 

type SlicerCreateVMRequest struct {
	GPUCount   int      `json:"gpuCount"`
	Persistent bool     `json:"persistent"`
	DiskImage  string   `json:"diskImage,omitempty"`
	ImportUser string   `json:"importUser,omitempty"`
	SSHKeys    []string `json:"sshKeys,omitempty"`
	Userdata   string   `json:"userdata,omitempty"`
	IP         string   `json:"ip,omitempty"`
	Tags       []string `json:"tags,omitempty"`
	Secrets    []string `json:"secrets,omitempty"`
}

SlicerCreateVMRequest contains parameters for creating a VM

type SlicerDeleteResponse added in v0.0.10 

type SlicerDeleteResponse struct {
	Message     string `json:"message"`
	DiskRemoved string `json:"disk_removed"`
	Error       string `json:"error"`
}

SlicerDeleteResponse represents the response from the delete endpoint

type SlicerExecRequest added in v0.0.9 

type SlicerExecRequest struct {
	Command     string   `json:"command,omitempty"`
	Args        []string `json:"args,omitempty"`
	UID         uint32   `json:"uid,omitempty"`
	GID         uint32   `json:"gid,omitempty"`
	Stdin       bool     `json:"stdin,omitempty"`
	Stdout      bool     `json:"stdout,omitempty"`
	Stderr      bool     `json:"stderr,omitempty"`
	Shell       string   `json:"shell,omitempty"`
	Cwd         string   `json:"cwd,omitempty"`
	Permissions string   `json:"permissions,omitempty"`
}

SlicerExecRequest contains parameters for invoking a command within a VM.

type SlicerExecWriteResult added in v0.0.9 

type SlicerExecWriteResult struct {
	Stdout   string `json:"stdout,omitempty"`
	Stderr   string `json:"stderr,omitempty"`
	ExitCode int    `json:"exit_code,omitempty"`
	Error    string `json:"error,omitempty"`
}

ExecWriteResult represents output from commands executing within a microVM.

type SlicerHostGroup 

type SlicerHostGroup struct {
	Name     string `json:"name"`
	Count    int    `json:"count"`
	RamGB    int    `json:"ram_gb"`
	CPUs     int    `json:"cpus"`
	Arch     string `json:"arch,omitempty"`
	GPUCount int    `json:"gpu_count,omitempty"`
}

SlicerHostGroup represents a host group from the /hostgroup endpoint.

type SlicerLogsResponse added in v0.0.10 

type SlicerLogsResponse struct {
	Hostname string `json:"hostname"`
	Lines    int    `json:"lines"`
	Content  string `json:"content"`
}

SlicerLogsResponse represents the response from the logs endpoint

type SlicerNode 

type SlicerNode struct {
	Hostname  string    `json:"hostname"`
	IP        string    `json:"ip"`
	CreatedAt time.Time `json:"created_at"`
	Arch      string    `json:"arch,omitempty"`
	Tags      []string  `json:"tags,omitempty"`
}

SlicerNode represents a node managed by the slicer REST API.

type SlicerNodeStat added in v0.0.10 

type SlicerNodeStat struct {
	Hostname  string          `json:"hostname"`
	IP        string          `json:"ip"`
	CreatedAt time.Time       `json:"created_at"`
	Snapshot  *SlicerSnapshot `json:"snapshot"`
	Error     string          `json:"error"`
}

SlicerNodeStat represents stats for a VM node

type SlicerSnapshot added in v0.0.10 

type SlicerSnapshot struct {
	Hostname             string    `json:"hostname"`
	Arch                 string    `json:"arch"`
	Timestamp            time.Time `json:"timestamp"`
	Uptime               string    `json:"uptime"`
	TotalCPUS            int       `json:"totalCpus"`
	TotalMemory          uint64    `json:"totalMemory"`
	MemoryUsed           uint64    `json:"memoryUsed"`
	MemoryAvailable      uint64    `json:"memoryAvailable"`
	MemoryUsedPercent    float64   `json:"memoryUsedPercent"`
	LoadAvg1             float64   `json:"loadAvg1"`
	LoadAvg5             float64   `json:"loadAvg5"`
	LoadAvg15            float64   `json:"loadAvg15"`
	DiskReadTotal        float64   `json:"diskReadTotal"`
	DiskWriteTotal       float64   `json:"diskWriteTotal"`
	NetworkReadTotal     float64   `json:"networkReadTotal"`
	NetworkWriteTotal    float64   `json:"networkWriteTotal"`
	DiskIOInflight       int64     `json:"diskIOInflight"`
	OpenConnections      int64     `json:"openConnections"`
	OpenFiles            int64     `json:"openFiles"`
	Entropy              int64     `json:"entropy"`
	DiskSpaceTotal       uint64    `json:"diskSpaceTotal"`
	DiskSpaceUsed        uint64    `json:"diskSpaceUsed"`
	DiskSpaceFree        uint64    `json:"diskSpaceFree"`
	DiskSpaceUsedPercent float64   `json:"diskSpaceUsedPercent"`
}

SlicerSnapshot represents a snapshot of VM metrics

type UpdateSecretRequest added in v0.0.6 

type UpdateSecretRequest struct {
	// Data is the updated secret content
	Data string `json:"data"`
	// Permissions specifies the file permissions
	Permissions string `json:"permissions,omitempty"`

	// GID is the user ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	UID uint32 `json:"uid,omitempty"`

	// GID is the group ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	GID uint32 `json:"gid,omitempty"`
}

UpdateSecretRequest is the payload for updating an existing secret via the REST API. All fields are optional - only provided fields will be updated.

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.