csclient

package
v4.1.1 Latest Latest
Warning

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

 Go to latest Published: Dec 5, 2018 License: LGPL-3.0 Imports: 20 Imported by: 1

Documentation

Overview

The csclient package provides access to the charm store API.

Errors returned from the remote API server with an associated error code will have a cause of type params.ErrorCode holding that code.

If a call to the API returns an error because authorization has been denied, an error with a cause satisfying IsAuthorizationError will be returned. Note that these errors can also include errors returned by httpbakery when it attempts to discharge macaroons.

Index

Constants

View Source 
const JujuMetadataHTTPHeader = "Juju-Metadata"

JujuMetadataHTTPHeader is the HTTP header name used to send Juju metadata attributes to the charm store.

Variables

View Source 
var ErrUploadNotFound = errgo.Newf("upload not found")
View Source 
var ServerURL = "https://api.jujucharms.com/charmstore"

ServerURL holds the default location of the global charm store. An alternate location can be configured by changing the URL field in the Params struct. For live testing or QAing the application, a different charm store location should be used, for instance "https://api.staging.jujucharms.com".

Functions

func IsAuthorizationError 

func IsAuthorizationError(err error) bool

IsAuthorizationError reports whether the given error was returned because authorization was denied for a charmstore request.

Types

type CharmRevision 

type CharmRevision struct {
	Revision int
	Err      error
}

CharmRevision holds the revision number of a charm and any error encountered in retrieving it.

type Client 

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

Client represents the client side of a charm store.

func New 

func New(p Params) *Client

New returns a new charm store client.

func (*Client) AddDockerResource 

func (c *Client) AddDockerResource(id *charm.URL, resourceName string, imageName, digest string) (revision int, err error)

AddDockerResource adds a reference to a docker image that is available in a docker registry as a resource to the charm with the given id. If imageName is non-empty, it names the image in some non-charmstore-associated registry; otherwise the image should have been uploaded to the charmstore-associated registry (see DockerResourceUploadInfo for details on how to do that). The digest should hold the digest of the image (in "sha256:hex" format).

AddDockerResource returns the revision of the newly added resource.

func (*Client) Channel 

func (c *Client) Channel() params.Channel

Channel returns the currently set channel.

func (*Client) DisableStats 

func (c *Client) DisableStats()

DisableStats disables incrementing download stats when retrieving archives from the charm store.

func (*Client) Do 

func (c *Client) Do(req *http.Request, path string) (*http.Response, error)

Do makes an arbitrary request to the charm store. It adds appropriate headers to the given HTTP request, sends it to the charm store, and returns the resulting response. Do never returns a response with a status that is not http.StatusOK.

The URL field in the request is ignored and overwritten.

This is a low level method - more specific Client methods should be used when possible.

Note that if a body is supplied in the request, it should implement io.Seeker.

Any error returned from the underlying httpbakery.Do request will have an unchanged error cause.

func (*Client) DoWithResponse 

func (c *Client) DoWithResponse(method string, path string, val, result interface{}) error

DoWithResponse is more general version of PutWithResponse. It performs the given HTTP method on the given charm store path, sending val as the JSON request body and unmarshaling the JSON response into result.

func (*Client) DockerResourceDownloadInfo 

func (c *Client) DockerResourceDownloadInfo(id *charm.URL, resourceName string, revision int) (*params.DockerInfoResponse, error)

DockerResourceDownloadInfo returns information on how to download the given resource in the given Kubernetes charm from a docker registry. The returned information includes the image name to use and the username and password to use for authentication.

func (*Client) DockerResourceUploadInfo 

func (c *Client) DockerResourceUploadInfo(id *charm.URL, resourceName string) (*params.DockerInfoResponse, error)

DockerResourceUploadInfo returns information on how to upload an image to the charm store's associated docker registry. The returned information includes a tag to associate with the image and username and password to use for push authentication.

func (*Client) Get 

func (c *Client) Get(path string, result interface{}) error

Get makes a GET request to the given path in the charm store (not including the host name or version prefix but including a leading /), parsing the result as JSON into the given result value, which should be a pointer to the expected data, but may be nil if no result is desired.

func (*Client) GetArchive 

func (c *Client) GetArchive(id *charm.URL) (r io.ReadCloser, eid *charm.URL, hash string, size int64, err error)

GetArchive retrieves the archive for the given charm or bundle, returning a reader its data can be read from, the fully qualified id of the corresponding entity, the hex-encoded SHA384 hash of the data and its size.

func (*Client) GetResource 

func (c *Client) GetResource(id *charm.URL, name string, revision int) (result ResourceData, err error)

GetResource retrieves byes of the resource with the given name and revision for the given charm, returning a reader its data can be read from, the SHA384 hash of the data.

If revision is negative, the currently published resource for the Client's channel will be returned.

Note that the result must be closed after use.

func (*Client) Latest 

func (cs *Client) Latest(curls []*charm.URL) ([]CharmRevision, error)

Latest returns the most current revision for each of the identified charms. The revision in the provided charm URLs is ignored.

func (*Client) ListResources 

func (c *Client) ListResources(id *charm.URL) ([]params.Resource, error)

