action

type Action struct {
	Type string

	// Summary is what the approval screen says this will do, in plain words. It
	// may contain {name} to name a parameter.
	Summary string

	Params        []Param
	Reversibility Reversibility

	// UndoWhy explains the reversibility in plain words: "the file is copied
	// before editing", "deleted logs cannot be brought back", "the images can be
	// pulled again from your registry".
	UndoWhy string

	// Settle is how long to wait after the change before checking it worked. A
	// service restarted a moment ago is not yet proof of anything.
	Settle time.Duration

	Variants []Variant
}

type ActionReport struct {
	Type          string        `json:"type"`
	Summary       string        `json:"summary"`
	Reversibility Reversibility `json:"reversibility"`
	UndoWhy       string        `json:"undo_why"`

	OK bool `json:"ok"`

	// Refused says, in plain words, why this action did not happen. Empty when
	// it did.
	Refused string `json:"refused,omitempty"`

	// Commands is never nil on the wire.
	//
	// A nil slice marshals to JSON null, and the screen flattens every action's
	// commands into one list to draw the terminal. flatMap over a null keeps the
	// null, so the list held one and the page crashed reading its `why`. Somebody
	// who clicked Solve got a blank screen and a stack trace.
	//
	// A refused action is a normal outcome. It must not be able to break the page
	// that exists to explain it. See emptyCommands.
	Commands []CommandRun `json:"commands"`

	// WouldRun is every command that would change this machine, written out as it
	// would be typed. Set by a dry run only; a real run reports what it did.
	//
	// It exists because a dry run runs its own steps — `cat` the file that would be
	// installed, ask the service what it believes — and those were the only commands
	// the report carried. The `install` that does the work appeared nowhere, so the
	// screen showed `cat …apt.update_package_lists=1.conf` and somebody approving
	// reasonably read that as the change. Reported from the UI.
	WouldRun []string `json:"would_run,omitempty"`

	// FreedBytes is what the dry run said would be freed, where the action frees
	// space. Zero for everything else.
	FreedBytes int64 `json:"freed_bytes,omitempty"`

	// DoItYourself is set when this action was refused because it is too dangerous
	// for us to carry out, and carries the way to do it by hand. Absent for every
	// other kind of refusal: explaining how to weaken a server is not help.
	DoItYourself *DoItYourself `json:"do_it_yourself,omitempty"`
}

type BackupKind string

type BackupPlan struct {
	Kind BackupKind

	// Target is the filesystem the archive would be written to, for
	// BackupArchiveFreed. It is the disk being freed, which is the whole problem.
	Target string

	// Freed matches the size a dry run says would be freed, so the space needed
	// can be measured rather than guessed. Required for BackupArchiveFreed.
	Freed *regexp.Regexp
}

type BackupReport struct {
	Asked bool  `json:"asked"`
	Taken bool  `json:"taken"`
	Needs int64 `json:"needs_bytes,omitempty"`
	Free  int64 `json:"free_bytes,omitempty"`

	// Why says in plain words what happened and, when a backup was skipped, the
	// numbers that decided it. Never skipped quietly.
	Why string `json:"why"`
}

type CheckID string

type CommandRun struct {
	Why      string `json:"why"`
	Display  string `json:"display"`
	Stdout   string `json:"stdout"`
	Stderr   string `json:"stderr"`
	ExitCode int    `json:"exit_code"`
	Millis   int64  `json:"duration_ms"`

	// Skipped is set when this step had nothing to do on this machine, and says
	// why. It is not a failure and not a success: the command never ran, because
	// the software it drives is not here.
	//
	// It is reported rather than quietly dropped. A person approving a plan has to
	// be able to see that a step they read was not part of the work.
	Skipped string `json:"skipped,omitempty"`

	// Advice is set by a step that refused a change as too dangerous, and carries
	// the way to make it by hand. The runner lifts it onto the action so the app
	// does not have to hunt for it among the commands.
	Advice *DoItYourself `json:"-"`
	// contains filtered or unexported fields
}

