suite

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Nov 2, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package suite is the client for suite runner protocol v1 (KyQuickStart docs/superpowers/specs/2026-10-16-suite-runner-design.md, "Runner protocol v1"): HTTP/1.1 over the runner's Unix socket, JSON both ways, unknown fields refused.

Index

Constants

View Source 
const (
	// MaxRequestBytes is the protocol's request cap.
	MaxRequestBytes = 64 << 10
)

Variables

View Source 
var (
	// ErrUnreachable is a failed exchange: the runner may or may not have seen the request.
	ErrUnreachable = errors.New("suite runner unreachable")
	// ErrInvalidResponse is an answer outside the protocol.
	ErrInvalidResponse = errors.New("suite runner answered outside protocol v1")
	// ErrNotFound is a 404: the runner does not know the operation.
	ErrNotFound = errors.New("suite runner does not know the operation")
	// ErrUnsafeSocket is a socket directory another user could control.
	ErrUnsafeSocket = errors.New("suite runner socket directory is not private")
)
View Source 
var (
	Kinds  = []string{"install", "uninstall", "unmanage", "upgrade"}
	States = []string{"running", "succeeded", "failed", "unknown"}
)

Kinds and States are the protocol's closed vocabularies.

Functions

func CheckSocketPath 

func CheckSocketPath(socket string) error

CheckSocketPath refuses a path that could bind outside the directory checked at dial time.

Types

type App 

type App struct {
	Name       string  `json:"name"`
	Category   string  `json:"category"`
	Version    string  `json:"version"`
	Target     string  `json:"target"`
	State      string  `json:"state"`
	Health     *Health `json:"health"`
	LastResult *Result `json:"last_result"`
}

type Catalog 

type Catalog struct {
	ReleaseSet string       `json:"release_set"`
	Apps       []CatalogApp `json:"apps"`
}

type CatalogApp 

type CatalogApp struct {
	Name        string   `json:"name"`
	Description string   `json:"description"`
	Category    string   `json:"category"`
	Version     string   `json:"version"`
	DependsOn   []string `json:"depends_on"`
	Installed   bool     `json:"installed"`
	Upgrade     Upgrade  `json:"upgrade"`
}

type Client 

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

func New 

func New(socket string) *Client

New takes a path CheckSocketPath accepted.

func (*Client) Catalog 

func (c *Client) Catalog(ctx context.Context) (*Catalog, error)

func (*Client) Operation 

func (c *Client) Operation(ctx context.Context, id string) (*Operation, error)

func (*Client) Plan 

func (c *Client) Plan(ctx context.Context) (*Plan, error)

func (*Client) Start 

func (c *Client) Start(ctx context.Context, r Request) error

Start asks the runner to begin r. Repeating the same request starts nothing new.

func (*Client) Status 

func (c *Client) Status(ctx context.Context) (*Status, error)

type Error 

type Error struct {
	Status  int    `json:"-"`
	Code    string `json:"code"`
	Message string `json:"message"`
}

Error is the runner's refusal, or a failed operation's cause.

func (*Error) Error 

func (e *Error) Error() string

type Health 

type Health struct {
	OK      bool      `json:"ok"`
	Checked time.Time `json:"checked"`
}

type Operation 

type Operation struct {
	ID       string     `json:"id"`
	Kind     string     `json:"kind"`
	Apps     []string   `json:"apps"`
	Actor    string     `json:"actor"`
	State    string     `json:"state"`
	Started  time.Time  `json:"started"`
	Finished *time.Time `json:"finished"`
	Steps    []Step     `json:"steps"`
	Error    *Error     `json:"error"`
}

type Plan 

type Plan struct {
	Revision int64  `json:"revision"`
	Stack    string `json:"stack"`
}

type Request 

type Request struct {
	ID                  string   `json:"id"`
	Kind                string   `json:"kind"`
	Apps                []string `json:"apps"`
	Target              string   `json:"target,omitempty"`
	AcknowledgeNoBackup bool     `json:"acknowledge_no_backup"`
	Actor               string   `json:"actor"`
}

Request starts an operation. Target is sent only for install; Apps is always a list.

type Result 

type Result struct {
	Step   string    `json:"step"`
	Status string    `json:"status"`
	Time   time.Time `json:"time"`
}

type Runner 

type Runner struct {
	ReleaseSet   string `json:"release_set"`
	RunnerID     string `json:"runner_id"`
	PlanRevision int64  `json:"plan_revision"`
	PlanOwner    string `json:"plan_owner"`
}

type Status 

type Status struct {
	Runner    Runner   `json:"runner"`
	Operation *string  `json:"operation"`
	Targets   []Target `json:"targets"`
	Apps      []App    `json:"apps"`
}

type Step 

type Step struct {
	ID          string    `json:"id"`
	Status      string    `json:"status"`
	Time        time.Time `json:"time"`
	Diagnostics string    `json:"diagnostics"`
}

type Target 

type Target struct {
	Name string `json:"name"`
	Kind string `json:"kind"`
}

type Upgrade 

type Upgrade struct {
	MinFrom      string   `json:"min_from"`
	NoSkip       []string `json:"no_skip"`
	MigratesData bool     `json:"migrates_data"`
}

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.