Update Azure SDK (#4985)

2026-08-08 23:33:30 +03:00 · 2017-09-29 03:53:46 +05:30
parent 789270af3c
commit 94670a387e
67 changed files with 9548 additions and 2435 deletions
@@ -4,9 +4,11 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"io/ioutil"
 	"net/http"
 	"net/url"
 	"strconv"
+	"sync"
 )

 const fourMB = uint64(4194304)
@@ -14,12 +16,14 @@ const oneTB = uint64(1099511627776)

 // File represents a file on a share.
 type File struct {
-	fsc        *FileServiceClient
-	Metadata   map[string]string
-	Name       string `xml:"Name"`
-	parent     *Directory
-	Properties FileProperties `xml:"Properties"`
-	share      *Share
+	fsc                *FileServiceClient
+	Metadata           map[string]string
+	Name               string `xml:"Name"`
+	parent             *Directory
+	Properties         FileProperties `xml:"Properties"`
+	share              *Share
+	FileCopyProperties FileCopyState
+	mutex              *sync.Mutex
 }

 // FileProperties contains various properties of a file.
@@ -30,7 +34,7 @@ type FileProperties struct {
 	Etag         string
 	Language     string `header:"x-ms-content-language"`
 	LastModified string
-	Length       uint64 `xml:"Content-Length"`
+	Length       uint64 `xml:"Content-Length" header:"x-ms-content-length"`
 	MD5          string `header:"x-ms-content-md5"`
 	Type         string `header:"x-ms-content-type"`
 }
