resolver

Documentation

Index

• Variables
• func SaveLockFile(w io.Writer, lockFile *LockFile) error
• func SaveLockFileTo(path string, lockFile *LockFile) error
• type Checksum
  • func (c Checksum) Compare(other Checksum) int
  • func (c Checksum) MarshalJSON() ([]byte, error)
  • func (c Checksum) MarshalText() ([]byte, error)
  • func (c Checksum) Match(list []Checksum) bool
  • func (c Checksum) String() string
  • func (c *Checksum) UnmarshalJSON(data []byte) error
  • func (c *Checksum) UnmarshalText(data []byte) error
• type ConstraintMap
  • func ParseConstraintMap(src map[string]string) (ConstraintMap, error)
• type LocalSource
  • func (source LocalSource) Lookup(ctx context.Context, name Name) ([]Version, error)
  • func (source LocalSource) Resolve(ctx context.Context, name Name, version Version, checksums []Checksum) (*ResolvedPlugin, error)
• type LockCheckResult
  • func (result LockCheckResult) IsInstallRequired() bool
• type LockFile
  • func ReadLockFile(r io.Reader) (*LockFile, error)
  • func ReadLockFileFrom(path string) (*LockFile, error)
  • func (file *LockFile) Check(constraints ConstraintMap) LockCheckResult
• type Name
  • func ParseName(name string) (Name, error)
  • func (n Name) Compare(other Name) int
  • func (n Name) MarshalJSON() ([]byte, error)
  • func (n Name) Namespace() string
  • func (n Name) Short() string
  • func (n Name) String() string
  • func (n *Name) UnmarshalJSON(data []byte) error
• type Option
  • func WithLogger(logger *slog.Logger) Option
  • func WithSources(sources ...Source) Option
• type PluginLock
• type RemoteSource
  • func (source RemoteSource) Lookup(ctx context.Context, name Name) ([]Version, error)
  • func (source RemoteSource) Resolve(ctx context.Context, name Name, version Version, checksums []Checksum) (*ResolvedPlugin, error)
• type ResolvedPlugin
• type Resolver
  • func NewResolver(constraints map[string]string, opts ...Option) (*Resolver, hcl.Diagnostics)
  • func (r *Resolver) Install(ctx context.Context, lockFile *LockFile, upgrade bool) (*LockFile, hcl.Diagnostics)
  • func (r *Resolver) Resolve(ctx context.Context, lockFile *LockFile) (map[string]string, hcl.Diagnostics)
• type Source
• type Version
  • func (v Version) Compare(other Version) int
  • func (v *Version) UnmarshalJSON(data []byte) error

Variables

var ErrPluginNotFound = fmt.Errorf("plugin not found")

ErrPluginNotFound is returned when a plugin is not found in the source.

Functions

func SaveLockFile

func SaveLockFile(w io.Writer, lockFile *LockFile) error

SaveLockFile saves a lock configuration to a writer.

func SaveLockFileTo

func SaveLockFileTo(path string, lockFile *LockFile) error

SaveLockFileTo saves a lock configuration to a local file.

Types

type Checksum

type Checksum struct {
	Object string
	OS     string
	Arch   string
	Sum    []byte
}

Checksum for plugin binaries and archives. It contains the object name, os, arch, and the hash sum value.

Format in string: '<object>:<os>:<arch>:<base64-sha256-sum>'.

Example: 'archive:darwin:arm64:lgNgp5LO81yt1boBsiaNsJCzLWD9r5ovW+el5k/dDZ8='.

func (Checksum) Compare

func (c Checksum) Compare(other Checksum) int

func (Checksum) MarshalJSON

func (c Checksum) MarshalJSON() ([]byte, error)

func (Checksum) MarshalText

func (c Checksum) MarshalText() ([]byte, error)

func (Checksum) Match

func (c Checksum) Match(list []Checksum) bool

func (Checksum) String

func (c Checksum) String() string

func (*Checksum) UnmarshalJSON

func (c *Checksum) UnmarshalJSON(data []byte) error

func (*Checksum) UnmarshalText

func (c *Checksum) UnmarshalText(data []byte) error

type ConstraintMap

type ConstraintMap map[Name]*semver.Constraints

ConstraintMap is a map of plugin names to version constraints.

func ParseConstraintMap

func ParseConstraintMap(src map[string]string) (ConstraintMap, error)

ParseConstraintMap parses string map into a PluginConstraintMap.

type LocalSource

type LocalSource struct {
	// Path is the root directory to look up plugins.
	Path string
}

LocalSource is a plugin source that looks up plugins from a local directory. The directory structure should be:

"<path>/<namespace>/<shortname>@<version>"

For example with the path ".fabric/plugins" plugin name "blackstork/sqlite" and version "1.0.0":

".fabric/plugins/blackstork/sqlite@1.0.0"

File checksums can be provided in a file with the same name as the plugin binary but with a "_checksums.txt" suffix. The file should contain a list of checksums for all supported platforms.

func (LocalSource) Lookup

func (source LocalSource) Lookup(ctx context.Context, name Name) ([]Version, error)

Lookup returns the versions found of the plugin with the given name.

func (LocalSource) Resolve

