charmhub

package
v0.0.0-...-b9bb202 Latest Latest
Warning

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

 Go to latest Published: Dec 20, 2024 License: AGPL-3.0 Imports: 37 Imported by: 0

Documentation

Overview

Package charmhub is an HTTP client for sending requests to the Charmhub API.

Call NewClient to create a client, and then Client's methods to perform individual requests, such as "info" or "refresh".

This package automatically handles retries, request logging, and so on. To enable fine-grained request logging, set the logging label "charmhub" to TRACE (or set "metrics" to TRACE for logging request times).

Index

Constants

View Source 
const (
	// DefaultServerURL is the default location of the global Charmhub API.
	// An alternate location can be configured by changing the URL
	// field in the Config struct.
	DefaultServerURL = "https://api.charmhub.io"

	// RefreshTimeout is the timout callers should use for Refresh calls.
	RefreshTimeout = 10 * time.Second
)
View Source 
const (
	// DownloadNameKey defines a name of a download, so the progress bar can
	// show it.
	DownloadNameKey downloadKey = "download-name-key"
)

Variables

This section is empty.

Functions

func CreateInstanceKey 

func CreateInstanceKey(app names.ApplicationTag, model names.ModelTag) string

CreateInstanceKey creates an InstanceKey which can be unique and stable from Refresh action to Refresh action. Required for KPI collection on the charmhub side, see LP:1944582. Rather than saving in state, use the model uuid + the app name, which are unique. Modeled after the applicationDoc DocID and globalKey in state.

func DefaultHTTPClient 

func DefaultHTTPClient(logger corelogger.Logger) *jujuhttp.Client

DefaultHTTPClient creates a new HTTPClient with the default configuration.

func ExtractConfigInstanceKey 

func ExtractConfigInstanceKey(cfg RefreshConfig) string

ExtractConfigInstanceKey is used to get the instance key from a refresh config.

Types

type Client 

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

Client represents the client side of a charm store.

func NewClient 

func NewClient(config Config) (*Client, error)

NewClient creates a new Charmhub client from the supplied configuration.

func (*Client) Download 

func (c *Client) Download(ctx context.Context, resourceURL *url.URL, archivePath string, options ...DownloadOption) (*Digest, error)

Download defines a client for downloading charms directly.

func (*Client) DownloadAndRead 

func (c *Client) DownloadAndRead(ctx context.Context, resourceURL *url.URL, archivePath string, options ...DownloadOption) (*charm.CharmArchive, *Digest, error)

DownloadAndRead defines a client for downloading charms directly.

func (*Client) DownloadAndReadBundle 

func (c *Client) DownloadAndReadBundle(ctx context.Context, resourceURL *url.URL, archivePath string, options ...DownloadOption) (charm.Bundle, *Digest, error)

DownloadAndReadBundle defines a client for downloading bundles directly.

func (*Client) DownloadResource 

func (c *Client) DownloadResource(ctx context.Context, resourceURL *url.URL) (r io.ReadCloser, err error)

DownloadResource returns an io.ReadCloser to read the Resource from.

func (*Client) Find 

func (c *Client) Find(ctx context.Context, name string, options ...FindOption) ([]transport.FindResponse, error)

Find searches for a given charm for a given name from CharmHub API.

func (*Client) Info 

func (c *Client) Info(ctx context.Context, name string, options ...InfoOption) (transport.InfoResponse, error)

Info returns charm info on the provided charm name from CharmHub API.

func (*Client) ListResourceRevisions 

func (c *Client) ListResourceRevisions(ctx context.Context, charm, resource string) ([]transport.ResourceRevision, error)

ListResourceRevisions returns resource revisions for the provided charm and resource.

func (*Client) Refresh 

func (c *Client) Refresh(ctx context.Context, config RefreshConfig) ([]transport.RefreshResponse, error)

Refresh defines a client for making refresh API calls with different actions.

func (*Client) RefreshWithMetricsOnly 

func (c *Client) RefreshWithMetricsOnly(ctx context.Context, metrics map[charmmetrics.MetricKey]map[charmmetrics.MetricKey]string) error

RefreshWithMetricsOnly defines a client making a refresh API call with no action, whose purpose is to send metrics data for models without current units. E.G. the controller model.

func (*Client) RefreshWithRequestMetrics 

