winget

Documentation

Overview

Package winget provides a client for programmatic access to WinGet package metadata from the microsoft/winget-pkgs repository.

Index

• Variables
• func IsCloneFailed(err error) bool
• func IsIndexBuildFailed(err error) bool
• func IsNotFound(err error) bool
• func IsPullFailed(err error) bool
• type Client
  • func NewClient(cfg *config.Config, opts ...ClientOption) (*Client, error)
  • func NewClientWithExecutor(cfg *config.Config, exec executor.Executor) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) Refresh(ctx context.Context) error
• type ClientOption
  • func WithAutoRefresh(interval time.Duration) ClientOption
  • func WithCacheDir(dir string) ClientOption
  • func WithCloneDepth(depth int) ClientOption
  • func WithLogger(logger *zap.Logger) ClientOption
  • func WithRepoURL(url string) ClientOption
  • func WithTimeout(d time.Duration) ClientOption
  • func WithWorkerCount(n int) ClientOption

Variables

var (
	// ErrCloneFailed is returned when the initial repository clone fails.
	ErrCloneFailed = errors.New("repository clone failed")

	// ErrPullFailed is returned when a git pull / refresh operation fails.
	ErrPullFailed = errors.New("repository pull failed")

	// ErrIndexBuildFailed is returned when building the in-memory index fails.
	ErrIndexBuildFailed = errors.New("index build failed")
)

Sentinel errors for client-level failures.

Functions

func IsCloneFailed

func IsCloneFailed(err error) bool

IsCloneFailed reports whether err (or any error in its chain) indicates a failure during initial repository cloning.

func IsIndexBuildFailed

func IsIndexBuildFailed(err error) bool

IsIndexBuildFailed reports whether err (or any error in its chain) indicates a failure during in-memory index construction.

func IsNotFound

func IsNotFound(err error) bool

IsNotFound reports whether err (or any error in its chain) indicates that the requested package or version was not found in the index.

func IsPullFailed

func IsPullFailed(err error) bool

IsPullFailed reports whether err (or any error in its chain) indicates a failure during repository pull / refresh.

Types

type Client

type Client struct {

	// Packages exposes GetByID, GetByIDAndVersion, GetByName, ListAll,
	// ListByPublisher, and Search.
	Packages *packages.Packages

	// Versions exposes ListByID and GetByIDAndVersion.
	Versions *versions.Versions

	// Manifests exposes low-level access to individual manifest files.
	Manifests *manifests.Manifests
	// contains filtered or unexported fields
}

Client is the top-level entry point for the WinGet library. It manages the local repository clone, the in-memory index, and all service objects.

Construct one with NewClient; call Refresh to pull the latest package data.

func NewClient

func NewClient(cfg *config.Config, opts ...ClientOption) (*Client, error)

NewClient creates and initialises a WinGet client. It clones the repository (if not already present) and builds the in-memory package index before returning.

Pass functional options to override configuration defaults:

client, err := winget.NewClient(&config.Config{},
    winget.WithCacheDir("~/.cache/winget"),
    winget.WithAutoRefresh(24*time.Hour),
)

func NewClientWithExecutor

func NewClientWithExecutor(cfg *config.Config, exec executor.Executor) (*Client, error)

NewClientWithExecutor creates a client using a custom Executor implementation. This is primarily used in tests where a mock executor is injected.

func (*Client) Close

func (c *Client) Close() error

Close is a no-op at present but is provided for forwards-compatibility. It should always be deferred after a successful NewClient call.

func (*Client) Refresh

func (c *Client) Refresh(ctx context.Context) error

Refresh pulls the latest changes from origin and rebuilds the in-memory index.

type ClientOption

type ClientOption func(*config.Config)

ClientOption is a functional option that modifies the client configuration before the client is initialised.

func WithAutoRefresh

func WithAutoRefresh(interval time.Duration) ClientOption

WithAutoRefresh configures the client to automatically pull the latest changes when the local clone is older than the given interval. Pass 0 to disable auto-refresh (the default).

func WithCacheDir

func WithCacheDir(dir string) ClientOption

WithCacheDir sets the local directory used to clone and cache the WinGet repository. The directory is created if it does not exist.

func WithCloneDepth

func WithCloneDepth(depth int) ClientOption

WithCloneDepth controls the shallow-clone depth. Use 0 for a full clone or 1 (the default) for a shallow clone that fetches only the latest commit.

func WithLogger

func WithLogger(logger *zap.Logger) ClientOption

WithLogger sets a custom zap logger. When not provided, a production logger writing JSON to stderr is created automatically. Pass zap.NewNop() to suppress all log output.

func WithRepoURL

func WithRepoURL(url string) ClientOption

WithRepoURL overrides the Git URL of the WinGet packages repository. Defaults to "https://github.com/microsoft/winget-pkgs".

func WithTimeout

func WithTimeout(d time.Duration) ClientOption

WithTimeout sets the maximum duration for clone or pull operations. Defaults to 5 minutes.

func WithWorkerCount

func WithWorkerCount(n int) ClientOption

WithWorkerCount sets the number of goroutines used during index construction. Defaults to runtime.NumCPU().