client

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 20, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package client is a typed Go client for the aptly REST API.

It decodes aptly's JSON error envelope into friendly errors, supports optional HTTP Basic auth that is triggered only when the server answers 401, and wraps aptly's asynchronous task API for live progress reporting.

Index

Constants

View Source 
const (
	TaskInit = iota
	TaskRunning
	TaskSucceeded
	TaskFailed
)

Task states reported by aptly.

Variables

This section is empty.

Functions

func TaskError 

func TaskError(task *Task, output string) error

TaskError builds an error describing a failed task, including its tail output.

Types

type APIError 

type APIError struct {
	Status  int
	Message string
}

APIError represents a non-2xx response from aptly.

func (*APIError) Error 

func (e *APIError) Error() string

type Client 

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

Client talks to a single aptly API server.

func New 

func New(opts Options) *Client

New builds a Client from Options.

func (*Client) AddPackagesFromDir 

func (c *Client) AddPackagesFromDir(repo, dir string) (*Task, error)

AddPackagesFromDir adds previously uploaded files (in upload dir) to a repository asynchronously, returning the task to wait on.

func (*Client) Authenticated added in v0.3.0 

func (c *Client) Authenticated() bool

Authenticated reports whether the client is currently sending Basic-auth credentials (because they were configured or supplied via a 401 prompt).

func (*Client) BaseURL 

func (c *Client) BaseURL() string

BaseURL returns the server's base URL.

func (*Client) CreateRepo 

func (c *Client) CreateRepo(req CreateRepoRequest) (*Repo, error)

CreateRepo creates a new local repository.

func (*Client) DeleteRepo 

func (c *Client) DeleteRepo(name string, force bool) error

DeleteRepo removes a local repository. When force is true, it is removed even if referenced by published repositories or snapshots.

func (*Client) DeleteUploadDir 

func (c *Client) DeleteUploadDir(dir string) error

DeleteUploadDir removes an upload directory and its contents.

func (*Client) EditRepo 

func (c *Client) EditRepo(name string, req EditRepoRequest) (*Repo, error)

EditRepo updates a local repository's configuration.

func (*Client) GetTask 

func (c *Client) GetTask(id int) (*Task, error)

GetTask returns a task's current state.

func (*Client) ListMirrors added in v0.3.0 

func (c *Client) ListMirrors() ([]Mirror, error)

ListMirrors returns all configured mirrors.

func (*Client) ListPublished 

func (c *Client) ListPublished() ([]PublishedRepo, error)

ListPublished returns all published repositories.

func (*Client) ListRepos 

func (c *Client) ListRepos() ([]Repo, error)

ListRepos returns all local repositories.

func (*Client) ListSnapshots added in v0.3.0 

func (c *Client) ListSnapshots() ([]Snapshot, error)

ListSnapshots returns all snapshots.

func (*Client) ListTasks 

func (c *Client) ListTasks() ([]Task, error)

ListTasks returns all known tasks.

func (*Client) ListUploadDirs 

func (c *Client) ListUploadDirs() ([]string, error)

ListUploadDirs lists the existing upload directories.

func (*Client) ListUploadedFiles 

func (c *Client) ListUploadedFiles(dir string) ([]string, error)

ListUploadedFiles lists files within an upload directory.

func (*Client) RepoPackageDetails added in v0.5.0 

func (c *Client) RepoPackageDetails(name string, q PackageQuery) ([]map[string]any, error)

RepoPackageDetails lists full package records (aptly format=details) in a repository. Each record is a map of Debian control fields (Package, Version, Architecture, Maintainer, Filename, Size, ...).

func (*Client) RepoPackageKeys added in v0.5.0 

func (c *Client) RepoPackageKeys(name string, q PackageQuery) ([]string, error)

RepoPackageKeys lists package keys in a repository with full query options.

func (*Client) RepoPackages 

func (c *Client) RepoPackages(name, query string) ([]string, error)

RepoPackages lists package keys in a repository, optionally filtered by an aptly query (e.g. `nginx (>= 1.20)`).

func (*Client) ShowPackage 

func (c *Client) ShowPackage(key string) (map[string]any, error)

ShowPackage returns the raw detail map for a package key (e.g. "Pamd64 nginx 1.20.1-1 abc..."). The shape varies by package, so it is returned as a generic map.

func (*Client) ShowRepo 

func (c *Client) ShowRepo(name string) (*Repo, error)

ShowRepo returns details for a single local repository.

func (*Client) StreamTask 

func (c *Client) StreamTask(id int, onChunk func(string)) (*Task, error)

StreamTask polls a task until completion, invoking onChunk with each newly appended slice of output for live progress. It returns the final task state.

func (*Client) TaskOutput 

func (c *Client) TaskOutput(id int) (string, error)

TaskOutput returns the accumulated output text of a task.

func (*Client) UpdatePublished 

func (c *Client) UpdatePublished(prefix, distribution string, req UpdatePublishRequest) (*Task, error)

UpdatePublished re-publishes a (prefix, distribution) publication asynchronously, returning the task to wait on. Used after adding packages to a local repo so the changes go live.

func (*Client) UploadFiles 

func (c *Client) UploadFiles(dir string, paths []string) ([]string, error)

