plugin

type Config interface {
	Validate() error
}

type Descriptor struct {
	// Name is the name of the plugin
	Name string
	// Type is the type of the plugin (cli, getter, postrenderer)
	Type string
}

type Downloaders struct {
	// Protocols are the list of schemes from the charts URL.
	Protocols []string `yaml:"protocols"`
	// Command is the executable path with which the plugin performs
	// the actual download for the corresponding Protocols
	Command string `yaml:"command"`
}

type ExtismV1PluginRuntime struct {
	// contains filtered or unexported fields
}

type Hooks map[string]string

type Input struct {
	// Message represents the type-elided value to be passed to the plugin.
	// The plugin is expected to interpret the message according to its type
	// The message object must be JSON-serializable
	Message any

	// Optional: Reader to be consumed plugin's "stdin"
	Stdin io.Reader

	// Optional: Writers to consume the plugin's "stdout" and "stderr"
	Stdout, Stderr io.Writer

	// Optional: Env represents the environment as a list of "key=value" strings
	// see os.Environ
	Env []string
}

type InvokeExecError struct {
	ExitCode int   // Exit code from plugin code execution
	Err      error // Underlying error
}

type Metadata struct {
	// APIVersion specifies the plugin API version
	APIVersion string

	// Name is the name of the plugin
	Name string

	// Type of plugin (eg, cli/v1, getter/v1, postrenderer/v1)
	Type string

	// Runtime specifies the runtime type (subprocess, wasm)
	Runtime string

	// Version is the SemVer 2 version of the plugin.
	Version string

	// SourceURL is the URL where this plugin can be found
	SourceURL string

	// Config contains the type-specific configuration for this plugin
	Config Config

	// RuntimeConfig contains the runtime-specific configuration
	RuntimeConfig RuntimeConfig
}

type MetadataLegacy struct {
	// Name is the name of the plugin
	Name string `yaml:"name"`

	// Version is a SemVer 2 version of the plugin.
	Version string `yaml:"version"`

	// Usage is the single-line usage text shown in help
	Usage string `yaml:"usage"`

	// Description is a long description shown in places like `helm help`
	Description string `yaml:"description"`

	// PlatformCommand is the plugin command, with a platform selector and support for args.
	PlatformCommand []PlatformCommand `yaml:"platformCommand"`

	// Command is the plugin command, as a single string.
	// DEPRECATED: Use PlatformCommand instead. Removed in subprocess/v1 plugins.
	Command string `yaml:"command"`

	// IgnoreFlags ignores any flags passed in from Helm
	IgnoreFlags bool `yaml:"ignoreFlags"`

	// PlatformHooks are commands that will run on plugin events, with a platform selector and support for args.
	PlatformHooks PlatformHooks `yaml:"platformHooks"`

	// Hooks are commands that will run on plugin events, as a single string.
	// DEPRECATED: Use PlatformHooks instead. Removed in subprocess/v1 plugins.
	Hooks Hooks `yaml:"hooks"`

	// Downloaders field is used if the plugin supply downloader mechanism
	// for special protocols.
	Downloaders []Downloaders `yaml:"downloaders"`
}

type MetadataV1 struct {
	// APIVersion specifies the plugin API version
	APIVersion string `yaml:"apiVersion"`

	// Name is the name of the plugin
	Name string `yaml:"name"`

	// Type of plugin (eg, cli/v1, getter/v1, postrenderer/v1)
	Type string `yaml:"type"`

	// Runtime specifies the runtime type (subprocess, wasm)
	Runtime string `yaml:"runtime"`

	// Version is a SemVer 2 version of the plugin.
	Version string `yaml:"version"`

	// SourceURL is the URL where this plugin can be found
	SourceURL string `yaml:"sourceURL,omitempty"`

	// Config contains the type-specific configuration for this plugin
	Config map[string]any `yaml:"config"`

	// RuntimeConfig contains the runtime-specific configuration
	RuntimeConfig map[string]any `yaml:"runtimeConfig"`
}

type Output struct {
	// Message represents the type-elided value returned from the plugin
	// The invoker is expected to interpret the message according to the plugin's type
	// The message object must be JSON-serializable
	Message any
}

type PlatformCommand struct {
	OperatingSystem string   `yaml:"os"`
	Architecture    string   `yaml:"arch"`
	Command         string   `yaml:"command"`
	Args            []string `yaml:"args"`
}

type PlatformHooks map[string][]PlatformCommand

