Struct: request.Request

import "../ibm-cos-sdk-go/aws/request"

Overview

nextPageTokens returns the tokens to use when asking for the next page of data.

Implemented Interfaces

s3crypto.Cipher, s3manager.ReadSeekerWriteTo, s3manager.WriterReadFrom

Structure Field Summary collapse

Method Summary collapse

Structure Field Details

AttemptTime time.Time

Body io.ReadSeeker

ClientInfo metadata.ClientInfo

Config aws.Config

Data interface{}

DisableFollowRedirects bool

Error error

ExpireTime time.Duration

A value greater than 0 instructs the request to be signed as Presigned URL You should not set this field directly. Instead use Request's Presign or PresignRequest methods.

HTTPRequest *http.Request

HTTPResponse *http.Response

Handlers Handlers

LastSignedAt time.Time

NotHoist bool

Operation *Operation

Params interface{}

RequestID string

RetryCount int

RetryDelay time.Duration

RetryErrorCodes []string

Additional API error codes that should be retried. IsErrorRetryable will consider these codes in addition to its built in cases.

Retryable *bool

SignedHeaderVals http.Header

ThrottleErrorCodes []string

Additional API error codes that should be retried with throttle backoff delay. IsErrorThrottle will consider these codes in addition to its built in cases.

Time time.Time

Method Details

func (r *Request) ApplyOptions(opts ...Option)

ApplyOptions will apply each option to the request calling them in the order the were provided.



223
224
225
226
227
 
// File 'aws/request/request.go', line 223


func (r *Request) ApplyOptions(opts ...Option) {
	for _, opt := range opts {
		opt(r)
	}
}

func (r *Request) Build() error

Build will build the request's object so it can be signed and sent to the service. Build will also validate all the request's parameters. Any additional build Handlers set on this request will be run in the order they were set.

The request will only be built once. Multiple calls to build will have no effect.

If any Validate or Build errors occur the build will stop and the error which occurred will be returned.



413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
 
// File 'aws/request/request.go', line 413


func (r *Request) Build() error {
	if !r.built {
		r.Handlers.Validate.Run(r)
		if r.Error != nil {
			debugLogReqError(r, "Validate Request", notRetrying, r.Error)
			return r.Error
		}
		r.Handlers.Build.Run(r)
		if r.Error != nil {
			debugLogReqError(r, "Build Request", notRetrying, r.Error)
			return r.Error
		}
		r.built = true
	}

	return r.Error
}

func (r *Request) Context() aws.Context

Context will always returns a non-nil context. If Request does not have a context aws.BackgroundContext will be returned.



231
232
233
234
235
236
 
// File 'aws/request/request.go', line 231


func (r *Request) Context() aws.Context {
	if r.context != nil {
		return r.context
	}
	return aws.BackgroundContext()
}

func (r *Request) DataFilled() bool

DataFilled returns true if the request's data for response deserialization target has been set and is a valid. False is returned if data is not set, or is invalid.



283
284
285
 
// File 'aws/request/request.go', line 283


func (r *Request) DataFilled() bool {
	return r.Data != nil && reflect.ValueOf(r.Data).Elem().IsValid()
}

func (r *Request) EachPage(fn func(data interface{}, isLastPage bool) (shouldContinue bool)) error

EachPage iterates over each page of a paginated request object. The fn parameter should be a function with the following sample signature:

func(page *T, lastPage bool) bool {
    return true // return false to stop iterating
}

Where “T” is the structure type matching the output structure of the given operation. For example, a request object generated by DynamoDB.ListTablesRequest() would expect to see dynamodb.ListTablesOutput as the structure “T”. The lastPage value represents whether the page is the last page of data or not. The return value of this function should return true to keep iterating or false to stop.

Deprecated Use Pagination type for configurable pagination of API operations



251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
// File 'aws/request/request_pagination.go', line 251


