Documentation

Overview

    Package client implements a Camlistore client.

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var ErrNoHelpRoot = errors.New("client: server does not have a help handler")

      ErrNoHelpRoot is returned by HelpRoot if the server doesn't have a help handler.

      View Source
      var ErrNoSearchRoot = errors.New("client: server doesn't support search")

        ErrNoSearchRoot is returned by SearchRoot if the server doesn't support search.

        View Source
        var ErrNoSigning = fmt.Errorf("client: server doesn't support signing")

          ErrNoSigning is returned by ServerKeyID if the server doesn't support signing.

          View Source
          var ErrNoStorageGeneration = errors.New("client: server doesn't report a storage generation")

            ErrNoStorageGeneration is returned by StorageGeneration if the server doesn't report a storage generation value.

            View Source
            var ErrNoSync = errors.New("client: server has no sync handlers")

              ErrNoSync is returned by SyncHandlers if the server does not advertise syncs.

              Functions

              func AddFlags

              func AddFlags()

              func ExplicitServer

              func ExplicitServer() string

                ExplicitServer returns the blobserver given in the flags, if any.

                Types

                type ByCountAndBytes

                type ByCountAndBytes struct {
                	Blobs int
                	Bytes int64
                }

                func (*ByCountAndBytes) String

                func (bb *ByCountAndBytes) String() string

                type Client

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

                  A Client provides access to a Camlistore server.

                  func New

                  func New(server string, opts ...ClientOption) *Client

                    New returns a new Camlistore Client. The provided server is either "host:port" (assumed http, not https) or a URL prefix, with or without a path, or a server alias from the client configuration file. A server alias should not be confused with a hostname, therefore it cannot contain any colon or period. Errors are not returned until subsequent operations.

                    func NewFromParams

                    func NewFromParams(server string, mode auth.AuthMode, opts ...ClientOption) *Client

                      NewFromParams returns a Client that uses the specified server base URL and auth but does not use any on-disk config files or environment variables for its configuration. It may still use the disk for caches.

                      func NewFromShareRoot

                      func NewFromShareRoot(shareBlobURL string, opts ...ClientOption) (c *Client, target blob.Ref, err error)

                        NewFromShareRoot uses shareBlobURL to set up and return a client that will be used to fetch shared blobs.

                        func NewOrFail

                        func NewOrFail(opts ...ClientOption) *Client

                        func NewStorageClient

                        func NewStorageClient(s blobserver.Storage) *Client

                          NewStorageClient returns a Client that doesn't use HTTP, but uses s directly. This exists mainly so all the convenience methods on Client (e.g. the Upload variants) are available against storage directly. When using NewStorageClient, callers should call Close when done, in case the storage wishes to do a cleaner shutdown.

                          func (*Client) BlobRoot

                          func (c *Client) BlobRoot() (string, error)

                            BlobRoot returns the server's blobroot URL prefix. If the client was constructed with an explicit path, that path is used. Otherwise the server's default advertised blobRoot is used.

                            func (*Client) Close

                            func (c *Client) Close() error

                              Close closes the client. In most cases, it's not necessary to close a Client. The exception is for Clients created using NewStorageClient, where the Storage might implement io.Closer.

                              func (*Client) Describe

                              func (*Client) DialFunc

                              func (c *Client) DialFunc() func(network, addr string) (net.Conn, error)

                                DialFunc returns the adequate dial function when we're on android.

                                func (*Client) DialTLSFunc

                                func (c *Client) DialTLSFunc() func(network, addr string) (net.Conn, error)

                                  DialTLSFunc returns the adequate dial function, when using SSL, depending on whether we're using insecure TLS (certificate verification is disabled), or we have some trusted certs, or we're on android.1 If the client's config has some trusted certs, the server's certificate will be checked against those in the config after the TLS handshake.

                                  func (*Client) DiscoveryDoc

                                  func (c *Client) DiscoveryDoc() (io.Reader, error)

                                    DiscoveryDoc returns the server's JSON discovery document. This method exists purely for the "camtool discovery" command. Clients shouldn't have to parse this themselves.

                                    func (*Client) EnumerateBlobs

                                    func (c *Client) EnumerateBlobs(ctx context.Context, dest chan<- blob.SizedRef, after string, limit int) error

                                    func (*Client) EnumerateBlobsOpts

                                    func (c *Client) EnumerateBlobsOpts(ctx context.Context, ch chan<- blob.SizedRef, opts EnumerateOpts) error

                                      EnumerateBlobsOpts sends blobs to the provided channel, as directed by opts. The channel will be closed, regardless of whether an error is returned.

                                      func (*Client) Fetch

                                      func (c *Client) Fetch(b blob.Ref) (io.ReadCloser, uint32, error)

                                      func (*Client) FetchSchemaBlob

                                      func (c *Client) FetchSchemaBlob(b blob.Ref) (*schema.Blob, error)

                                      func (*Client) FetchVia

                                      func (c *Client) FetchVia(b blob.Ref, v []blob.Ref) (body io.ReadCloser, size uint32, err error)

                                      func (*Client) FileHasContents

                                      func (c *Client) FileHasContents(f, wholeRef blob.Ref) bool

                                        FileHasContents returns true iff f refers to a "file" or "bytes" schema blob, the server is configured with a "download helper", and the server responds that all chunks of 'f' are available and match the digest of wholeRef.

                                        func (*Client) GetClaims

                                        func (c *Client) GetClaims(req *search.ClaimsRequest) (*search.ClaimsResponse, error)

                                        func (*Client) GetJSON

                                        func (c *Client) GetJSON(url string, data interface{}) error

                                          GetJSON sends a GET request to url, and unmarshals the returned JSON response into data. The URL's host must match the client's configured server.

                                          func (*Client) GetPermanodesWithAttr

                                          func (c *Client) GetPermanodesWithAttr(req *search.WithAttrRequest) (*search.WithAttrResponse, error)

                                          func (*Client) GetRecentPermanodes

                                          func (c *Client) GetRecentPermanodes(req *search.RecentRequest) (*search.RecentResponse, error)

                                            GetRecentPermanodes implements search.GetRecentPermanoder against a remote server over HTTP.

                                            func (*Client) HTTPClient

                                            func (c *Client) HTTPClient() *http.Client

                                              HTTPClient returns the Client's underlying http.Client.

                                              func (*Client) HTTPStats

                                              func (c *Client) HTTPStats() *httputil.StatsTransport

                                                HTTPStats returns the client's underlying httputil.StatsTransport, if in use. If another transport is being used, nil is returned.

                                                func (*Client) HTTPVersion

                                                func (c *Client) HTTPVersion() (string, error)

                                                  HTTPVersion reports the HTTP version in use.

                                                  func (*Client) HelpRoot

                                                  func (c *Client) HelpRoot() (string, error)

                                                    HelpRoot returns the server's help handler. If the server isn't running a help handler, the error will be ErrNoHelpRoot.

                                                    func (*Client) IsIgnoredFile

                                                    func (c *Client) IsIgnoredFile(fullpath string) bool

                                                      IsIgnoredFile returns whether the file at fullpath should be ignored by camput. The fullpath is checked against the ignoredFiles list, trying the following rules in this order: 1) star-suffix style matching (.e.g *.jpg). 2) Shell pattern match as done by http://golang.org/pkg/path/filepath/#Match 3) If the pattern is an absolute path to a directory, fullpath matches if it is that directory or a child of it. 4) If the pattern is a relative path, fullpath matches if it has pattern as a path component (i.e the pattern is a part of fullpath that fits exactly between two path separators).

                                                      func (*Client) NewPathClient

                                                      func (c *Client) NewPathClient(path string) *Client

                                                        NewPathClient returns a new client accessing a subpath of c.

                                                        func (*Client) Post

                                                        func (c *Client) Post(url string, bodyType string, body io.Reader) error

                                                          Post is like http://golang.org/pkg/net/http/#Client.Post but with implementation details like gated requests. The URL's host must match the client's configured server.

                                                          func (*Client) Query

                                                          func (c *Client) Query(req *search.SearchQuery) (*search.SearchResult, error)

                                                          func (*Client) ReceiveBlob

                                                          func (c *Client) ReceiveBlob(br blob.Ref, source io.Reader) (blob.SizedRef, error)

                                                          func (*Client) RemoveBlob

                                                          func (c *Client) RemoveBlob(b blob.Ref) error

                                                            Remove the single blob. An error is returned if the server failed to remove the blob. Removing a non-existent blob isn't an error.

                                                            func (*Client) RemoveBlobs

                                                            func (c *Client) RemoveBlobs(blobs []blob.Ref) error

                                                              Remove the list of blobs. An error is returned if the server failed to remove a blob. Removing a non-existent blob isn't an error.

                                                              func (*Client) SearchExistingFileSchema

                                                              func (c *Client) SearchExistingFileSchema(wholeRef blob.Ref) (blob.Ref, error)

                                                                SearchExistingFileSchema does a search query looking for an existing file with entire contents of wholeRef, then does a HEAD request to verify the file still exists on the server. If so, it returns that file schema's blobref.

                                                                May return (zero, nil) on ENOENT. A non-nil error is only returned if there were problems searching.

                                                                func (*Client) SearchRoot

                                                                func (c *Client) SearchRoot() (string, error)

                                                                  SearchRoot returns the server's search handler. If the server isn't running an index and search handler, the error will be ErrNoSearchRoot.

                                                                  func (*Client) SecretRingFile

                                                                  func (c *Client) SecretRingFile() string

                                                                    SecretRingFile returns the filename to the user's GPG secret ring. The value comes from either the --secret-keyring flag, the CAMLI_SECRET_RING environment variable, the client config file's "identitySecretRing" value, or the operating system default location.

                                                                    func (*Client) ServerKeyID

                                                                    func (c *Client) ServerKeyID() (string, error)

                                                                      ServerKeyID returns the server's GPG public key ID, in its long (16 capital hex digits) format. If the server isn't running a sign handler, the error will be ErrNoSigning.

                                                                      func (*Client) SetHTTPClient

                                                                      func (c *Client) SetHTTPClient(client *http.Client)

                                                                        SetHTTPClient sets the Camlistore client's HTTP client. If nil, the default HTTP client is used.

                                                                        func (*Client) SetHaveCache

                                                                        func (c *Client) SetHaveCache(cache HaveCache)

                                                                        func (*Client) SetLogger

                                                                        func (c *Client) SetLogger(logger *log.Logger)

                                                                        func (*Client) SetupAuth

                                                                        func (c *Client) SetupAuth() error

                                                                          SetupAuth sets the client's authMode. It tries from the environment first if we're on android or in dev mode, and then from the client configuration.

                                                                          func (*Client) SetupAuthFromString

                                                                          func (c *Client) SetupAuthFromString(a string) error

                                                                            SetupAuthFromString configures the clients authentication mode from an explicit auth string.

                                                                            func (*Client) Signer

                                                                            func (c *Client) Signer() (*schema.Signer, error)

                                                                            func (*Client) SignerPublicKeyBlobref

                                                                            func (c *Client) SignerPublicKeyBlobref() blob.Ref

                                                                              SignerPublicKeyBlobref returns the blobref of signer's public key. The blobref may not be valid (zero blob.Ref) if e.g the configuration is invalid or incomplete.

                                                                              func (*Client) SimpleEnumerateBlobs

                                                                              func (c *Client) SimpleEnumerateBlobs(ctx context.Context, ch chan<- blob.SizedRef) error

                                                                                SimpleEnumerateBlobs sends all blobs to the provided channel. The channel will be closed, regardless of whether an error is returned.

                                                                                func (*Client) StatBlobs

                                                                                func (c *Client) StatBlobs(dest chan<- blob.SizedRef, blobs []blob.Ref) error

                                                                                func (*Client) Stats

                                                                                func (c *Client) Stats() Stats

                                                                                func (*Client) StorageGeneration

                                                                                func (c *Client) StorageGeneration() (string, error)

                                                                                  StorageGeneration returns the server's unique ID for its storage generation, reset whenever storage is reset, moved, or partially lost.

                                                                                  This is a value that can be used in client cache keys to add certainty that they're talking to the same instance as previously.

                                                                                  If the server doesn't return such a value, the error will be ErrNoStorageGeneration.

                                                                                  func (*Client) SyncHandlers

                                                                                  func (c *Client) SyncHandlers() ([]*SyncInfo, error)

                                                                                    SyncHandlers returns the server's sync handlers "from" and "to" prefix URLs. If the server isn't running any sync handler, the error will be ErrNoSync.

                                                                                    func (*Client) Upload

                                                                                    func (c *Client) Upload(h *UploadHandle) (*PutResult, error)

                                                                                      Upload uploads a blob, as described by the provided UploadHandle parameters.

                                                                                      func (*Client) UploadAndSignBlob

                                                                                      func (c *Client) UploadAndSignBlob(b schema.AnyBlob) (*PutResult, error)

                                                                                      func (*Client) UploadBlob

                                                                                      func (c *Client) UploadBlob(b schema.AnyBlob) (*PutResult, error)

                                                                                      func (*Client) UploadFile

                                                                                      func (cl *Client) UploadFile(filename string, contents io.Reader, opts *FileUploadOptions) (blob.Ref, error)

                                                                                        UploadFile uploads the contents of the file, as well as a file blob with filename for these contents. If the contents or the file blob are found on the server, they're not uploaded.

                                                                                        Note: this method is still a work in progress, and might change to accomodate the needs of camput file.

                                                                                        func (*Client) UploadNewPermanode

                                                                                        func (c *Client) UploadNewPermanode() (*PutResult, error)

                                                                                        func (*Client) UploadPlannedPermanode

                                                                                        func (c *Client) UploadPlannedPermanode(key string, sigTime time.Time) (*PutResult, error)

                                                                                        type ClientOption

                                                                                        type ClientOption interface {
                                                                                        	// contains filtered or unexported methods
                                                                                        }

                                                                                        func OptionInsecure

                                                                                        func OptionInsecure(v bool) ClientOption

                                                                                        func OptionTransportConfig

                                                                                        func OptionTransportConfig(tc *TransportConfig) ClientOption

                                                                                        func OptionTrustedCert

                                                                                        func OptionTrustedCert(cert string) ClientOption

                                                                                        type EnumerateOpts

                                                                                        type EnumerateOpts struct {
                                                                                        	After   string        // last blobref seen; start with ones greater than this
                                                                                        	MaxWait time.Duration // how long to poll for (second granularity), waiting for any blob, or 0 for no limit
                                                                                        	Limit   int           // if non-zero, the max blobs to return
                                                                                        }

                                                                                          EnumerateOpts are the options to Client.EnumerateBlobsOpts.

                                                                                          type FileUploadOptions

                                                                                          type FileUploadOptions struct {
                                                                                          	// FileInfo optionally specifies the FileInfo to populate the schema of the file blob.
                                                                                          	FileInfo os.FileInfo
                                                                                          	// WholeRef optionally specifies the digest of the uploaded file contents, which
                                                                                          	// allows UploadFile to skip computing the digest (needed to check if the contents
                                                                                          	// are already on the server).
                                                                                          	WholeRef blob.Ref
                                                                                          }

                                                                                            FileUploadOptions is optionally provided to UploadFile.

                                                                                            type HaveCache

                                                                                            type HaveCache interface {
                                                                                            	StatBlobCache(br blob.Ref) (size uint32, ok bool)
                                                                                            	NoteBlobExists(br blob.Ref, size uint32)
                                                                                            }

                                                                                              A HaveCache caches whether a remote blobserver has a blob.

                                                                                              type PutResult

                                                                                              type PutResult struct {
                                                                                              	BlobRef blob.Ref
                                                                                              	Size    uint32
                                                                                              	Skipped bool // already present on blobserver
                                                                                              }

                                                                                              func (*PutResult) SizedBlobRef

                                                                                              func (pr *PutResult) SizedBlobRef() blob.SizedRef

                                                                                              type ResponseFormatError

                                                                                              type ResponseFormatError error

                                                                                              type Stats

                                                                                              type Stats struct {
                                                                                              	// The number of uploads that were requested, but perhaps
                                                                                              	// not actually performed if the server already had the items.
                                                                                              	UploadRequests ByCountAndBytes
                                                                                              
                                                                                              	// The uploads which were actually sent to the blobserver
                                                                                              	// due to the server not having the blobs
                                                                                              	Uploads ByCountAndBytes
                                                                                              }

                                                                                              func (*Stats) String

                                                                                              func (s *Stats) String() string

                                                                                              type SyncInfo

                                                                                              type SyncInfo struct {
                                                                                              	From    string
                                                                                              	To      string
                                                                                              	ToIndex bool // whether this sync is from a blob storage to an index
                                                                                              }

                                                                                                SyncInfo holds the data that were acquired with a discovery and that are relevant to a syncHandler.

                                                                                                type TransportConfig

                                                                                                type TransportConfig struct {
                                                                                                	// Proxy optionally specifies the Proxy for the transport. Useful with
                                                                                                	// camput for debugging even localhost requests.
                                                                                                	Proxy   func(*http.Request) (*url.URL, error)
                                                                                                	Verbose bool // Verbose enables verbose logging of HTTP requests.
                                                                                                }

                                                                                                  TransportConfig contains options for SetupTransport.

                                                                                                  type UploadHandle

                                                                                                  type UploadHandle struct {
                                                                                                  	// BlobRef is the required blobref of the blob to upload.
                                                                                                  	BlobRef blob.Ref
                                                                                                  
                                                                                                  	// Contents is the blob data.
                                                                                                  	Contents io.Reader
                                                                                                  
                                                                                                  	// Size optionally specifies the size of Contents.
                                                                                                  	// If <= 0, the Contents are slurped into memory to count the size.
                                                                                                  	Size uint32
                                                                                                  
                                                                                                  	// Vivify optionally instructs the server to create a
                                                                                                  	// permanode for this blob. If used, the blob should be a
                                                                                                  	// "file" schema blob. This is typically used by
                                                                                                  	// lesser-trusted clients (such a mobile phones) which don't
                                                                                                  	// have rights to do signing directly.
                                                                                                  	Vivify bool
                                                                                                  
                                                                                                  	// SkipStat indicates whether the stat check (checking whether
                                                                                                  	// the server already has the blob) will be skipped and the
                                                                                                  	// blob should be uploaded immediately. This is useful for
                                                                                                  	// small blobs that the server is unlikely to already have
                                                                                                  	// (e.g. new claims).
                                                                                                  	SkipStat bool
                                                                                                  }

                                                                                                    UploadHandle contains the parameters is a request to upload a blob.

                                                                                                    func NewUploadHandleFromString

                                                                                                    func NewUploadHandleFromString(data string) *UploadHandle

                                                                                                      NewUploadHandleFromString returns an upload handle

                                                                                                      Directories

                                                                                                      Path Synopsis
                                                                                                      Package android contains code specific to running the Camlistore client code as a child process on Android.
                                                                                                      Package android contains code specific to running the Camlistore client code as a child process on Android.