gdrive

Documentation

Overview

Package gdrive provides a slightly higher-level API for Google Drive than is provided by the official Google Drive API Go language bindings. In addition to handling transient network errors, rate limit errors, and other http miscellania, gdrive also provides functionality for limiting bandwidth consumption in both uploads and downloads.

gdrive was written to be independent of the skicka application; issues like encryption, mapping Google Drive files to Unix file semantics, etc., are intentionally not included here.

Index

• Constants
• Variables
• func MakeLimitedDownloadReader(r io.ReadCloser) io.ReadCloser
• type File
  • func PartitionUniquesAndMultiples(files []*File) ([]*File, map[string][]*File)
  • func (f *File) GetProperty(name string) (string, error)
  • func (f *File) IsFolder() bool
  • func (f *File) IsGoogleAppsFile() bool
• type GDrive
  • func New(uploadBytesPerSecond, downloadBytesPerSecond int, ...) (*GDrive, error)
  • func (gd *GDrive) AddProperty(key, value string, f *File) error
  • func (gd *GDrive) CheckMetadata(filename string, report func(string)) error
  • func (gd *GDrive) CreateFile(name string, parent *File, modTime time.Time, proplist []Property) (*File, error)
  • func (gd *GDrive) CreateFolder(name string, parent *File, modTime time.Time, proplist []Property) (*File, error)
  • func (gd *GDrive) DeleteFile(f *File) error
  • func (gd *GDrive) GetDriveUsage() (Usage, error)
  • func (gd *GDrive) GetFile(path string) (*File, error)
  • func (gd *GDrive) GetFileById(id string) (*drive.File, error)
  • func (gd *GDrive) GetFileContents(f *File) (io.ReadCloser, error)
  • func (gd *GDrive) GetFiles(path string) []*File
  • func (gd *GDrive) GetFilesInFolder(path string) ([]*File, error)
  • func (gd *GDrive) GetFilesUnderFolder(path string, includeBase bool) ([]*File, error)
  • func (gd *GDrive) TrashFile(f *File) error
  • func (gd *GDrive) UpdateMetadataCache(filename string) error
  • func (gd *GDrive) UpdateModificationTime(f *File, newTime time.Time) error
  • func (gd *GDrive) UpdateProperty(f *File, key string, value string) error
  • func (gd *GDrive) UploadFileContents(f *File, contentsReader io.Reader, length int64, try int) error
  • func (gd *GDrive) UploadFileContentsResumable(file *File, contentsReader io.Reader, contentLength int64) error
• type HTTPResponseResult
• type Property
• type RetryHTTPTransmitError
  • func (r RetryHTTPTransmitError) Error() string
• type SpaceUser
• type Usage

Constants

const (
	Success    HTTPResponseResult = iota
	Retry                         = iota
	Fail                          = iota
	RefreshURI                    = iota
)

Variables

var ErrMultipleFiles = errors.New("multiple files on Drive")

var ErrNotExist = errors.New("file does not exist")

Functions

func MakeLimitedDownloadReader

func MakeLimitedDownloadReader(r io.ReadCloser) io.ReadCloser

Types

type File

type File struct {
	// Path name on Drive. Does not start with a slash.
	Path string
	// Size of the file in bytes.
	FileSize int64
	// Unique id of the file (that persists over file modifications,
	// renamings, etc.) This value is generated by Google Drive when a file
	// is first created.
	Id string
	// MD5 checksum of the file's contents.
	Md5      string
	MimeType string
	// Last time that the file's contents were modified.
	ModTime time.Time
	// Array of Google Drive file ids for the folder or folders that have
	// this file in it.
	ParentIds []string
	// User-defined properties associated with the file.
	Properties []Property
}

File represents a file or folder in Google Drive.

func PartitionUniquesAndMultiples

func PartitionUniquesAndMultiples(files []*File) ([]*File, map[string][]*File)

PartitionUniquesAndMultiples partitions all of the files by path name and then returns an array of File structures for the uniquely-named files and a map from path names to arrays of files for cases where more than one file has the same pathname.

func (*File) GetProperty

func (f *File) GetProperty(name string) (string, error)

GetProperty returns the property of the given name associated with the given file, if the named property is present. If the property isn't present in the fie, then an empty string and an error are returned.

func (*File) IsFolder

func (f *File) IsFolder() bool

IsFolder returns a boolean indicating whether the given File is a folder.

func (*File) IsGoogleAppsFile

func (f *File) IsGoogleAppsFile() bool

IsGoogleAppsFile returns a boolean indicating whether the given File was created with Google Docs, Google Sheets, etc.

type GDrive

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

GDrive encapsulates a session for performing operations with Google Drive. It provides a variety of methods for working with files and folders stored in Google Drive.

func New

func New(uploadBytesPerSecond, downloadBytesPerSecond int,
	debug func(s string, args ...interface{}), client *http.Client,
	metadataCacheFilename string, quiet bool) (*GDrive, error)

New returns a pointer to a new GDrive instance.

The uploadBytesPerSecond and downloadBytesPerSecond parameters can be used to specify bandwidth limits if rate-limited uploads or downloads are desired. If zero, bandwidth use is unconstrained.

The debug parameter can be used to provide a callback function to be used to log debugging information and all HTTP requrests go over the provided http.Client. Finally, metadata about files stored on Drive is cached locally in metadataCacheFilename.

func (*GDrive) AddProperty

func (gd *GDrive) AddProperty(key, value string, f *File) error