UploadFiles uploads local package files into the named upload directory, returning the server-side file list.

func (*Client) Version 

func (c *Client) Version() (*Version, error)

Version returns the remote aptly version (GET /api/version).

func (*Client) WaitTask 

func (c *Client) WaitTask(id int) (*Task, error)

WaitTask blocks server-side until the task reaches a terminal state.

type CreateRepoRequest 

type CreateRepoRequest struct {
	Name                string `json:"Name"`
	Comment             string `json:"Comment,omitempty"`
	DefaultDistribution string `json:"DefaultDistribution,omitempty"`
	DefaultComponent    string `json:"DefaultComponent,omitempty"`
}

CreateRepoRequest is the body for POST /api/repos.

type EditRepoRequest 

type EditRepoRequest struct {
	Comment             string `json:"Comment,omitempty"`
	DefaultDistribution string `json:"DefaultDistribution,omitempty"`
	DefaultComponent    string `json:"DefaultComponent,omitempty"`
}

EditRepoRequest is the body for PUT /api/repos/:name.

type Mirror added in v0.3.0 

type Mirror struct {
	Name          string   `json:"Name"`
	ArchiveRoot   string   `json:"ArchiveRoot"`
	Distribution  string   `json:"Distribution"`
	Components    []string `json:"Components"`
	Architectures []string `json:"Architectures"`
}

Mirror is a remote repository mirror (GET /api/mirrors).

type Options 

type Options struct {
	BaseURL  string
	User     string
	Password string
	HasAuth  bool // true when a password was supplied up front
	Insecure bool
	Timeout  time.Duration
	Prompt   Prompter // used on 401 when no credentials are known
}

Options configures a Client.

type PackageQuery added in v0.5.0 

type PackageQuery struct {
	Query          string // aptly query, e.g. `nginx (>= 1.20)` (empty lists all)
	MaximumVersion bool   // only the newest version of each package
	WithDeps       bool   // include packages that satisfy dependencies
}

PackageQuery holds options for listing/searching packages in a repository.

type Prompter 

type Prompter interface {
	// Credentials returns the username and password to authenticate with.
	// defaultUser is the configured user (may be empty).
	Credentials(realm, defaultUser string) (user, pass string, err error)
}

Prompter supplies Basic-auth credentials when the server issues a 401 challenge and none were preconfigured.

type PublishedRepo 

type PublishedRepo struct {
	Storage       string            `json:"Storage"`
	Prefix        string            `json:"Prefix"`
	Distribution  string            `json:"Distribution"`
	SourceKind    string            `json:"SourceKind"`
	Sources       []PublishedSource `json:"Sources"`
	Architectures []string          `json:"Architectures"`
	Label         string            `json:"Label"`
	Origin        string            `json:"Origin"`
}

PublishedRepo is an entry from GET /api/publish.

type PublishedSource 

type PublishedSource struct {
	Component string `json:"Component"`
	Name      string `json:"Name"`
}

PublishedSource is a component/source pair within a publication.

type Repo 

type Repo struct {
	Name                string `json:"Name"`
	Comment             string `json:"Comment"`
	DefaultDistribution string `json:"DefaultDistribution"`
	DefaultComponent    string `json:"DefaultComponent"`
}

Repo is a local repository (GET /api/repos).

type Signing 

type Signing struct {
	Skip       bool   `json:"Skip,omitempty"`
	GpgKey     string `json:"GpgKey,omitempty"`
	Keyring    string `json:"Keyring,omitempty"`
	Passphrase string `json:"Passphrase,omitempty"`
	Batch      bool   `json:"Batch,omitempty"`
}

Signing controls GPG signing options on publish operations.

type Snapshot added in v0.3.0 

type Snapshot struct {
	Name        string `json:"Name"`
	Description string `json:"Description"`
	CreatedAt   string `json:"CreatedAt"`
}

Snapshot is a point-in-time snapshot (GET /api/snapshots).

type Task 

type Task struct {
	ID    int    `json:"ID"`
	Name  string `json:"Name"`
	State int    `json:"State"`
}

Task is an asynchronous aptly task (returned when ?_async=1 is used).

func (Task) Done 

func (t Task) Done() bool

Done reports whether the task has reached a terminal state.

func (Task) Failed 

func (t Task) Failed() bool

Failed reports whether the task ended in failure.

func (Task) StateString 

func (t Task) StateString() string

StateString renders a task state as a human label.

type TerminalPrompter 

type TerminalPrompter struct{}

TerminalPrompter reads credentials interactively from the controlling terminal, reading the password without echo.

func (TerminalPrompter) Credentials 

func (TerminalPrompter) Credentials(realm, defaultUser string) (string, string, error)

Credentials implements Prompter against the terminal. It fails clearly when no interactive terminal is attached (e.g. in scripts or --json runs) rather than blocking.

type UpdatePublishRequest 

type UpdatePublishRequest struct {
	Signing        Signing `json:"Signing"`
	ForceOverwrite bool    `json:"ForceOverwrite,omitempty"`
}

UpdatePublishRequest is the body for PUT /api/publish/:prefix/:distribution.

type Version 

type Version struct {
	Version string `json:"Version"`
}

Version is the response from GET /api/version.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.