You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 

416 lines
13 KiB

  1. // Copyright 2011 Google Inc. 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. // Package googleapi contains the common code shared by all Google API
  5. // libraries.
  6. package googleapi // import "google.golang.org/api/googleapi"
  7. import (
  8. "bytes"
  9. "encoding/json"
  10. "fmt"
  11. "io"
  12. "io/ioutil"
  13. "net/http"
  14. "net/url"
  15. "strings"
  16. "google.golang.org/api/googleapi/internal/uritemplates"
  17. )
  18. // ContentTyper is an interface for Readers which know (or would like
  19. // to override) their Content-Type. If a media body doesn't implement
  20. // ContentTyper, the type is sniffed from the content using
  21. // http.DetectContentType.
  22. type ContentTyper interface {
  23. ContentType() string
  24. }
  25. // A SizeReaderAt is a ReaderAt with a Size method.
  26. // An io.SectionReader implements SizeReaderAt.
  27. type SizeReaderAt interface {
  28. io.ReaderAt
  29. Size() int64
  30. }
  31. // ServerResponse is embedded in each Do response and
  32. // provides the HTTP status code and header sent by the server.
  33. type ServerResponse struct {
  34. // HTTPStatusCode is the server's response status code.
  35. // When using a resource method's Do call, this will always be in the 2xx range.
  36. HTTPStatusCode int
  37. // Header contains the response header fields from the server.
  38. Header http.Header
  39. }
  40. const (
  41. Version = "0.5"
  42. // UserAgent is the header string used to identify this package.
  43. UserAgent = "google-api-go-client/" + Version
  44. // The default chunk size to use for resumable uploads if not specified by the user.
  45. DefaultUploadChunkSize = 8 * 1024 * 1024
  46. // The minimum chunk size that can be used for resumable uploads. All
  47. // user-specified chunk sizes must be multiple of this value.
  48. MinUploadChunkSize = 256 * 1024
  49. )
  50. // Error contains an error response from the server.
  51. type Error struct {
  52. // Code is the HTTP response status code and will always be populated.
  53. Code int `json:"code"`
  54. // Message is the server response message and is only populated when
  55. // explicitly referenced by the JSON server response.
  56. Message string `json:"message"`
  57. // Body is the raw response returned by the server.
  58. // It is often but not always JSON, depending on how the request fails.
  59. Body string
  60. // Header contains the response header fields from the server.
  61. Header http.Header
  62. Errors []ErrorItem
  63. }
  64. // ErrorItem is a detailed error code & message from the Google API frontend.
  65. type ErrorItem struct {
  66. // Reason is the typed error code. For example: "some_example".
  67. Reason string `json:"reason"`
  68. // Message is the human-readable description of the error.
  69. Message string `json:"message"`
  70. }
  71. func (e *Error) Error() string {
  72. if len(e.Errors) == 0 && e.Message == "" {
  73. return fmt.Sprintf("googleapi: got HTTP response code %d with body: %v", e.Code, e.Body)
  74. }
  75. var buf bytes.Buffer
  76. fmt.Fprintf(&buf, "googleapi: Error %d: ", e.Code)
  77. if e.Message != "" {
  78. fmt.Fprintf(&buf, "%s", e.Message)
  79. }
  80. if len(e.Errors) == 0 {
  81. return strings.TrimSpace(buf.String())
  82. }
  83. if len(e.Errors) == 1 && e.Errors[0].Message == e.Message {
  84. fmt.Fprintf(&buf, ", %s", e.Errors[0].Reason)
  85. return buf.String()
  86. }
  87. fmt.Fprintln(&buf, "\nMore details:")
  88. for _, v := range e.Errors {
  89. fmt.Fprintf(&buf, "Reason: %s, Message: %s\n", v.Reason, v.Message)
  90. }
  91. return buf.String()
  92. }
  93. type errorReply struct {
  94. Error *Error `json:"error"`
  95. }
  96. // CheckResponse returns an error (of type *Error) if the response
  97. // status code is not 2xx.
  98. func CheckResponse(res *http.Response) error {
  99. if res.StatusCode >= 200 && res.StatusCode <= 299 {
  100. return nil
  101. }
  102. slurp, err := ioutil.ReadAll(res.Body)
  103. if err == nil {
  104. jerr := new(errorReply)
  105. err = json.Unmarshal(slurp, jerr)
  106. if err == nil && jerr.Error != nil {
  107. if jerr.Error.Code == 0 {
  108. jerr.Error.Code = res.StatusCode
  109. }
  110. jerr.Error.Body = string(slurp)
  111. return jerr.Error
  112. }
  113. }
  114. return &Error{
  115. Code: res.StatusCode,
  116. Body: string(slurp),
  117. Header: res.Header,
  118. }
  119. }
  120. // IsNotModified reports whether err is the result of the
  121. // server replying with http.StatusNotModified.
  122. // Such error values are sometimes returned by "Do" methods
  123. // on calls when If-None-Match is used.
  124. func IsNotModified(err error) bool {
  125. if err == nil {
  126. return false
  127. }
  128. ae, ok := err.(*Error)
  129. return ok && ae.Code == http.StatusNotModified
  130. }
  131. // CheckMediaResponse returns an error (of type *Error) if the response
  132. // status code is not 2xx. Unlike CheckResponse it does not assume the
  133. // body is a JSON error document.
  134. // It is the caller's responsibility to close res.Body.
  135. func CheckMediaResponse(res *http.Response) error {
  136. if res.StatusCode >= 200 && res.StatusCode <= 299 {
  137. return nil
  138. }
  139. slurp, _ := ioutil.ReadAll(io.LimitReader(res.Body, 1<<20))
  140. return &Error{
  141. Code: res.StatusCode,
  142. Body: string(slurp),
  143. }
  144. }
  145. type MarshalStyle bool
  146. var WithDataWrapper = MarshalStyle(true)
  147. var WithoutDataWrapper = MarshalStyle(false)
  148. func (wrap MarshalStyle) JSONReader(v interface{}) (io.Reader, error) {
  149. buf := new(bytes.Buffer)
  150. if wrap {
  151. buf.Write([]byte(`{"data": `))
  152. }
  153. err := json.NewEncoder(buf).Encode(v)
  154. if err != nil {
  155. return nil, err
  156. }
  157. if wrap {
  158. buf.Write([]byte(`}`))
  159. }
  160. return buf, nil
  161. }
  162. // endingWithErrorReader from r until it returns an error. If the
  163. // final error from r is io.EOF and e is non-nil, e is used instead.
  164. type endingWithErrorReader struct {
  165. r io.Reader
  166. e error
  167. }
  168. func (er endingWithErrorReader) Read(p []byte) (n int, err error) {
  169. n, err = er.r.Read(p)
  170. if err == io.EOF && er.e != nil {
  171. err = er.e
  172. }
  173. return
  174. }
  175. // countingWriter counts the number of bytes it receives to write, but
  176. // discards them.
  177. type countingWriter struct {
  178. n *int64
  179. }
  180. func (w countingWriter) Write(p []byte) (int, error) {
  181. *w.n += int64(len(p))
  182. return len(p), nil
  183. }
  184. // ProgressUpdater is a function that is called upon every progress update of a resumable upload.
  185. // This is the only part of a resumable upload (from googleapi) that is usable by the developer.
  186. // The remaining usable pieces of resumable uploads is exposed in each auto-generated API.
  187. type ProgressUpdater func(current, total int64)
  188. type MediaOption interface {
  189. setOptions(o *MediaOptions)
  190. }
  191. type contentTypeOption string
  192. func (ct contentTypeOption) setOptions(o *MediaOptions) {
  193. o.ContentType = string(ct)
  194. if o.ContentType == "" {
  195. o.ForceEmptyContentType = true
  196. }
  197. }
  198. // ContentType returns a MediaOption which sets the Content-Type header for media uploads.
  199. // If ctype is empty, the Content-Type header will be omitted.
  200. func ContentType(ctype string) MediaOption {
  201. return contentTypeOption(ctype)
  202. }
  203. type chunkSizeOption int
  204. func (cs chunkSizeOption) setOptions(o *MediaOptions) {
  205. size := int(cs)
  206. if size%MinUploadChunkSize != 0 {
  207. size += MinUploadChunkSize - (size % MinUploadChunkSize)
  208. }
  209. o.ChunkSize = size
  210. }
  211. // ChunkSize returns a MediaOption which sets the chunk size for media uploads.
  212. // size will be rounded up to the nearest multiple of 256K.
  213. // Media which contains fewer than size bytes will be uploaded in a single request.
  214. // Media which contains size bytes or more will be uploaded in separate chunks.
  215. // If size is zero, media will be uploaded in a single request.
  216. func ChunkSize(size int) MediaOption {
  217. return chunkSizeOption(size)
  218. }
  219. // MediaOptions stores options for customizing media upload. It is not used by developers directly.
  220. type MediaOptions struct {
  221. ContentType string
  222. ForceEmptyContentType bool
  223. ChunkSize int
  224. }
  225. // ProcessMediaOptions stores options from opts in a MediaOptions.
  226. // It is not used by developers directly.
  227. func ProcessMediaOptions(opts []MediaOption) *MediaOptions {
  228. mo := &MediaOptions{ChunkSize: DefaultUploadChunkSize}
  229. for _, o := range opts {
  230. o.setOptions(mo)
  231. }
  232. return mo
  233. }
  234. func ResolveRelative(basestr, relstr string) string {
  235. u, _ := url.Parse(basestr)
  236. afterColonPath := ""
  237. if i := strings.IndexRune(relstr, ':'); i > 0 {
  238. afterColonPath = relstr[i+1:]
  239. relstr = relstr[:i]
  240. }
  241. rel, _ := url.Parse(relstr)
  242. u = u.ResolveReference(rel)
  243. us := u.String()
  244. if afterColonPath != "" {
  245. us = fmt.Sprintf("%s:%s", us, afterColonPath)
  246. }
  247. us = strings.Replace(us, "%7B", "{", -1)
  248. us = strings.Replace(us, "%7D", "}", -1)
  249. us = strings.Replace(us, "%2A", "*", -1)
  250. return us
  251. }
  252. // Expand subsitutes any {encoded} strings in the URL passed in using
  253. // the map supplied.
  254. //
  255. // This calls SetOpaque to avoid encoding of the parameters in the URL path.
  256. func Expand(u *url.URL, expansions map[string]string) {
  257. escaped, unescaped, err := uritemplates.Expand(u.Path, expansions)
  258. if err == nil {
  259. u.Path = unescaped
  260. u.RawPath = escaped
  261. }
  262. }
  263. // CloseBody is used to close res.Body.
  264. // Prior to calling Close, it also tries to Read a small amount to see an EOF.
  265. // Not seeing an EOF can prevent HTTP Transports from reusing connections.
  266. func CloseBody(res *http.Response) {
  267. if res == nil || res.Body == nil {
  268. return
  269. }
  270. // Justification for 3 byte reads: two for up to "\r\n" after
  271. // a JSON/XML document, and then 1 to see EOF if we haven't yet.
  272. // TODO(bradfitz): detect Go 1.3+ and skip these reads.
  273. // See https://codereview.appspot.com/58240043
  274. // and https://codereview.appspot.com/49570044
  275. buf := make([]byte, 1)
  276. for i := 0; i < 3; i++ {
  277. _, err := res.Body.Read(buf)
  278. if err != nil {
  279. break
  280. }
  281. }
  282. res.Body.Close()
  283. }
  284. // VariantType returns the type name of the given variant.
  285. // If the map doesn't contain the named key or the value is not a []interface{}, "" is returned.
  286. // This is used to support "variant" APIs that can return one of a number of different types.
  287. func VariantType(t map[string]interface{}) string {
  288. s, _ := t["type"].(string)
  289. return s
  290. }
  291. // ConvertVariant uses the JSON encoder/decoder to fill in the struct 'dst' with the fields found in variant 'v'.
  292. // This is used to support "variant" APIs that can return one of a number of different types.
  293. // It reports whether the conversion was successful.
  294. func ConvertVariant(v map[string]interface{}, dst interface{}) bool {
  295. var buf bytes.Buffer
  296. err := json.NewEncoder(&buf).Encode(v)
  297. if err != nil {
  298. return false
  299. }
  300. return json.Unmarshal(buf.Bytes(), dst) == nil
  301. }
  302. // A Field names a field to be retrieved with a partial response.
  303. // See https://developers.google.com/gdata/docs/2.0/basics#PartialResponse
  304. //
  305. // Partial responses can dramatically reduce the amount of data that must be sent to your application.
  306. // In order to request partial responses, you can specify the full list of fields
  307. // that your application needs by adding the Fields option to your request.
  308. //
  309. // Field strings use camelCase with leading lower-case characters to identify fields within the response.
  310. //
  311. // For example, if your response has a "NextPageToken" and a slice of "Items" with "Id" fields,
  312. // you could request just those fields like this:
  313. //
  314. // svc.Events.List().Fields("nextPageToken", "items/id").Do()
  315. //
  316. // or if you were also interested in each Item's "Updated" field, you can combine them like this:
  317. //
  318. // svc.Events.List().Fields("nextPageToken", "items(id,updated)").Do()
  319. //
  320. // More information about field formatting can be found here:
  321. // https://developers.google.com/+/api/#fields-syntax
  322. //
  323. // Another way to find field names is through the Google API explorer:
  324. // https://developers.google.com/apis-explorer/#p/
  325. type Field string
  326. // CombineFields combines fields into a single string.
  327. func CombineFields(s []Field) string {
  328. r := make([]string, len(s))
  329. for i, v := range s {
  330. r[i] = string(v)
  331. }
  332. return strings.Join(r, ",")
  333. }
  334. // A CallOption is an optional argument to an API call.
  335. // It should be treated as an opaque value by users of Google APIs.
  336. //
  337. // A CallOption is something that configures an API call in a way that is
  338. // not specific to that API; for instance, controlling the quota user for
  339. // an API call is common across many APIs, and is thus a CallOption.
  340. type CallOption interface {
  341. Get() (key, value string)
  342. }
  343. // QuotaUser returns a CallOption that will set the quota user for a call.
  344. // The quota user can be used by server-side applications to control accounting.
  345. // It can be an arbitrary string up to 40 characters, and will override UserIP
  346. // if both are provided.
  347. func QuotaUser(u string) CallOption { return quotaUser(u) }
  348. type quotaUser string
  349. func (q quotaUser) Get() (string, string) { return "quotaUser", string(q) }
  350. // UserIP returns a CallOption that will set the "userIp" parameter of a call.
  351. // This should be the IP address of the originating request.
  352. func UserIP(ip string) CallOption { return userIP(ip) }
  353. type userIP string
  354. func (i userIP) Get() (string, string) { return "userIp", string(i) }
  355. // Trace returns a CallOption that enables diagnostic tracing for a call.
  356. // traceToken is an ID supplied by Google support.
  357. func Trace(traceToken string) CallOption { return traceTok(traceToken) }
  358. type traceTok string
  359. func (t traceTok) Get() (string, string) { return "trace", "token:" + string(t) }
  360. // TODO: Fields too