Documentation
¶
Overview ¶
Package write is the surface the mutating commands of manager tools share: naming the Unit to write to, saying whether this is a dry run, and reporting what a function invocation did -- including, path by path, what it changed or on a dry run would change, so a reader can judge a change before committing it.
It is deliberately the reporting half only. Which function to run, and with what arguments, is what each tool is about; how the outcome is rendered is not, and tools rendering it each their own way would be that many things to keep in step for no gain.
Index ¶
- func Change(changeDesc string, dryRun bool) cubapi.Change
- func DryRunSuffix(dryRun bool) string
- func ReleaseNote(space string) string
- func ReportMutations(cmd *cobra.Command, command, space string, dryRun bool, output string, ...) error
- func WriteDiffs(w io.Writer, command string, rep Report)
- func WriteUnitDiffs(w io.Writer, command string, diffs []UnitDiff)
- func WriteWithheld(w io.Writer, rep Report)
- type CommitFlags
- type Outcome
- type Report
- type UnitDiff
- type UnitRef
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Change ¶
Change turns dry-run/description into a cubapi.Change. An empty description is what makes a call a dry run, so a dry run is spelled by not describing one. Either way it asks for each Unit's diff, which ReportMutations shows.
func DryRunSuffix ¶
DryRunSuffix is the reminder a dry run's summary line ends with.
func ReleaseNote ¶ added in v0.10.4
ReleaseNote is what a committed write's report ends with, for a command with a report of its own as for ReportMutations: the Units changed, and none of it reaches a Target until the Space is released. A write command edits configuration; releasing it is a separate, deliberate step.
func ReportMutations ¶
func ReportMutations(cmd *cobra.Command, command, space string, dryRun bool, output string, results ...*cubapi.Result) error
ReportMutations renders one or more cubapi function Results as JSON or a table, aggregated per Unit -- so a command that runs several functions over the same Unit shows a single row, mutated if any function changed it. On a dry run the mutated count is what would change; on a commit it is what did. The table is followed by each changed Unit's diff, when the Change asked for one.
func WriteDiffs ¶
WriteDiffs writes what each changed Unit in rep was changed by, or on a dry run would be.
func WriteUnitDiffs ¶
WriteUnitDiffs writes each diff under a header naming the Unit and the command, colored only for a terminal.
func WriteWithheld ¶ added in v0.10.14
WriteWithheld writes, per Unit, what rep's change did not write, or on a dry run would not, and the --clearance that would let it. A write the guards held back is otherwise easy to read as complete: the Unit still counts as changed when the rest of the change was written.
Types ¶
type CommitFlags ¶ added in v0.10.14
type CommitFlags struct {
cliutil.CommitFlags
Guards []string
InheritedGuards []string
Clearance []string
// ChangeSet is the ChangeSet to make the change in, by space/slug or UUID.
ChangeSet string
}
CommitFlags are the flags every mutating command of a manager tool takes: --commit and --change-desc, which make it write; the guards it records on what it writes and the clearance it writes with, as cub's own writes take them; and the ChangeSet to make it in.
A value a tool writes into a Unit whose configuration is uploaded from somewhere else, such as a rendered chart, is lost the next time it is uploaded unless it is guarded, as in --guard Override=External; and a Unit that is already guarded is written only where --clearance covers its guards.
func (*CommitFlags) Bind ¶ added in v0.10.14
func (c *CommitFlags) Bind(cmd *cobra.Command)
Bind registers --commit, --change-desc, --guard, --inherited-guard, --changeset and --clearance on cmd.
func (CommitFlags) Change ¶ added in v0.10.14
func (c CommitFlags) Change(summary string) (cubapi.Change, error)
Change validates the flags and returns the change they describe: a dry run unless --commit, asking for each Unit's diff either way, as Change does, with the guards to record and the clearance to write with. summary is suggested when --change-desc is missing.
The clearance includes each guard being recorded, because a change has to be cleared for the guards on a path before overwriting it: without that, running a command a second time would withhold the very paths the first run guarded.
type Outcome ¶
type Outcome struct {
// Space is where the Unit lives. A slug is unique only within a Space, so a
// fleet-wide report has to carry it to name the Unit at all.
Space string `json:"space,omitempty"`
Unit string `json:"unit"`
Mutated bool `json:"mutated"`
Error string `json:"error,omitempty"`
// Diffs are what each contributing invocation did to the Unit, or on a dry
// run would do, in the order they ran. An invocation that changed nothing
// adds none.
Diffs []goclientnew.ConfigDiff `json:"diffs,omitempty"`
// Withheld is what the change did not write to the Unit, or on a dry run would not, with
// the reason: above all each path whose guards the change's clearance did not cover. The
// rest of the change is written, so a Unit can be both mutated and withheld from.
Withheld []goclientnew.MutationConflict `json:"withheld,omitempty"`
// contains filtered or unexported fields
}
Outcome is one Unit's aggregated result from one or more mutating function invocations.
type Report ¶
type Report struct {
Command string `json:"command"`
Space string `json:"space,omitempty"`
DryRun bool `json:"dryRun"`
Outcomes []Outcome `json:"outcomes"`
Mutated int `json:"mutated"`
Committed int `json:"committed"`
}
Report is the JSON/table result of a write command.
func Summarize ¶
Summarize aggregates results per Unit without rendering them, for a command that folds the outcome into a report of its own.
Aggregation is by UnitID, not by slug. A slug is unique only within a Space, and a bulk edit spans Spaces: keying by slug silently folds every `app` in the fleet into one row, so the count an operator reads off a dry run is the number of distinct names rather than the number of Units about to change.
type UnitDiff ¶
type UnitDiff struct {
Space string `json:"space,omitempty"`
Unit string `json:"unit"`
Diff goclientnew.ConfigDiff `json:"diff"`
}
UnitDiff is what a change did to one Unit, or on a dry run would do. A command with a report of its own carries these in it, from Diffs.
type UnitRef ¶
type UnitRef struct {
SpaceID goclientnew.UUID
SpaceSlug string
UnitSlug string
}
UnitRef is a resolved <space>/<unit> target for a single-Unit write command.
func ParseUnitRef ¶
ParseUnitRef parses a "<space>/<unit>" argument and resolves the Space to its ID against the server.
A Unit slug carrying a quote or a backslash is rejected here rather than at the selector, where the error would name a filter expression the operator never wrote.
Source Files