googleapi.go

Documentation: google.golang.org/api/googleapi

     1  // Copyright 2011 Google LLC. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package googleapi contains the common code shared by all Google API
     6  // libraries.
     7  package googleapi // import "google.golang.org/api/googleapi"
     8  
     9  import (
    10  	"bytes"
    11  	"encoding/json"
    12  	"fmt"
    13  	"io"
    14  	"net/http"
    15  	"net/url"
    16  	"strings"
    17  	"time"
    18  
    19  	"google.golang.org/api/internal/third_party/uritemplates"
    20  )
    21  
    22  // ContentTyper is an interface for Readers which know (or would like
    23  // to override) their Content-Type. If a media body doesn't implement
    24  // ContentTyper, the type is sniffed from the content using
    25  // http.DetectContentType.
    26  type ContentTyper interface {
    27  	ContentType() string
    28  }
    29  
    30  // A SizeReaderAt is a ReaderAt with a Size method.
    31  // An io.SectionReader implements SizeReaderAt.
    32  type SizeReaderAt interface {
    33  	io.ReaderAt
    34  	Size() int64
    35  }
    36  
    37  // ServerResponse is embedded in each Do response and
    38  // provides the HTTP status code and header sent by the server.
    39  type ServerResponse struct {
    40  	// HTTPStatusCode is the server's response status code. When using a
    41  	// resource method's Do call, this will always be in the 2xx range.
    42  	HTTPStatusCode int
    43  	// Header contains the response header fields from the server.
    44  	Header http.Header
    45  }
    46  
    47  const (
    48  	// Version defines the gax version being used. This is typically sent
    49  	// in an HTTP header to services.
    50  	Version = "0.5"
    51  
    52  	// UserAgent is the header string used to identify this package.
    53  	UserAgent = "google-api-go-client/" + Version
    54  
    55  	// DefaultUploadChunkSize is the default chunk size to use for resumable
    56  	// uploads if not specified by the user.
    57  	DefaultUploadChunkSize = 16 * 1024 * 1024
    58  
    59  	// MinUploadChunkSize is the minimum chunk size that can be used for
    60  	// resumable uploads.  All user-specified chunk sizes must be multiple of
    61  	// this value.
    62  	MinUploadChunkSize = 256 * 1024
    63  )
    64  
    65  // Error contains an error response from the server.
    66  type Error struct {
    67  	// Code is the HTTP response status code and will always be populated.
    68  	Code int `json:"code"`
    69  	// Message is the server response message and is only populated when
    70  	// explicitly referenced by the JSON server response.
    71  	Message string `json:"message"`
    72  	// Details provide more context to an error.
    73  	Details []interface{} `json:"details"`
    74  	// Body is the raw response returned by the server.
    75  	// It is often but not always JSON, depending on how the request fails.
    76  	Body string
    77  	// Header contains the response header fields from the server.
    78  	Header http.Header
    79  
    80  	Errors []ErrorItem
    81  	// err is typically a wrapped apierror.APIError, see
    82  	// google-api-go-client/internal/gensupport/error.go.
    83  	err error
    84  }
    85  
    86  // ErrorItem is a detailed error code & message from the Google API frontend.
    87  type ErrorItem struct {
    88  	// Reason is the typed error code. For example: "some_example".
    89  	Reason string `json:"reason"`
    90  	// Message is the human-readable description of the error.
    91  	Message string `json:"message"`
    92  }
    93  
    94  func (e *Error) Error() string {
    95  	if len(e.Errors) == 0 && e.Message == "" {
    96  		return fmt.Sprintf("googleapi: got HTTP response code %d with body: %v", e.Code, e.Body)
    97  	}
    98  	var buf bytes.Buffer
    99  	fmt.Fprintf(&buf, "googleapi: Error %d: ", e.Code)
   100  	if e.Message != "" {
   101  		fmt.Fprintf(&buf, "%s", e.Message)
   102  	}
   103  	if len(e.Details) > 0 {
   104  		var detailBuf bytes.Buffer
   105  		enc := json.NewEncoder(&detailBuf)
   106  		enc.SetIndent("", "  ")
   107  		if err := enc.Encode(e.Details); err == nil {
   108  			fmt.Fprint(&buf, "\nDetails:")
   109  			fmt.Fprintf(&buf, "\n%s", detailBuf.String())
   110  
   111  		}
   112  	}
   113  	if len(e.Errors) == 0 {
   114  		return strings.TrimSpace(buf.String())
   115  	}
   116  	if len(e.Errors) == 1 && e.Errors[0].Message == e.Message {
   117  		fmt.Fprintf(&buf, ", %s", e.Errors[0].Reason)
   118  		return buf.String()
   119  	}
   120  	fmt.Fprintln(&buf, "\nMore details:")
   121  	for _, v := range e.Errors {
   122  		fmt.Fprintf(&buf, "Reason: %s, Message: %s\n", v.Reason, v.Message)
   123  	}
   124  	return buf.String()
   125  }
   126  
   127  // Wrap allows an existing Error to wrap another error. See also [Error.Unwrap].
   128  func (e *Error) Wrap(err error) {
   129  	e.err = err
   130  }
   131  
   132  func (e *Error) Unwrap() error {
   133  	return e.err
   134  }
   135  
   136  type errorReply struct {
   137  	Error *Error `json:"error"`
   138  }
   139  
   140  // CheckResponse returns an error (of type *Error) if the response
   141  // status code is not 2xx.
   142  func CheckResponse(res *http.Response) error {
   143  	if res.StatusCode >= 200 && res.StatusCode <= 299 {
   144  		return nil
   145  	}
   146  	slurp, err := io.ReadAll(res.Body)
   147  	if err == nil {
   148  		jerr := new(errorReply)
   149  		err = json.Unmarshal(slurp, jerr)
   150  		if err == nil && jerr.Error != nil {
   151  			if jerr.Error.Code == 0 {
   152  				jerr.Error.Code = res.StatusCode
   153  			}
   154  			jerr.Error.Body = string(slurp)
   155  			jerr.Error.Header = res.Header
   156  			return jerr.Error
   157  		}
   158  	}
   159  	return &Error{
   160  		Code:   res.StatusCode,
   161  		Body:   string(slurp),
   162  		Header: res.Header,
   163  	}
   164  }
   165  
   166  // IsNotModified reports whether err is the result of the
   167  // server replying with http.StatusNotModified.
   168  // Such error values are sometimes returned by "Do" methods
   169  // on calls when If-None-Match is used.
   170  func IsNotModified(err error) bool {
   171  	if err == nil {
   172  		return false
   173  	}
   174  	ae, ok := err.(*Error)
   175  	return ok && ae.Code == http.StatusNotModified
   176  }
   177  
   178  // CheckMediaResponse returns an error (of type *Error) if the response
   179  // status code is not 2xx. Unlike CheckResponse it does not assume the
   180  // body is a JSON error document.
   181  // It is the caller's responsibility to close res.Body.
   182  func CheckMediaResponse(res *http.Response) error {
   183  	if res.StatusCode >= 200 && res.StatusCode <= 299 {
   184  		return nil
   185  	}
   186  	slurp, _ := io.ReadAll(io.LimitReader(res.Body, 1<<20))
   187  	return &Error{
   188  		Code:   res.StatusCode,
   189  		Body:   string(slurp),
   190  		Header: res.Header,
   191  	}
   192  }
   193  
   194  // MarshalStyle defines whether to marshal JSON with a {"data": ...} wrapper.
   195  type MarshalStyle bool
   196  
   197  // WithDataWrapper marshals JSON with a {"data": ...} wrapper.
   198  var WithDataWrapper = MarshalStyle(true)
   199  
   200  // WithoutDataWrapper marshals JSON without a {"data": ...} wrapper.
   201  var WithoutDataWrapper = MarshalStyle(false)
   202  
   203  func (wrap MarshalStyle) JSONReader(v interface{}) (io.Reader, error) {
   204  	buf := new(bytes.Buffer)
   205  	if wrap {
   206  		buf.Write([]byte(`{"data": `))
   207  	}
   208  	err := json.NewEncoder(buf).Encode(v)
   209  	if err != nil {
   210  		return nil, err
   211  	}
   212  	if wrap {
   213  		buf.Write([]byte(`}`))
   214  	}
   215  	return buf, nil
   216  }
   217  
   218  // ProgressUpdater is a function that is called upon every progress update of a resumable upload.
   219  // This is the only part of a resumable upload (from googleapi) that is usable by the developer.
   220  // The remaining usable pieces of resumable uploads is exposed in each auto-generated API.
   221  type ProgressUpdater func(current, total int64)
   222  
   223  // MediaOption defines the interface for setting media options.
   224  type MediaOption interface {
   225  	setOptions(o *MediaOptions)
   226  }
   227  
   228  type contentTypeOption string
   229  
   230  func (ct contentTypeOption) setOptions(o *MediaOptions) {
   231  	o.ContentType = string(ct)
   232  	if o.ContentType == "" {
   233  		o.ForceEmptyContentType = true
   234  	}
   235  }
   236  
   237  // ContentType returns a MediaOption which sets the Content-Type header for media uploads.
   238  // If ctype is empty, the Content-Type header will be omitted.
   239  func ContentType(ctype string) MediaOption {
   240  	return contentTypeOption(ctype)
   241  }
   242  
   243  type chunkSizeOption int
   244  
   245  func (cs chunkSizeOption) setOptions(o *MediaOptions) {
   246  	size := int(cs)
   247  	if size%MinUploadChunkSize != 0 {
   248  		size += MinUploadChunkSize - (size % MinUploadChunkSize)
   249  	}
   250  	o.ChunkSize = size
   251  }
   252  
   253  // ChunkSize returns a MediaOption which sets the chunk size for media uploads.
   254  // size will be rounded up to the nearest multiple of 256K.
   255  // Media which contains fewer than size bytes will be uploaded in a single request.
   256  // Media which contains size bytes or more will be uploaded in separate chunks.
   257  // If size is zero, media will be uploaded in a single request.
   258  func ChunkSize(size int) MediaOption {
   259  	return chunkSizeOption(size)
   260  }
   261  
   262  type chunkRetryDeadlineOption time.Duration
   263  
   264  func (cd chunkRetryDeadlineOption) setOptions(o *MediaOptions) {
   265  	o.ChunkRetryDeadline = time.Duration(cd)
   266  }
   267  
   268  // ChunkRetryDeadline returns a MediaOption which sets a per-chunk retry
   269  // deadline. If a single chunk has been attempting to upload for longer than
   270  // this time and the request fails, it will no longer be retried, and the error
   271  // will be returned to the caller.
   272  // This is only applicable for files which are large enough to require
   273  // a multi-chunk resumable upload.
   274  // The default value is 32s.
   275  // To set a deadline on the entire upload, use context timeout or cancellation.
   276  func ChunkRetryDeadline(deadline time.Duration) MediaOption {
   277  	return chunkRetryDeadlineOption(deadline)
   278  }
   279  
   280  // MediaOptions stores options for customizing media upload.  It is not used by developers directly.
   281  type MediaOptions struct {
   282  	ContentType           string
   283  	ForceEmptyContentType bool
   284  	ChunkSize             int
   285  	ChunkRetryDeadline    time.Duration
   286  }
   287  
   288  // ProcessMediaOptions stores options from opts in a MediaOptions.
   289  // It is not used by developers directly.
   290  func ProcessMediaOptions(opts []MediaOption) *MediaOptions {
   291  	mo := &MediaOptions{ChunkSize: DefaultUploadChunkSize}
   292  	for _, o := range opts {
   293  		o.setOptions(mo)
   294  	}
   295  	return mo
   296  }
   297  
   298  // ResolveRelative resolves relatives such as "http://www.golang.org/" and
   299  // "topics/myproject/mytopic" into a single string, such as
   300  // "http://www.golang.org/topics/myproject/mytopic". It strips all parent
   301  // references (e.g. ../..) as well as anything after the host
   302  // (e.g. /bar/gaz gets stripped out of foo.com/bar/gaz).
   303  //
   304  // ResolveRelative panics if either basestr or relstr is not able to be parsed.
   305  func ResolveRelative(basestr, relstr string) string {
   306  	u, err := url.Parse(basestr)
   307  	if err != nil {
   308  		panic(fmt.Sprintf("failed to parse %q", basestr))
   309  	}
   310  	afterColonPath := ""
   311  	if i := strings.IndexRune(relstr, ':'); i > 0 {
   312  		afterColonPath = relstr[i+1:]
   313  		relstr = relstr[:i]
   314  	}
   315  	rel, err := url.Parse(relstr)
   316  	if err != nil {
   317  		panic(fmt.Sprintf("failed to parse %q", relstr))
   318  	}
   319  	u = u.ResolveReference(rel)
   320  	us := u.String()
   321  	if afterColonPath != "" {
   322  		us = fmt.Sprintf("%s:%s", us, afterColonPath)
   323  	}
   324  	us = strings.Replace(us, "%7B", "{", -1)
   325  	us = strings.Replace(us, "%7D", "}", -1)
   326  	us = strings.Replace(us, "%2A", "*", -1)
   327  	return us
   328  }
   329  
   330  // Expand subsitutes any {encoded} strings in the URL passed in using
   331  // the map supplied.
   332  //
   333  // This calls SetOpaque to avoid encoding of the parameters in the URL path.
   334  func Expand(u *url.URL, expansions map[string]string) {
   335  	escaped, unescaped, err := uritemplates.Expand(u.Path, expansions)
   336  	if err == nil {
   337  		u.Path = unescaped
   338  		u.RawPath = escaped
   339  	}
   340  }
   341  
   342  // CloseBody is used to close res.Body.
   343  // Prior to calling Close, it also tries to Read a small amount to see an EOF.
   344  // Not seeing an EOF can prevent HTTP Transports from reusing connections.
   345  func CloseBody(res *http.Response) {
   346  	if res == nil || res.Body == nil {
   347  		return
   348  	}
   349  	// Justification for 3 byte reads: two for up to "\r\n" after
   350  	// a JSON/XML document, and then 1 to see EOF if we haven't yet.
   351  	// TODO(bradfitz): detect Go 1.3+ and skip these reads.
   352  	// See https://codereview.appspot.com/58240043
   353  	// and https://codereview.appspot.com/49570044
   354  	buf := make([]byte, 1)
   355  	for i := 0; i < 3; i++ {
   356  		_, err := res.Body.Read(buf)
   357  		if err != nil {
   358  			break
   359  		}
   360  	}
   361  	res.Body.Close()
   362  
   363  }
   364  
   365  // VariantType returns the type name of the given variant.
   366  // If the map doesn't contain the named key or the value is not a []interface{}, "" is returned.
   367  // This is used to support "variant" APIs that can return one of a number of different types.
   368  func VariantType(t map[string]interface{}) string {
   369  	s, _ := t["type"].(string)
   370  	return s
   371  }
   372  
   373  // ConvertVariant uses the JSON encoder/decoder to fill in the struct 'dst' with the fields found in variant 'v'.
   374  // This is used to support "variant" APIs that can return one of a number of different types.
   375  // It reports whether the conversion was successful.
   376  func ConvertVariant(v map[string]interface{}, dst interface{}) bool {
   377  	var buf bytes.Buffer
   378  	err := json.NewEncoder(&buf).Encode(v)
   379  	if err != nil {
   380  		return false
   381  	}
   382  	return json.Unmarshal(buf.Bytes(), dst) == nil
   383  }
   384  
   385  // A Field names a field to be retrieved with a partial response.
   386  // https://cloud.google.com/storage/docs/json_api/v1/how-tos/performance
   387  //
   388  // Partial responses can dramatically reduce the amount of data that must be sent to your application.
   389  // In order to request partial responses, you can specify the full list of fields
   390  // that your application needs by adding the Fields option to your request.
   391  //
   392  // Field strings use camelCase with leading lower-case characters to identify fields within the response.
   393  //
   394  // For example, if your response has a "NextPageToken" and a slice of "Items" with "Id" fields,
   395  // you could request just those fields like this:
   396  //
   397  //	svc.Events.List().Fields("nextPageToken", "items/id").Do()
   398  //
   399  // or if you were also interested in each Item's "Updated" field, you can combine them like this:
   400  //
   401  //	svc.Events.List().Fields("nextPageToken", "items(id,updated)").Do()
   402  //
   403  // Another way to find field names is through the Google API explorer:
   404  // https://developers.google.com/apis-explorer/#p/
   405  type Field string
   406  
   407  // CombineFields combines fields into a single string.
   408  func CombineFields(s []Field) string {
   409  	r := make([]string, len(s))
   410  	for i, v := range s {
   411  		r[i] = string(v)
   412  	}
   413  	return strings.Join(r, ",")
   414  }
   415  
   416  // A CallOption is an optional argument to an API call.
   417  // It should be treated as an opaque value by users of Google APIs.
   418  //
   419  // A CallOption is something that configures an API call in a way that is
   420  // not specific to that API; for instance, controlling the quota user for
   421  // an API call is common across many APIs, and is thus a CallOption.
   422  type CallOption interface {
   423  	Get() (key, value string)
   424  }
   425  
   426  // A MultiCallOption is an option argument to an API call and can be passed
   427  // anywhere a CallOption is accepted. It additionally supports returning a slice
   428  // of values for a given key.
   429  type MultiCallOption interface {
   430  	CallOption
   431  	GetMulti() (key string, value []string)
   432  }
   433  
   434  // QuotaUser returns a CallOption that will set the quota user for a call.
   435  // The quota user can be used by server-side applications to control accounting.
   436  // It can be an arbitrary string up to 40 characters, and will override UserIP
   437  // if both are provided.
   438  func QuotaUser(u string) CallOption { return quotaUser(u) }
   439  
   440  type quotaUser string
   441  
   442  func (q quotaUser) Get() (string, string) { return "quotaUser", string(q) }
   443  
   444  // UserIP returns a CallOption that will set the "userIp" parameter of a call.
   445  // This should be the IP address of the originating request.
   446  func UserIP(ip string) CallOption { return userIP(ip) }
   447  
   448  type userIP string
   449  
   450  func (i userIP) Get() (string, string) { return "userIp", string(i) }
   451  
   452  // Trace returns a CallOption that enables diagnostic tracing for a call.
   453  // traceToken is an ID supplied by Google support.
   454  func Trace(traceToken string) CallOption { return traceTok(traceToken) }
   455  
   456  type traceTok string
   457  
   458  func (t traceTok) Get() (string, string) { return "trace", "token:" + string(t) }
   459  
   460  type queryParameter struct {
   461  	key    string
   462  	values []string
   463  }
   464  
   465  // QueryParameter allows setting the value(s) of an arbitrary key.
   466  func QueryParameter(key string, values ...string) CallOption {
   467  	return queryParameter{key: key, values: append([]string{}, values...)}
   468  }
   469  
   470  // Get will never actually be called -- GetMulti will.
   471  func (q queryParameter) Get() (string, string) {
   472  	return "", ""
   473  }
   474  
   475  // GetMulti returns the key and values values associated to that key.
   476  func (q queryParameter) GetMulti() (string, []string) {
   477  	return q.key, q.values
   478  }
   479  
   480  // TODO: Fields too
   481
View as plain text