type Plugin interface {
	// Dir return the plugin directory (as an absolute path) on the filesystem
	Dir() string

	// Metadata describes the plugin's type, version, etc.
	// (This metadata type is the converted and plugin version independented in-memory representation of the plugin.yaml file)
	Metadata() Metadata

	// Invoke takes the given input, and dispatches the contents to plugin instance
	// The input is expected to be a JSON-serializable object, which the plugin will interpret according to its type
	// The plugin is expected to return a JSON-serializable object, which the invoker
	// will interpret according to the plugin's type
	//
	// Invoke can be thought of as a request/response mechanism. Similar to e.g. http.RoundTripper
	//
	// If plugin's execution fails with a non-zero "return code" (this is plugin runtime implementation specific)
	// an InvokeExecError is returned
	Invoke(ctx context.Context, input *Input) (*Output, error)
}

type PluginHook interface {
	InvokeHook(event string) error
}

type Runtime interface {
	// CreatePlugin creates a plugin instance from the given metadata
	CreatePlugin(pluginDir string, metadata *Metadata) (Plugin, error)
}

type RuntimeConfig interface {
	Validate() error
}

type RuntimeConfigExtismV1 struct {
	// Describes the limits on the memory the plugin may be allocated.
	Memory RuntimeConfigExtismV1Memory `yaml:"memory"`

	// The "config" key is a free-form map that can be passed to the plugin.
	// The plugin must interpret arbitrary data this map may contain
	Config map[string]string `yaml:"config,omitempty"`

	// An optional set of hosts this plugin can communicate with.
	// This only has an effect if the plugin makes HTTP requests.
	// If not specified, then no hosts are allowed.
	AllowedHosts []string `yaml:"allowedHosts,omitempty"`

	FileSystem RuntimeConfigExtismV1FileSystem `yaml:"fileSystem,omitempty"`

	// The timeout in milliseconds for the plugin to execute
	Timeout uint64 `yaml:"timeout,omitempty"`

	// HostFunction names exposed in Helm the plugin may access
	// see: https://extism.org/docs/concepts/host-functions/
	HostFunctions []string `yaml:"hostFunctions,omitempty"`

	// The name of entry function name to call in the plugin
	// Defaults to "helm_plugin_main".
	EntryFuncName string `yaml:"entryFuncName,omitempty"`
}

type RuntimeConfigExtismV1FileSystem struct {
	// If specified, a temporary directory will be created and mapped to /tmp in the plugin's filesystem.
	// Data written to the directory will be visible on the host filesystem.
	// The directory will be removed when the plugin invocation completes.
	CreateTempDir bool `yaml:"createTempDir,omitempty"`
}

type RuntimeConfigExtismV1Memory struct {
	// The max amount of pages the plugin can allocate
	// One page is 64Kib. e.g. 16 pages would require 1MiB.
	// Default is 4 pages (256KiB)
	MaxPages uint32 `yaml:"maxPages,omitempty"`

	// The max size of an Extism HTTP response in bytes
	// Default is 4096 bytes (4KiB)
	MaxHTTPResponseBytes int64 `yaml:"maxHttpResponseBytes,omitempty"`

	// The max size of all Extism vars in bytes
	// Default is 4096 bytes (4KiB)
	MaxVarBytes int64 `yaml:"maxVarBytes,omitempty"`
}

type RuntimeConfigSubprocess struct {
	// PlatformCommand is a list containing a plugin command, with a platform selector and support for args.
	PlatformCommand []PlatformCommand `yaml:"platformCommand"`
	// PlatformHooks are commands that will run on plugin events, with a platform selector and support for args.
	PlatformHooks PlatformHooks `yaml:"platformHooks"`
	// ProtocolCommands allows the plugin to specify protocol specific commands
	//
	// Obsolete/deprecated: This is a compatibility hangover from the old plugin downloader mechanism, which was extended
	// to support multiple protocols in a given plugin. The command supplied in PlatformCommand should implement protocol
	// specific logic by inspecting the download URL
	ProtocolCommands []SubprocessProtocolCommand `yaml:"protocolCommands,omitempty"`
	// contains filtered or unexported fields
}

type RuntimeExtismV1 struct {
	HostFunctions    map[string]extism.HostFunction
	CompilationCache wazero.CompilationCache
}

type RuntimeSubprocess struct {
	EnvVars map[string]string
}

type SigningInfo struct {
	// Status can be:
	// - "local dev": Plugin is a symlink (development mode)
	// - "unsigned": No provenance file found
	// - "invalid provenance": Provenance file is malformed
	// - "mismatched provenance": Provenance file does not match the installed tarball
	// - "signed": Valid signature exists for the installed tarball
	Status   string
	IsSigned bool // True if plugin has a valid signature (even if not verified against keyring)
}

type SubprocessPluginRuntime struct {
	RuntimeConfig RuntimeConfigSubprocess
	EnvVars       map[string]string
	// contains filtered or unexported fields
}

type SubprocessProtocolCommand struct {
	// Protocols are the list of schemes from the charts URL.
	Protocols []string `yaml:"protocols"`
	// PlatformCommand is the platform based command which the plugin performs
	// to download for the corresponding getter Protocols.
	PlatformCommand []PlatformCommand `yaml:"platformCommand"`
}