func (r *Request) EachPage(fn func(data interface{}, isLastPage bool) (shouldContinue bool)) error {
	logDeprecatedf(r.Config.Logger, &logDeprecatedEachPage,
		"Request.EachPage deprecated. Use Pagination type for configurable pagination of API operations")

	for page := r; page != nil; page = page.NextPage() {
		if err := page.Send(); err != nil {
			return err
		}
		if getNextPage := fn(page.Data, !page.HasNextPage()); !getNextPage {
			return page.Error
		}
	}

	return nil
}

func (r *Request) GetBody() io.ReadSeeker

GetBody will return an io.ReadSeeker of the Request's underlying input body with a concurrency safe wrapper.



509
510
511
 
// File 'aws/request/request.go', line 509


func (r *Request) GetBody() io.ReadSeeker {
	return r.safeBody
}

func (r *Request) HasNextPage() bool

HasNextPage returns true if this request has more pages of data available.

Deprecated Use Pagination type for configurable pagination of API operations



208
209
210
211
212
213
 
// File 'aws/request/request_pagination.go', line 208


func (r *Request) HasNextPage() bool {
	logDeprecatedf(r.Config.Logger, &logDeprecatedHasNextPage,
		"Request.HasNextPage deprecated. Use Pagination type for configurable pagination of API operations")

	return len(r.nextPageTokens()) > 0
}

func (r *Request) IsErrorExpired() bool

IsErrorExpired returns whether the error code is a credential expiry error. Returns false if the request has no Error set.

Alias for the utility function IsErrorExpiredCreds



306
307
308
 
// File 'aws/request/retryer.go', line 306


func (r *Request) IsErrorExpired() bool {
	return IsErrorExpiredCreds(r.Error)
}

func (r *Request) IsErrorRetryable() bool 



249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
// File 'aws/request/retryer.go', line 249


func (r *Request) IsErrorRetryable() bool {
	if isErrCode(r.Error, r.RetryErrorCodes) {
		return true
	}

	// HTTP response status code 501 should not be retried.
	// 501 represents Not Implemented which means the request method is not
	// supported by the server and cannot be handled.
	if r.HTTPResponse != nil {
		// HTTP response status code 500 represents internal server error and
		// should be retried without any throttle.
		if r.HTTPResponse.StatusCode == 500 {
			return true
		}
	}
	return IsErrorRetryable(r.Error)
}

func (r *Request) IsErrorThrottle() bool

IsErrorThrottle returns whether the error is to be throttled based on its code. Returns false if the request has no Error set.

Alias for the utility function IsErrorThrottle



271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
 
// File 'aws/request/retryer.go', line 271


func (r *Request) IsErrorThrottle() bool {
	if isErrCode(r.Error, r.ThrottleErrorCodes) {
		return true
	}

	if r.HTTPResponse != nil {
		switch r.HTTPResponse.StatusCode {
		case
			429, // error caused due to too many requests
			502, // Bad Gateway error should be throttled
			503, // caused when service is unavailable
			504: // error occurred due to gateway timeout
			return true
		}
	}

	return IsErrorThrottle(r.Error)
}

func (r *Request) IsPresigned() bool

IsPresigned returns true if the request represents a presigned API url.



362
363
364
 
// File 'aws/request/request.go', line 362


func (r *Request) IsPresigned() bool {
	return r.ExpireTime != 0
}

func (r *Request) NextPage() *Request

NextPage returns a new Request that can be executed to return the next page of result data. Call .Send() on this request to execute it.

Deprecated Use Pagination type for configurable pagination of API operations



219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
 
// File 'aws/request/request_pagination.go', line 219


func (r *Request) NextPage() *Request {
	logDeprecatedf(r.Config.Logger, &logDeprecatedNextPage,
		"Request.NextPage deprecated. Use Pagination type for configurable pagination of API operations")

	tokens := r.nextPageTokens()
	if len(tokens) == 0 {
		return nil
	}

	data := reflect.New(reflect.TypeOf(r.Data).Elem()).Interface()
	nr := New(r.Config, r.ClientInfo, r.Handlers, r.Retryer, r.Operation, awsutil.CopyOf(r.Params), data)
	for i, intok := range nr.Operation.InputTokens {
		awsutil.SetValueAtPath(nr.Params, intok, tokens[i])
	}
	return nr
}

