pkg

type AddOptions struct {
	// The edition to consider, if given.  Falls back to
	// [Options.Edition].
	Edition string

	// The version to install, if given.  Otherwise, the latest
	// version available will be used.
	Version string

	// If exists a older version of the plugin, remove it prior
	// to install this version.
	Upgrade bool

	// If exists a newer version of the plugin, remove it prior
	// to install this version.
	Downgrade bool

	// Remove other version of the plugin, even if it's the same,
	// and install this version.
	Replace bool

	// Don't fail if other versions of the same plugin exist.
	AllowMultipleVersions bool

	// If target does not point at a .ptar file, attempt to fetch
	// the pre-packaged plugin from the repository.
	ImplicitFetch bool

	// Install the package even if the OS and Architecture don't
	// match.
	AllowOSArchMismatch bool

	// Install the container flavor when fetching from the repository: the
	// package whose OS atom is OSContainer, carrying an image pin instead
	// of executables. Local .ptar files carry it in the filename instead.
	Container bool
}

type Artifact struct {
	Filename  string
	Package   *Package // nil for files that are not packages, such as a recipe
	Origin    string   // registry base URL, or LocalOrigin
	Signature []byte   // the .sum.sig, or nil if it shipped without one
}

type ArtifactKind int

type Backend interface {
	// List returns an iterator of plugin names,
	// e.g. s3_v1.0.0_openbsd_amd64.ptar, optionally filtered by
	// the given name, or an error.
	List(name string) iter.Seq2[*Package, error]

	// Load a plugin' ptar from the given reader. sig is the artifact's
	// signature, retained alongside it, or nil if it has none.
	Load(pkg *Package, rd io.Reader, sig []byte) error

	// Signature returns the retained signature of an installed package,
	// or nil if it was installed without one.
	Signature(*Package) ([]byte, error)

	// Unload a plugin
	Unload(*Package) error
}

type BuildOptions struct{}

type Connector struct {
	Type      string     `json:"type"` // importer, exporter, storage
	Protocols []Protocol `json:"protocols"`
	Class     string     `json:"class"`
	SubClass  string     `json:"subclass"`
	Validator any        `json:"validator"` // json schema
}

type CreateOptions struct{}

type DelOptions struct {
	// If target is the empty string, delete all the packages
	// installed.
	All bool

	// If version is not the empty string, delete only the given
	// version.  It's incompatible with All.
	Version string
}

type FetchOptions struct {
	// The edition to consider, if given.  Falls back to
	// [Options.Edition].
	Edition string
}

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

type FlatBackendOptions struct {
	PreLoadHook func(*Manifest) error

	// InstallHook runs once per package at install time, after the manifest
	// passed validation and before the package is enabled, giving the
	// consumer a chance to fulfill external prerequisites (e.g. pull the
	// the image for a container package). An error aborts the install.
	InstallHook func(*Manifest) error

	LoadHook   func(*Manifest, *Package, string)
	UnloadHook func(*Manifest, *Package)
}

type InstallError struct {
	Name       string       // requested package name, always set
	Package    *Package     // nil until the version is resolved
	Edition    string       // the resolved edition, empty for a local install
	Artifact   ArtifactKind // the file that failed
	URL        string       // where it was fetched from, or the local path
	StatusCode int          // 0 when there was no HTTP response
	Err        error
}

type Integration struct {
	Edition string `json:"edition"`
	API     string `json:"api"`

	Tier          string      `json:"tier"`
	Contact       string      `json:"contact"`
	Name          string      `json:"name"`
	DisplayName   string      `json:"display_name"`
	Description   string      `json:"description"`
	Homepage      string      `json:"homepage"`
	Repository    string      `json:"repository"`
	License       string      `json:"license"`
	Tags          []string    `json:"tags"`
	Version       string      `json:"version"` // integration version
	Connectors    []Connector `json:"connectors"`
	Documentation string      `json:"documentation"` // README.md
	Icon          string      `json:"icon"`          // assets/icon.{png,svg}
	Featured      string      `json:"featured"`      // assets/featured.{png,svg}

	Id            string                  `json:"id"`
	Types         IntegrationTypes        `json:"types"`
	Stage         string                  `json:"stage"`
	Installation  IntegrationInstallation `json:"installation"`
	LatestVersion string                  `json:"latest_version"`
}

type IntegrationIndex struct {
	Version      string        `json:"version"`
	Timestamp    time.Time     `json:"timestamp"`
	Integrations []Integration `json:"integrations"`
}

type IntegrationInstallation struct {
	Status    string `json:"status"`
	Version   string `json:"version,omitempty"`
	Available bool   `json:"available"`
}

type IntegrationTypes struct {
	Storage     bool `json:"storage"`
	Source      bool `json:"source"`
	Destination bool `json:"destination"`
	Provider    bool `json:"provider"`
}

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

type Manifest struct {
	Name        string   `yaml:"name"`
	DisplayName string   `yaml:"display_name"`
	Description string   `yaml:"description"`
	Tier        string   `yaml:"tier"`
	Contact     string   `yaml:"contact"`
	Homepage    string   `yaml:"homepage"`
	License     string   `yaml:"license"`
	Tags        []string `yaml:"tags"`
	APIVersion  string   `yaml:"api_version"`

	Connectors []ManifestConnector `yaml:"connectors"`
}

type ManifestConnector struct {
	Type          integration.ConnectorType    `yaml:"type"`
	Class         integration.ResourceClass    `yaml:"class,omitempty"`
	SubClass      integration.ResourceSubClass `yaml:"subclass,omitempty"`
	Validator     string                       `yaml:"validator,omitempty"`
	Protocols     []string                     `yaml:"protocols"`
	LocationFlags []string                     `yaml:"location_flags,omitempty"`
	Executable    string                       `yaml:"executable,omitempty"`
	Args          []string                     `yaml:"args,omitempty"`
	ExtraFiles    []string                     `yaml:"extra_files,omitempty"`

	// Containerized connectors carry an image pin instead of an executable.
	// ImageID is the sha256 of the image, filled at package creation time
	// following a docker build.
	// Image is registry reference to pull from when install pre-built packages.
	ImageID string `yaml:"image_id,omitempty"`
	Image   string `yaml:"image,omitempty"`
}

type Options struct {
	DistURL string
	Edition string // community, devel, enterprise, ...
	ApiURL  string

	// IndexURL is where [Manager.Query] fetches the integrations
	// index from, overriding the default location on the API
	// server.  A mirror of the distribution tree serves it at its
	// root, next to the edition directories.
	IndexURL        string
	BinaryNeedsAuth bool
	RequestHook     RequestHook

	// User agent name for network requests on the repository at
	// DistURL.  "(os/architecture)" will be appended implicitly.
	UserAgent string

	// Verifier decides whether an artifact may be installed. When nil,
	// nothing is verified and no signature is fetched.
	Verifier Verifier
}

type Package struct {
	Name            string
	Version         string
	Architecture    string
	OperatingSystem string
}

type Protocol struct {
	Scheme    string `json:"scheme"`    // sftp, s3, http, ...
	Validator any    `json:"validator"` // json schema, override connector schema if defined
}

type QueryOptions struct {
	Type    string
	Tag     string
	Status  string
	Edition string

	OnlyLocal bool
}

type Recipe struct {
	Name       string `yaml:"name"`
	Version    string `yaml:"version"`
	Repository string `yaml:"repository"`
}

type RequestHook func(*http.Request) error

type Verifier interface {
	Verify(artifact *Artifact, rd io.Reader) error
}

type VerifierFunc func(artifact *Artifact, rd io.Reader) error