func (c *Client) RefreshWithRequestMetrics(ctx context.Context, config RefreshConfig, metrics map[charmmetrics.MetricKey]map[charmmetrics.MetricKey]string) ([]transport.RefreshResponse, error)

RefreshWithRequestMetrics defines a client for making refresh API calls. Specifically to use the refresh action and provide metrics. Intended for use in the charm revision updater facade only. Otherwise use Refresh.

func (*Client) URL 

func (c *Client) URL() string

URL returns the underlying store URL.

type Config 

type Config struct {
	// Logger to use during the API requests. This field is required.
	Logger corelogger.Logger

	// URL holds the base endpoint URL of the Charmhub API,
	// with no trailing slash, not including the version.
	// If empty string, use the default Charmhub API server.
	URL string

	// HTTPClient represents the HTTP client to use for all API
	// requests. If nil, use the default HTTP client.
	HTTPClient HTTPClient

	// FileSystem represents the file system operations for downloading.
	// If nil, use the real OS file system.
	FileSystem FileSystem
}

Config holds configuration for creating a new charm hub client. The zero value is a valid default configuration.

type Digest 

type Digest struct {
	SHA256 string
	SHA384 string
	Size   int64
}

Digest represents a digest of a file.

type DownloadClient 

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

DownloadClient represents a client for downloading charm resources directly.

func NewDownloadClient 

func NewDownloadClient(httpClient HTTPClient, fileSystem FileSystem, logger corelogger.Logger) *DownloadClient

newDownloadClient creates a DownloadClient for requesting

func (*DownloadClient) Download 

func (c *DownloadClient) Download(ctx context.Context, resourceURL *url.URL, archivePath string, options ...DownloadOption) (digest *Digest, err error)

Download returns the raw charm zip file, which is retrieved from the given URL. It is expected that the archive path doesn't already exist and if it does, it will error out. It is expected that the callee handles the clean up of the archivePath. TODO (stickupkid): We should either create and remove, or take a file and let the callee remove. The fact that the operations are asymmetrical can lead to unexpected expectations; namely leaking of files.

func (*DownloadClient) DownloadAndRead 

func (c *DownloadClient) DownloadAndRead(ctx context.Context, resourceURL *url.URL, archivePath string, options ...DownloadOption) (*charm.CharmArchive, *Digest, error)

DownloadAndRead returns a charm archive retrieved from the given URL.

func (*DownloadClient) DownloadAndReadBundle 

func (c *DownloadClient) DownloadAndReadBundle(ctx context.Context, resourceURL *url.URL, archivePath string, options ...DownloadOption) (*charm.BundleArchive, *Digest, error)

DownloadAndReadBundle returns a bundle archive retrieved from the given URL.

func (*DownloadClient) DownloadResource 

func (c *DownloadClient) DownloadResource(ctx context.Context, resourceURL *url.URL) (r io.ReadCloser, err error)

DownloadResource returns an io.ReadCloser to read the Resource from.

type DownloadOption 

type DownloadOption func(*downloadOptions)

DownloadOption to be passed to Info to customize the resulting request.

func WithProgressBar 

func WithProgressBar(pb ProgressBar) DownloadOption

WithProgressBar sets the channel on the option.

type FileSystem 

type FileSystem interface {
	// Create creates or truncates the named file. If the file already exists,
	// it is truncated.
	Create(string) (*os.File, error)
}

FileSystem defines a file system for modifying files on a users system.

func DefaultFileSystem 

func DefaultFileSystem() FileSystem

DefaultFileSystem returns the default file system.

type FindOption 

type FindOption func(*findOptions)

FindOption to be passed to Find to customize the resulting request.

func WithFindCategory 

func WithFindCategory(category string) FindOption

WithFindCategory sets the category on the option.

func WithFindChannel 

func WithFindChannel(channel string) FindOption

WithFindChannel sets the channel on the option.

func WithFindPlatforms 

func WithFindPlatforms(platforms string) FindOption

WithFindPlatforms sets the charmPlatforms on the option.

func WithFindPublisher 

func WithFindPublisher(publisher string) FindOption

WithFindPublisher sets the publisher on the option.

func WithFindRelationProvides 

func WithFindRelationProvides(relationProvides string) FindOption

WithFindRelationProvides sets the relationProvides on the option.

func WithFindRelationRequires 

