diff --git a/README.md b/README.md index aab0bb6..14bcf47 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,32 @@ By default, Valar uses the default valarconfig file in `$HOME/.valar/config`. If VALAR_TOKEN=... valar build push --wait ``` +### Machine-readable output + +With `--json`, or `VALAR_OUTPUT=json`, every command prints its result as one JSON document on stdout. Lists are arrays of objects whose fields match the API's JSON. Logs (`service logs`, `build logs`, `build watch`, `batch logs`) are printed as one JSON object per line, progress goes to stderr, and an error is printed on stderr as: + +```json +{"error": {"kind": "notFound", "message": "no builds available"}} +``` + +```bash +valar service list --json | jq -r '.[].name' +``` + +### Exit codes + +| Code | Kind | Meaning | +|---|---|---| +| 0 | | Success | +| 1 | `failed` | The operation ran and failed, such as a build or deployment | +| 2 | `invalid` | Bad arguments, flags or configuration | +| 3 | `notFound` | Not found | +| 4 | `notAllowed` | Missing or rejected credentials or permissions | +| 5 | `conflict` | Conflict with the current state | +| 6 | `unavailable` | The server could not be reached or answered with an error | + +`valar build status` exits with 1 for any build that is not done. + ### Configuration #### Initialize configuration @@ -46,6 +72,14 @@ valar config init [--token token] [--project project] [--url url] [--name name] valar config view ``` +#### Print the JSON Schema of `.valar.yml` + +```bash +valar config schema +``` + +The schema is also checked in at [`schema/valar.yml.json`](schema/valar.yml.json), for editors. The CLI refuses a `.valar.yml` with keys the schema does not know, naming the key and its line. + #### Add an API endpoint ```bash diff --git a/cmd/batch.go b/cmd/batch.go index 8548348..31c8596 100644 --- a/cmd/batch.go +++ b/cmd/batch.go @@ -2,6 +2,7 @@ package cmd import ( "fmt" + "io" "os" "strconv" "strings" @@ -43,7 +44,7 @@ latest successful build is used.`, } env, err := parseBatchEnv(batchRunEnv) if err != nil { - return err + return withKind(kindInvalid, err) } exec, err := client.TriggerBatchExecution(cfg.Project(), cfg.Service(), &api.BatchExecutionRequest{ Build: batchRunBuild, @@ -53,12 +54,19 @@ latest successful build is used.`, if err != nil { return err } - fmt.Printf("Execution %s %s\n", exec.ID, colorize(exec.Status)) + if !outputJSON { + fmt.Printf("Execution %s %s\n", exec.ID, colorize(exec.Status)) + } if !batchRunFollow && !batchRunWait { - return nil + return result(exec, func(io.Writer) error { return nil }) } if batchRunFollow { - if err := followBatchOutput(client, cfg, exec.ID); err != nil { + // In JSON mode the output is progress, so it goes to stderr. + var out io.Writer = os.Stdout + if outputJSON { + out = os.Stderr + } + if err := followBatchOutput(client, cfg, exec.ID, out); err != nil { fmt.Fprintf(os.Stderr, "could not read execution output: %v\n", err) } } @@ -66,12 +74,17 @@ latest successful build is used.`, if err != nil { return err } - fmt.Printf("Execution %s %s (exit %d)\n", final.ID, colorize(final.Status), final.ExitCode) + if err := result(final, func(w io.Writer) error { + _, err := fmt.Fprintf(w, "Execution %s %s (exit %d)\n", final.ID, colorize(final.Status), final.ExitCode) + return err + }); err != nil { + return err + } if final.Status != "succeeded" { if final.Error != "" { - fmt.Fprintln(os.Stderr, final.Error) + return newError(kindFailed, "%s", final.Error) } - os.Exit(1) + return &cliError{kind: kindFailed, err: fmt.Errorf("execution %s %s", final.ID, final.Status), silent: true} } return nil }), @@ -89,7 +102,10 @@ latest successful build is used.`, if err != nil { return err } - tw := tabwriter.NewWriter(os.Stdout, 0, 0, 1, ' ', 0) + if outputJSON { + return writeJSON(stdout, execs) + } + tw := tabwriter.NewWriter(stdout, 0, 0, 1, ' ', 0) fmt.Fprintln(tw, "ID\tSTATUS\tEXIT\tBUILD\tCREATED\tNOTE") for _, exec := range execs { fmt.Fprintln(tw, strings.Join([]string{ @@ -118,7 +134,10 @@ latest successful build is used.`, if err != nil { return err } - tw := tabwriter.NewWriter(os.Stdout, 0, 0, 2, ' ', 0) + if outputJSON { + return writeJSON(stdout, exec) + } + tw := tabwriter.NewWriter(stdout, 0, 0, 2, ' ', 0) fmt.Fprintf(tw, "ID:\t%s\n", exec.ID) fmt.Fprintf(tw, "Status:\t%s\n", colorize(exec.Status)) fmt.Fprintf(tw, "Exit code:\t%d\n", exec.ExitCode) @@ -158,11 +177,16 @@ latest successful build is used.`, if err != nil { return err } + w, flush := logOutput() if batchLogsFollow { - return followBatchOutput(client, cfg, args[0]) + err = followBatchOutput(client, cfg, args[0], w) + } else { + _, err = client.ReadBatchExecutionLogs(cfg.Project(), cfg.Service(), args[0], 0, w) } - _, err = client.ReadBatchExecutionLogs(cfg.Project(), cfg.Service(), args[0], 0, os.Stdout) - return err + if err != nil { + return err + } + return flush() }), } @@ -178,8 +202,13 @@ latest successful build is used.`, if err := client.CancelBatchExecution(cfg.Project(), cfg.Service(), args[0]); err != nil { return err } - fmt.Printf("Execution %s cancelled\n", args[0]) - return nil + return result(struct { + ID string `json:"id"` + Cancelled bool `json:"cancelled"` + }{args[0], true}, func(w io.Writer) error { + _, err := fmt.Fprintf(w, "Execution %s cancelled\n", args[0]) + return err + }) }), } @@ -223,7 +252,10 @@ latest successful build is used.`, return err } } - tw := tabwriter.NewWriter(os.Stdout, 0, 0, 2, ' ', 0) + if outputJSON { + return writeJSON(stdout, current) + } + tw := tabwriter.NewWriter(stdout, 0, 0, 2, ' ', 0) fmt.Fprintf(tw, "Max parallelism:\t%s\n", zeroAsDefault(current.MaxParallelism, "1")) fmt.Fprintf(tw, "Timeout:\t%s\n", zeroAsDefault(current.TimeoutSeconds, "3600 (platform default)")) fmt.Fprintf(tw, "Weight:\t%s\n", zeroAsDefault(current.Weight, "1 (platform default)")) @@ -327,7 +359,7 @@ func awaitBatchCompletion(client *api.Client, cfg config.ServiceConfig, id strin // server never closes a followed batch log, so a follower cannot tell when the // execution is done and simply hangs -- which it did. Polling puts the // termination condition where the answer actually lives: the execution's status. -func followBatchOutput(client *api.Client, cfg config.ServiceConfig, id string) error { +func followBatchOutput(client *api.Client, cfg config.ServiceConfig, id string, w io.Writer) error { offset := 0 for { exec, err := client.InspectBatchExecution(cfg.Project(), cfg.Service(), id) @@ -337,7 +369,7 @@ func followBatchOutput(client *api.Client, cfg config.ServiceConfig, id string) // A queued execution has no log yet, and asking for one is an error // rather than an empty read. if exec.Status != "pending" { - n, err := client.ReadBatchExecutionLogs(cfg.Project(), cfg.Service(), id, offset, os.Stdout) + n, err := client.ReadBatchExecutionLogs(cfg.Project(), cfg.Service(), id, offset, w) offset += n if err != nil && !isTerminalBatchStatus(exec.Status) { // Transient while the container is still coming up. @@ -350,7 +382,7 @@ func followBatchOutput(client *api.Client, cfg config.ServiceConfig, id string) if isTerminalBatchStatus(exec.Status) { // The status was read before the log, so anything written between // the two reads is still outstanding. - n, err := client.ReadBatchExecutionLogs(cfg.Project(), cfg.Service(), id, offset, os.Stdout) + n, err := client.ReadBatchExecutionLogs(cfg.Project(), cfg.Service(), id, offset, w) offset += n if err != nil { return err diff --git a/cmd/builds.go b/cmd/builds.go index 1d32c01..09413f5 100644 --- a/cmd/builds.go +++ b/cmd/builds.go @@ -32,7 +32,7 @@ func validateServiceKind(kind string) error { case "", "function", "batch": return nil default: - return fmt.Errorf("unknown service kind %q, want \"function\" or \"batch\"", kind) + return newError(kindInvalid, "unknown service kind %q, want \"function\" or \"batch\"", kind) } } @@ -78,7 +78,13 @@ var buildAbortCmd = &cobra.Command{ if len(args) < 1 { args = append(args, "") } - return client.AbortBuild(cfg.Project(), cfg.Service(), args[0]) + if err := client.AbortBuild(cfg.Project(), cfg.Service(), args[0]); err != nil { + return err + } + return result(struct { + Build string `json:"build"` + Aborted bool `json:"aborted"` + }{args[0], true}, func(io.Writer) error { return nil }) }), } @@ -151,21 +157,18 @@ var buildLogsCmd = &cobra.Command{ if len(args) > 0 { prefix = args[0] } - builds, err := client.ListBuilds(cfg.Project(), cfg.Service(), prefix) + latestBuildID, err := latestBuild(client, cfg, prefix) if err != nil { return err } - if len(builds) == 0 { - return fmt.Errorf("no builds available") - } - // Sort builds by date width, _, _ := term.GetSize(int(os.Stdout.Fd())) - sort.Slice(builds, func(i, j int) bool { return builds[i].CreatedAt.After(builds[j].CreatedAt) }) - latestBuildID := builds[0].ID consumer := func(le api.LogEntry) { - if logsRaw { + switch { + case outputJSON: + writeJSONLine(stdout, le) + case logsRaw: fmt.Println(le.Content) - } else { + default: fmt.Println(formatLogEntry(&le, width)) } } @@ -194,17 +197,14 @@ var buildWatchCmd = &cobra.Command{ if len(args) > 0 { prefix = args[0] } - builds, err := client.ListBuilds(cfg.Project(), cfg.Service(), prefix) + latestBuildID, err := latestBuild(client, cfg, prefix) if err != nil { return err } - if len(builds) == 0 { - return fmt.Errorf("no builds available") - } - // Sort builds by date - sort.Slice(builds, func(i, j int) bool { return builds[i].CreatedAt.After(builds[j].CreatedAt) }) - latestBuildID := builds[0].ID + if outputJSON { + return watchBuildJSON(client, cfg, latestBuildID) + } if !term.IsTerminal(int(os.Stdout.Fd())) { return watchBuildPlain(client, cfg, latestBuildID) } @@ -259,6 +259,34 @@ var buildWatchCmd = &cobra.Command{ }), } +// latestBuild returns the ID of the newest build matching prefix. +func latestBuild(client *api.Client, cfg config.ServiceConfig, prefix string) (string, error) { + builds, err := client.ListBuilds(cfg.Project(), cfg.Service(), prefix) + if err != nil { + return "", err + } + if len(builds) == 0 { + return "", newError(kindNotFound, "no builds available") + } + sort.Slice(builds, func(i, j int) bool { return builds[i].CreatedAt.After(builds[j].CreatedAt) }) + return builds[0].ID, nil +} + +// watchBuildJSON streams the build log as JSON lines; the exit code tells the +// outcome. +func watchBuildJSON(client *api.Client, cfg config.ServiceConfig, buildID string) error { + if err := client.StreamBuildLogs(cfg.Project(), cfg.Service(), buildID, func(le api.LogEntry) { + writeJSONLine(stdout, le) + }); err != nil { + return fmt.Errorf("streaming build logs: %w", err) + } + build, err := client.InspectBuild(cfg.Project(), cfg.Service(), buildID) + if err != nil { + return err + } + return buildOutcome(build) +} + // watchBuildPlain streams the build logs line by line without any cursor // movement, for when stdout is not a terminal (CI, pipes, redirects). func watchBuildPlain(client *api.Client, cfg config.ServiceConfig, buildID string) error { @@ -285,7 +313,7 @@ func watchBuildPlain(client *api.Client, cfg config.ServiceConfig, buildID strin // buildOutcome turns a failed build into an error, so the exit code tells. func buildOutcome(build *api.Build) error { if build.Status == "failed" { - return fmt.Errorf("build %s failed%s", build.ID, detail(build.Err)) + return newError(kindFailed, "build %s failed%s", build.ID, detail(build.Err)) } return nil } @@ -320,8 +348,7 @@ var buildStatusCmd = &cobra.Command{ if err != nil { return err } - showBuildStatusAndExit(client, cfg, args[0]) - return nil + return showBuildStatusAndExit(client, cfg, args[0]) }), } @@ -334,17 +361,19 @@ func listBuilds(client *api.Client, cfg config.ServiceConfig, id string) error { sort.Slice(builds, func(i, j int) bool { return builds[i].CreatedAt.Before(builds[j].CreatedAt) }) - tw := ansiterm.NewTabWriter(os.Stdout, 6, 0, 1, ' ', 0) - fmt.Fprintln(tw, "ID\tSTATUS\tCREATED") - for _, b := range builds { - fmt.Fprintln(tw, strings.Join([]string{ - b.ID, - colorize(b.Status), - humanize.Time(b.CreatedAt), - }, "\t")) - } - tw.Flush() - return nil + return result(builds, func(w io.Writer) error { + tw := ansiterm.NewTabWriter(w, 6, 0, 1, ' ', 0) + fmt.Fprintln(tw, "ID\tSTATUS\tCREATED") + for _, b := range builds { + fmt.Fprintln(tw, strings.Join([]string{ + b.ID, + colorize(b.Status), + humanize.Time(b.CreatedAt), + }, "\t")) + } + tw.Flush() + return nil + }) } func showBuildStatusAndExit(client *api.Client, cfg config.ServiceConfig, id string) error { @@ -352,7 +381,10 @@ func showBuildStatusAndExit(client *api.Client, cfg config.ServiceConfig, id str if err != nil { return err } - fmt.Fprintln(os.Stdout, colorize(build.Status)) + result(build, func(w io.Writer) error { + _, err := fmt.Fprintln(w, colorize(build.Status)) + return err + }) os.Exit(statusToExitCode(build.Status)) return nil } @@ -362,18 +394,20 @@ func inspectBuild(client *api.Client, cfg config.ServiceConfig, id string) error if err != nil { return err } - tw := tabwriter.NewWriter(os.Stdout, 0, 0, 1, ' ', 0) - fmt.Fprintln(tw, "ID:\t", build.ID) - fmt.Fprintln(tw, "Constructor:\t", build.Constructor) - fmt.Fprintln(tw, "CreatedAt:\t", build.CreatedAt) - fmt.Fprintln(tw, "Status:\t", colorize(build.Status)) - fmt.Fprintln(tw, "Flags:\t", build.Flags) - fmt.Fprintln(tw, "Owner:\t", build.Owner) - if build.Err != "" { - fmt.Fprintln(tw, "Err:\t", build.Err) - } - tw.Flush() - return nil + return result(build, func(w io.Writer) error { + tw := tabwriter.NewWriter(w, 0, 0, 1, ' ', 0) + fmt.Fprintln(tw, "ID:\t", build.ID) + fmt.Fprintln(tw, "Constructor:\t", build.Constructor) + fmt.Fprintln(tw, "CreatedAt:\t", build.CreatedAt) + fmt.Fprintln(tw, "Status:\t", colorize(build.Status)) + fmt.Fprintln(tw, "Flags:\t", build.Flags) + fmt.Fprintln(tw, "Owner:\t", build.Owner) + if build.Err != "" { + fmt.Fprintln(tw, "Err:\t", build.Err) + } + tw.Flush() + return nil + }) } // deployBuild deploys a build, or without one redeploys the active build with @@ -396,8 +430,10 @@ func deployBuild(client *api.Client, cfg *config.ValidatedServiceConfig, id stri if err != nil { return err } - fmt.Fprintln(w, deployment.Version) - return nil + return emit(w, deployment, func(w io.Writer) error { + _, err := fmt.Fprintln(w, deployment.Version) + return err + }) } // newBuildRequest carries the inline lists of .valar.yml only for servers that @@ -505,7 +541,12 @@ var buildPushCmd = &cobra.Command{ if err != nil { return err } - fmt.Println(build.ID) + if err := result(build, func(w io.Writer) error { + _, err := fmt.Fprintln(w, build.ID) + return err + }); err != nil { + return err + } if !buildPushWait { return nil } diff --git a/cmd/config.go b/cmd/config.go index 74924fe..7b91811 100644 --- a/cmd/config.go +++ b/cmd/config.go @@ -3,7 +3,10 @@ package cmd import ( "bufio" "fmt" + "io" + "maps" "os" + "slices" "strings" "github.com/juju/ansiterm" @@ -44,17 +47,44 @@ var configViewCmd = &cobra.Command{ Use: "view", Short: "View the merged configuration as YAML.", Run: func(cmd *cobra.Command, args []string) { + if outputJSON { + writeJSON(stdout, globalConfiguration) + return + } enc := yaml.NewEncoder(os.Stdout) enc.SetIndent(2) enc.Encode(globalConfiguration) }, } +var configSchemaCmd = &cobra.Command{ + Use: "schema", + Short: "Print the JSON Schema of .valar.yml.", + Args: cobra.NoArgs, + Run: runAndHandle(func(cmd *cobra.Command, args []string) error { + return writeJSON(stdout, config.Schema()) + }), +} + var configEndpointCmd = &cobra.Command{ Use: "endpoint", Short: "Manage API endpoints.", Args: cobra.NoArgs, Run: func(cmd *cobra.Command, args []string) { + if outputJSON { + type endpoint struct { + Name string `json:"name"` + URL string `json:"url"` + Token string `json:"token"` + } + list := []endpoint{} + for _, name := range slices.Sorted(maps.Keys(globalConfiguration.Endpoints)) { + ep := globalConfiguration.Endpoints[name] + list = append(list, endpoint{name, ep.URL, ep.Token}) + } + writeJSON(stdout, list) + return + } tw := ansiterm.NewTabWriter(os.Stdout, 6, 0, 1, ' ', 0) fmt.Fprintln(tw, "NAME\tURL\tTOKEN") for name, ep := range globalConfiguration.Endpoints { @@ -83,9 +113,12 @@ var configEndpointSetCmd = &cobra.Command{ } globalConfiguration.Endpoints[args[0]] = ep if err := globalConfiguration.Write(); err != nil { - return fmt.Errorf("write config: %w", err) + return writeConfigError(err) } - return nil + return result(struct { + Name string `json:"name"` + URL string `json:"url"` + }{args[0], ep.URL}, func(io.Writer) error { return nil }) }, } @@ -96,9 +129,9 @@ var configEndpointRemoveCmd = &cobra.Command{ RunE: func(cmd *cobra.Command, args []string) error { delete(globalConfiguration.Endpoints, args[0]) if err := globalConfiguration.Write(); err != nil { - return fmt.Errorf("write config: %w", err) + return writeConfigError(err) } - return nil + return result(removed{args[0], true}, func(io.Writer) error { return nil }) }, } @@ -107,6 +140,15 @@ var configContextCmd = &cobra.Command{ Short: "Manage CLI contexts.", Args: cobra.NoArgs, Run: func(cmd *cobra.Command, args []string) { + if outputJSON { + list := []contextEntry{} + for _, name := range slices.Sorted(maps.Keys(globalConfiguration.Contexts)) { + ctx := globalConfiguration.Contexts[name] + list = append(list, contextEntry{name, ctx.Endpoint, ctx.Project, name == globalConfiguration.ActiveContext}) + } + writeJSON(stdout, list) + return + } tw := ansiterm.NewTabWriter(os.Stdout, 6, 0, 1, ' ', 0) fmt.Fprintln(tw, "ACTIVE\tNAME\tENDPOINT\tPROJECT") for name, ctx := range globalConfiguration.Contexts { @@ -127,9 +169,10 @@ var configContextUseCmd = &cobra.Command{ RunE: func(cmd *cobra.Command, args []string) error { globalConfiguration.ActiveContext = args[0] if err := globalConfiguration.Write(); err != nil { - return fmt.Errorf("write config: %w", err) + return writeConfigError(err) } - return nil + ctx := globalConfiguration.Contexts[args[0]] + return result(contextEntry{args[0], ctx.Endpoint, ctx.Project, true}, func(io.Writer) error { return nil }) }, } @@ -149,9 +192,9 @@ var configContextSetCmd = &cobra.Command{ } globalConfiguration.Contexts[args[0]] = ctx if err := globalConfiguration.Write(); err != nil { - return fmt.Errorf("write config: %w", err) + return writeConfigError(err) } - return nil + return result(contextEntry{args[0], ctx.Endpoint, ctx.Project, args[0] == globalConfiguration.ActiveContext}, func(io.Writer) error { return nil }) }, } @@ -162,12 +205,30 @@ var configContextRemoveCmd = &cobra.Command{ RunE: func(cmd *cobra.Command, args []string) error { delete(globalConfiguration.Contexts, args[0]) if err := globalConfiguration.Write(); err != nil { - return fmt.Errorf("write config: %w", err) + return writeConfigError(err) } - return nil + return result(removed{args[0], true}, func(io.Writer) error { return nil }) }, } +type contextEntry struct { + Name string `json:"name"` + Endpoint string `json:"endpoint"` + Project string `json:"project"` + Active bool `json:"active"` +} + +type removed struct { + Name string `json:"name"` + Removed bool `json:"removed"` +} + +// writeConfigError is a failure, unlike the other errors of the RunE config +// commands, which reject their input. +func writeConfigError(err error) error { + return withKind(kindFailed, fmt.Errorf("write config: %w", err)) +} + var configInitUrl, configInitToken, configInitProject, configInitName string var configInitForce bool @@ -246,10 +307,10 @@ var configInitCmd = &cobra.Command{ } globalConfiguration.ActiveContext = nameValue if err := globalConfiguration.Write(); err != nil { - return fmt.Errorf("write config: %w", err) + return writeConfigError(err) } fmt.Fprintf(os.Stderr, "Configuration written to %s.\n", globalConfiguration.Path) - return nil + return result(contextEntry{nameValue, nameValue, projectValue, true}, func(io.Writer) error { return nil }) }, } @@ -272,5 +333,6 @@ func initConfigCmd() { configCmd.AddCommand(configContextCmd) configCmd.AddCommand(configEndpointCmd) configCmd.AddCommand(configViewCmd) + configCmd.AddCommand(configSchemaCmd) rootCmd.AddCommand(configCmd) } diff --git a/cmd/cron.go b/cmd/cron.go index d0330a8..0aa76a9 100644 --- a/cmd/cron.go +++ b/cmd/cron.go @@ -3,8 +3,8 @@ package cmd import ( "errors" "fmt" + "io" "net/http" - "os" "strings" "text/tabwriter" @@ -37,13 +37,15 @@ var ( if err != nil { return err } - tw := tabwriter.NewWriter(os.Stdout, 0, 0, 1, ' ', 0) - fmt.Fprintln(tw, "NAME\tTIMESPEC\tPATH\tSTATUS") - for _, sched := range schedules { - fmt.Fprintln(tw, strings.Join([]string{sched.Name, sched.Timespec, sched.Path, colorize(sched.Status)}, "\t")) - } - tw.Flush() - return nil + return result(schedules, func(w io.Writer) error { + tw := tabwriter.NewWriter(w, 0, 0, 1, ' ', 0) + fmt.Fprintln(tw, "NAME\tTIMESPEC\tPATH\tSTATUS") + for _, sched := range schedules { + fmt.Fprintln(tw, strings.Join([]string{sched.Name, sched.Timespec, sched.Path, colorize(sched.Status)}, "\t")) + } + tw.Flush() + return nil + }) }), } @@ -91,8 +93,7 @@ var ( } } else { if len(args) != 2 { - fmt.Fprintln(os.Stderr, "Timespec must be specified when setting a schedule for the first time.") - os.Exit(1) + return newError(kindInvalid, "Timespec must be specified when setting a schedule for the first time.") } schedule = api.Schedule{ Name: args[0], @@ -109,7 +110,7 @@ var ( if err := client.SetSchedule(cfg.Project(), cfg.Service(), schedule); err != nil { return err } - return nil + return result(schedule, func(io.Writer) error { return nil }) }), } @@ -129,7 +130,10 @@ var ( if err := client.TriggerSchedule(cfg.Project(), cfg.Service(), args[0]); err != nil { return err } - return nil + return result(struct { + Name string `json:"name"` + Triggered bool `json:"triggered"` + }{args[0], true}, func(io.Writer) error { return nil }) }), } cronDeleteCmd = &cobra.Command{ @@ -148,7 +152,10 @@ var ( if err := client.DeleteSchedule(cfg.Project(), cfg.Service(), args[0]); err != nil { return err } - return nil + return result(struct { + Name string `json:"name"` + Deleted bool `json:"deleted"` + }{args[0], true}, func(io.Writer) error { return nil }) }), } cronInspectCmd = &cobra.Command{ @@ -168,7 +175,10 @@ var ( if err != nil { return err } - tw := tabwriter.NewWriter(os.Stdout, 0, 0, 1, ' ', 0) + if outputJSON { + return writeJSON(stdout, details) + } + tw := tabwriter.NewWriter(stdout, 0, 0, 1, ' ', 0) fmt.Fprintln(tw, "Name:\t", details.Schedule.Name) fmt.Fprintln(tw, "Timespec:\t", details.Schedule.Timespec) fmt.Fprintln(tw, "Path:\t", details.Schedule.Path) diff --git a/cmd/deployments.go b/cmd/deployments.go index f889cbc..f13e6d1 100644 --- a/cmd/deployments.go +++ b/cmd/deployments.go @@ -62,7 +62,7 @@ service's current runtime variables, for example after 'valar env set'.`, if len(args) > 0 { build = args[0] } - return deployBuild(client, cfg, build, os.Stdout) + return deployBuild(client, cfg, build, stdout) }), } @@ -89,7 +89,7 @@ from the current ones. With --env current, it gets the current variables.`, if err != nil { return err } - return rollbackLatestDeployment(client, cfg, rollbackDelta, rollbackEnv, os.Stdout, os.Stderr) + return rollbackLatestDeployment(client, cfg, rollbackDelta, rollbackEnv, stdout, os.Stderr) }), } @@ -108,14 +108,14 @@ func rollbackLatestDeployment(client *api.Client, cfg config.ServiceConfig, delt return fmt.Errorf("--env current needs Valar platform %s or newer with the environment API enabled", api.EnvMinPlatform) } default: - return fmt.Errorf("unknown --env %q, want %q or %q", env, api.RollbackEnvPinned, api.RollbackEnvCurrent) + return newError(kindInvalid, "unknown --env %q, want %q or %q", env, api.RollbackEnvPinned, api.RollbackEnvCurrent) } deployments, err := client.ListDeployments(cfg.Project(), cfg.Service()) if err != nil { return err } if len(deployments) < delta+1 { - return fmt.Errorf("not enough deployments available") + return newError(kindNotFound, "not enough deployments available") } // Sort by version (desc) sort.Slice(deployments, func(i, j int) bool { @@ -129,7 +129,12 @@ func rollbackLatestDeployment(client *api.Client, cfg config.ServiceConfig, delt if err != nil { return err } - fmt.Fprintln(stdout, result.Version) + if err := emit(stdout, result, func(w io.Writer) error { + _, err := fmt.Fprintln(w, result.Version) + return err + }); err != nil { + return err + } if len(result.Changed) > 0 { fmt.Fprintf(stderr, "The environment of version %d differs from the current one in %s.\n", target, strings.Join(result.Changed, ", ")) } @@ -145,19 +150,21 @@ func listDeployments(client *api.Client, cfg config.ServiceConfig) error { sort.Slice(deployments, func(i, j int) bool { return deployments[i].Version < deployments[j].Version }) - tw := ansiterm.NewTabWriter(os.Stdout, 6, 0, 1, ' ', 0) - fmt.Fprintln(tw, "VERSION\tSTATUS\tCREATED\tBUILD\tERROR") - for _, d := range deployments { - fmt.Fprintln(tw, strings.Join([]string{ - strconv.FormatInt(d.Version, 10), - colorize(d.Status), - humanize.Time(d.CreatedAt), - d.Build, - d.Error, - }, "\t")) - } - tw.Flush() - return nil + return result(deployments, func(w io.Writer) error { + tw := ansiterm.NewTabWriter(w, 6, 0, 1, ' ', 0) + fmt.Fprintln(tw, "VERSION\tSTATUS\tCREATED\tBUILD\tERROR") + for _, d := range deployments { + fmt.Fprintln(tw, strings.Join([]string{ + strconv.FormatInt(d.Version, 10), + colorize(d.Status), + humanize.Time(d.CreatedAt), + d.Build, + d.Error, + }, "\t")) + } + tw.Flush() + return nil + }) } func initDeploymentsCmd() { diff --git a/cmd/domains.go b/cmd/domains.go index 3a92452..50861c4 100644 --- a/cmd/domains.go +++ b/cmd/domains.go @@ -2,7 +2,7 @@ package cmd import ( "fmt" - "os" + "io" "strings" "github.com/juju/ansiterm" @@ -39,18 +39,19 @@ var domainsListCmd = &cobra.Command{ } // Sort domains before printing them out slices.SortFunc(doms, func(a, b api.Domain) int { return strings.Compare(a.Domain, b.Domain) }) - // Print them pretty - tw := ansiterm.NewTabWriter(os.Stdout, 6, 0, 1, ' ', 0) - fmt.Fprintln(tw, "DOMAIN\tVERIFIED\tSERVICE\tERROR") - for _, d := range doms { - svc := "" - if d.Service != nil { - svc = *d.Service + return result(doms, func(w io.Writer) error { + tw := ansiterm.NewTabWriter(w, 6, 0, 1, ' ', 0) + fmt.Fprintln(tw, "DOMAIN\tVERIFIED\tSERVICE\tERROR") + for _, d := range doms { + svc := "" + if d.Service != nil { + svc = *d.Service + } + fmt.Fprintf(tw, "%s\t%v\t%s\t%s\n", d.Domain, d.Verified, svc, d.Error) } - fmt.Fprintf(tw, "%s\t%v\t%s\t%s\n", d.Domain, d.Verified, svc, d.Error) - } - tw.Flush() - return nil + tw.Flush() + return nil + }) }), } @@ -72,14 +73,18 @@ var domainsAddCmd = &cobra.Command{ if err != nil { return err } - fmt.Println("Please set the following records (choose one for A/AAAA and CNAME):") - fmt.Println() - tw := ansiterm.NewTabWriter(os.Stdout, 6, 0, 1, ' ', 0) - for rt, rr := range records { - fmt.Fprintf(tw, "%s\t%s\n", rt, rr) - } - tw.Flush() - return nil + return result(struct { + Domain string `json:"domain"` + Records map[string]string `json:"records"` + }{args[0], records}, func(w io.Writer) error { + fmt.Fprintln(w, "Please set the following records (choose one for A/AAAA and CNAME):") + fmt.Fprintln(w) + tw := ansiterm.NewTabWriter(w, 6, 0, 1, ' ', 0) + for rt, rr := range records { + fmt.Fprintf(tw, "%s\t%s\n", rt, rr) + } + return tw.Flush() + }) }), } @@ -100,7 +105,10 @@ var domainsDeleteCmd = &cobra.Command{ if err := client.DeleteDomain(cfg.Project(), args[0]); err != nil { return err } - return nil + return result(struct { + Domain string `json:"domain"` + Deleted bool `json:"deleted"` + }{args[0], true}, func(io.Writer) error { return nil }) }), } @@ -122,8 +130,10 @@ var domainsVerifyCmd = &cobra.Command{ if err != nil { return err } - fmt.Println("Verified until", dom.Expiration) - return nil + return result(dom, func(w io.Writer) error { + _, err := fmt.Fprintln(w, "Verified until", dom.Expiration) + return err + }) }), } @@ -144,12 +154,15 @@ var domainsLinkCmd = &cobra.Command{ if err != nil { return err } - return client.LinkDomain(api.LinkDomainArgs{ + if err := client.LinkDomain(api.LinkDomainArgs{ Project: cfg.Project(), Service: cfg.Service(), Domain: args[0], AllowInsecureTraffic: domainsLinkAllowInsecureTraffic, - }) + }); err != nil { + return err + } + return result(domainLink{args[0], cfg.Service(), true}, func(io.Writer) error { return nil }) }), } @@ -169,14 +182,23 @@ var domainsUnlinkCmd = &cobra.Command{ if err != nil { return err } - return client.UnlinkDomain(api.UnlinkDomainArgs{ + if err := client.UnlinkDomain(api.UnlinkDomainArgs{ Project: cfg.Project(), Service: cfg.Service(), Domain: args[0], - }) + }); err != nil { + return err + } + return result(domainLink{args[0], cfg.Service(), false}, func(io.Writer) error { return nil }) }), } +type domainLink struct { + Domain string `json:"domain"` + Service string `json:"service"` + Linked bool `json:"linked"` +} + func initDomainsCmd() { domainsLinkCmd.Flags().StringVarP(&domainsLinkService, "service", "s", "", "The service to link the domain to") domainsLinkCmd.Flags().BoolVarP(&domainsLinkAllowInsecureTraffic, "insecure", "i", false, "Allow insecure traffic to the service. Disables the default HTTPS redirect for this domain.") diff --git a/cmd/env.go b/cmd/env.go index 3566691..b1e9a8b 100644 --- a/cmd/env.go +++ b/cmd/env.go @@ -51,7 +51,8 @@ var envListCmd = &cobra.Command{ if err != nil { return err } - return printEnv(os.Stdout, filterEnv(vars, envTargets(envBuild, envAll)), envFormat) + vars = filterEnv(vars, envTargets(envBuild, envAll)) + return result(vars, func(w io.Writer) error { return printEnv(w, vars, envFormat) }) }), } @@ -73,7 +74,7 @@ history and process listings.`, return readEnvValue(os.Stdin, name) }) if err != nil { - return err + return withKind(kindInvalid, err) } targets := envTargets(envBuild, envAll) changes := &api.EnvChangeset{Set: map[string]api.EnvValue{}} @@ -83,8 +84,11 @@ history and process listings.`, if _, err := client.PatchEnv(cfg.Project(), cfg.Service(), changes); err != nil { return err } - fmt.Printf("Set %s (%s).\n", strings.Join(slices.Sorted(maps.Keys(values)), ", "), strings.Join(targets, ", ")) - return nil + names := slices.Sorted(maps.Keys(values)) + return result(envChange{Set: names, Targets: targets}, func(w io.Writer) error { + _, err := fmt.Fprintf(w, "Set %s (%s).\n", strings.Join(names, ", "), strings.Join(targets, ", ")) + return err + }) }), } @@ -106,11 +110,19 @@ var envUnsetCmd = &cobra.Command{ if _, err := client.PatchEnv(cfg.Project(), cfg.Service(), changes); err != nil { return err } - fmt.Printf("Unset %s (%s).\n", strings.Join(args, ", "), strings.Join(targets, ", ")) - return nil + return result(envChange{Unset: args, Targets: targets}, func(w io.Writer) error { + _, err := fmt.Fprintf(w, "Unset %s (%s).\n", strings.Join(args, ", "), strings.Join(targets, ", ")) + return err + }) }), } +type envChange struct { + Set []string `json:"set,omitempty"` + Unset []string `json:"unset,omitempty"` + Targets []string `json:"targets"` +} + var envHistoryCmd = &cobra.Command{ Use: "history", Short: "Show the change log of the variables, newest first.", @@ -125,16 +137,21 @@ var envHistoryCmd = &cobra.Command{ return err } targets := envTargets(envBuild, envAll) - tw := tabwriter.NewWriter(os.Stdout, 0, 1, 1, ' ', 0) - fmt.Fprintln(tw, "TIME\tACTION\tNAME\tTARGET\tSECRET\tORIGIN\tBY") + kept := []api.EnvChange{} for _, c := range changes { - if !slices.Contains(targets, c.Target) { - continue + if slices.Contains(targets, c.Target) { + kept = append(kept, c) } - fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%v\t%s\t%s\n", - c.CreatedAt.Local().Format("2006-01-02 15:04:05"), c.Action, c.Name, c.Target, c.Secret, c.Origin, c.CreatedBy) } - return tw.Flush() + return result(kept, func(w io.Writer) error { + tw := tabwriter.NewWriter(w, 0, 1, 1, ' ', 0) + fmt.Fprintln(tw, "TIME\tACTION\tNAME\tTARGET\tSECRET\tORIGIN\tBY") + for _, c := range kept { + fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%v\t%s\t%s\n", + c.CreatedAt.Local().Format("2006-01-02 15:04:05"), c.Action, c.Name, c.Target, c.Secret, c.Origin, c.CreatedBy) + } + return tw.Flush() + }) }), } @@ -151,17 +168,28 @@ ciphertexts: the command names those the service lacks, to be set again with Args: cobra.NoArgs, Run: runAndHandle(func(cmd *cobra.Command, args []string) error { if envService != "" { - return fmt.Errorf("import uses the service named in %s, drop --service", functionConfiguration) + return newError(kindInvalid, "import uses the service named in %s, drop --service", functionConfiguration) } cfg, err := config.NewServiceConfigFromFile(functionConfiguration) if err != nil { - return fmt.Errorf("read %s: %w", functionConfiguration, err) + return withKind(kindInvalid, fmt.Errorf("read %s: %w", functionConfiguration, err)) } client, err := globalConfiguration.APIClient() if err != nil { return err } - return importEnv(client, cfg, os.Stdout) + w := stdout + if outputJSON { + w = io.Discard + } + imported, err := importEnv(client, cfg, w) + if err != nil { + return err + } + if outputJSON { + return writeJSON(stdout, imported) + } + return nil }), } @@ -227,7 +255,7 @@ func printEnv(w io.Writer, vars []api.EnvVariable, format string) error { } return tw.Flush() default: - return fmt.Errorf("unknown env format %s", format) + return newError(kindInvalid, "unknown env format %s", format) } } @@ -283,9 +311,23 @@ func readValue(r io.Reader) (string, error) { return value, nil } +// envImport is the outcome of importEnv for each target. +type envImport struct { + Targets []envImportTarget `json:"targets"` + Emptied bool `json:"emptied"` +} + +type envImportTarget struct { + Target string `json:"target"` + Imported []string `json:"imported"` + Skipped []string `json:"skipped"` + MissingSecrets []string `json:"missingSecrets"` +} + // importEnv moves the inline lists of cfg to the service and empties them in -// the file. -func importEnv(client *api.Client, cfg *config.ValidatedServiceConfig, w io.Writer) error { +// the file. It reports progress to w. +func importEnv(client *api.Client, cfg *config.ValidatedServiceConfig, w io.Writer) (*envImport, error) { + outcome := &envImport{Targets: []envImportTarget{}} yamlCfg := cfg.Unwrap() lists := map[string][]config.EnvironmentConfig{} if yamlCfg.Deployment != nil { @@ -296,14 +338,15 @@ func importEnv(client *api.Client, cfg *config.ValidatedServiceConfig, w io.Writ } if len(lists[api.EnvTargetRuntime]) == 0 && len(lists[api.EnvTargetBuild]) == 0 { fmt.Fprintf(w, "The environment lists in %s are empty, nothing to import.\n", functionConfiguration) - return nil + return outcome, nil } // Reading first also stops before any change on a server without the API. stored, err := client.ListEnv(cfg.Project(), cfg.Service()) if err != nil { - return err + return nil, err } for _, target := range []string{api.EnvTargetRuntime, api.EnvTargetBuild} { + report := envImportTarget{Target: target, Imported: []string{}, Skipped: []string{}, MissingSecrets: []string{}} plain, secrets := splitInlineList(lists[target]) if len(plain) > 0 { changes := &api.EnvChangeset{Set: map[string]api.EnvValue{}, OnlySeeded: true} @@ -312,7 +355,7 @@ func importEnv(client *api.Client, cfg *config.ValidatedServiceConfig, w io.Writ } result, err := client.PatchEnv(cfg.Project(), cfg.Service(), changes) if err != nil { - return fmt.Errorf("import %s variables: %w", target, err) + return nil, fmt.Errorf("import %s variables: %w", target, err) } var imported []string for _, name := range slices.Sorted(maps.Keys(plain)) { @@ -325,9 +368,18 @@ func importEnv(client *api.Client, cfg *config.ValidatedServiceConfig, w io.Writ } if len(result.Skipped) > 0 { fmt.Fprintf(w, "Left %s as stored, since they changed on the service after the seed.\n", strings.Join(result.Skipped, ", ")) + report.Skipped = result.Skipped + } + if imported != nil { + report.Imported = imported } } - if missing := missingSecrets(secrets, stored, target); len(missing) > 0 { + missing := missingSecrets(secrets, stored, target) + if missing != nil { + report.MissingSecrets = missing + } + outcome.Targets = append(outcome.Targets, report) + if len(missing) > 0 { flag := "" if target == api.EnvTargetBuild { flag = " --build" @@ -343,10 +395,11 @@ func importEnv(client *api.Client, cfg *config.ValidatedServiceConfig, w io.Writ yamlCfg.Build.Environment = []config.EnvironmentConfig{} } if err := yamlCfg.WriteBack(); err != nil { - return err + return nil, err } + outcome.Emptied = true fmt.Fprintf(w, "Emptied the environment lists in %s.\n", functionConfiguration) - return nil + return outcome, nil } // splitInlineList resolves an inline list the way the server applies it: the diff --git a/cmd/env_test.go b/cmd/env_test.go index f31b316..a9e8dfd 100644 --- a/cmd/env_test.go +++ b/cmd/env_test.go @@ -231,7 +231,7 @@ func TestImportEnv(t *testing.T) { "PATCH /projects/p/services/s/env": `{"skipped":[]}`, }) var out bytes.Buffer - if err := importEnv(client, cfg, &out); err != nil { + if _, err := importEnv(client, cfg, &out); err != nil { t.Fatalf("importEnv: %v", err) } @@ -286,7 +286,7 @@ func TestImportEnv_ReportsSkipped(t *testing.T) { "PATCH /projects/p/services/s/env": `{"skipped":["B"]}`, }) var out bytes.Buffer - if err := importEnv(client, cfg, &out); err != nil { + if _, err := importEnv(client, cfg, &out); err != nil { t.Fatalf("importEnv: %v", err) } if !strings.Contains(out.String(), "Imported the plain runtime variables A.") || !strings.Contains(out.String(), "Left B as stored") { @@ -297,7 +297,7 @@ func TestImportEnv_ReportsSkipped(t *testing.T) { func TestImportEnv_OldServerChangesNothing(t *testing.T) { cfg, path := writeServiceConfig(t, importConfig) client, requests := newFakeAPI(t, nil) - err := importEnv(client, cfg, io.Discard) + _, err := importEnv(client, cfg, io.Discard) if !errors.Is(err, api.ErrNoEnvAPI) { t.Fatalf("got %v, want ErrNoEnvAPI", err) } @@ -314,7 +314,7 @@ func TestImportEnv_OldServerChangesNothing(t *testing.T) { func TestImportEnv_NothingToImport(t *testing.T) { cfg, _ := writeServiceConfig(t, "project: p\nservice: s\nbuild:\n environment: []\ndeployment:\n environment: []\n") client, requests := newFakeAPI(t, nil) - if err := importEnv(client, cfg, io.Discard); err != nil { + if _, err := importEnv(client, cfg, io.Discard); err != nil { t.Fatalf("importEnv: %v", err) } if len(*requests) != 0 { diff --git a/cmd/output.go b/cmd/output.go new file mode 100644 index 0000000..1539673 --- /dev/null +++ b/cmd/output.go @@ -0,0 +1,244 @@ +package cmd + +import ( + "bytes" + "encoding/json" + "errors" + "fmt" + "io" + "net/http" + "net/url" + "os" + "reflect" + "strconv" + "strings" + + "github.com/valar/cli/api" + "github.com/valar/cli/config" +) + +// outputJSON is set by --json or VALAR_OUTPUT=json. +var outputJSON bool + +// stdout receives command results; tests replace it. +var stdout io.Writer = os.Stdout + +const exitCodeHelp = `Exit codes: + 0 success + 1 failed: the operation ran and failed, such as a build or deployment + 2 invalid: bad arguments, flags or configuration + 3 not found + 4 not allowed: missing or rejected credentials or permissions + 5 conflict with the current state + 6 unavailable: the server could not be reached or answered with an error` + +// errorKind classifies a failure. Its value is the exit code. +type errorKind int + +const ( + kindFailed errorKind = iota + 1 + kindInvalid + kindNotFound + kindNotAllowed + kindConflict + kindUnavailable +) + +func (k errorKind) String() string { + switch k { + case kindInvalid: + return "invalid" + case kindNotFound: + return "notFound" + case kindNotAllowed: + return "notAllowed" + case kindConflict: + return "conflict" + case kindUnavailable: + return "unavailable" + default: + return "failed" + } +} + +// cliError carries the kind of a failure. A silent error has already been +// reported in human output. +type cliError struct { + kind errorKind + err error + silent bool +} + +func (e *cliError) Error() string { return e.err.Error() } +func (e *cliError) Unwrap() error { return e.err } + +func newError(kind errorKind, format string, args ...any) error { + return &cliError{kind: kind, err: fmt.Errorf(format, args...)} +} + +func withKind(kind errorKind, err error) error { + if err == nil { + return nil + } + return &cliError{kind: kind, err: err} +} + +// classify finds the kind of err, or returns fallback for an untyped error. +func classify(err error, fallback errorKind) errorKind { + var cliErr *cliError + var apiErr api.Error + var cfgErr *config.Error + var urlErr *url.Error + switch { + case errors.As(err, &cliErr): + return cliErr.kind + case errors.As(err, &cfgErr): + return kindInvalid + case errors.As(err, &apiErr): + return statusKind(apiErr.StatusCode) + case errors.As(err, &urlErr): + return kindUnavailable + } + return fallback +} + +func statusKind(status int) errorKind { + switch { + case status == http.StatusBadRequest || status == http.StatusUnprocessableEntity: + return kindInvalid + case status == http.StatusUnauthorized || status == http.StatusForbidden: + return kindNotAllowed + case status == http.StatusNotFound || status == http.StatusGone: + return kindNotFound + case status == http.StatusConflict: + return kindConflict + case status == http.StatusTooManyRequests || status >= 500: + return kindUnavailable + default: + return kindFailed + } +} + +// reportError writes err to w, as JSON in JSON mode, and returns its exit +// code. printed means the human message was already written. +func reportError(w io.Writer, err error, fallback errorKind, printed bool) int { + kind := classify(err, fallback) + var cliErr *cliError + silent := printed || errors.As(err, &cliErr) && cliErr.silent + switch { + case outputJSON: + var doc struct { + Error struct { + Kind string `json:"kind"` + Message string `json:"message"` + } `json:"error"` + } + doc.Error.Kind = kind.String() + doc.Error.Message = err.Error() + enc := json.NewEncoder(w) + enc.SetEscapeHTML(false) + enc.Encode(doc) + case !silent: + fmt.Fprintln(w, err) + } + return int(kind) +} + +func exitWithError(err error, fallback errorKind, printed bool) { + os.Exit(reportError(os.Stderr, err, fallback, printed)) +} + +// jsonRequested reports whether args or VALAR_OUTPUT ask for JSON output, +// before cobra has parsed the flags. +func jsonRequested(args []string, env string) bool { + requested := env == "json" + for _, arg := range args { + if arg == "--" { + break + } + if arg == "--json" { + requested = true + } else if value, ok := strings.CutPrefix(arg, "--json="); ok { + if b, err := strconv.ParseBool(value); err == nil { + requested = b + } + } + } + return requested +} + +// result prints v to stdout as JSON in JSON mode and calls human otherwise. +func result(v any, human func(w io.Writer) error) error { + return emit(stdout, v, human) +} + +func emit(w io.Writer, v any, human func(w io.Writer) error) error { + if outputJSON { + return writeJSON(w, v) + } + return human(w) +} + +// writeJSON writes v as one indented document. A nil slice becomes []. +func writeJSON(w io.Writer, v any) error { + if rv := reflect.ValueOf(v); rv.Kind() == reflect.Slice && rv.IsNil() { + v = reflect.MakeSlice(rv.Type(), 0, 0).Interface() + } + enc := json.NewEncoder(w) + enc.SetEscapeHTML(false) + enc.SetIndent("", " ") + return enc.Encode(v) +} + +// writeJSONLine writes v as a single line, for streams. +func writeJSONLine(w io.Writer, v any) error { + enc := json.NewEncoder(w) + enc.SetEscapeHTML(false) + return enc.Encode(v) +} + +// logLine is a line of service or batch output in a JSON stream. +type logLine struct { + Content string `json:"content"` +} + +// jsonLineWriter turns raw output into one {"content": ...} object per line. +// Flush writes a final line that has no line break. +type jsonLineWriter struct { + w io.Writer + buf []byte +} + +func (lw *jsonLineWriter) Write(b []byte) (int, error) { + lw.buf = append(lw.buf, b...) + for { + i := bytes.IndexByte(lw.buf, '\n') + if i < 0 { + return len(b), nil + } + line := bytes.TrimSuffix(lw.buf[:i], []byte("\r")) + if err := writeJSONLine(lw.w, logLine{Content: string(line)}); err != nil { + return 0, err + } + lw.buf = lw.buf[i+1:] + } +} + +func (lw *jsonLineWriter) Flush() error { + if len(lw.buf) == 0 { + return nil + } + line := string(lw.buf) + lw.buf = nil + return writeJSONLine(lw.w, logLine{Content: line}) +} + +// logOutput returns where raw log output goes, and a flush to call once it +// ends. +func logOutput() (io.Writer, func() error) { + if !outputJSON { + return stdout, func() error { return nil } + } + lw := &jsonLineWriter{w: stdout} + return lw, lw.Flush +} diff --git a/cmd/output_test.go b/cmd/output_test.go new file mode 100644 index 0000000..a53f4f4 --- /dev/null +++ b/cmd/output_test.go @@ -0,0 +1,253 @@ +package cmd + +import ( + "bytes" + "encoding/json" + "errors" + "fmt" + "net/http" + "strings" + "testing" + + "github.com/valar/cli/api" + "github.com/valar/cli/config" +) + +// setJSON switches JSON output on and captures stdout for one test. +func setJSON(t *testing.T, on bool) *bytes.Buffer { + t.Helper() + var out bytes.Buffer + prevJSON, prevStdout := outputJSON, stdout + outputJSON, stdout = on, &out + t.Cleanup(func() { outputJSON, stdout = prevJSON, prevStdout }) + return &out +} + +func TestClassify(t *testing.T) { + apiErr := func(status int) error { + return fmt.Errorf("listing services: %w", api.Error{StatusCode: status, ServerError: errors.New("x")}) + } + for _, tc := range []struct { + Name string + Err error + Fallback errorKind + WantCode int + WantKind string + }{ + {"Untyped", errors.New("boom"), kindFailed, 1, "failed"}, + {"UntypedFromCobra", errors.New("unknown flag: --nope"), kindInvalid, 2, "invalid"}, + {"Typed", newError(kindConflict, "exists"), kindFailed, 5, "conflict"}, + {"TypedWinsOverAPI", withKind(kindFailed, apiErr(http.StatusNotFound)), kindFailed, 1, "failed"}, + {"BadRequest", apiErr(http.StatusBadRequest), kindFailed, 2, "invalid"}, + {"Unprocessable", apiErr(http.StatusUnprocessableEntity), kindFailed, 2, "invalid"}, + {"NotFound", apiErr(http.StatusNotFound), kindFailed, 3, "notFound"}, + {"Gone", apiErr(http.StatusGone), kindFailed, 3, "notFound"}, + {"Unauthorized", apiErr(http.StatusUnauthorized), kindFailed, 4, "notAllowed"}, + {"Forbidden", apiErr(http.StatusForbidden), kindFailed, 4, "notAllowed"}, + {"Conflict", apiErr(http.StatusConflict), kindFailed, 5, "conflict"}, + {"TooManyRequests", apiErr(http.StatusTooManyRequests), kindFailed, 6, "unavailable"}, + {"InternalError", apiErr(http.StatusInternalServerError), kindFailed, 6, "unavailable"}, + {"BadGateway", apiErr(http.StatusBadGateway), kindFailed, 6, "unavailable"}, + {"OtherClientError", apiErr(http.StatusMethodNotAllowed), kindFailed, 1, "failed"}, + {"NoEnvAPI", api.ErrNoEnvAPI, kindFailed, 1, "failed"}, + {"ServiceConfig", &config.Error{Path: ".valar.yml", Err: errors.New("unknown key")}, kindFailed, 2, "invalid"}, + } { + t.Run(tc.Name, func(t *testing.T) { + kind := classify(tc.Err, tc.Fallback) + if int(kind) != tc.WantCode || kind.String() != tc.WantKind { + t.Errorf("classify = %d %s, want %d %s", kind, kind, tc.WantCode, tc.WantKind) + } + }) + } +} + +func TestClassify_Unreachable(t *testing.T) { + _, err := api.NewClient("http://127.0.0.1:1", "token") + if err == nil { + t.Fatal("expected a connection error") + } + if kind := classify(err, kindFailed); kind != kindUnavailable { + t.Errorf("classify(%v) = %s, want unavailable", err, kind) + } +} + +func TestReportError(t *testing.T) { + for _, tc := range []struct { + Name string + JSON bool + Err error + Printed bool + Want string + }{ + {"Human", false, newError(kindNotFound, "no builds available"), false, "no builds available\n"}, + {"HumanAlreadyPrinted", false, errors.New("unknown flag"), true, ""}, + {"HumanSilent", false, &cliError{kind: kindFailed, err: errors.New("x"), silent: true}, false, ""}, + {"JSON", true, newError(kindNotFound, "no builds available"), false, `{"error":{"kind":"notFound","message":"no builds available"}}` + "\n"}, + // cobra's own message is suppressed in JSON mode, so it is never printed. + {"JSONSilent", true, &cliError{kind: kindFailed, err: errors.New("execution e1 failed"), silent: true}, false, `{"error":{"kind":"failed","message":"execution e1 failed"}}` + "\n"}, + } { + t.Run(tc.Name, func(t *testing.T) { + setJSON(t, tc.JSON) + var stderr bytes.Buffer + code := reportError(&stderr, tc.Err, kindFailed, tc.Printed) + if stderr.String() != tc.Want { + t.Errorf("stderr %q, want %q", stderr.String(), tc.Want) + } + if want := int(classify(tc.Err, kindFailed)); code != want { + t.Errorf("code %d, want %d", code, want) + } + }) + } +} + +func TestJSONRequested(t *testing.T) { + for _, tc := range []struct { + Name string + Args []string + Env string + Want bool + }{ + {"None", []string{"service", "list"}, "", false}, + {"Flag", []string{"service", "list", "--json"}, "", true}, + {"FlagValue", []string{"--json=true", "service", "list"}, "", true}, + {"Env", []string{"service", "list"}, "json", true}, + {"FlagOverridesEnv", []string{"--json=false"}, "json", false}, + {"OtherEnv", nil, "table", false}, + {"AfterDashDash", []string{"batch", "run", "--", "--json"}, "", false}, + } { + t.Run(tc.Name, func(t *testing.T) { + if got := jsonRequested(tc.Args, tc.Env); got != tc.Want { + t.Errorf("got %v, want %v", got, tc.Want) + } + }) + } +} + +func TestJSONLineWriter(t *testing.T) { + var out bytes.Buffer + lw := &jsonLineWriter{w: &out} + lw.Write([]byte("first\nsec")) + lw.Write([]byte("ond\r\n\"quoted\" \nlast")) + if err := lw.Flush(); err != nil { + t.Fatal(err) + } + want := `{"content":"first"} +{"content":"second"} +{"content":"\"quoted\" "} +{"content":"last"} +` + if out.String() != want { + t.Errorf("got\n%s\nwant\n%s", out.String(), want) + } +} + +func TestWriteJSON_NilSliceIsEmptyArray(t *testing.T) { + var out bytes.Buffer + var builds []api.Build + if err := writeJSON(&out, builds); err != nil { + t.Fatal(err) + } + if out.String() != "[]\n" { + t.Errorf("got %q, want []", out.String()) + } +} + +func TestListBuilds_JSON(t *testing.T) { + cfg, _ := writeServiceConfig(t, deployConfig) + client, _ := newFakeAPI(t, map[string]string{ + "GET /projects/p/services/s/builds/": `[ + {"id":"b2","constructor":"go","status":"failed","error":"exit 1","createdAt":"2026-11-20T10:00:00Z","flags":"","owner":"u"}, + {"id":"b1","constructor":"go","status":"done","error":"","createdAt":"2026-11-19T10:00:00Z","flags":"","owner":"u"} + ]`, + }) + out := setJSON(t, true) + if err := listBuilds(client, cfg, ""); err != nil { + t.Fatalf("listBuilds: %v", err) + } + var got []map[string]any + if err := json.Unmarshal(out.Bytes(), &got); err != nil { + t.Fatalf("output is not one JSON array: %v\n%s", err, out) + } + if len(got) != 2 || got[0]["id"] != "b1" || got[1]["status"] != "failed" || got[1]["error"] != "exit 1" { + t.Errorf("got %v, want both builds oldest first", got) + } + for _, key := range []string{"id", "constructor", "status", "error", "createdAt", "flags", "owner"} { + if _, ok := got[0][key]; !ok { + t.Errorf("build lacks field %q: %v", key, got[0]) + } + } +} + +func TestListBuilds_HumanUnchanged(t *testing.T) { + cfg, _ := writeServiceConfig(t, deployConfig) + client, _ := newFakeAPI(t, map[string]string{"GET /projects/p/services/s/builds/": `[{"id":"b1","status":"done"}]`}) + out := setJSON(t, false) + if err := listBuilds(client, cfg, ""); err != nil { + t.Fatalf("listBuilds: %v", err) + } + if !strings.HasPrefix(out.String(), "ID") || strings.Contains(out.String(), "{") { + t.Errorf("human output changed: %q", out.String()) + } +} + +func TestInspectBuild_JSON(t *testing.T) { + cfg, _ := writeServiceConfig(t, deployConfig) + client, _ := newFakeAPI(t, map[string]string{ + "GET /projects/p/services/s/builds/b1/inspect": `{"id":"b1","constructor":"go","status":"done","createdAt":"2026-11-20T10:00:00Z"}`, + }) + out := setJSON(t, true) + if err := inspectBuild(client, cfg, "b1"); err != nil { + t.Fatalf("inspectBuild: %v", err) + } + var got api.Build + if err := json.Unmarshal(out.Bytes(), &got); err != nil { + t.Fatalf("output is not one JSON object: %v\n%s", err, out) + } + if got.ID != "b1" || got.Status != "done" || got.Constructor != "go" { + t.Errorf("got %+v", got) + } +} + +func TestListDeployments_JSON(t *testing.T) { + cfg, _ := writeServiceConfig(t, deployConfig) + client, _ := newFakeAPI(t, map[string]string{ + listRoute: `[{"version":2,"status":"done","build":"b2"},{"version":1,"status":"expired","build":"b1"}]`, + }) + out := setJSON(t, true) + if err := listDeployments(client, cfg); err != nil { + t.Fatalf("listDeployments: %v", err) + } + var got []api.Deployment + if err := json.Unmarshal(out.Bytes(), &got); err != nil { + t.Fatalf("output is not one JSON array: %v\n%s", err, out) + } + if len(got) != 2 || got[0].Version != 1 || got[1].Build != "b2" { + t.Errorf("got %+v, want both deployments by version", got) + } +} + +func TestDeployBuild_JSON(t *testing.T) { + cfg, _ := writeServiceConfig(t, deployConfig) + client, _ := newFakeAPI(t, map[string]string{deployRoute: `{"version":7,"status":"scheduled","build":"b1"}`, envRoute: `[]`}) + setJSON(t, true) + var out bytes.Buffer + if err := deployBuild(client, cfg, "b1", &out); err != nil { + t.Fatalf("deployBuild: %v", err) + } + var got api.Deployment + if err := json.Unmarshal(out.Bytes(), &got); err != nil || got.Version != 7 || got.Build != "b1" { + t.Errorf("got %+v (%v) from %s", got, err, out.String()) + } +} + +func TestCreateProject_JSON(t *testing.T) { + client, _ := newFakeAPI(t, map[string]string{"POST /projects": `{"name":"demo","creator":"user:kc/alice","public":true}`}) + setJSON(t, true) + var out bytes.Buffer + if err := createProject(client, "demo", true, &out); err != nil { + t.Fatalf("createProject: %v", err) + } + if got := strings.Join(strings.Fields(out.String()), ""); got != `{"name":"demo","creator":"user:kc/alice","public":true}` { + t.Errorf("got %s", got) + } +} diff --git a/cmd/projects.go b/cmd/projects.go index a1e11cb..6b4c215 100644 --- a/cmd/projects.go +++ b/cmd/projects.go @@ -40,7 +40,7 @@ project without a token.`, if err != nil { return err } - return createProject(client, args[0], projectsCreatePublic, os.Stdout) + return createProject(client, args[0], projectsCreatePublic, stdout) }), } @@ -62,7 +62,13 @@ for the project name to confirm, unless --yes is given.`, if projectsDeleteYes { confirm = nil } - return deleteProject(client, args[0], confirm, os.Stderr) + if err := deleteProject(client, args[0], confirm, os.Stderr); err != nil { + return err + } + return result(struct { + Name string `json:"name"` + Deleted bool `json:"deleted"` + }{args[0], true}, func(io.Writer) error { return nil }) }), } ) @@ -72,6 +78,10 @@ func createProject(client *api.Client, name string, public bool, w io.Writer) er if err != nil { return err } + return emit(w, project, func(w io.Writer) error { return printProject(project, w) }) +} + +func printProject(project *api.Project, w io.Writer) error { tw := ansiterm.NewTabWriter(w, 6, 0, 1, ' ', 0) fmt.Fprintf(tw, "Project:\t%s\n", project.Name) fmt.Fprintf(tw, "Creator:\t%s\n", project.Creator) @@ -87,14 +97,14 @@ func createProject(client *api.Client, name string, public bool, w io.Writer) er // confirm is nil. func deleteProject(client *api.Client, name string, confirm io.Reader, w io.Writer) error { if err := api.VerifyProjectName(name); err != nil { - return err + return withKind(kindInvalid, err) } if confirm != nil { fmt.Fprintf(w, "Deleting project %s retires its name for good: no project can use it again.\n", name) fmt.Fprint(w, "Type the project name to confirm: ") line, _ := bufio.NewReader(confirm).ReadString('\n') if strings.TrimSpace(line) != name { - return fmt.Errorf("aborted: the input does not match %s, pass --yes to skip the confirmation", name) + return newError(kindInvalid, "aborted: the input does not match %s, pass --yes to skip the confirmation", name) } } if err := client.DeleteProject(name); err != nil { @@ -122,7 +132,7 @@ var ( if len(args) == 1 { subargs := strings.SplitN(args[0], ":", 2) if len(subargs) != 2 { - return fmt.Errorf("expect path to be in the form namespace:prefix") + return newError(kindInvalid, "expect path to be in the form namespace:prefix") } namespace, prefix = subargs[0], subargs[1] } @@ -130,13 +140,15 @@ var ( if err != nil { return err } - tw := tabwriter.NewWriter(os.Stdout, 0, 0, 1, ' ', 0) - fmt.Fprintln(tw, "PATH\tUSER\tACTION\tSTATE") - for _, pm := range permissions { - fmt.Fprintf(tw, "%s\t%s\t%s\t%s\n", pm.Path, pm.User, pm.Action, pm.State) - } - tw.Flush() - return nil + return result(permissions, func(w io.Writer) error { + tw := tabwriter.NewWriter(w, 0, 0, 1, ' ', 0) + fmt.Fprintln(tw, "PATH\tUSER\tACTION\tSTATE") + for _, pm := range permissions { + fmt.Fprintf(tw, "%s\t%s\t%s\t%s\n", pm.Path, pm.User, pm.Action, pm.State) + } + tw.Flush() + return nil + }) }), } @@ -173,11 +185,11 @@ var ( } path, err := api.PermissionPathFromString(args[0]) if err != nil { - return err + return withKind(kindInvalid, err) } user, err := api.PermissionUserFromString(args[1]) if err != nil { - return err + return withKind(kindInvalid, err) } permission := api.Permission{ Path: path, @@ -188,12 +200,16 @@ var ( if err != nil { return err } - if allowed { - fmt.Println("allowed") - } else { - fmt.Println("forbidden") - } - return nil + return result(struct { + Allowed bool `json:"allowed"` + }{allowed}, func(w io.Writer) error { + answer := "forbidden" + if allowed { + answer = "allowed" + } + _, err := fmt.Fprintln(w, answer) + return err + }) }), } @@ -215,11 +231,12 @@ var ( if err != nil { return err } - tw := ansiterm.NewTabWriter(os.Stdout, 6, 0, 1, ' ', 0) - fmt.Fprintf(tw, "User:\t%s\n", info.Name) - fmt.Fprintf(tw, "Projects:\t%s\n", strings.Join(info.Projects, ", ")) - tw.Flush() - return nil + return result(info, func(w io.Writer) error { + tw := ansiterm.NewTabWriter(w, 6, 0, 1, ' ', 0) + fmt.Fprintf(tw, "User:\t%s\n", info.Name) + fmt.Fprintf(tw, "Projects:\t%s\n", strings.Join(info.Projects, ", ")) + return tw.Flush() + }) }), } ) @@ -236,11 +253,11 @@ func authModifyWithState(state string) func(cmd *cobra.Command, args []string) e } path, err := api.PermissionPathFromString(args[0]) if err != nil { - return err + return withKind(kindInvalid, err) } user, err := api.PermissionUserFromString(args[1]) if err != nil { - return err + return withKind(kindInvalid, err) } permission := api.Permission{ Path: path, @@ -252,12 +269,16 @@ func authModifyWithState(state string) func(cmd *cobra.Command, args []string) e if err != nil { return err } - if modified { - fmt.Println("modified") - } else { - fmt.Println("unchanged") - } - return nil + return result(struct { + Modified bool `json:"modified"` + }{modified}, func(w io.Writer) error { + answer := "unchanged" + if modified { + answer = "modified" + } + _, err := fmt.Fprintln(w, answer) + return err + }) } } diff --git a/cmd/root.go b/cmd/root.go index 5b07254..0ef3a15 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -16,12 +16,19 @@ var rootCmd = &cobra.Command{ Long: `Valar is a next-generation serverless platform. You code. We do the rest. -We take care while you do what you do best.`, +We take care while you do what you do best. + +With --json, or VALAR_OUTPUT=json, a command prints its result as one JSON +document on stdout, logs as one JSON object per line, and an error as +{"error": {"kind": "...", "message": "..."}} on stderr. Progress goes to +stderr. + +` + exitCodeHelp, PersistentPreRunE: func(cmd *cobra.Command, args []string) error { var err error globalConfiguration, err = config.NewCLIConfigFromEnvironment() if err != nil { - return fmt.Errorf("configure interface: %w", err) + return withKind(kindInvalid, fmt.Errorf("configure interface: %w", err)) } return nil }, @@ -33,6 +40,10 @@ func init() { // Try to load config, if not found we're fine rootCmd.SetVersionTemplate("Valar CLI {{.Version}}\n") rootCmd.Version = version + rootCmd.PersistentFlags().BoolVar(&outputJSON, "json", false, "Print results as JSON and errors as JSON on stderr (or set VALAR_OUTPUT=json)") + config.Abort = func(msg string) { + exitWithError(newError(kindInvalid, "%s", msg), kindInvalid, false) + } // Configure projects.go initProjectsCmd() // Configure deployments.go @@ -53,17 +64,25 @@ func init() { initBatchCmd() } +// runAndHandle prints the error of f and exits with the code of its kind. func runAndHandle(f func(*cobra.Command, []string) error) func(*cobra.Command, []string) { return func(cmd *cobra.Command, args []string) { if err := f(cmd, args); err != nil { - fmt.Fprintln(os.Stderr, err) - os.Exit(1) + exitWithError(err, kindFailed, false) } } } +// Execute runs the CLI. Errors that reach it come from cobra's argument and +// flag checks, loading the CLI configuration, or a RunE command; cobra has +// printed them unless JSON output is on. func Execute() { + outputJSON = jsonRequested(os.Args[1:], os.Getenv("VALAR_OUTPUT")) + if outputJSON { + rootCmd.SilenceErrors = true + rootCmd.SilenceUsage = true + } if err := rootCmd.Execute(); err != nil { - os.Exit(1) + exitWithError(err, kindInvalid, !outputJSON) } } diff --git a/cmd/services.go b/cmd/services.go index 6d2e518..8454533 100644 --- a/cmd/services.go +++ b/cmd/services.go @@ -39,7 +39,7 @@ var serviceInitCmd = &cobra.Command{ initProject = globalConfiguration.Project() } if err := api.VerifyNames(initProject, args[0]); err != nil { - return fmt.Errorf("bad naming scheme: %w", err) + return newError(kindInvalid, "bad naming scheme: %w", err) } cfg := &config.ServiceConfigYAML{ Project: initProject, @@ -51,9 +51,12 @@ var serviceInitCmd = &cobra.Command{ Deployment: &config.DeploymentConfig{}, } if _, err := os.Stat(functionConfiguration); err == nil && !initForce { - return fmt.Errorf("configuration already exists, please use --force flag to override") + return newError(kindConflict, "configuration already exists, please use --force flag to override") } - return cfg.WriteToFile(functionConfiguration) + if err := cfg.WriteToFile(functionConfiguration); err != nil { + return err + } + return result(cfg, func(io.Writer) error { return nil }) }), } @@ -81,20 +84,22 @@ var serviceListCmd = &cobra.Command{ sort.Slice(services, func(i, j int) bool { return services[i].DeployedAt.Before(services[j].DeployedAt) }) - tw := tabwriter.NewWriter(os.Stdout, 0, 0, 1, ' ', 0) - fmt.Fprintln(tw, "NAME\tKIND\tVERSION\tCREATED\tLAST DEPLOYED\tDOMAINS") - for _, svc := range services { - fmt.Fprintln(tw, strings.Join([]string{ - svc.Name, - serviceKind(svc.Kind), - deployedVersion(svc), - humanize.Time(svc.CreatedAt), - lastDeployed(svc), - strings.Join(svc.Domains, " "), - }, "\t")) - } - tw.Flush() - return nil + return result(services, func(w io.Writer) error { + tw := tabwriter.NewWriter(w, 0, 0, 1, ' ', 0) + fmt.Fprintln(tw, "NAME\tKIND\tVERSION\tCREATED\tLAST DEPLOYED\tDOMAINS") + for _, svc := range services { + fmt.Fprintln(tw, strings.Join([]string{ + svc.Name, + serviceKind(svc.Kind), + deployedVersion(svc), + humanize.Time(svc.CreatedAt), + lastDeployed(svc), + strings.Join(svc.Domains, " "), + }, "\t")) + } + tw.Flush() + return nil + }) }), } @@ -156,7 +161,11 @@ var serviceLogsCmd = &cobra.Command{ if err != nil { return err } - return client.StreamServiceLogs(cfg.Project(), cfg.Service(), os.Stdout, serviceLogsFollow, serviceLogsTail, serviceLogsLines) + w, flush := logOutput() + if err := client.StreamServiceLogs(cfg.Project(), cfg.Service(), w, serviceLogsFollow, serviceLogsTail, serviceLogsLines); err != nil { + return err + } + return flush() }), } @@ -175,7 +184,10 @@ var serviceDisableCmd = &cobra.Command{ if err != nil { return err } - return client.ChangeServiceStatus(cfg.Project(), cfg.Service(), true) + if err := client.ChangeServiceStatus(cfg.Project(), cfg.Service(), true); err != nil { + return err + } + return result(serviceStatus{cfg.Project(), cfg.Service(), true}, func(io.Writer) error { return nil }) }), } @@ -194,10 +206,19 @@ var serviceEnableCmd = &cobra.Command{ if err != nil { return err } - return enableService(client, cfg.Project(), cfg.Service(), os.Stderr) + if err := enableService(client, cfg.Project(), cfg.Service(), os.Stderr); err != nil { + return err + } + return result(serviceStatus{cfg.Project(), cfg.Service(), false}, func(io.Writer) error { return nil }) }), } +type serviceStatus struct { + Project string `json:"project"` + Service string `json:"service"` + Disabled bool `json:"disabled"` +} + // enableRetryWindow bounds how long enabling retries while the platform still // stops the instances of an earlier disable, which it answers with 409. var enableRetryWindow = 2 * time.Minute @@ -245,12 +266,16 @@ var serviceURLCmd = &cobra.Command{ } urls := serviceURLs(project, svc) if len(urls) == 0 { - return fmt.Errorf("service %s has no domains yet; it gets them with its first deployment", service) + return newError(kindNotFound, "service %s has no domains yet; it gets them with its first deployment", service) } - fmt.Println(strings.Join(urls, "\n")) - return nil + return result(struct { + URLs []string `json:"urls"` + }{urls}, func(w io.Writer) error { + _, err := fmt.Fprintln(w, strings.Join(urls, "\n")) + return err + }) } - return fmt.Errorf("service %s not found", service) + return newError(kindNotFound, "service %s not found", service) }), } diff --git a/config/context.go b/config/context.go index 2681116..a557187 100644 --- a/config/context.go +++ b/config/context.go @@ -84,12 +84,12 @@ type envOverrides struct { } type CLIConfig struct { - Version string `yaml:"version"` - ActiveContext string `yaml:"activeContext"` - Endpoints map[string]APIEndpoint `yaml:"endpoints"` - Contexts map[string]CLIContext `yaml:"contexts"` + Version string `yaml:"version" json:"version"` + ActiveContext string `yaml:"activeContext" json:"activeContext"` + Endpoints map[string]APIEndpoint `yaml:"endpoints" json:"endpoints"` + Contexts map[string]CLIContext `yaml:"contexts" json:"contexts"` - Path string `yaml:"-"` + Path string `yaml:"-" json:"-"` env envOverrides } @@ -100,8 +100,7 @@ func (cfg *CLIConfig) Token() string { } token := cfg.Endpoints[cfg.Contexts[cfg.ActiveContext].Endpoint].Token if len(token) == 0 { - fmt.Fprintln(os.Stderr, "Operation requires valid endpoint token.") - os.Exit(1) + Abort("Operation requires valid endpoint token.") } return token } @@ -115,8 +114,7 @@ func (cfg *CLIConfig) Endpoint() string { return DefaultEndpoint } if len(url) == 0 { - fmt.Fprintln(os.Stderr, "Operation requires valid endpoint URL.") - os.Exit(1) + Abort("Operation requires valid endpoint URL.") } return url } @@ -127,8 +125,7 @@ func (cfg *CLIConfig) Project() string { } project := cfg.Contexts[cfg.ActiveContext].Project if len(project) == 0 { - fmt.Fprintln(os.Stderr, "Operation requires valid context project.") - os.Exit(1) + Abort("Operation requires valid context project.") } return project } @@ -150,11 +147,11 @@ func (cfg *CLIConfig) Write() error { } type APIEndpoint struct { - Token string `yaml:"token"` - URL string `yaml:"url"` + Token string `yaml:"token" json:"token"` + URL string `yaml:"url" json:"url"` } type CLIContext struct { - Endpoint string `yaml:"endpoint"` - Project string `yaml:"project"` + Endpoint string `yaml:"endpoint" json:"endpoint"` + Project string `yaml:"project" json:"project"` } diff --git a/config/schema.go b/config/schema.go new file mode 100644 index 0000000..4cf2953 --- /dev/null +++ b/config/schema.go @@ -0,0 +1,162 @@ +package config + +import ( + "fmt" + "reflect" + "sort" + "strings" + + "gopkg.in/yaml.v3" +) + +// Error is an invalid service configuration file. +type Error struct { + Path string + Err error +} + +func (e *Error) Error() string { return e.Err.Error() } +func (e *Error) Unwrap() error { return e.Err } + +// Schema returns the JSON Schema of .valar.yml, derived from ServiceConfigYAML. +func Schema() map[string]any { + schema := schemaOf(reflect.TypeOf(ServiceConfigYAML{})) + schema["$schema"] = "https://json-schema.org/draft/2020-12/schema" + schema["title"] = "Valar service configuration (.valar.yml)" + return schema +} + +func (EnvironmentConfig) jsonSchema() map[string]any { + return map[string]any{ + "oneOf": []any{ + map[string]any{ + "type": "string", + "pattern": "^[^=]+=", + "description": "A plain variable as KEY=VALUE.", + }, + map[string]any{ + "type": "object", + "additionalProperties": false, + "properties": map[string]any{ + "key": map[string]any{"type": "string"}, + "value": map[string]any{"type": "string"}, + "secret": map[string]any{"type": "boolean"}, + }, + }, + }, + } +} + +type schemaProvider interface{ jsonSchema() map[string]any } + +func schemaOf(t reflect.Type) map[string]any { + if p, ok := reflect.Zero(t).Interface().(schemaProvider); ok { + return p.jsonSchema() + } + switch t.Kind() { + case reflect.Pointer: + schema := schemaOf(t.Elem()) + schema["type"] = []any{schema["type"], "null"} + return schema + case reflect.Slice: + return map[string]any{"type": []any{"array", "null"}, "items": schemaOf(t.Elem())} + case reflect.String: + return map[string]any{"type": "string"} + case reflect.Bool: + return map[string]any{"type": "boolean"} + case reflect.Struct: + props := map[string]any{} + for i := 0; i < t.NumField(); i++ { + field := t.Field(i) + name, _, _ := strings.Cut(field.Tag.Get("yaml"), ",") + if !field.IsExported() || name == "-" || name == "" { + continue + } + prop := schemaOf(field.Type) + if doc := field.Tag.Get("doc"); doc != "" { + prop["description"] = doc + } + if strings.HasPrefix(field.Tag.Get("doc"), "Deprecated") { + prop["deprecated"] = true + } + props[name] = prop + } + return map[string]any{"type": "object", "additionalProperties": false, "properties": props} + } + panic(fmt.Sprintf("no schema for %s", t)) +} + +// validate refuses keys that schema does not know. Value types are left to +// the decoder. +func validate(doc *yaml.Node, schema map[string]any) error { + if doc.Kind == yaml.DocumentNode && len(doc.Content) == 1 { + return validateNode(doc.Content[0], schema, "") + } + return nil +} + +func validateNode(node *yaml.Node, schema map[string]any, at string) error { + if node.Kind == yaml.AliasNode { + node = node.Alias + } + if branches, ok := schema["oneOf"].([]any); ok { + for _, branch := range branches { + b := branch.(map[string]any) + if (node.Kind == yaml.MappingNode) == (b["type"] == "object") { + return validateNode(node, b, at) + } + } + return nil + } + switch node.Kind { + case yaml.MappingNode: + props, ok := schema["properties"].(map[string]any) + if !ok { + return nil + } + for i := 0; i+1 < len(node.Content); i += 2 { + key, value := node.Content[i], node.Content[i+1] + if key.Value == "<<" { + continue + } + prop, known := props[key.Value].(map[string]any) + if !known { + return unknownKeyError(key, at, props) + } + if err := validateNode(value, prop, join(at, key.Value)); err != nil { + return err + } + } + case yaml.SequenceNode: + items, ok := schema["items"].(map[string]any) + if !ok { + return nil + } + for i, item := range node.Content { + if err := validateNode(item, items, fmt.Sprintf("%s[%d]", at, i)); err != nil { + return err + } + } + } + return nil +} + +func unknownKeyError(key *yaml.Node, at string, props map[string]any) error { + known := make([]string, 0, len(props)) + for name := range props { + known = append(known, name) + } + sort.Strings(known) + where := "at the top level" + if at != "" { + where = "in " + at + } + return fmt.Errorf("line %d: unknown key %q %s, known keys are %s", key.Line, key.Value, where, strings.Join(known, ", ")) +} + +func join(at, key string) string { + if at == "" { + return key + } + return at + "." + key +} diff --git a/config/schema_test.go b/config/schema_test.go new file mode 100644 index 0000000..4030caa --- /dev/null +++ b/config/schema_test.go @@ -0,0 +1,96 @@ +package config + +import ( + "bytes" + "encoding/json" + "errors" + "flag" + "os" + "path/filepath" + "strings" + "testing" +) + +var update = flag.Bool("update", false, "rewrite schema/valar.yml.json") + +const schemaPath = "../schema/valar.yml.json" + +// TestSchema_MatchesCheckedInFile keeps schema/valar.yml.json in step with the +// config types. Regenerate it with: go test ./config -run TestSchema -update +func TestSchema_MatchesCheckedInFile(t *testing.T) { + var buf bytes.Buffer + enc := json.NewEncoder(&buf) + enc.SetEscapeHTML(false) + enc.SetIndent("", " ") + if err := enc.Encode(Schema()); err != nil { + t.Fatal(err) + } + if *update { + if err := os.WriteFile(schemaPath, buf.Bytes(), 0o644); err != nil { + t.Fatal(err) + } + } + want, err := os.ReadFile(schemaPath) + if err != nil { + t.Fatal(err) + } + if !bytes.Equal(buf.Bytes(), want) { + t.Errorf("%s is out of date, run: go test ./config -run TestSchema -update", schemaPath) + } +} + +func TestReadFromFile_Validation(t *testing.T) { + for _, tc := range []struct { + Name string + Config string + WantErr string + }{ + {"Minimal", "project: p\nservice: s\n", ""}, + {"Full", `project: p +service: s +build: + constructor: go + ignore: [.git] + environment: + - A=1 + - key: B + value: "2" + secret: true +deployment: + skip: false + environment: [] +`, ""}, + // Deprecated lists stay accepted; pushes warn about them. + {"DeprecatedEnvironment", "project: p\nservice: s\ndeployment:\n environment:\n - A=1\n", ""}, + {"NullSections", "project: p\nservice: s\nbuild:\ndeployment:\n", ""}, + {"UnknownTopLevel", "project: p\nservice: s\nregion: eu\n", `line 3: unknown key "region" at the top level`}, + {"UnknownInBuild", "project: p\nbuild:\n constructr: go\n", `line 3: unknown key "constructr" in build`}, + {"UnknownInEnvEntry", "build:\n environment:\n - key: A\n val: x\n", `line 4: unknown key "val" in build.environment[0]`}, + } { + t.Run(tc.Name, func(t *testing.T) { + dir := t.TempDir() + path := filepath.Join(dir, ".valar.yml") + if err := os.WriteFile(path, []byte(tc.Config), 0o644); err != nil { + t.Fatal(err) + } + t.Chdir(dir) + var cfg ServiceConfigYAML + err := cfg.ReadFromFile(".valar.yml") + if tc.WantErr == "" { + if err != nil { + t.Fatalf("ReadFromFile: %v", err) + } + return + } + var cfgErr *Error + if !errors.As(err, &cfgErr) { + t.Fatalf("got %v, want a *config.Error", err) + } + for _, want := range []string{path, tc.WantErr} { + if !strings.Contains(err.Error(), want) { + t.Errorf("error %q lacks %q", err, want) + } + } + }) + } +} diff --git a/config/service.go b/config/service.go index fcc6405..c0cf2de 100644 --- a/config/service.go +++ b/config/service.go @@ -11,8 +11,9 @@ import ( ) type EnvironmentConfig struct { - Key, Value string - Secret bool + Key string `json:"key"` + Value string `json:"value"` + Secret bool `json:"secret"` } func (e *EnvironmentConfig) MarshalYAML() (interface{}, error) { @@ -58,14 +59,21 @@ func (e *EnvironmentConfig) UnmarshalYAML(value *yaml.Node) error { } type BuildConfig struct { - Constructor string `yaml:"constructor,omitempty"` - Ignore []string `yaml:"ignore"` - Environment []EnvironmentConfig `yaml:"environment"` + Constructor string `yaml:"constructor,omitempty" json:"constructor" doc:"Constructor that builds the service, such as go, node, python, static or docker."` + Ignore []string `yaml:"ignore" json:"ignore" doc:"Path prefixes, relative to the pushed folder, left out of the upload."` + Environment []EnvironmentConfig `yaml:"environment" json:"environment" doc:"Deprecated: build variables are stored by the platform, see 'valar env'. Move them with 'valar env import'."` } type DeploymentConfig struct { - Skip bool `yaml:"skip"` - Environment []EnvironmentConfig `yaml:"environment"` + Skip bool `yaml:"skip" json:"skip" doc:"Build without deploying."` + Environment []EnvironmentConfig `yaml:"environment" json:"environment" doc:"Deprecated: runtime variables are stored by the platform, see 'valar env'. Move them with 'valar env import'."` +} + +// Abort reports a missing setting and ends the process. The CLI replaces it to +// apply its exit codes and output format. +var Abort = func(msg string) { + fmt.Fprintln(os.Stderr, msg) + os.Exit(1) } type ServiceConfig interface { @@ -81,32 +89,28 @@ type ValidatedServiceConfig struct { func (w *ValidatedServiceConfig) Project() string { if w.yaml.Project == "" { - fmt.Fprintln(os.Stderr, "Operation requires service project.") - os.Exit(1) + Abort("Operation requires service project.") } return w.yaml.Project } func (w *ValidatedServiceConfig) Service() string { if w.yaml.Service == "" { - fmt.Fprintln(os.Stderr, "Operation requires service reference (may be specified using --service).") - os.Exit(1) + Abort("Operation requires service reference (may be specified using --service).") } return w.yaml.Service } func (w *ValidatedServiceConfig) Build() BuildConfig { if w.yaml.Build == nil { - fmt.Fprintln(os.Stderr, "Operation requires build specification.") - os.Exit(1) + Abort("Operation requires build specification.") } return *w.yaml.Build } func (w *ValidatedServiceConfig) Deployment() DeploymentConfig { if w.yaml.Deployment == nil { - fmt.Fprintln(os.Stderr, "Operation requires deployment specification.") - os.Exit(1) + Abort("Operation requires deployment specification.") } return *w.yaml.Deployment } @@ -143,12 +147,12 @@ func NewServiceConfigWithFallback(path string, service *string, cli *CLIConfig) } type ServiceConfigYAML struct { - Project string `yaml:"project,omitempty"` - Service string `yaml:"service,omitempty"` - Build *BuildConfig `yaml:"build"` - Deployment *DeploymentConfig `yaml:"deployment"` + Project string `yaml:"project,omitempty" json:"project" doc:"Project the service belongs to."` + Service string `yaml:"service,omitempty" json:"service" doc:"Name of the service."` + Build *BuildConfig `yaml:"build" json:"build" doc:"How the service is built."` + Deployment *DeploymentConfig `yaml:"deployment" json:"deployment" doc:"How builds are deployed."` - filePath string `yaml:"-"` + filePath string } func (config *ServiceConfigYAML) ReadFromFile(name string) error { @@ -167,9 +171,15 @@ func (config *ServiceConfigYAML) ReadFromFile(name string) error { continue } defer fd.Close() - decoder := yaml.NewDecoder(fd) - if err := decoder.Decode(config); err != nil { - return fmt.Errorf("config read: %w", err) + var doc yaml.Node + if err := yaml.NewDecoder(fd).Decode(&doc); err != nil { + return &Error{Path: path, Err: fmt.Errorf("config read: %w", err)} + } + if err := validate(&doc, Schema()); err != nil { + return &Error{Path: path, Err: fmt.Errorf("%s: %w", path, err)} + } + if err := doc.Decode(config); err != nil { + return &Error{Path: path, Err: fmt.Errorf("config read: %w", err)} } config.filePath = path return nil diff --git a/schema/valar.yml.json b/schema/valar.yml.json new file mode 100644 index 0000000..fe017c4 --- /dev/null +++ b/schema/valar.yml.json @@ -0,0 +1,118 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "properties": { + "build": { + "additionalProperties": false, + "description": "How the service is built.", + "properties": { + "constructor": { + "description": "Constructor that builds the service, such as go, node, python, static or docker.", + "type": "string" + }, + "environment": { + "deprecated": true, + "description": "Deprecated: build variables are stored by the platform, see 'valar env'. Move them with 'valar env import'.", + "items": { + "oneOf": [ + { + "description": "A plain variable as KEY=VALUE.", + "pattern": "^[^=]+=", + "type": "string" + }, + { + "additionalProperties": false, + "properties": { + "key": { + "type": "string" + }, + "secret": { + "type": "boolean" + }, + "value": { + "type": "string" + } + }, + "type": "object" + } + ] + }, + "type": [ + "array", + "null" + ] + }, + "ignore": { + "description": "Path prefixes, relative to the pushed folder, left out of the upload.", + "items": { + "type": "string" + }, + "type": [ + "array", + "null" + ] + } + }, + "type": [ + "object", + "null" + ] + }, + "deployment": { + "additionalProperties": false, + "description": "How builds are deployed.", + "properties": { + "environment": { + "deprecated": true, + "description": "Deprecated: runtime variables are stored by the platform, see 'valar env'. Move them with 'valar env import'.", + "items": { + "oneOf": [ + { + "description": "A plain variable as KEY=VALUE.", + "pattern": "^[^=]+=", + "type": "string" + }, + { + "additionalProperties": false, + "properties": { + "key": { + "type": "string" + }, + "secret": { + "type": "boolean" + }, + "value": { + "type": "string" + } + }, + "type": "object" + } + ] + }, + "type": [ + "array", + "null" + ] + }, + "skip": { + "description": "Build without deploying.", + "type": "boolean" + } + }, + "type": [ + "object", + "null" + ] + }, + "project": { + "description": "Project the service belongs to.", + "type": "string" + }, + "service": { + "description": "Name of the service.", + "type": "string" + } + }, + "title": "Valar service configuration (.valar.yml)", + "type": "object" +}