-
Notifications
You must be signed in to change notification settings - Fork 250
/
tcobject.go
271 lines (254 loc) · 9.23 KB
/
tcobject.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
// The following code is AUTO-GENERATED. Please DO NOT edit.
// To update this generated code, run the following command:
// in the /codegenerator/model subdirectory of this project,
// making sure that `${GOPATH}/bin` is in your `PATH`:
//
// go install && go generate
// This package was generated from the schema defined at
// /references/object/v1/api.json
// The object service provides HTTP-accessible storage for large blobs of data.
//
// Objects can be uploaded and downloaded, with the object data flowing directly
// from the storage "backend" to the caller, and not directly via this service.
// Once uploaded, objects are immutable until their expiration time.
//
// See:
//
// # How to use this package
//
// First create an Object object:
//
// object := tcobject.New(nil)
//
// and then call one or more of object's methods, e.g.:
//
// err := object.Ping(.....)
//
// handling any errors...
//
// if err != nil {
// // handle error...
// }
//
// # Taskcluster Schema
//
// The source code of this go package was auto-generated from the API definition at
// <rootUrl>/references/object/v1/api.json together with the input and output schemas it references,
package tcobject
import (
"net/url"
"time"
tcclient "github.com/taskcluster/taskcluster/v57/clients/client-go"
)
type Object tcclient.Client
// New returns an Object client, configured to run against production. Pass in
// nil credentials to create a client without authentication. The
// returned client is mutable, so returned settings can be altered.
//
// object := tcobject.New(
// nil, // client without authentication
// "http://localhost:1234/my/taskcluster", // taskcluster hosted at this root URL on local machine
// )
// err := object.Ping(.....) // for example, call the Ping(.....) API endpoint (described further down)...
// if err != nil {
// // handle errors...
// }
func New(credentials *tcclient.Credentials, rootURL string) *Object {
return &Object{
Credentials: credentials,
RootURL: rootURL,
ServiceName: "object",
APIVersion: "v1",
Authenticate: credentials != nil,
}
}
// NewFromEnv returns an *Object configured from environment variables.
//
// The root URL is taken from TASKCLUSTER_PROXY_URL if set to a non-empty
// string, otherwise from TASKCLUSTER_ROOT_URL if set, otherwise the empty
// string.
//
// The credentials are taken from environment variables:
//
// TASKCLUSTER_CLIENT_ID
// TASKCLUSTER_ACCESS_TOKEN
// TASKCLUSTER_CERTIFICATE
//
// If TASKCLUSTER_CLIENT_ID is empty/unset, authentication will be
// disabled.
func NewFromEnv() *Object {
c := tcclient.CredentialsFromEnvVars()
rootURL := tcclient.RootURLFromEnvVars()
return &Object{
Credentials: c,
RootURL: rootURL,
ServiceName: "object",
APIVersion: "v1",
Authenticate: c.ClientID != "",
}
}
// Respond without doing anything.
// This endpoint is used to check that the service is up.
//
// See #ping
func (object *Object) Ping() error {
cd := tcclient.Client(*object)
_, _, err := (&cd).APICall(nil, "GET", "/ping", nil, nil)
return err
}
// Respond without doing anything.
// This endpoint is used to check that the service is up.
//
// See #lbheartbeat
func (object *Object) Lbheartbeat() error {
cd := tcclient.Client(*object)
_, _, err := (&cd).APICall(nil, "GET", "/__lbheartbeat__", nil, nil)
return err
}
// Respond with the JSON version object.
// https://github.com/mozilla-services/Dockerflow/blob/main/docs/version_object.md
//
// See #version
func (object *Object) Version() error {
cd := tcclient.Client(*object)
_, _, err := (&cd).APICall(nil, "GET", "/__version__", nil, nil)
return err
}
// Create a new object by initiating upload of its data.
//
// This endpoint implements negotiation of upload methods. It can be called
// multiple times if necessary, either to propose new upload methods or to
// renew credentials for an already-agreed upload.
//
// The `name` parameter can contain any printable ASCII character (0x20 - 0x7e).
// The `uploadId` must be supplied by the caller, and any attempts to upload
// an object with the same name but a different `uploadId` will fail.
// Thus the first call to this method establishes the `uploadId` for the
// object, and as long as that value is kept secret, no other caller can
// upload an object of that name, regardless of scopes. Object expiration
// cannot be changed after the initial call, either. It is possible to call
// this method with no proposed upload methods, which has the effect of "locking
// in" the `expiration`, `projectId`, and `uploadId` properties and any
// supplied hashes.
//
// Unfinished uploads expire after 1 day.
//
// Required scopes:
//
// object:upload:<projectId>:<name>
//
// See #createUpload
func (object *Object) CreateUpload(name string, payload *CreateUploadRequest) (*CreateUploadResponse, error) {
cd := tcclient.Client(*object)
responseObject, _, err := (&cd).APICall(payload, "PUT", "/upload/"+url.QueryEscape(name), new(CreateUploadResponse), nil)
return responseObject.(*CreateUploadResponse), err
}
// This endpoint marks an upload as complete. This indicates that all data has been
// transmitted to the backend. After this call, no further calls to `uploadObject` are
// allowed, and downloads of the object may begin. This method is idempotent, but will
// fail if given an incorrect uploadId for an unfinished upload.
//
// It is possible to finish an upload with no hashes specified via either
// `startUpload` or `finishUpload`. However, many clients will refuse to
// download an object with no hashes. The utility methods included with the
// client libraries always include hashes as of version 44.0.0.
//
// Note that, once `finishUpload` is complete, the object is considered immutable.
//
// Required scopes:
//
// object:upload:<projectId>:<name>
//
// See #finishUpload
func (object *Object) FinishUpload(name string, payload *FinishUploadRequest) error {
cd := tcclient.Client(*object)
_, _, err := (&cd).APICall(payload, "POST", "/finish-upload/"+url.QueryEscape(name), nil, nil)
return err
}
// Start the process of downloading an object's data. Call this endpoint with a list of acceptable
// download methods, and the server will select a method and return the corresponding payload.
//
// Returns a 406 error if none of the given download methods are available.
//
// See [Download Methods](https://docs.taskcluster.net/docs/reference/platform/object/download-methods) for more detail.
//
// Required scopes:
//
// object:download:<name>
//
// See #startDownload
func (object *Object) StartDownload(name string, payload *DownloadObjectRequest) (*DownloadObjectResponse, error) {
cd := tcclient.Client(*object)
responseObject, _, err := (&cd).APICall(payload, "PUT", "/start-download/"+url.QueryEscape(name), new(DownloadObjectResponse), nil)
return responseObject.(*DownloadObjectResponse), err
}
// Get the metadata for the named object. This metadata is not sufficient to
// get the object's content; for that use `startDownload`.
//
// Required scopes:
//
// object:download:<name>
//
// See #object
func (object *Object) Object(name string) (*ObjectMetadata, error) {
cd := tcclient.Client(*object)
responseObject, _, err := (&cd).APICall(nil, "GET", "/metadata/"+url.QueryEscape(name), new(ObjectMetadata), nil)
return responseObject.(*ObjectMetadata), err
}
// Returns a signed URL for Object, valid for the specified duration.
//
// Required scopes:
//
// object:download:<name>
//
// See Object for more details.
func (object *Object) Object_SignedURL(name string, duration time.Duration) (*url.URL, error) {
cd := tcclient.Client(*object)
return (&cd).SignedURL("/metadata/"+url.QueryEscape(name), nil, duration)
}
// Get the data in an object directly. This method does not return a JSON body, but
// redirects to a location that will serve the object content directly.
//
// URLs for this endpoint, perhaps with attached authentication (`?bewit=..`),
// are typically used for downloads of objects by simple HTTP clients such as
// web browsers, curl, or wget.
//
// This method is limited by the common capabilities of HTTP, so it may not be
// the most efficient, resilient, or featureful way to retrieve an artifact.
// Situations where such functionality is required should ues the
// `startDownload` API endpoint.
//
// See [Simple Downloads](https://docs.taskcluster.net/docs/reference/platform/object/simple-downloads) for more detail.
//
// Required scopes:
//
// object:download:<name>
//
// See #download
func (object *Object) Download(name string) error {
cd := tcclient.Client(*object)
_, _, err := (&cd).APICall(nil, "GET", "/download/"+url.QueryEscape(name), nil, nil)
return err
}
// Returns a signed URL for Download, valid for the specified duration.
//
// Required scopes:
//
// object:download:<name>
//
// See Download for more details.
func (object *Object) Download_SignedURL(name string, duration time.Duration) (*url.URL, error) {
cd := tcclient.Client(*object)
return (&cd).SignedURL("/download/"+url.QueryEscape(name), nil, duration)
}
// Respond with a service heartbeat.
//
// This endpoint is used to check on backing services this service
// depends on.
//
// See #heartbeat
func (object *Object) Heartbeat() error {
cd := tcclient.Client(*object)
_, _, err := (&cd).APICall(nil, "GET", "/__heartbeat__", nil, nil)
return err
}