Files
archipelago/connectors/incus/incus.go
T

420 lines
14 KiB
Go

package main
import (
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json/jsontext"
json "encoding/json/v2"
"errors"
"fmt"
"maps"
"net/url"
"path"
"regexp"
"slices"
"strings"
"time"
"github.com/samcharles93/archipelago/sdk/connector"
connectorv1 "github.com/samcharles93/archipelago/sdk/connector/v1"
)
const (
actionSnapshot = "snapshot_container"
actionDeleteCache = "delete_cache"
lookupList = "list_containers"
lookupCommand = "run_command"
targetKind = "container"
)
// Container is one container the connector may act on, from the containers
// setting. A container not listed is never touched.
type Container struct {
Project string `json:"project"`
Name string `json:"name"`
// Environment overrides default_environment for this container.
Environment string `json:"environment"`
// CachePaths are the absolute directories delete_cache may remove
// something under. The directories themselves are never removed.
CachePaths []string `json:"cache_paths"`
}
// Command is one entry of the read-only allow-list: a name the agent asks
// for and the fixed argv it runs. The agent supplies no argument.
type Command struct {
Name string `json:"name"`
Argv []string `json:"argv"`
}
var validName = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$`)
type incusConnector struct {
api incusAPI
containers map[string]Container
projects []string
commands map[string]Command
defaultEnv string
snapshotAge time.Duration
now func() time.Time
}
func newIncus(cfg connector.Config) (*incusConnector, error) {
u, err := url.Parse(cfg.Settings["endpoint"])
if err != nil || u.Scheme != "https" || u.Host == "" {
return nil, fmt.Errorf("endpoint %q must be an https URL", cfg.Settings["endpoint"])
}
serverCert := cfg.Settings["server_certificate"]
clientCert, clientKey := cfg.Secrets["client.certificate"], cfg.Secrets["client.key"]
if serverCert == "" {
return nil, errors.New("server_certificate must pin the server's certificate")
}
if clientCert == "" || clientKey == "" {
return nil, errors.New("the client credential slot needs a certificate and a key")
}
return configure(cfg.Settings, newRemote(u.String(), serverCert, clientCert, clientKey))
}
// configure validates the settings that decide where the connector may act.
func configure(settings map[string]string, api incusAPI) (*incusConnector, error) {
var containers []Container
var commands []Command
if err := json.Unmarshal([]byte(settings["containers"]), &containers, json.RejectUnknownMembers(true)); err != nil {
return nil, fmt.Errorf("containers setting: %w", err)
}
if s := settings["commands"]; s != "" {
if err := json.Unmarshal([]byte(s), &commands, json.RejectUnknownMembers(true)); err != nil {
return nil, fmt.Errorf("commands setting: %w", err)
}
}
c := &incusConnector{
api: api, containers: map[string]Container{}, commands: map[string]Command{},
defaultEnv: settings["default_environment"], now: time.Now,
}
if w := settings["snapshot_window"]; w != "" {
d, err := time.ParseDuration(w)
if err != nil || d <= 0 {
return nil, fmt.Errorf("snapshot_window %q must be a positive duration", w)
}
c.snapshotAge = d
}
for _, ct := range containers {
if !validName.MatchString(ct.Project) || !validName.MatchString(ct.Name) {
return nil, fmt.Errorf("container %q in project %q needs valid names", ct.Name, ct.Project)
}
for i, p := range ct.CachePaths {
if !path.IsAbs(p) || path.Clean(p) == "/" || hasControl(p) {
return nil, fmt.Errorf("container %q: cache path %q must be absolute and not the root", ct.Name, p)
}
ct.CachePaths[i] = path.Clean(p)
}
c.containers[key(ct.Project, ct.Name)] = ct
if !slices.Contains(c.projects, ct.Project) {
c.projects = append(c.projects, ct.Project)
}
}
slices.Sort(c.projects)
for _, cmd := range commands {
if !validName.MatchString(cmd.Name) || len(cmd.Argv) == 0 || !path.IsAbs(cmd.Argv[0]) {
return nil, fmt.Errorf("command %q needs a name and an argv starting with an absolute program path", cmd.Name)
}
c.commands[cmd.Name] = cmd
}
return c, nil
}
func key(project, name string) string { return project + "/" + name }
func hasControl(s string) bool {
return strings.ContainsFunc(s, func(r rune) bool { return r < 0x20 || r == 0x7f })
}
func (c *incusConnector) Describe() connector.Description {
cmds := slices.Sorted(maps.Keys(c.commands))
cmdSchema, _ := json.Marshal(map[string]any{
"type": "object", "additionalProperties": false, "required": []string{"project", "container", "command"},
"properties": map[string]any{
"project": map[string]any{"type": "string"}, "container": map[string]any{"type": "string"},
"command": map[string]any{"type": "string", "enum": cmds, "description": "The name of an allowed read-only command."},
},
})
return connector.Description{
Lookups: []*connectorv1.LookupType{
{
Name: lookupList, Description: "Containers in a project with their state.",
InputSchema: []byte(`{"type":"object","required":["project"],"additionalProperties":false,"properties":{"project":{"type":"string"}}}`),
},
{
Name: lookupCommand, Description: "Run an allowed read-only command inside a container and return its exit code and output.",
InputSchema: cmdSchema,
},
},
Actions: []*connectorv1.ActionType{
{
Name: actionSnapshot, Description: "Take a snapshot of a container.",
InputSchema: []byte(`{"type":"object","required":["project","container"],"additionalProperties":false,"properties":{"project":{"type":"string"},"container":{"type":"string"}}}`),
Effect: &connectorv1.Effect{
Reversibility: connectorv1.Reversibility_REVERSIBILITY_UNDONE_AUTOMATICALLY,
Summary: "Takes a snapshot of the container; the snapshot can be deleted to undo it.",
},
Idempotent: true,
},
{
Name: actionDeleteCache, Description: "Delete a cache directory or file inside a container, under one of the container's allowed cache paths.",
InputSchema: []byte(`{"type":"object","required":["project","container","path"],"additionalProperties":false,"properties":{"project":{"type":"string"},"container":{"type":"string"},"path":{"type":"string","description":"An absolute path under an allowed cache path."}}}`),
Effect: &connectorv1.Effect{
Reversibility: connectorv1.Reversibility_REVERSIBILITY_IRREVERSIBLE,
Summary: "Deletes the path and everything under it inside the container; recoverable only from a recent snapshot.",
},
Idempotent: true,
},
},
}
}
type ref struct {
Project string `json:"project"`
Container string `json:"container"`
}
type deleteInput struct {
ref
Path string `json:"path"`
}
type commandInput struct {
ref
Command string `json:"command"`
}
func decode(raw jsontext.Value, in any) error {
if err := json.Unmarshal(raw, in, json.RejectUnknownMembers(true)); err != nil {
return fmt.Errorf("input: %w", err)
}
return nil
}
func (c *incusConnector) container(r ref) (Container, error) {
ct, ok := c.containers[key(r.Project, r.Container)]
if !ok {
return Container{}, fmt.Errorf("container %q in project %q isn't configured", r.Container, r.Project)
}
return ct, nil
}
func (c *incusConnector) Lookup(ctx context.Context, name string, raw jsontext.Value) (jsontext.Value, bool, error) {
switch name {
case lookupList:
var in struct {
Project string `json:"project"`
}
if err := decode(raw, &in); err != nil {
return nil, false, err
}
if !slices.Contains(c.projects, in.Project) {
return nil, false, fmt.Errorf("project %q isn't configured", in.Project)
}
list, err := c.api.Instances(ctx, in.Project)
if err != nil {
return nil, false, fmt.Errorf("list containers: %w", err)
}
type item struct {
Name string `json:"name"`
Status string `json:"status"`
}
items := []item{}
for _, i := range list {
if _, ok := c.containers[key(in.Project, i.Name)]; ok {
items = append(items, item(i))
}
}
out, err := json.Marshal(map[string]any{"containers": items})
return out, true, err
case lookupCommand:
var in commandInput
if err := decode(raw, &in); err != nil {
return nil, false, err
}
if _, err := c.container(in.ref); err != nil {
return nil, false, err
}
cmd, ok := c.commands[in.Command]
if !ok {
return nil, false, fmt.Errorf("command %q isn't in the allow-list", in.Command)
}
res, err := c.api.Exec(ctx, in.Project, in.Container, slices.Clone(cmd.Argv))
if err != nil {
return nil, false, fmt.Errorf("run %s in %s: %w", in.Command, key(in.Project, in.Container), err)
}
out, err := json.Marshal(map[string]any{"exit_code": res.Exit, "output": res.Stdout})
return out, true, err
}
return nil, false, fmt.Errorf("no lookup named %q", name)
}
// confine returns the cleaned path when it lies strictly under one of roots.
func confine(p string, roots []string) (string, error) {
if !path.IsAbs(p) || hasControl(p) {
return "", fmt.Errorf("path %q must be absolute with no control characters", p)
}
clean := path.Clean(p)
for _, root := range roots {
if strings.HasPrefix(clean, root+"/") {
return clean, nil
}
}
return "", fmt.Errorf("path %q is outside the container's cache paths %v", clean, roots)
}
func (c *incusConnector) environment(ct Container) string {
if ct.Environment != "" {
return ct.Environment
}
return c.defaultEnv
}
func (c *incusConnector) Resolve(ctx context.Context, action string, raw jsontext.Value) (*connectorv1.ResolveResponse, error) {
var r ref
var p string
switch action {
case actionSnapshot:
if err := decode(raw, &r); err != nil {
return nil, err
}
case actionDeleteCache:
var in deleteInput
if err := decode(raw, &in); err != nil {
return nil, err
}
r, p = in.ref, in.Path
default:
return nil, fmt.Errorf("no action named %q", action)
}
ct, err := c.container(r)
if err != nil {
return nil, err
}
resp := &connectorv1.ResolveResponse{
Target: &connectorv1.Target{Kind: targetKind, Id: key(r.Project, r.Container), Environment: c.environment(ct)},
}
switch action {
case actionSnapshot:
resp.Effect = &connectorv1.Effect{
Reversibility: connectorv1.Reversibility_REVERSIBILITY_UNDONE_AUTOMATICALLY,
Summary: "Takes a snapshot of the container; the snapshot can be deleted to undo it.",
}
default:
if _, err := confine(p, ct.CachePaths); err != nil {
return nil, err
}
resp.Effect = &connectorv1.Effect{
Reversibility: c.deleteReversibility(ctx, r),
Summary: "Deletes " + path.Clean(p) + " and everything under it inside the container.",
}
}
return resp, nil
}
// deleteReversibility is recoverable when a snapshot taken within the window
// exists, and irreversible otherwise, including when that can't be read.
func (c *incusConnector) deleteReversibility(ctx context.Context, r ref) connectorv1.Reversibility {
if c.snapshotAge > 0 {
snaps, err := c.api.Snapshots(ctx, r.Project, r.Container)
if err == nil && slices.ContainsFunc(snaps, func(s snapshot) bool { return c.now().Sub(s.Created) <= c.snapshotAge }) {
return connectorv1.Reversibility_REVERSIBILITY_RECOVERABLE
}
}
return connectorv1.Reversibility_REVERSIBILITY_IRREVERSIBLE
}
func (c *incusConnector) Invoke(ctx context.Context, action string, raw jsontext.Value, idem string) (jsontext.Value, bool, error) {
if idem == "" {
return nil, false, errors.New("an idempotency key is required")
}
switch action {
case actionSnapshot:
var r ref
if err := decode(raw, &r); err != nil {
return nil, false, err
}
if _, err := c.container(r); err != nil {
return nil, false, err
}
return c.snapshot(ctx, r, idem)
case actionDeleteCache:
var in deleteInput
if err := decode(raw, &in); err != nil {
return nil, false, err
}
ct, err := c.container(in.ref)
if err != nil {
return nil, false, err
}
return c.deleteCache(ctx, ct, in.Path)
}
return nil, false, fmt.Errorf("no action named %q", action)
}
// snapshotName derives the snapshot's name from the idempotency key, so a
// retry finds the snapshot instead of taking another.
func snapshotName(idem string) string {
sum := sha256.Sum256([]byte(idem))
return "archie-" + hex.EncodeToString(sum[:8])
}
func (c *incusConnector) hasSnapshot(ctx context.Context, r ref, name string) (bool, error) {
snaps, err := c.api.Snapshots(ctx, r.Project, r.Container)
if err != nil {
return false, err
}
return slices.ContainsFunc(snaps, func(s snapshot) bool { return s.Name == name }), nil
}
func (c *incusConnector) snapshot(ctx context.Context, r ref, idem string) (jsontext.Value, bool, error) {
name := snapshotName(idem)
have, err := c.hasSnapshot(ctx, r, name)
if err != nil {
return nil, true, fmt.Errorf("list snapshots: %w", err)
}
if !have {
if err := c.api.Snapshot(ctx, r.Project, r.Container, name); err != nil {
// The create may have landed before the error.
if have, lerr := c.hasSnapshot(ctx, r, name); lerr != nil || !have {
return nil, true, fmt.Errorf("snapshot %s: %w", key(r.Project, r.Container), err)
}
}
}
out, err := json.Marshal(map[string]any{"snapshot": name})
return out, false, err
}
// deleteCache resolves symlinks inside the container before removing, so a
// link under an allowed path can't lead outside it. Removing a path that is
// already gone succeeds, which makes a retry safe.
func (c *incusConnector) deleteCache(ctx context.Context, ct Container, p string) (jsontext.Value, bool, error) {
if _, err := confine(p, ct.CachePaths); err != nil {
return nil, false, err
}
id := key(ct.Project, ct.Name)
res, err := c.api.Exec(ctx, ct.Project, ct.Name, []string{"realpath", "-m", "--", path.Clean(p)})
if err != nil {
return nil, true, fmt.Errorf("resolve %s in %s: %w", p, id, err)
}
if res.Exit != 0 {
return nil, false, fmt.Errorf("resolve %s in %s: exit %d", p, id, res.Exit)
}
real, err := confine(strings.TrimSpace(res.Stdout), ct.CachePaths)
if err != nil {
return nil, false, fmt.Errorf("%s resolves outside the cache paths: %w", p, err)
}
res, err = c.api.Exec(ctx, ct.Project, ct.Name, []string{"rm", "-rf", "--one-file-system", "--", real})
if err != nil {
return nil, true, fmt.Errorf("remove %s in %s: %w", real, id, err)
}
if res.Exit != 0 {
return nil, false, fmt.Errorf("remove %s in %s: exit %d", real, id, res.Exit)
}
out, err := json.Marshal(map[string]any{"deleted": real})
return out, false, err
}