Documentation
¶
Overview ¶
Package vaultrun provides a Go SDK for the VaultRun API.
Index ¶
- type APIKey
- type AsyncRunOptions
- type AsyncRunResult
- type AuditLog
- type Client
- func (c *Client) AddOrgMember(ctx context.Context, orgID, principal, role string) (*OrgMember, error)
- func (c *Client) CreateKey(ctx context.Context, opts CreateKeyOptions) (*CreatedKey, error)
- func (c *Client) CreateOrg(ctx context.Context, name, slug string) (*Organization, error)
- func (c *Client) CreateSession(ctx context.Context, opts CreateSessionOptions) (*Session, error)
- func (c *Client) CreateSnapshot(ctx context.Context, sessionID, name string) (*Snapshot, error)
- func (c *Client) DeleteArtifact(ctx context.Context, artifactID string) error
- func (c *Client) DeleteFile(ctx context.Context, sessionID, remotePath string) error
- func (c *Client) DeleteOrg(ctx context.Context, orgID string) error
- func (c *Client) DeleteSession(ctx context.Context, sessionID string) error
- func (c *Client) DeleteSnapshot(ctx context.Context, snapshotID string) error
- func (c *Client) DownloadArtifact(ctx context.Context, artifactID string) ([]byte, error)
- func (c *Client) DownloadFile(ctx context.Context, sessionID, remotePath string) (io.ReadCloser, error)
- func (c *Client) DownloadSnapshot(ctx context.Context, snapshotID string) ([]byte, error)
- func (c *Client) DownloadWorkspace(ctx context.Context, sessionID string) (io.ReadCloser, error)
- func (c *Client) GetOrg(ctx context.Context, orgID string) (*Organization, error)
- func (c *Client) GetRun(ctx context.Context, runID string) (*Run, error)
- func (c *Client) GetSession(ctx context.Context, sessionID string) (*Session, error)
- func (c *Client) GetSessionLogs(ctx context.Context, sessionID string, tail int) (string, error)
- func (c *Client) GetSessionStats(ctx context.Context, sessionID string) (*SessionStats, error)
- func (c *Client) ListArtifacts(ctx context.Context) ([]*SharedArtifact, error)
- func (c *Client) ListAuditLogs(ctx context.Context, opts ...ListAuditLogsOptions) ([]*AuditLog, error)
- func (c *Client) ListFiles(ctx context.Context, sessionID string) ([]*File, error)
- func (c *Client) ListImages(ctx context.Context) ([]*Image, error)
- func (c *Client) ListKeys(ctx context.Context) ([]*APIKey, error)
- func (c *Client) ListOrgMembers(ctx context.Context, orgID string) ([]*OrgMember, error)
- func (c *Client) ListOrgSessions(ctx context.Context, orgID string) ([]*Session, error)
- func (c *Client) ListOrgs(ctx context.Context) ([]*Organization, error)
- func (c *Client) ListRuns(ctx context.Context, sessionID string) ([]*Run, error)
- func (c *Client) ListSessions(ctx context.Context, opts ...ListSessionsOptions) ([]*Session, error)
- func (c *Client) ListSnapshots(ctx context.Context, sessionID string) ([]*Snapshot, error)
- func (c *Client) PromoteArtifact(ctx context.Context, sessionID, path string, name ...string) (*SharedArtifact, error)
- func (c *Client) PullImage(ctx context.Context, image string) (*PullStatus, error)
- func (c *Client) RemoveOrgMember(ctx context.Context, orgID, principal string) error
- func (c *Client) RevokeKey(ctx context.Context, keyID string) error
- func (c *Client) Run(ctx context.Context, sessionID string, opts RunOptions) (*Run, error)
- func (c *Client) RunAsync(ctx context.Context, sessionID string, opts AsyncRunOptions) (*AsyncRunResult, error)
- func (c *Client) Stream(ctx context.Context, sessionID string, opts RunOptions, ...) (*StreamEvent, error)
- func (c *Client) UpdateSessionLabels(ctx context.Context, sessionID string, labels map[string]string) error
- func (c *Client) UploadFile(ctx context.Context, sessionID, remotePath string, content io.Reader) (*File, error)
- type CreateKeyOptions
- type CreateSessionOptions
- type CreatedKey
- type File
- type Image
- type ListAuditLogsOptions
- type ListSessionsOptions
- type OrgMember
- type Organization
- type PullStatus
- type Run
- type RunOptions
- type Session
- type SessionStats
- type SharedArtifact
- type Snapshot
- type StreamEvent
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type APIKey ¶
type APIKey struct {
ID string `json:"id"`
Name string `json:"name"`
Prefix string `json:"prefix"`
Active bool `json:"active"`
CreatedAt time.Time `json:"created_at"`
LastUsedAt *time.Time `json:"last_used_at,omitempty"`
}
APIKey represents a VaultRun API key (plaintext is never returned after creation).
type AsyncRunOptions ¶
type AsyncRunOptions struct {
RunOptions
// CallbackURL receives an HTTP POST with the completed Run when the job finishes.
CallbackURL string
}
AsyncRunOptions extends RunOptions with an optional webhook callback URL.
type AsyncRunResult ¶
type AsyncRunResult struct {
RunID string `json:"run_id"`
Status string `json:"status"`
Message string `json:"message"`
}
AsyncRunResult is returned by RunAsync — contains the pending run's ID.
type AuditLog ¶
type AuditLog struct {
ID string `json:"id"`
Actor string `json:"actor"`
SessionID *string `json:"session_id,omitempty"`
RunID *string `json:"run_id,omitempty"`
Action string `json:"action"`
Metadata any `json:"metadata,omitempty"`
Timestamp time.Time `json:"timestamp"`
}
AuditLog is a single entry in the audit trail.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the VaultRun API client.
func (*Client) AddOrgMember ¶
func (c *Client) AddOrgMember(ctx context.Context, orgID, principal, role string) (*OrgMember, error)
AddOrgMember adds (or updates) a member in an org. Role must be one of "viewer", "executor", or "admin". Requires master key or org admin.
func (*Client) CreateKey ¶
func (c *Client) CreateKey(ctx context.Context, opts CreateKeyOptions) (*CreatedKey, error)
CreateKey creates a new API key. The plaintext key is returned in CreatedKey.Key and will never be retrievable again.
func (*Client) CreateOrg ¶
CreateOrg creates a new organization. Slug is auto-generated from name if omitted. Requires master key.
func (*Client) CreateSession ¶
CreateSession creates a new sandbox session.
func (*Client) CreateSnapshot ¶
CreateSnapshot creates a snapshot archive of a session's workspace.
func (*Client) DeleteArtifact ¶
DeleteArtifact deletes a shared artifact.
func (*Client) DeleteFile ¶
DeleteFile removes a file from a session workspace.
func (*Client) DeleteSession ¶
DeleteSession stops and removes a session.
func (*Client) DeleteSnapshot ¶
DeleteSnapshot deletes a snapshot.
func (*Client) DownloadArtifact ¶
DownloadArtifact streams an artifact file and returns the raw bytes.
func (*Client) DownloadFile ¶
func (c *Client) DownloadFile(ctx context.Context, sessionID, remotePath string) (io.ReadCloser, error)
DownloadFile downloads a single file from a session workspace.
func (*Client) DownloadSnapshot ¶
DownloadSnapshot streams a snapshot archive and returns the raw bytes.
func (*Client) DownloadWorkspace ¶
DownloadWorkspace downloads the entire workspace as a ZIP archive. The caller is responsible for closing the returned ReadCloser.
func (*Client) GetSession ¶
GetSession retrieves a session by ID.
func (*Client) GetSessionLogs ¶
GetSessionLogs returns the last n lines of container logs for the session. Pass 0 to use the server default.
func (*Client) GetSessionStats ¶
GetSessionStats returns live CPU/memory usage for the given session.
func (*Client) ListArtifacts ¶
func (c *Client) ListArtifacts(ctx context.Context) ([]*SharedArtifact, error)
ListArtifacts returns shared artifacts visible to the caller.
func (*Client) ListAuditLogs ¶
func (c *Client) ListAuditLogs(ctx context.Context, opts ...ListAuditLogsOptions) ([]*AuditLog, error)
ListAuditLogs returns audit log entries for the current actor. Master key holders receive all actors' entries; regular keys receive only their own. Use opts.SessionID to narrow results to a specific session.
func (*Client) ListImages ¶
ListImages returns Docker images available on the host.
func (*Client) ListOrgMembers ¶
ListOrgMembers lists all members of an org. Accessible to org members.
func (*Client) ListOrgSessions ¶
ListOrgSessions returns active sessions belonging to the org. The caller must be an org member; results are filtered by the server.
func (*Client) ListOrgs ¶
func (c *Client) ListOrgs(ctx context.Context) ([]*Organization, error)
ListOrgs returns all organizations. Requires master key.
func (*Client) ListSessions ¶
ListSessions returns active sessions visible to the authenticated caller.
func (*Client) ListSnapshots ¶
ListSnapshots lists all snapshots for a session.
func (*Client) PromoteArtifact ¶
func (c *Client) PromoteArtifact(ctx context.Context, sessionID, path string, name ...string) (*SharedArtifact, error)
PromoteArtifact promotes a session file to the shared artifact registry. path is the file path inside the session workspace.
func (*Client) RemoveOrgMember ¶
RemoveOrgMember removes a principal from an org. Requires master key or org admin.
func (*Client) RunAsync ¶
func (c *Client) RunAsync(ctx context.Context, sessionID string, opts AsyncRunOptions) (*AsyncRunResult, error)
RunAsync submits a command for non-blocking execution. It returns immediately with the pending run's ID. Poll GetRun to check for completion, or supply a CallbackURL to receive a webhook when done.
func (*Client) Stream ¶
func (c *Client) Stream(ctx context.Context, sessionID string, opts RunOptions, stdout, stderr io.Writer) (*StreamEvent, error)
Stream executes a command via SSE, writing stdout/stderr chunks to the provided writers as they arrive. Returns the final StreamEvent (type="done"). Pass nil for stdout or stderr to discard that stream.
type CreateKeyOptions ¶
CreateKeyOptions configures a new API key.
type CreateSessionOptions ¶
type CreateSessionOptions struct {
Name string
Image string
NetworkEnabled bool
CPULimit float64
MemoryLimitMB int
TimeoutSeconds int
Labels map[string]string
// AllowedHosts limits outbound traffic to these hostnames or CIDRs. It needs
// NetworkEnabled; the API rejects the combination otherwise.
AllowedHosts []string
}
CreateSessionOptions configures a new session.
type CreatedKey ¶
CreatedKey is returned once on key creation — it includes the plaintext key.
type File ¶
type File struct {
ID string `json:"id"`
SessionID string `json:"session_id"`
Path string `json:"path"`
SizeBytes int64 `json:"size_bytes"`
ContentType string `json:"content_type"`
CreatedAt time.Time `json:"created_at"`
}
File represents a file in a session workspace.
type Image ¶
type Image struct {
ID string `json:"id"`
Tags []string `json:"tags"`
SizeBytes int64 `json:"size_bytes"`
CreatedAt string `json:"created_at"`
}
Image represents a Docker image available on the host.
type ListAuditLogsOptions ¶
type ListAuditLogsOptions struct {
// SessionID restricts entries to a single session.
// Non-master callers may only query sessions they own.
SessionID string
Limit int // 0 uses the server default (50)
Offset int
}
ListAuditLogsOptions filters the audit log query.
type ListSessionsOptions ¶
type ListSessionsOptions struct {
// LabelKey and LabelValue filter by a specific label (both must be set).
LabelKey string
LabelValue string
}
ListSessionsOptions filters the session list.
type OrgMember ¶
type OrgMember struct {
OrgID string `json:"org_id"`
Principal string `json:"principal"`
Role string `json:"role"` // "viewer" | "executor" | "admin"
CreatedAt time.Time `json:"created_at"`
}
OrgMember represents a principal's membership in an org.
type Organization ¶
type Organization struct {
ID string `json:"id"`
Name string `json:"name"`
Slug string `json:"slug"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
Organization represents a VaultRun team/org.
type PullStatus ¶
type PullStatus struct {
Image string `json:"image"`
Status string `json:"status"`
Message string `json:"message"`
}
PullStatus is returned after requesting an image pull.
type Run ¶
type Run struct {
ID string `json:"id"`
SessionID string `json:"session_id"`
Command string `json:"command"`
Args []string `json:"args"`
Status string `json:"status"`
ExitCode *int `json:"exit_code,omitempty"`
Stdout *string `json:"stdout,omitempty"`
Stderr *string `json:"stderr,omitempty"`
DurationMS *int64 `json:"duration_ms,omitempty"`
TimeoutSeconds int `json:"timeout_seconds"`
OutputTruncated bool `json:"output_truncated,omitempty"`
CreatedAt time.Time `json:"created_at"`
StartedAt *time.Time `json:"started_at,omitempty"`
FinishedAt *time.Time `json:"finished_at,omitempty"`
}
Run represents a command execution result.
type RunOptions ¶
type RunOptions struct {
Command string
Args []string
Env map[string]string
WorkingDir string
TimeoutSeconds int
// Secrets names secrets to inject as environment variables; the API key
// must be allowed to use them.
Secrets []string
}
RunOptions configures a command execution.
type Session ¶
type Session struct {
ID string `json:"id"`
Name *string `json:"name,omitempty"`
Image string `json:"image"`
Status string `json:"status"`
ContainerID *string `json:"container_id,omitempty"`
NetworkEnabled bool `json:"network_enabled"`
CPULimit float64 `json:"cpu_limit"`
MemoryLimitMB int `json:"memory_limit_mb"`
TimeoutSeconds int `json:"timeout_seconds"`
Labels map[string]string `json:"labels,omitempty"`
CreatedAt time.Time `json:"created_at"`
StoppedAt *time.Time `json:"stopped_at,omitempty"`
AllowedHosts []string `json:"allowed_hosts,omitempty"`
}
Session represents a VaultRun sandbox session.
type SessionStats ¶
type SessionStats struct {
SessionID string `json:"session_id"`
CPUPercent float64 `json:"cpu_percent"`
MemoryUsageMB float64 `json:"memory_usage_mb"`
MemoryLimitMB int `json:"memory_limit_mb"`
PIDs int `json:"pids"`
}
SessionStats holds live resource usage for a running session.
type SharedArtifact ¶
type SharedArtifact struct {
}
SharedArtifact represents a file promoted to the shared artifact registry.
type Snapshot ¶
type Snapshot struct {
ID string `json:"id"`
SessionID string `json:"session_id"`
Name string `json:"name"`
CreatedBy string `json:"created_by"`
SizeBytes int64 `json:"size_bytes"`
CreatedAt time.Time `json:"created_at"`
}
Snapshot represents a compressed workspace archive.
type StreamEvent ¶
type StreamEvent struct {
Type string `json:"type"` // "stdout", "stderr", or "done"
Data string `json:"data"` // populated for stdout/stderr
RunID string `json:"run_id"` // populated in done
Status string `json:"status"` // populated in done
ExitCode *int `json:"exit_code"` // populated in done
DurationMS *int64 `json:"duration_ms"` // populated in done
Error string `json:"error"` // populated on error
}
StreamEvent is a single SSE event from the run/stream endpoint.