func WithFindRelationRequires(relationRequires string) FindOption

WithFindRelationRequires sets the relationRequires on the option.

func WithFindType 

func WithFindType(charmType string) FindOption

WithFindType sets the charmType on the option.

type HTTPClient 

type HTTPClient interface {
	// Do performs the *http.Request and returns an *http.Response or an error.
	Do(*http.Request) (*http.Response, error)
}

HTTPClient defines a type for making the actual request. It may be an *http.Client.

type InfoOption 

type InfoOption func(*infoOptions)

InfoOption to be passed to Info to customize the resulting request.

func WithInfoChannel 

func WithInfoChannel(ch string) InfoOption

WithInfoChannel sets the channel on the option.

type ProgressBar 

type ProgressBar interface {
	io.Writer

	// Start progress with max "total" steps.
	Start(label string, total float64)
	// Finished the progress display
	Finished()
}

ProgressBar defines a progress bar type for giving feedback to the user about the state of the download.

type RESTClient 

type RESTClient interface {
	// Get performs GET requests to a given Path.
	Get(context.Context, path.Path, interface{}) (restResponse, error)
	// Post performs POST requests to a given Path.
	Post(context.Context, path.Path, http.Header, interface{}, interface{}) (restResponse, error)
}

RESTClient defines a type for making requests to a server.

type RefreshBase 

type RefreshBase struct {
	Architecture string
	Name         string
	Channel      string
}

RefreshBase defines a base for selecting a specific charm. Continues to exist to allow for incoming bases to be converted to bases inside this package.

func (RefreshBase) String 

func (p RefreshBase) String() string

type RefreshConfig 

type RefreshConfig interface {
	// Build a refresh request for sending to the API.
	Build() (transport.RefreshRequest, error)

	// Ensure that the request back contains the information we requested.
	Ensure([]transport.RefreshResponse) error

	// String describes the underlying refresh config.
	String() string
}

RefreshConfig defines a type for building refresh requests.

func AddConfigMetrics 

func AddConfigMetrics(config RefreshConfig, metrics map[charmmetrics.MetricKey]string) (RefreshConfig, error)

AddConfigMetrics adds metrics to a refreshOne config. All values are applied at once, subsequent calls, replace all values.

func AddResource 

func AddResource(config RefreshConfig, name string, revision int) (RefreshConfig, bool)

AddResource adds resource revision data to a executeOne config. Used for install by revision.

func DownloadOneFromChannel 

func DownloadOneFromChannel(id string, channel string, base RefreshBase) (RefreshConfig, error)

DownloadOneFromChannel creates a request config using the channel and not the revision for requesting only one charm.

func DownloadOneFromChannelByName 

func DownloadOneFromChannelByName(name string, channel string, base RefreshBase) (RefreshConfig, error)

DownloadOneFromChannelByName creates a request config using the channel and not the revision for requesting only one charm.

func DownloadOneFromRevision 

func DownloadOneFromRevision(id string, revision int) (RefreshConfig, error)

DownloadOneFromRevision creates a request config using the revision and not the channel for requesting only one charm.

func DownloadOneFromRevisionByName 

func DownloadOneFromRevisionByName(name string, revision int) (RefreshConfig, error)

DownloadOneFromRevisionByName creates a request config using the revision and not the channel for requesting only one charm.

func InstallOneFromChannel 

func InstallOneFromChannel(name string, channel string, base RefreshBase) (RefreshConfig, error)

InstallOneFromChannel creates a request config using the channel and not the revision for requesting only one charm.

func InstallOneFromRevision 

func InstallOneFromRevision(name string, revision int) (RefreshConfig, error)

InstallOneFromRevision creates a request config using the revision and not the channel for requesting only one charm.

func RefreshMany 

func RefreshMany(configs ...RefreshConfig) RefreshConfig

RefreshMany will compose many refresh configs.

func RefreshOne 

func RefreshOne(key, id string, revision int, channel string, base RefreshBase) (RefreshConfig, error)

RefreshOne creates a request config for requesting only one charm.

Source Files

View all Source files

Directories

Path Synopsis
Package path defines helpers for constructing Charmhub API URL paths.
 Package path defines helpers for constructing Charmhub API URL paths.
Package transport defines the request and response structs for use with the Charmhub API client.
 Package transport defines the request and response structs for use with the Charmhub API client.

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.