@@ -38,10 +42,10 @@ type FileProperties struct {
 // FileCopyState contains various properties of a file copy operation.
 type FileCopyState struct {
 	CompletionTime string
-	ID             string
+	ID             string `header:"x-ms-copy-id"`
 	Progress       string
 	Source         string
-	Status         string
+	Status         string `header:"x-ms-copy-status"`
 	StatusDesc     string
 }

@@ -51,9 +55,23 @@ type FileStream struct {
 	ContentMD5 string
 }

+// FileRequestOptions will be passed to misc file operations.
+// Currently just Timeout (in seconds) but could expand.
+type FileRequestOptions struct {
+	Timeout uint // timeout duration in seconds.
+}
+
+func prepareOptions(options *FileRequestOptions) url.Values {
+	params := url.Values{}
+	if options != nil {
+		params = addTimeout(params, options.Timeout)
+	}
+	return params
+}
+
 // FileRanges contains a list of file range information for a file.
 //
-// See https://msdn.microsoft.com/en-us/library/azure/dn166984.aspx
+// See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/List-Ranges
 type FileRanges struct {
 	ContentLength uint64
 	LastModified  string
@@ -63,7 +81,7 @@ type FileRanges struct {

 // FileRange contains range information for a file.
 //
-// See https://msdn.microsoft.com/en-us/library/azure/dn166984.aspx
+// See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/List-Ranges
 type FileRange struct {
 	Start uint64 `xml:"Start"`
 	End   uint64 `xml:"End"`
@@ -80,9 +98,13 @@ func (f *File) buildPath() string {

 // ClearRange releases the specified range of space in a file.
 //
-// See https://msdn.microsoft.com/en-us/library/azure/dn194276.aspx
-func (f *File) ClearRange(fileRange FileRange) error {
-	headers, err := f.modifyRange(nil, fileRange, nil)
+// See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/Put-Range
+func (f *File) ClearRange(fileRange FileRange, options *FileRequestOptions) error {
+	var timeout *uint
+	if options != nil {
+		timeout = &options.Timeout
+	}
+	headers, err := f.modifyRange(nil, fileRange, timeout, nil)
 	if err != nil {
 		return err
 	}
@@ -93,41 +115,61 @@ func (f *File) ClearRange(fileRange FileRange) error {

 // Create creates a new file or replaces an existing one.
 //
-// See https://msdn.microsoft.com/en-us/library/azure/dn194271.aspx
-func (f *File) Create(maxSize uint64) error {
+// See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/Create-File
+func (f *File) Create(maxSize uint64, options *FileRequestOptions) error {
 	if maxSize > oneTB {
 		return fmt.Errorf("max file size is 1TB")
 	}
+	params := prepareOptions(options)
+	headers := headersFromStruct(f.Properties)
+	headers["x-ms-content-length"] = strconv.FormatUint(maxSize, 10)
+	headers["x-ms-type"] = "file"

-	extraHeaders := map[string]string{
-		"x-ms-content-length": strconv.FormatUint(maxSize, 10),
-		"x-ms-type":           "file",
-	}
-
-	headers, err := f.fsc.createResource(f.buildPath(), resourceFile, mergeMDIntoExtraHeaders(f.Metadata, extraHeaders))
+	outputHeaders, err := f.fsc.createResource(f.buildPath(), resourceFile, params, mergeMDIntoExtraHeaders(f.Metadata, headers), []int{http.StatusCreated})
 	if err != nil {
 		return err
 	}

 	f.Properties.Length = maxSize
+	f.updateEtagAndLastModified(outputHeaders)
+	return nil
+}
+
+// CopyFile operation copied a file/blob from the sourceURL to the path provided.
+//
+// See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/copy-file
+func (f *File) CopyFile(sourceURL string, options *FileRequestOptions) error {
+	extraHeaders := map[string]string{
+		"x-ms-type":        "file",
+		"x-ms-copy-source": sourceURL,
+	}
+	params := prepareOptions(options)
+
+	headers, err := f.fsc.createResource(f.buildPath(), resourceFile, params, mergeMDIntoExtraHeaders(f.Metadata, extraHeaders), []int{http.StatusAccepted})
+	if err != nil {
+		return err
+	}
+
 	f.updateEtagAndLastModified(headers)
+	f.FileCopyProperties.ID = headers.Get("X-Ms-Copy-Id")
+	f.FileCopyProperties.Status = headers.Get("X-Ms-Copy-Status")
 	return nil
 }

 // Delete immediately removes this file from the storage account.
 //
-// See https://msdn.microsoft.com/en-us/library/azure/dn689085.aspx
-func (f *File) Delete() error {
-	return f.fsc.deleteResource(f.buildPath(), resourceFile)
+// See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/Delete-File2
+func (f *File) Delete(options *FileRequestOptions) error {
+	return f.fsc.deleteResource(f.buildPath(), resourceFile, options)
 }

 // DeleteIfExists removes this file if it exists.
 //
-// See https://msdn.microsoft.com/en-us/library/azure/dn689085.aspx
-func (f *File) DeleteIfExists() (bool, error) {
-	resp, err := f.fsc.deleteResourceNoClose(f.buildPath(), resourceFile)
+// See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/Delete-File2
+func (f *File) DeleteIfExists(options *FileRequestOptions) (bool, error) {
+	resp, err := f.fsc.deleteResourceNoClose(f.buildPath(), resourceFile, options)
 	if resp != nil {
-		defer resp.body.Close()
+		defer readAndCloseBody(resp.body)
 		if resp.statusCode == http.StatusAccepted || resp.statusCode == http.StatusNotFound {
 			return resp.statusCode == http.StatusAccepted, nil
 		}
@@ -135,33 +177,59 @@ func (f *File) DeleteIfExists() (bool, error) {
 	return false, err
 }

+// GetFileOptions includes options for a get file operation
+type GetFileOptions struct {
+	Timeout       uint
+	GetContentMD5 bool
+}
+
+// DownloadToStream operation downloads the file.
+//
+// See: https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/get-file
+func (f *File) DownloadToStream(options *FileRequestOptions) (io.ReadCloser, error) {
+	params := prepareOptions(options)
+	resp, err := f.fsc.getResourceNoClose(f.buildPath(), compNone, resourceFile, params, http.MethodGet, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	if err = checkRespCode(resp.statusCode, []int{http.StatusOK}); err != nil {
+		readAndCloseBody(resp.body)
+		return nil, err
+	}
+	return resp.body, nil
+}
+
 // DownloadRangeToStream operation downloads the specified range of this file with optional MD5 hash.
 //
 // See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/get-file
-func (f *File) DownloadRangeToStream(fileRange FileRange, getContentMD5 bool) (fs FileStream, err error) {
-	if getContentMD5 && isRangeTooBig(fileRange) {
-		return fs, fmt.Errorf("must specify a range less than or equal to 4MB when getContentMD5 is true")
-	}
-
+func (f *File) DownloadRangeToStream(fileRange FileRange, options *GetFileOptions) (fs FileStream, err error) {
 	extraHeaders := map[string]string{
 		"Range": fileRange.String(),
 	}
-	if getContentMD5 == true {
-		extraHeaders["x-ms-range-get-content-md5"] = "true"
+	params := url.Values{}
+	if options != nil {
+		if options.GetContentMD5 {
+			if isRangeTooBig(fileRange) {
+				return fs, fmt.Errorf("must specify a range less than or equal to 4MB when getContentMD5 is true")
+			}
+			extraHeaders["x-ms-range-get-content-md5"] = "true"
+		}
+		params = addTimeout(params, options.Timeout)
 	}

-	resp, err := f.fsc.getResourceNoClose(f.buildPath(), compNone, resourceFile, http.MethodGet, extraHeaders)
+	resp, err := f.fsc.getResourceNoClose(f.buildPath(), compNone, resourceFile, params, http.MethodGet, extraHeaders)
 	if err != nil {
 		return fs, err
 	}

 	if err = checkRespCode(resp.statusCode, []int{http.StatusOK, http.StatusPartialContent}); err != nil {
-		resp.body.Close()
+		readAndCloseBody(resp.body)
 		return fs, err
 	}

 	fs.Body = resp.body
-	if getContentMD5 {
+	if options != nil && options.GetContentMD5 {
 		fs.ContentMD5 = resp.headers.Get("Content-MD5")
 	}
 	return fs, nil
@@ -178,8 +246,10 @@ func (f *File) Exists() (bool, error) {
 }

 // FetchAttributes updates metadata and properties for this file.
-func (f *File) FetchAttributes() error {
-	headers, err := f.fsc.getResourceHeaders(f.buildPath(), compNone, resourceFile, http.MethodHead)
+// See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/get-file-properties
+func (f *File) FetchAttributes(options *FileRequestOptions) error {
+	params := prepareOptions(options)
+	headers, err := f.fsc.getResourceHeaders(f.buildPath(), compNone, resourceFile, params, http.MethodHead)
 	if err != nil {
 		return err
 	}
@@ -199,17 +269,26 @@ func isRangeTooBig(fileRange FileRange) bool {
 	return false
 }

+// ListRangesOptions includes options for a list file ranges operation
+type ListRangesOptions struct {
+	Timeout   uint
+	ListRange *FileRange
+}
+
 // ListRanges returns the list of valid ranges for this file.
 //
-// See https://msdn.microsoft.com/en-us/library/azure/dn166984.aspx
-func (f *File) ListRanges(listRange *FileRange) (*FileRanges, error) {
+// See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/List-Ranges
+func (f *File) ListRanges(options *ListRangesOptions) (*FileRanges, error) {
 	params := url.Values{"comp": {"rangelist"}}

 	// add optional range to list
 	var headers map[string]string
-	if listRange != nil {
-		headers = make(map[string]string)
-		headers["Range"] = listRange.String()
+	if options != nil {
+		params = addTimeout(params, options.Timeout)
+		if options.ListRange != nil {
+			headers = make(map[string]string)
+			headers["Range"] = options.ListRange.String()
+		}
 	}

 	resp, err := f.fsc.listContent(f.buildPath(), params, headers)
@@ -221,6 +300,7 @@ func (f *File) ListRanges(listRange *FileRange) (*FileRanges, error) {
 	var cl uint64
 	cl, err = strconv.ParseUint(resp.headers.Get("x-ms-content-length"), 10, 64)
 	if err != nil {
+		ioutil.ReadAll(resp.body)
 		return nil, err
 	}

@@ -234,7 +314,7 @@ func (f *File) ListRanges(listRange *FileRange) (*FileRanges, error) {
 }

 // modifies a range of bytes in this file
-func (f *File) modifyRange(bytes io.Reader, fileRange FileRange, contentMD5 *string) (http.Header, error) {
+func (f *File) modifyRange(bytes io.Reader, fileRange FileRange, timeout *uint, contentMD5 *string) (http.Header, error) {
 	if err := f.fsc.checkForStorageEmulator(); err != nil {
 		return nil, err
 	}
@@ -245,7 +325,12 @@ func (f *File) modifyRange(bytes io.Reader, fileRange FileRange, contentMD5 *str
 		return nil, errors.New("range cannot exceed 4MB in size")
 	}

-	uri := f.fsc.client.getEndpoint(fileServiceName, f.buildPath(), url.Values{"comp": {"range"}})
+	params := url.Values{"comp": {"range"}}
+	if timeout != nil {
+		params = addTimeout(params, *timeout)
+	}
+
+	uri := f.fsc.client.getEndpoint(fileServiceName, f.buildPath(), params)

 	// default to clear
 	write := "clear"
@@ -272,7 +357,7 @@ func (f *File) modifyRange(bytes io.Reader, fileRange FileRange, contentMD5 *str
 	if err != nil {
 		return nil, err
 	}
-	defer resp.body.Close()
+	defer readAndCloseBody(resp.body)
 	return resp.headers, checkRespCode(resp.statusCode, []int{http.StatusCreated})
 }

@@ -283,9 +368,9 @@ func (f *File) modifyRange(bytes io.Reader, fileRange FileRange, contentMD5 *str
 // are case-insensitive so case munging should not matter to other
 // applications either.
 //
-// See https://msdn.microsoft.com/en-us/library/azure/dn689097.aspx
-func (f *File) SetMetadata() error {
-	headers, err := f.fsc.setResourceHeaders(f.buildPath(), compMetadata, resourceFile, mergeMDIntoExtraHeaders(f.Metadata, nil))
+// See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/Set-File-Metadata
+func (f *File) SetMetadata(options *FileRequestOptions) error {
+	headers, err := f.fsc.setResourceHeaders(f.buildPath(), compMetadata, resourceFile, mergeMDIntoExtraHeaders(f.Metadata, nil), options)
 	if err != nil {
 		return err
 	}
@@ -301,9 +386,9 @@ func (f *File) SetMetadata() error {
 // are case-insensitive so case munging should not matter to other
 // applications either.
 //
-// See https://msdn.microsoft.com/en-us/library/azure/dn166975.aspx
-func (f *File) SetProperties() error {
-	headers, err := f.fsc.setResourceHeaders(f.buildPath(), compProperties, resourceFile, headersFromStruct(f.Properties))
+// See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/Set-File-Properties
+func (f *File) SetProperties(options *FileRequestOptions) error {
+	headers, err := f.fsc.setResourceHeaders(f.buildPath(), compProperties, resourceFile, headersFromStruct(f.Properties), options)
 	if err != nil {
 		return err
 	}
@@ -338,23 +423,40 @@ func (f *File) updateProperties(header http.Header) {
 // This method does not create a publicly accessible URL if the file
 // is private and this method does not check if the file exists.
 func (f *File) URL() string {
-	return f.fsc.client.getEndpoint(fileServiceName, f.buildPath(), url.Values{})
+	return f.fsc.client.getEndpoint(fileServiceName, f.buildPath(), nil)
 }

-// WriteRange writes a range of bytes to this file with an optional MD5 hash of the content.
-// Note that the length of bytes must match (rangeEnd - rangeStart) + 1 with a maximum size of 4MB.
+// WriteRangeOptions includes options for a write file range operation
+type WriteRangeOptions struct {
+	Timeout    uint
+	ContentMD5 string
+}
+
+// WriteRange writes a range of bytes to this file with an optional MD5 hash of the content (inside
+// options parameter). Note that the length of bytes must match (rangeEnd - rangeStart) + 1 with
+// a maximum size of 4MB.
 //
-// See https://msdn.microsoft.com/en-us/library/azure/dn194276.aspx
-func (f *File) WriteRange(bytes io.Reader, fileRange FileRange, contentMD5 *string) error {
+// See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/Put-Range
+func (f *File) WriteRange(bytes io.Reader, fileRange FileRange, options *WriteRangeOptions) error {
 	if bytes == nil {
 		return errors.New("bytes cannot be nil")
 	}
+	var timeout *uint
+	var md5 *string
+	if options != nil {
+		timeout = &options.Timeout
+		md5 = &options.ContentMD5
+	}

-	headers, err := f.modifyRange(bytes, fileRange, contentMD5)
+	headers, err := f.modifyRange(bytes, fileRange, timeout, md5)
 	if err != nil {
 		return err
 	}
-
+	// it's perfectly legal for multiple go routines to call WriteRange
+	// on the same *File (e.g. concurrently writing non-overlapping ranges)
+	// so we must take the file mutex before updating our properties.
+	f.mutex.Lock()
 	f.updateEtagAndLastModified(headers)
+	f.mutex.Unlock()
 	return nil
 }