type Deps struct {
	// Exec runs a declared privileged command. Nothing else here can run
	// anything.
	Exec func(context.Context, privexec.ID, privexec.Values) (privexec.Result, error)

	// Installed reports whether a binary exists on this host, which is how a
	// variant is chosen.
	Installed func(binary string) bool

	// Applies reports whether a declared command has anything to do on this host,
	// and why not when it does not. Injected like Exec, so a test can decide the
	// answer instead of depending on what happens to be installed where the test
	// runs.
	//
	// Nil means everything applies. That keeps every existing caller and test
	// working, and the one place that matters — the real agent — sets it.
	Applies func(privexec.ID) (bool, string)

	// FreeBytes reports the space left on the filesystem holding path.
	FreeBytes func(path string) (int64, error)

	// SwitchedOff asks the machine whether its owner has turned actions off, and
	// why. It beats an approved job from the cloud.
	SwitchedOff func() (bool, string)

	// InboundPorts lists the ports of connections somebody is currently using to
	// reach this machine. That is how a firewall change can be stopped before it
	// locks its own operator out.
	InboundPorts func() ([]int, error)

	// Listening reports whether anything is accepting connections on a port.
	Listening func(port int) bool

	// Protected lists the services this machine's owner has said ghostpsy must
	// not touch. Their list beats an approved job.
	Protected func() ([]string, error)

	// SSHAccess counts how many accounts could still log in over SSH. It is what
	// stops a hardening change closing the last door.
	SSHAccess func(context.Context) (confedit.Access, error)

	// Accounts names the people with an account on this machine, so their names can
	// be covered in everything a command printed before any of it is sent.
	Accounts func() ([]string, error)

	Sleep func(context.Context, time.Duration) error
}

type DoItYourself struct {
	Risk       string `json:"risk"`
	CheckFirst string `json:"check_first"`
	Script     string `json:"script"`
}

type Job struct {
	Mode    string    `json:"mode"`
	Actions []Request `json:"actions"`

	// Backup is true when the person asked for one. It is a request, not an
	// instruction: whether one is possible is measured on the machine.
	Backup bool `json:"backup"`
}

type LedgerEntry struct {
	Type string `json:"type"`

	// CanPutBack is whether an undo is possible at all.
	CanPutBack bool `json:"can_put_back"`

	// PutBack is whether it actually was put back. Only ever true after a real
	// undo ran.
	PutBack bool `json:"put_back"`

	Why string `json:"why"`
}

type Param struct {
	Name string

	// Why says in plain words what may go here. It reaches the approval screen.
	Why string

	// Allow is the only shape accepted, anchored so it matches whole values.
	// Checked here, and checked again by privexec when the command is built.
	Allow *regexp.Regexp
}

type PhaseReport struct {
	OK       bool         `json:"ok"`
	Commands []CommandRun `json:"commands"`
}

type Report struct {
	Mode string `json:"mode"`

	OK bool `json:"ok"`

	// Refused says why nothing ran at all — the local switch, an empty job.
	Refused string `json:"refused,omitempty"`

	// PreviewID identifies this exact preview, on a dry run only. An approval
	// names it, so an approval given for an older preview is detectably old.
	PreviewID string `json:"preview_id,omitempty"`

	Actions []ActionReport `json:"actions"`
	Backup  BackupReport   `json:"backup"`
	Verify  *PhaseReport   `json:"verify,omitempty"`
	Undo    *UndoReport    `json:"undo,omitempty"`
}

type Request struct {
	Type   string            `json:"type"`
	Params map[string]string `json:"params,omitempty"`
}

type Reversibility string

type Step struct {
	// Why says what this step is for, in plain words. It is shown next to the
	// command in the output the customer reads.
	Why string

	Command privexec.ID
	Check   CheckID

	// Args gives the command's parameters their values. A value is either a
	// literal or {name}, naming one of the action's own parameters.
	Args map[string]string
}

type UndoReport struct {
	Ran      bool          `json:"ran"`
	Ledger   []LedgerEntry `json:"ledger"`
	Commands []CommandRun  `json:"commands,omitempty"`
}

type Variant struct {
	// Needs is the binary that must be installed for this variant to apply.
	// Empty means it applies anywhere.
	Needs string

	// DryRun changes nothing. It is required — see checkAction.
	DryRun []Step
	Run    []Step
	Verify []Step

	// Undo must be absent when the action says it cannot be undone. A rollback
	// step on an irreversible action is a button that lies.
	Undo []Step

	// Backup is how this variant would be backed up. It belongs here rather than
	// on the action because two ways of doing the same fix can differ: switching
	// on automatic updates edits a file on Debian and flips a timer on the RHEL
	// family, and only one of those has anything to copy.
	Backup BackupPlan
}