func (source LocalSource) Resolve(ctx context.Context, name Name, version Version, checksums []Checksum) (*ResolvedPlugin, error)

Resolve returns the binary path and checksum for the given plugin version.

type LockCheckResult

type LockCheckResult struct {
	Missing  ConstraintMap
	Mismatch ConstraintMap
	Removed  map[Name]Version
}

LockCheckResult is the result of a lock check.

func (LockCheckResult) IsInstallRequired

func (result LockCheckResult) IsInstallRequired() bool

IsInstallRequired returns true if the lock check result requires an install.

type LockFile

type LockFile struct {
	Plugins []PluginLock `json:"plugins"`
}

LockFile is a plugin lock configuration.

func ReadLockFile

func ReadLockFile(r io.Reader) (*LockFile, error)

ReadLockFile parses a lock configuration from a reader.

func ReadLockFileFrom

func ReadLockFileFrom(path string) (*LockFile, error)

ReadLockFileFrom parses a lock configuration from a local file.

func (*LockFile) Check

func (file *LockFile) Check(constraints ConstraintMap) LockCheckResult

Check the lock configuration against the given constraints.

type Name

type Name [2]string

Name of a plugin structured as '<namespace>/<name>'.

func ParseName

func ParseName(name string) (Name, error)

ParseName parses a plugin name from '<namespace>/<name>' format.

func (Name) Compare

func (n Name) Compare(other Name) int

Compare compares the plugin name with another plugin name.

func (Name) MarshalJSON

func (n Name) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON representation of the plugin name in '<namespace>/<name>' format.

func (Name) Namespace

func (n Name) Namespace() string

Namespace returns the namespace part of the plugin name.

func (Name) Short

func (n Name) Short() string

Short returns the short name part of the plugin name.

func (Name) String

func (n Name) String() string

String returns the full plugin name in the form '<namespace>/<name>'.

func (*Name) UnmarshalJSON

func (n *Name) UnmarshalJSON(data []byte) error

UnmarshalJSON parses a JSON string into a PluginName from '<namespace>/<name>' format.

type Option

type Option func(*options)

Option is a functional option for the resolver.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger sets the logger for the resolver.

func WithSources

func WithSources(sources ...Source) Option

WithSources sets the sources for the resolver.

type PluginLock

type PluginLock struct {
	Name      Name       `json:"name"`
	Version   Version    `json:"version"`
	Checksums []Checksum `json:"checksums"`
}

PluginLock is a lock for a one plugin.

type RemoteSource

type RemoteSource struct {
	// BaseURL is the base URL of the registry.
	BaseURL string
	// DownloadDir is the directory where the plugins are downloaded.
	DownloadDir string
	// UserAgent is the http user agent to use for the requests.
	// Useful for debugging and statistics on the registry side.
	UserAgent string
}

RemoteSource is a plugin source that looks up plugins from a remote registry. The registry should implement the Fabric Registry API.

func (RemoteSource) Lookup

func (source RemoteSource) Lookup(ctx context.Context, name Name) ([]Version, error)

Lookup returns the versions found of the plugin with the given name.

func (RemoteSource) Resolve

func (source RemoteSource) Resolve(ctx context.Context, name Name, version Version, checksums []Checksum) (*ResolvedPlugin, error)

Resolve returns the binary path and checksum for the given plugin version.

type ResolvedPlugin

type ResolvedPlugin struct {
	// BinaryPath for the current platform.
	BinaryPath string
	// Checksums is a list of checksums for the plugin including all supported platforms.
	Checksums []Checksum
}

ResolvedPlugin contains the binary path and checksum for a plugin.

type Resolver

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

Resolver resolves and installs plugins.

func NewResolver

func NewResolver(constraints map[string]string, opts ...Option) (*Resolver, hcl.Diagnostics)

NewResolver creates a new plugin resolver.

func (*Resolver) Install

func (r *Resolver) Install(ctx context.Context, lockFile *LockFile, upgrade bool) (*LockFile, hcl.Diagnostics)

Install all plugins based the version constraints and return updated a lock file.

func (*Resolver) Resolve

func (r *Resolver) Resolve(ctx context.Context, lockFile *LockFile) (map[string]string, hcl.Diagnostics)

Resolve all plugins based on the constraints and returns a map of plugin names to binary paths. If the lock file is not satisfied, an error is returned.

type Source

type Source interface {
	// Lookup returns a list of available versions for the given plugin.
	Lookup(ctx context.Context, name Name) ([]Version, error)
	// Resolve returns the binary path and checksums for the given plugin version.
	Resolve(ctx context.Context, name Name, version Version, checksums []Checksum) (*ResolvedPlugin, error)
}

Source is the interface for plugin sources. A source is responsible for listing, looking up, and resolving plugins. The source may use a local directory, a registry, or any other source. If the source is unable to find a plugin, it should return ErrPluginNotFound.

type Version

type Version struct {
	*semver.Version
}

Version is a version of a plugin. It is a wrapper around semver.Version with strict parsing.

func (Version) Compare

func (v Version) Compare(other Version) int

Compare compares the version with another version.

func (*Version) UnmarshalJSON

func (v *Version) UnmarshalJSON(data []byte) error

UnmarshalJSON parses a JSON string into a PluginVersion using strict semver parsing.