go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/gae/service/taskqueue/task.go (about)

     1  // Copyright 2015 The LUCI Authors.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //      http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package taskqueue
    16  
    17  import (
    18  	"net/http"
    19  	"net/url"
    20  	"time"
    21  )
    22  
    23  // RetryOptions let you control whether to retry a task and the backoff intervals between tries.
    24  type RetryOptions struct {
    25  	// Number of tries/leases after which the task fails permanently and is deleted.
    26  	// If AgeLimit is also set, both limits must be exceeded for the task to fail permanently.
    27  	RetryLimit int32
    28  
    29  	// Maximum time allowed since the task's first try before the task fails permanently and is deleted (only for push tasks).
    30  	// If RetryLimit is also set, both limits must be exceeded for the task to fail permanently.
    31  	AgeLimit time.Duration
    32  
    33  	// Minimum time between successive tries (only for push tasks).
    34  	MinBackoff time.Duration
    35  
    36  	// Maximum time between successive tries (only for push tasks).
    37  	MaxBackoff time.Duration
    38  
    39  	// Maximum number of times to double the interval between successive tries before the intervals increase linearly (only for push tasks).
    40  	MaxDoublings int32
    41  
    42  	// If MaxDoublings is zero, set ApplyZeroMaxDoublings to true to override the default non-zero value.
    43  	// Otherwise a zero MaxDoublings is ignored and the default is used.
    44  	ApplyZeroMaxDoublings bool
    45  }
    46  
    47  // Task represents a taskqueue task to be executed.
    48  type Task struct {
    49  	// Path is the worker URL for the task.
    50  	// If unset, it will default to /_ah/queue/<queue_name>.
    51  	Path string
    52  
    53  	// Payload is the data for the task.
    54  	// This will be delivered as the HTTP request body.
    55  	// It is only used when Method is POST, PUT or PULL.
    56  	// url.Values' Encode method may be used to generate this for POST requests.
    57  	Payload []byte
    58  
    59  	// Additional HTTP headers to pass at the task's execution time.
    60  	// To schedule the task to be run with an alternate app version
    61  	// or backend, set the "Host" header.
    62  	Header http.Header
    63  
    64  	// Method is the HTTP method for the task ("GET", "POST", etc.),
    65  	// or "PULL" if this is task is destined for a pull-based queue.
    66  	// If empty, this defaults to "POST".
    67  	Method string
    68  
    69  	// A name for the task.
    70  	// If empty, a name will be chosen.
    71  	Name string
    72  
    73  	// Delay specifies the duration the task queue service must wait
    74  	// before executing the task.
    75  	// Either Delay or ETA may be set, but not both.
    76  	Delay time.Duration
    77  
    78  	// ETA specifies the earliest time a task may be executed (push queues)
    79  	// or leased (pull queues).
    80  	// Either Delay or ETA may be set, but not both.
    81  	ETA time.Time
    82  
    83  	// The number of times the task has been dispatched or leased.
    84  	RetryCount int32
    85  
    86  	// Tag for the task. Only used when Method is PULL.
    87  	Tag string
    88  
    89  	// Retry options for this task. May be nil.
    90  	RetryOptions *RetryOptions
    91  }
    92  
    93  // NewPOSTTask creates a Task that will POST to a path with URL-encoded values.
    94  func NewPOSTTask(path string, params url.Values) *Task {
    95  	h := make(http.Header)
    96  	h.Set("Content-Type", "application/x-www-form-urlencoded")
    97  	return &Task{
    98  		Path:    path,
    99  		Payload: []byte(params.Encode()),
   100  		Header:  h,
   101  		Method:  "POST",
   102  	}
   103  }
   104  
   105  // Duplicate returns a deep copy of this Task.
   106  func (t *Task) Duplicate() *Task {
   107  	ret := *t
   108  
   109  	if len(t.Header) > 0 {
   110  		ret.Header = make(http.Header, len(t.Header))
   111  		for k, vs := range t.Header {
   112  			newVs := make([]string, len(vs))
   113  			copy(newVs, vs)
   114  			ret.Header[k] = newVs
   115  		}
   116  	}
   117  
   118  	if len(t.Payload) > 0 {
   119  		ret.Payload = make([]byte, len(t.Payload))
   120  		copy(ret.Payload, t.Payload)
   121  	}
   122  
   123  	if t.RetryOptions != nil {
   124  		ret.RetryOptions = &RetryOptions{}
   125  		*ret.RetryOptions = *t.RetryOptions
   126  	}
   127  
   128  	return &ret
   129  }