func (r *Request) ParamsFilled() bool

ParamsFilled returns if the request's parameters have been populated and the parameters are valid. False is returned if no parameters are provided or invalid.



276
277
278
 
// File 'aws/request/request.go', line 276


func (r *Request) ParamsFilled() bool {
	return r.Params != nil && reflect.ValueOf(r.Params).Elem().IsValid()
}

func (r *Request) Presign(expire time.Duration) (string, error)

Presign returns the request's signed URL. Error will be returned if the signing fails. The expire parameter is only used for presigned Amazon S3 API requests. All other AWS services will use a fixed expiration time of 15 minutes.

It is invalid to create a presigned URL with a expire duration 0 or less. An error is returned if expire duration is 0 or less.



330
331
332
333
334
335
336
337
338
339
340
 
// File 'aws/request/request.go', line 330


func (r *Request) Presign(expire time.Duration) (string, error) {
	r = r.copy()

	// Presign requires all headers be hoisted. There is no way to retrieve
	// the signed headers not hoisted without this. Making the presigned URL
	// useless.
	r.NotHoist = false

	u, _, err := getPresignedURL(r, expire)
	return u, err
}

func (r *Request) PresignRequest(expire time.Duration) (string, http.Header, error)

PresignRequest behaves just like presign, with the addition of returning a set of headers that were signed. The expire parameter is only used for presigned Amazon S3 API requests. All other AWS services will use a fixed expiration time of 15 minutes.

It is invalid to create a presigned URL with a expire duration 0 or less. An error is returned if expire duration is 0 or less.

Returns the URL string for the API operation with signature in the query string, and the HTTP headers that were included in the signature. These headers must be included in any HTTP request made with the presigned URL.

To prevent hoisting any headers to the query string set NotHoist to true on this Request value prior to calling PresignRequest.



356
357
358
359
 
// File 'aws/request/request.go', line 356


func (r *Request) PresignRequest(expire time.Duration) (string, http.Header, error) {
	r = r.copy()
	return getPresignedURL(r, expire)
}

func (r *Request) ResetBody() 



26
27
28
29
30
31
32
33
34
35
36
 
// File 'aws/request/request_1_8.go', line 26


func (r *Request) ResetBody() {
	body, err := r.getNextRequestBody()
	if err != nil {
		r.Error = awserr.New(ErrCodeSerialization,
			"failed to reset request body", err)
		return
	}

	r.HTTPRequest.Body = body
	r.HTTPRequest.GetBody = r.getNextRequestBody
}

func (r *Request) Send() error

Send will send the request, returning error if errors are encountered.

Send will sign the request prior to sending. All Send Handlers will be executed in the order they were set.

Canceling a request is non-deterministic. If a request has been canceled, then the transport will choose, randomly, one of the state channels during reads or getting the connection.

readLoop() and getConn(req *Request, cm connectMethod) github.com/golang/go/blob/master/src/net/http/transport.go

Send will not close the request.Request's body.



526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
 
// File 'aws/request/request.go', line 526


func (r *Request) Send() error {
	defer func() {
		// Ensure a non-nil HTTPResponse parameter is set to ensure handlers
		// checking for HTTPResponse values, don't fail.
		if r.HTTPResponse == nil {
			r.HTTPResponse = &http.Response{
				Header: http.Header{},
				Body:   ioutil.NopCloser(&bytes.Buffer{}),
			}
		}
		// Regardless of success or failure of the request trigger the Complete
		// request handlers.
		r.Handlers.Complete.Run(r)
	}()

	if err := r.Error; err != nil {
		return err
	}

	for {
		r.Error = nil
		r.AttemptTime = time.Now()

		if err := r.Sign(); err != nil {
			debugLogReqError(r, "Sign Request", notRetrying, err)
			return err
		}

		if err := r.sendRequest(); err == nil {
			return nil
		}
		r.Handlers.Retry.Run(r)
		r.Handlers.AfterRetry.Run(r)

		if r.Error != nil || !aws.BoolValue(r.Retryable) {
			return r.Error
		}

		if err := r.prepareRetry(); err != nil {
			r.Error = err
			return err
		}
	}
}

