blob: 7851d75dbb0107ebdb0e1126d58079db85070d0c [file] [log] [blame]
Jamie Hannaford4baa1232014-09-23 15:23:04 +02001package gophercloud
Jamie Hannafordb3120f52014-09-23 15:17:57 +02002
Ash Wilsone8192ac2014-10-21 09:02:01 -04003import (
4 "encoding/json"
5 "net/http"
6)
Ash Wilsoneab6a702014-10-20 08:18:30 -04007
Ash Wilson3ce1bd82014-10-31 12:20:00 -04008/*
9Result is an internal type to be used by individual resource packages.
10
11It acts as a base struct that other Result types, returned from request
12functions, can embed for convenience. All Results capture basic information
13from the HTTP transaction that was performed, including the response body,
14HTTP headers, and any errors that happened.
15
16Generally, each Result type will have an Extract method that can be used to
17further interpret the result's payload in a specific context. Extensions or
18providers can then provide additional extraction functions to pull out
19provider- or extension-specific information as well.
20*/
Ash Wilsoneab6a702014-10-20 08:18:30 -040021type Result struct {
Ash Wilson3ce1bd82014-10-31 12:20:00 -040022 // Body is the payload of the HTTP response from the server. In most cases,
23 // this will be the deserialized JSON structure.
Ash Wilsond3dc2542014-10-20 10:10:48 -040024 Body interface{}
Ash Wilsoneab6a702014-10-20 08:18:30 -040025
Ash Wilson72e4d2c2014-10-20 10:27:30 -040026 // Header contains the HTTP header structure from the original response.
27 Header http.Header
Ash Wilsoneab6a702014-10-20 08:18:30 -040028
Ash Wilson3ce1bd82014-10-31 12:20:00 -040029 // Err is an error that occurred during the operation. It's deferred until
30 // extraction to make it easier to chain the Extract call.
Ash Wilsoneab6a702014-10-20 08:18:30 -040031 Err error
Jamie Hannafordb3120f52014-09-23 15:17:57 +020032}
Ash Wilsona6b08312014-10-02 15:27:45 -040033
Ash Wilson3ce1bd82014-10-31 12:20:00 -040034// PrettyPrintJSON creates a string containing the full response body as
35// pretty-printed JSON. It's useful for capturing test fixtures and for
36// debugging extraction bugs.
Ash Wilsone8192ac2014-10-21 09:02:01 -040037func (r Result) PrettyPrintJSON() string {
38 pretty, err := json.MarshalIndent(r.Body, "", " ")
39 if err != nil {
40 panic(err.Error())
41 }
42 return string(pretty)
43}
44
Jon Perrittba2395e2014-10-27 15:23:21 -050045// ErrResult represents results that only contain a potential error and
Ash Wilson3ce1bd82014-10-31 12:20:00 -040046// nothing else. Usually, if the operation executed successfully, the Err field
47// will be nil; otherwise it will be stocked with a relevant error. Use the
48// ExtractErr method to cleanly pull it out.
Jon Perrittba2395e2014-10-27 15:23:21 -050049type ErrResult struct {
Jon Perritt0c2b0372014-10-27 15:57:29 -050050 Result
Jamie Hannaford021b35c2014-10-27 14:01:53 +010051}
52
Ash Wilson3ce1bd82014-10-31 12:20:00 -040053// ExtractErr is a function that extracts error information, or nil, from a result.
Jon Perrittba2395e2014-10-27 15:23:21 -050054func (r ErrResult) ExtractErr() error {
Jamie Hannaford021b35c2014-10-27 14:01:53 +010055 return r.Err
56}
57
Ash Wilson3ce1bd82014-10-31 12:20:00 -040058/*
59HeaderResult is an internal type to be used by individual resource packages.
60
61It represents a result that only contains an error (possibly nil) and an
62http.Header. This is used, for example, by the objectstorage packages in
63openstack, because most of the operations don't return response bodies, but do
64have relevant information in headers.
65*/
Jon Perrittd50f93e2014-10-27 14:19:27 -050066type HeaderResult struct {
Jon Perritt0c2b0372014-10-27 15:57:29 -050067 Result
Jon Perrittd50f93e2014-10-27 14:19:27 -050068}
69
70// ExtractHeader will return the http.Header and error from the HeaderResult.
Ash Wilson3ce1bd82014-10-31 12:20:00 -040071//
72// header, err := objects.Create(client, "my_container", objects.CreateOpts{}).ExtractHeader()
Jon Perrittd50f93e2014-10-27 14:19:27 -050073func (hr HeaderResult) ExtractHeader() (http.Header, error) {
74 return hr.Header, hr.Err
75}
76
Ash Wilson3ce1bd82014-10-31 12:20:00 -040077// RFC3339Milli describes a common time format used by some API responses.
Ash Wilsona6b08312014-10-02 15:27:45 -040078const RFC3339Milli = "2006-01-02T15:04:05.999999Z"
Jamie Hannaford369c9c62014-10-08 15:14:43 +020079
Ash Wilson3ce1bd82014-10-31 12:20:00 -040080/*
81Link is an internal type to be used in packages of collection resources that are
82paginated in a certain way.
83
84It's a response substructure common to many paginated collection results that is
85used to point to related pages. Usually, the one we care about is the one with
86Rel field set to "next".
87*/
Jamie Hannaford369c9c62014-10-08 15:14:43 +020088type Link struct {
89 Href string `mapstructure:"href"`
90 Rel string `mapstructure:"rel"`
91}
92
Ash Wilson3ce1bd82014-10-31 12:20:00 -040093/*
94ExtractNextURL is an internal function useful for packages of collection
95resources that are paginated in a certain way.
96
97It attempts attempts to extract the "next" URL from slice of Link structs, or
98"" if no such URL is present.
99*/
Jamie Hannaford369c9c62014-10-08 15:14:43 +0200100func ExtractNextURL(links []Link) (string, error) {
101 var url string
102
103 for _, l := range links {
104 if l.Rel == "next" {
105 url = l.Href
106 }
107 }
108
109 if url == "" {
110 return "", nil
111 }
112
113 return url, nil
114}