ListResources retrieves the metadata about resources for the given charms. It returns a slice with an element for each of the given ids, holding the resources for the respective id.

func (*Client) Log 

func (cs *Client) Log(typ params.LogType, level params.LogLevel, message string, urls ...*charm.URL) error

Log sends a log message to the charmstore's log database.

func (*Client) Login 

func (cs *Client) Login() error

Login explicitly obtains authorization credentials for the charm store and stores them in the client's cookie jar. If there was an error perfoming a login interaction then the error will have a cause of type *httpbakery.InteractionError.

func (*Client) Meta 

func (c *Client) Meta(id *charm.URL, result interface{}) (*charm.URL, error)

Meta fetches metadata on the charm or bundle with the given id. The result value provides a value to be filled in with the result, which must be a pointer to a struct containing members corresponding to possible metadata include parameters (see https://github.com/juju/charmstore/blob/v4/docs/API.md#get-idmeta).

It returns the fully qualified id of the entity.

The name of the struct member is translated to a lower case hyphen-separated form; for example, ArchiveSize becomes "archive-size", and BundleMachineCount becomes "bundle-machine-count", but may also be specified in the field's tag

This example will fill in the result structure with information about the given id, including information on its archive size (include archive-size), upload time (include archive-upload-time) and digest (include extra-info/digest). 

var result struct {
	ArchiveSize params.ArchiveSizeResponse
	ArchiveUploadTime params.ArchiveUploadTimeResponse
	Digest string `csclient:"extra-info/digest"`
}
id, err := client.Meta(id, &result)

func (*Client) Publish 

func (c *Client) Publish(id *charm.URL, channels []params.Channel, resources map[string]int) error

Publish tells the charmstore to mark the given charm as published with the given resource revisions to the given channels.

func (*Client) Put 

func (c *Client) Put(path string, val interface{}) error

Put makes a PUT request to the given path in the charm store (not including the host name or version prefix, but including a leading /), marshaling the given value as JSON to use as the request body.

func (*Client) PutCommonInfo 

func (c *Client) PutCommonInfo(id *charm.URL, info map[string]interface{}) error

PutCommonInfo puts common-info data for the given id. Each entry in the info map causes a value in common-info with that key to be set to the associated value. Entries not set in the map will be unchanged.

func (*Client) PutExtraInfo 

func (c *Client) PutExtraInfo(id *charm.URL, info map[string]interface{}) error

PutExtraInfo puts extra-info data for the given id. Each entry in the info map causes a value in extra-info with that key to be set to the associated value. Entries not set in the map will be unchanged.

func (*Client) PutWithResponse 

func (c *Client) PutWithResponse(path string, val, result interface{}) error

PutWithResponse makes a PUT request to the given path in the charm store (not including the host name or version prefix, but including a leading /), marshaling the given value as JSON to use as the request body. Additionally, this method parses the result as JSON into the given result value, which should be a pointer to the expected data, but may be nil if no result is desired.

func (*Client) ResourceMeta 

func (c *Client) ResourceMeta(id *charm.URL, name string, revision int) (params.Resource, error)

ResourceMeta returns the metadata for the resource on charm id with the given name and revision. If the revision is negative, the latest version of the resource will be returned.

func (*Client) ResumeUploadResource 

func (c *Client) ResumeUploadResource(uploadId string, id *charm.URL, resourceName, path string, content io.ReaderAt, size int64, progress Progress) (revision int, err error)

ResumeUploadResource is like UploadResource except that if uploadId is non-empty, it specifies the id of an existing upload to resume; if an upload with this ID is not found, an error with an ErrUploadNotFound cause is returned.

func (*Client) ResumeUploadResourceWithRevision 

func (c *Client) ResumeUploadResourceWithRevision(
	uploadId string,
	id *charm.URL,
	resourceName string,
	rev int,
	path string,
	content io.ReaderAt,
	size int64,
	progress Progress,
) (revision int, err error)

ResumeUploadResource is like UploadResource except that if uploadId is non-empty, it specifies the id of an existing upload to resume; if an upload with this ID is not found, an error with an ErrUploadNotFound cause is returned.

func (*Client) ServerURL 

func (c *Client) ServerURL() string

ServerURL returns the charm store URL used by the client.

func (*Client) SetHTTPHeader 

func (c *Client) SetHTTPHeader(header http.Header)

SetHTTPHeader sets custom HTTP headers that will be sent to the charm store on each request.

func (*Client) SetMinMultipartUploadSize 

func (c *Client) SetMinMultipartUploadSize(n int64)

SetMinMultipartUploadSize sets the minimum size of resource upload that will trigger a multipart upload. This is mainly useful for testing.

func (*Client) StatsUpdate 

func (c *Client) StatsUpdate(req params.StatsUpdateRequest) error

StatsUpdate updates the download stats for the given id and specific time.

func (*Client) UploadArchive 

func (c *Client) UploadArchive(id *charm.URL, body io.ReadSeeker, hash string, size int64, promulgatedRevision int, chans []params.Channel) (*charm.URL, error)

UploadArchive pushes the archive for the charm or bundle represented by the given body, its hex-encoded SHA384 hash and its size. It returns the resulting entity reference. The given id should include the series should usually include the revision, unless a specific revision is required (for example when synchronizing between charmstores). If a revision is specified, then PUT will be used instead of POST.

This is the method used internally by UploadBundle, UploadCharm and UploadCharmWithRevision; one of those methods should usually be used in preference.

func (*Client) UploadBundle 

func (c *Client) UploadBundle(id *charm.URL, b charm.Bundle) (*charm.URL, error)

UploadBundle uploads the given charm to the charm store with the given id, which must not specify a revision. The accepted bundle implementations are charm.BundleDir and charm.BundleArchive.

UploadBundle returns the id that the bundle has been given in the store - this will be the same as id except the revision.

func (*Client) UploadBundleWithRevision 

func (c *Client) UploadBundleWithRevision(id *charm.URL, b charm.Bundle, promulgatedRevision int) error

UploadBundleWithRevision uploads the given bundle to the given id in the charm store, which must contain a revision. If promulgatedRevision is not -1, it specifies that the charm should be marked as promulgated with that revision.

This method is provided only for testing and should not generally be used otherwise.

func (*Client) UploadCharm 

func (c *Client) UploadCharm(id *charm.URL, ch charm.Charm) (*charm.URL, error)

UploadCharm uploads the given charm to the charm store with the given id, which must not specify a revision. The accepted charm implementations are charm.CharmDir and charm.CharmArchive.

UploadCharm returns the id that the charm has been given in the store - this will be the same as id except the revision.

func (*Client) UploadCharmWithRevision 

func (c *Client) UploadCharmWithRevision(id *charm.URL, ch charm.Charm, promulgatedRevision int) error

UploadCharmWithRevision uploads the given charm to the given id in the charm store, which must contain a revision. If promulgatedRevision is not -1, it specifies that the charm should be marked as promulgated with that revision.

This method is provided only for testing and should not generally be used otherwise.

func (*Client) UploadResource 

func (c *Client) UploadResource(id *charm.URL, name, path string, file io.ReaderAt, size int64, progress Progress) (revision int, err error)

UploadResource uploads the contents of a resource of the given name attached to a charm with the given id. The given path will be used as the resource path metadata and the contents will be read from the given file, which must have the given size. If progress is not nil, it will be called to inform the caller of the progress of the upload.

func (*Client) UploadResourceWithRevision 

func (c *Client) UploadResourceWithRevision(
	id *charm.URL,
	name string,
	rev int,
	path string,
	file io.ReaderAt,
	size int64,
	progress Progress,
) (revision int, err error)

UploadResourceWithRevision is like UploadResource except that it puts the resource at a known revision, useful when transferring resources between charm store instances.

func (*Client) WhoAmI 

func (cs *Client) WhoAmI() (*params.WhoAmIResponse, error)

WhoAmI returns the user and list of groups associated with the macaroon used to authenticate.

func (*Client) WithChannel 

func (c *Client) WithChannel(channel params.Channel) *Client

WithChannel returns a new client whose requests are done using the given channel.

type Params 

type Params struct {
	// URL holds the root endpoint URL of the charmstore,
	// with no trailing slash, not including the version.
	// For example https://api.jujucharms.com/charmstore
	// If empty, the default charm store client location is used.
	URL string

	// User holds the name to authenticate as for the client. If User is empty,
	// no credentials will be sent.
	User string

	// Password holds the password for the given user, for authenticating the
	// client.
	Password string

	// BakeryClient holds the bakery client to use when making
	// requests to the store. This is used in preference to
	// HTTPClient.
	BakeryClient *httpbakery.Client
}

Params holds parameters for creating a new charm store client.

type Progress 

type Progress interface {
	// Start is called with the upload id when the upload starts.
	// The upload id will be empty when multipart upload is not
	// being used (when the upload is small or the server does not
	// support multipart upload).
	Start(uploadId string, expires time.Time)

	// Transferred is called periodically to notify the caller that
	// the given number of bytes have been uploaded. Note that the
	// number may decrease - for example when most of a file has
	// been transferred before a network error occurs.
	Transferred(total int64)

	// Error is called when a non-fatal error (any non-API error) has
	// been encountered when uploading.
	Error(err error)

	// Finalizing is called when all the parts of a multipart upload
	// are being stitched together into the final resource.
	// This will not be called if the upload is not split into
	// multiple parts.
	Finalizing()
}

Progress lets an upload notify a caller about the progress of the upload.

type ReadSeekCloser 

type ReadSeekCloser interface {
	io.ReadSeeker
	io.Closer
}

ReadSeekCloser implements io.ReadSeeker and io.Closer.

type ResourceData 

type ResourceData struct {
	io.ReadCloser
	Size int64
	Hash string
}

ResourceData holds information about a resource. It must be closed after use.

Source Files

View all Source files

Directories

Path Synopsis
The params package holds types that are a part of the charm store's external contract - they will be marshalled (or unmarshalled) as JSON and delivered through the HTTP API.
 The params package holds types that are a part of the charm store's external contract - they will be marshalled (or unmarshalled) as JSON and delivered through the HTTP API.

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.