AddProperty adds the property with given key and value to the provided file and updates the file in Google Drive.

func (*GDrive) CheckMetadata

func (gd *GDrive) CheckMetadata(filename string, report func(string)) error

CheckMetadata downloads the metadata about all of the files currently stored on Drive and compares it with the local cache.

func (*GDrive) CreateFile

func (gd *GDrive) CreateFile(name string, parent *File,
	modTime time.Time, proplist []Property) (*File, error)

CreateFile creates an actual file in Google Drive with the given filename. The new file is in the folder given by represented by the 'parent' parameter, is initialized to have the given modification time and the provided Google Drive file properties. The returned File value represents the file in Drive.

func (*GDrive) CreateFolder

func (gd *GDrive) CreateFolder(name string, parent *File,
	modTime time.Time, proplist []Property) (*File, error)

CreateFolder creates a new folder in Google Drive with given name.

func (*GDrive) DeleteFile

func (gd *GDrive) DeleteFile(f *File) error

DeleteFile deletes the given file from Google Drive; note that deletion is permanent and un-reversable! (Consider TrashFile instead.)

func (*GDrive) GetDriveUsage

func (gd *GDrive) GetDriveUsage() (Usage, error)

GetDriveUsage returns a structure with information about the current storage usage on Google Drive.

func (*GDrive) GetFile

func (gd *GDrive) GetFile(path string) (*File, error)

GetFile returns the File corresponding to a file or folder specified by the given path starting from the root of the Google Drive filesystem. (Note that File is used to represent both files and folders in Google Drive.)

func (*GDrive) GetFileById

func (gd *GDrive) GetFileById(id string) (*drive.File, error)

GetFileById returns the *drive.File corresponding to the string Id Google Drive uses to uniquely identify the file. It deals with timeouts and transient errors.

func (*GDrive) GetFileContents

func (gd *GDrive) GetFileContents(f *File) (io.ReadCloser, error)

GetFileContents returns an io.ReadCloser that provides the contents of the given File.

func (*GDrive) GetFiles

func (gd *GDrive) GetFiles(path string) []*File

GetFiles returns File structures for *all* of the files in Google Drive that correspond to the given path. Because Google Drive allows multiple files to have the same title (and allows multiple folders of the same name), more than one file may be returned

Note: an error is not returned if the file doesn't exist; the caller should detect that case by checking for a zero-length returned array.

func (*GDrive) GetFilesInFolder

func (gd *GDrive) GetFilesInFolder(path string) ([]*File, error)

GetFilesInFolder returns a *File array representing the files in the given folder with the given name. The files are sorted by pathname.

func (*GDrive) GetFilesUnderFolder

func (gd *GDrive) GetFilesUnderFolder(path string, includeBase bool) ([]*File, error)

GetFilesUnderFolder returns an array of File pointers that represents all of the files stored in GoogleDrive under the given path. The 'includeBase' parameter indicates whether the file corresponding to the given path's folder should be included.

func (*GDrive) TrashFile

func (gd *GDrive) TrashFile(f *File) error

TrashFile moves the given Google Drive file to the trash; it is not immediately deleted permanently.

func (*GDrive) UpdateMetadataCache

func (gd *GDrive) UpdateMetadataCache(filename string) error

UpdateMetadataCache initializes the local cache of metadata about the files and folders currently on Google Drive, reading content from filename and querying Drive for changes. If updates are found, the local cache in filename is updated.

func (*GDrive) UpdateModificationTime

func (gd *GDrive) UpdateModificationTime(f *File, newTime time.Time) error

UpdateModificationTime updates the modification time of the given Google Drive file to the given time.

func (*GDrive) UpdateProperty

func (gd *GDrive) UpdateProperty(f *File, key string, value string) error

UpdateProperty updates the property with name 'key' to the value 'value' in the given file on Google Drive.

func (*GDrive) UploadFileContents

func (gd *GDrive) UploadFileContents(f *File, contentsReader io.Reader,
	length int64, try int) error

UploadFileContents uploads the file contents given by the io.Reader to the given File. The upload may fail due to various transient network errors; as such, the caller should check to see if a non-nil returned error code is a RetryHTTPTransmitError. In this case, it should try again, providing a new io.Reader that points to the start of the file. The 'try' parameter should track how many times this function has been called to try to upload the given file due to RetryHTTPTransmitErrors.

func (*GDrive) UploadFileContentsResumable

func (gd *GDrive) UploadFileContentsResumable(file *File,
	contentsReader io.Reader, contentLength int64) error

UploadFileContentsResumable uses the resumable upload protocol to upload the file contents from the given Reader to the given *drive.File on Google Drive. This approach is more expensive than UploadFileContents() for files under a few megabytes, but is helpful for large files in that it's more robust to transient errors and can handle OAuth2 token refreshes in the middle of an upload, unlike the regular approach.

type HTTPResponseResult

type HTTPResponseResult int

type Property

type Property struct {
	Key, Value string
}

Property represents a user-specified property associated with a Drive file.

type RetryHTTPTransmitError

type RetryHTTPTransmitError struct {
	StatusCode int
	StatusBody string
}

RetryHTTPTransmitError is a small struct to let us detect error cases where the caller should retry the operation, as the error seems to be a transient HTTP issue.

func (RetryHTTPTransmitError) Error

func (r RetryHTTPTransmitError) Error() string

type SpaceUser

type SpaceUser struct {
	Name string
	Used int64
}

type Usage

type Usage struct {
	Capacity int64
	Used     int64
	Users    []SpaceUser
}