jsonoutput

Documentation

Overview

Package jsonoutput provides stable and versioned JSON serialisation for CLI output. This allows us to provide stable output to scripts/clients, but also make breaking changes to the output when it's useful.

Historically we only used `--json` as a boolean flag, so changing the output could break scripts that rely on the existing format.

This package allows callers to pass a version number to `--json` and get a consistent output. We'll bump the version when we make a breaking change that's likely to break scripts that rely on the existing output, e.g. if we remove a field or change the type/format.

Passing just the boolean flag `--json` will always return v1, to preserve compatibility with scripts written before we versioned our output.

Index

• func PrintNetworkLockJSONV1(out io.Writer, updates []ipnstate.NetworkLockUpdate) error
• type JSONSchemaVersion
  • func (v *JSONSchemaVersion) IsBoolFlag() bool
  • func (v *JSONSchemaVersion) Set(s string) error
  • func (v *JSONSchemaVersion) String() string
• type ResponseEnvelope

Functions

func PrintNetworkLockJSONV1

func PrintNetworkLockJSONV1(out io.Writer, updates []ipnstate.NetworkLockUpdate) error

PrintNetworkLockJSONV1 prints the stored TKA state as a JSON object to the CLI, in a stable "v1" format.

This format includes:

• the AUM hash as a base32-encoded string
• the raw AUM as base64-encoded bytes
• the expanded AUM, which prints named fields for consumption by other tools

Types

type JSONSchemaVersion

type JSONSchemaVersion struct {
	// IsSet tracks if the flag was provided at all.
	IsSet bool

	// Value tracks the desired schema version, which defaults to 1 if
	// the user passes `--json` without an argument.
	Value int
}

JSONSchemaVersion implements flag.Value, and tracks whether the CLI has been called with `--json`, and if so, with what value.

func (*JSONSchemaVersion) IsBoolFlag

func (v *JSONSchemaVersion) IsBoolFlag() bool

IsBoolFlag tells the flag package that JSONSchemaVersion can be set without an argument.

func (*JSONSchemaVersion) Set

func (v *JSONSchemaVersion) Set(s string) error

Set is called when the user passes the flag as a command-line argument.

func (*JSONSchemaVersion) String

func (v *JSONSchemaVersion) String() string

String returns the default value which is printed in the CLI help text.

type ResponseEnvelope

type ResponseEnvelope struct {
	// SchemaVersion is the version of the JSON output, e.g. "1", "2", "3"
	SchemaVersion string

	// ResponseWarning tells a user if a newer version of the JSON output
	// is available.
	ResponseWarning string `json:"_WARNING,omitzero"`
}

ResponseEnvelope is a set of fields common to all versioned JSON output.