Documentation
¶
Overview ¶
Package deprecation — G4: sunset date computation for per-plugin API entries.
Package deprecation — G7: client-side plugin compatibility checker. CheckPluginCompat is called during nself start to warn when installed plugin versions are below or at a version that has deprecated endpoints.
Package deprecation provides the CLI deprecation warning system.
Usage:
reg, err := deprecation.LoadRegistry("internal/deprecation/registry.yaml")
if err != nil {
// warn in debug log, do not crash
}
if item, ok := reg.Lookup("nself old-cmd"); ok {
reg.Warn(os.Stderr, item)
}
Index ¶
- func HTTPSunsetHeader(removedIn string) string
- func PrintWarnings(w io.Writer, warnings []Warning)
- func Warn(w io.Writer, name, since, replacement, docsURL string)
- type InstalledPlugin
- type Item
- type ItemType
- type PluginEndpoint
- type PluginEntry
- type PluginRegistry
- type Registry
- type SunsetCalendarEntry
- type Warning
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HTTPSunsetHeader ¶ added in v1.0.12
HTTPSunsetHeader formats a Sunset HTTP header value for the given removal version. Returns an empty string if removedIn is empty.
func PrintWarnings ¶ added in v1.0.12
PrintWarnings writes all warnings to w, one per line.
Types ¶
type InstalledPlugin ¶ added in v1.0.12
InstalledPlugin is the caller-supplied record for an installed plugin.
type Item ¶
type Item struct {
Name string `yaml:"name"`
Type ItemType `yaml:"type"`
Since string `yaml:"since"`
Replacement string `yaml:"replacement"`
DocsURL string `yaml:"docs_url"`
Phase int `yaml:"phase"`
}
Item represents a single deprecated CLI element.
type PluginEndpoint ¶ added in v1.0.12
type PluginEndpoint struct {
Path string `yaml:"path"`
DeprecatedIn string `yaml:"deprecated_in"`
RemovedIn string `yaml:"removed_in"`
Replacement string `yaml:"replacement"`
Reason string `yaml:"reason"`
}
PluginEndpoint represents a single deprecated HTTP endpoint within a plugin.
type PluginEntry ¶ added in v1.0.12
type PluginEntry struct {
Name string `yaml:"name"`
APIVersion string `yaml:"api_version"`
DeprecatedEndpoints []PluginEndpoint `yaml:"deprecated_endpoints"`
}
PluginEntry represents a single plugin's API version entry in registry.yaml.
type PluginRegistry ¶ added in v1.0.12
type PluginRegistry struct {
// contains filtered or unexported fields
}
PluginRegistry holds the per-plugin versioning entries loaded from registry.yaml.
func LoadPluginRegistry ¶ added in v1.0.12
func LoadPluginRegistry(path string) (*PluginRegistry, error)
LoadPluginRegistry reads the plugins section from the registry YAML file. Returns an empty PluginRegistry (not nil) on any error.
func (*PluginRegistry) AllPlugins ¶ added in v1.0.12
func (pr *PluginRegistry) AllPlugins() []PluginEntry
AllPlugins returns all plugin entries sorted by name.
func (*PluginRegistry) LookupPlugin ¶ added in v1.0.12
func (pr *PluginRegistry) LookupPlugin(name string) (PluginEntry, bool)
LookupPlugin returns the PluginEntry for the given plugin name and true if found.
func (*PluginRegistry) SunsetDate ¶ added in v1.0.12
func (pr *PluginRegistry) SunsetDate(pluginName string) []SunsetCalendarEntry
SunsetDate returns the SunsetCalendarEntries for a plugin, sorted by RemovedIn. If the plugin is not found in the registry, it returns nil.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds the loaded deprecation entries.
func LoadRegistry ¶
LoadRegistry reads the YAML registry file and returns a Registry. If the file does not exist or fails to parse, it returns an empty Registry and a non-nil error (caller should log in debug mode, not crash).
func (*Registry) IsDeprecated ¶
IsDeprecated returns true if the given name is in the registry.
type SunsetCalendarEntry ¶ added in v1.0.12
type SunsetCalendarEntry struct {
Plugin string
Path string
DeprecatedIn string
RemovedIn string
Replacement string
Reason string
SunsetDate time.Time // zero value when not applicable
}
SunsetCalendarEntry is one row in the human-readable sunset calendar for a plugin.
type Warning ¶ added in v1.0.12
type Warning struct {
Plugin string
InstalledVersion string
Path string
DeprecatedIn string
RemovedIn string
Replacement string
Docs string
}
Warning is a single compatibility warning emitted by CheckPluginCompat.
func CheckPluginCompat ¶ added in v1.0.12
func CheckPluginCompat(installed []InstalledPlugin, reg *PluginRegistry) []Warning
CheckPluginCompat compares each installed plugin's version against the registry. It returns warnings for every deprecated endpoint where the installed version is greater than or equal to the version where the deprecation was introduced.
Version comparison is done lexicographically on the SemVer strings. This is accurate for well-formed SemVer within the same major version (which all nSelf plugins are expected to be during the v1.x lifecycle).