func (r *Request) SetBufferBody(buf []byte)

SetBufferBody will set the request's body bytes that will be sent to the service API.



289
290
291
 
// File 'aws/request/request.go', line 289


func (r *Request) SetBufferBody(buf []byte) {
	r.SetReaderBody(bytes.NewReader(buf))
}

func (r *Request) SetContext(ctx aws.Context)

SetContext adds a Context to the current request that can be used to cancel a in-flight request. The Context value must not be nil, or this method will panic.

Unlike http.Request.WithContext, SetContext does not return a copy of the Request. It is not safe to use use a single Request value for multiple requests. A new Request should be created for each API operation request.

Go 1.6 and below: The http.Request's Cancel field will be set to the Done() value of the context. This will overwrite the Cancel field's value.

Go 1.7 and above: The http.Request.WithContext will be used to set the context on the underlying http.Request. This will create a shallow copy of the http.Request. The SDK may create sub contexts in the future for nested requests such as retries.



254
255
256
257
258
259
 
// File 'aws/request/request.go', line 254


func (r *Request) SetContext(ctx aws.Context) {
	if ctx == nil {
		panic("context cannot be nil")
	}
	setRequestContext(r, ctx)
}

func (r *Request) SetReaderBody(reader io.ReadSeeker)

SetReaderBody will set the request's body reader.



299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
 
// File 'aws/request/request.go', line 299


func (r *Request) SetReaderBody(reader io.ReadSeeker) {
	r.Body = reader

	if aws.IsReaderSeekable(reader) {
		var err error
		// Get the Bodies current offset so retries will start from the same
		// initial position.
		r.BodyStart, err = reader.Seek(0, sdkio.SeekCurrent)
		if err != nil {
			r.Error = awserr.New(ErrCodeSerialization,
				"failed to determine start of request body", err)
			return
		}
	}
	r.ResetBody()
}

func (r *Request) SetStreamingBody(reader io.ReadCloser)

SetStreamingBody set the reader to be used for the request that will stream bytes to the server. Request's Body must not be set to any reader.



318
319
320
321
 
// File 'aws/request/request.go', line 318


func (r *Request) SetStreamingBody(reader io.ReadCloser) {
	r.streamingBody = reader
	r.SetReaderBody(aws.ReadSeekCloser(reader))
}

func (r *Request) SetStringBody(s string)

SetStringBody sets the body of the request to be backed by a string.



294
295
296
 
// File 'aws/request/request.go', line 294


func (r *Request) SetStringBody(s string) {
	r.SetReaderBody(strings.NewReader(s))
}

func (r *Request) Sign() error

Sign will sign the request, returning error if errors are encountered.

Sign will build the request prior to signing. All Sign Handlers will be executed in the order they were set.



435
436
437
438
439
440
441
442
443
444
445
446
 
// File 'aws/request/request.go', line 435


func (r *Request) Sign() error {
	r.Build()
	if r.Error != nil {
		debugLogReqError(r, "Build Request", notRetrying, r.Error)
		return r.Error
	}

	SanitizeHostForHeader(r.HTTPRequest)

	r.Handlers.Sign.Run(r)
	return r.Error
}

func (r *Request) WillRetry() bool

WillRetry returns if the request's can be retried.



262
263
264
265
266
267
 
// File 'aws/request/request.go', line 262


func (r *Request) WillRetry() bool {
	if !aws.IsReaderSeekable(r.Body) && r.HTTPRequest.Body != NoBody {
		return false
	}
	return r.Error != nil && aws.BoolValue(r.Retryable) && r.RetryCount < r.MaxRetries()
}