1// Copyright 2020 Google LLC 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 15syntax = "proto3"; 16 17package google.cloud.tasks.v2beta2; 18 19import "google/api/field_behavior.proto"; 20import "google/api/resource.proto"; 21import "google/cloud/tasks/v2beta2/target.proto"; 22import "google/protobuf/duration.proto"; 23import "google/protobuf/timestamp.proto"; 24 25option go_package = "cloud.google.com/go/cloudtasks/apiv2beta2/cloudtaskspb;cloudtaskspb"; 26option java_multiple_files = true; 27option java_outer_classname = "QueueProto"; 28option java_package = "com.google.cloud.tasks.v2beta2"; 29 30// A queue is a container of related tasks. Queues are configured to manage 31// how those tasks are dispatched. Configurable properties include rate limits, 32// retry options, target types, and others. 33message Queue { 34 option (google.api.resource) = { 35 type: "cloudtasks.googleapis.com/Queue" 36 pattern: "projects/{project}/locations/{location}/queues/{queue}" 37 }; 38 39 // State of the queue. 40 enum State { 41 // Unspecified state. 42 STATE_UNSPECIFIED = 0; 43 44 // The queue is running. Tasks can be dispatched. 45 // 46 // If the queue was created using Cloud Tasks and the queue has 47 // had no activity (method calls or task dispatches) for 30 days, 48 // the queue may take a few minutes to re-activate. Some method 49 // calls may return [NOT_FOUND][google.rpc.Code.NOT_FOUND] and 50 // tasks may not be dispatched for a few minutes until the queue 51 // has been re-activated. 52 RUNNING = 1; 53 54 // Tasks are paused by the user. If the queue is paused then Cloud 55 // Tasks will stop delivering tasks from it, but more tasks can 56 // still be added to it by the user. When a pull queue is paused, 57 // all [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] calls 58 // will return a [FAILED_PRECONDITION][google.rpc.Code.FAILED_PRECONDITION]. 59 PAUSED = 2; 60 61 // The queue is disabled. 62 // 63 // A queue becomes `DISABLED` when 64 // [queue.yaml](https://cloud.google.com/appengine/docs/python/config/queueref) 65 // or 66 // [queue.xml](https://cloud.google.com/appengine/docs/standard/java/config/queueref) 67 // is uploaded which does not contain the queue. You cannot directly disable 68 // a queue. 69 // 70 // When a queue is disabled, tasks can still be added to a queue 71 // but the tasks are not dispatched and 72 // [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] calls 73 // return a `FAILED_PRECONDITION` error. 74 // 75 // To permanently delete this queue and all of its tasks, call 76 // [DeleteQueue][google.cloud.tasks.v2beta2.CloudTasks.DeleteQueue]. 77 DISABLED = 3; 78 } 79 80 // Caller-specified and required in 81 // [CreateQueue][google.cloud.tasks.v2beta2.CloudTasks.CreateQueue], after 82 // which it becomes output only. 83 // 84 // The queue name. 85 // 86 // The queue name must have the following format: 87 // `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID` 88 // 89 // * `PROJECT_ID` can contain letters ([A-Za-z]), numbers ([0-9]), 90 // hyphens (-), colons (:), or periods (.). 91 // For more information, see 92 // [Identifying 93 // projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects) 94 // * `LOCATION_ID` is the canonical ID for the queue's location. 95 // The list of available locations can be obtained by calling 96 // [ListLocations][google.cloud.location.Locations.ListLocations]. 97 // For more information, see https://cloud.google.com/about/locations/. 98 // * `QUEUE_ID` can contain letters ([A-Za-z]), numbers ([0-9]), or 99 // hyphens (-). The maximum length is 100 characters. 100 string name = 1; 101 102 // Caller-specified and required in 103 // [CreateQueue][google.cloud.tasks.v2beta2.CloudTasks.CreateQueue][], after 104 // which the queue config type becomes output only, though fields within the 105 // config are mutable. 106 // 107 // The queue's target. 108 // 109 // The target applies to all tasks in the queue. 110 oneof target_type { 111 // App Engine HTTP target. 112 // 113 // An App Engine queue is a queue that has an 114 // [AppEngineHttpTarget][google.cloud.tasks.v2beta2.AppEngineHttpTarget]. 115 AppEngineHttpTarget app_engine_http_target = 3; 116 117 // Pull target. 118 // 119 // A pull queue is a queue that has a 120 // [PullTarget][google.cloud.tasks.v2beta2.PullTarget]. 121 PullTarget pull_target = 4; 122 } 123 124 // Rate limits for task dispatches. 125 // 126 // [rate_limits][google.cloud.tasks.v2beta2.Queue.rate_limits] and 127 // [retry_config][google.cloud.tasks.v2beta2.Queue.retry_config] are related 128 // because they both control task attempts however they control how tasks are 129 // attempted in different ways: 130 // 131 // * [rate_limits][google.cloud.tasks.v2beta2.Queue.rate_limits] controls the 132 // total rate of 133 // dispatches from a queue (i.e. all traffic dispatched from the 134 // queue, regardless of whether the dispatch is from a first 135 // attempt or a retry). 136 // * [retry_config][google.cloud.tasks.v2beta2.Queue.retry_config] controls 137 // what happens to 138 // particular a task after its first attempt fails. That is, 139 // [retry_config][google.cloud.tasks.v2beta2.Queue.retry_config] controls 140 // task retries (the second attempt, third attempt, etc). 141 RateLimits rate_limits = 5; 142 143 // Settings that determine the retry behavior. 144 // 145 // * For tasks created using Cloud Tasks: the queue-level retry settings 146 // apply to all tasks in the queue that were created using Cloud Tasks. 147 // Retry settings cannot be set on individual tasks. 148 // * For tasks created using the App Engine SDK: the queue-level retry 149 // settings apply to all tasks in the queue which do not have retry settings 150 // explicitly set on the task and were created by the App Engine SDK. See 151 // [App Engine 152 // documentation](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/retrying-tasks). 153 RetryConfig retry_config = 6; 154 155 // Output only. The state of the queue. 156 // 157 // `state` can only be changed by calling 158 // [PauseQueue][google.cloud.tasks.v2beta2.CloudTasks.PauseQueue], 159 // [ResumeQueue][google.cloud.tasks.v2beta2.CloudTasks.ResumeQueue], or 160 // uploading 161 // [queue.yaml/xml](https://cloud.google.com/appengine/docs/python/config/queueref). 162 // [UpdateQueue][google.cloud.tasks.v2beta2.CloudTasks.UpdateQueue] cannot be 163 // used to change `state`. 164 State state = 7; 165 166 // Output only. The last time this queue was purged. 167 // 168 // All tasks that were [created][google.cloud.tasks.v2beta2.Task.create_time] 169 // before this time were purged. 170 // 171 // A queue can be purged using 172 // [PurgeQueue][google.cloud.tasks.v2beta2.CloudTasks.PurgeQueue], the [App 173 // Engine Task Queue SDK, or the Cloud 174 // Console](https://cloud.google.com/appengine/docs/standard/python/taskqueue/push/deleting-tasks-and-queues#purging_all_tasks_from_a_queue). 175 // 176 // Purge time will be truncated to the nearest microsecond. Purge 177 // time will be unset if the queue has never been purged. 178 google.protobuf.Timestamp purge_time = 8; 179 180 // The maximum amount of time that a task will be retained in 181 // this queue. 182 // 183 // Queues created by Cloud Tasks have a default `task_ttl` of 31 days. 184 // After a task has lived for `task_ttl`, the task will be deleted 185 // regardless of whether it was dispatched or not. 186 // 187 // The `task_ttl` for queues created via queue.yaml/xml is equal to the 188 // maximum duration because there is a 189 // [storage quota](https://cloud.google.com/appengine/quotas#Task_Queue) for 190 // these queues. To view the maximum valid duration, see the documentation for 191 // [Duration][google.protobuf.Duration]. 192 google.protobuf.Duration task_ttl = 9; 193 194 // The task tombstone time to live (TTL). 195 // 196 // After a task is deleted or completed, the task's tombstone is 197 // retained for the length of time specified by `tombstone_ttl`. 198 // The tombstone is used by task de-duplication; another task with the same 199 // name can't be created until the tombstone has expired. For more information 200 // about task de-duplication, see the documentation for 201 // [CreateTaskRequest][google.cloud.tasks.v2beta2.CreateTaskRequest.task]. 202 // 203 // Queues created by Cloud Tasks have a default `tombstone_ttl` of 1 hour. 204 google.protobuf.Duration tombstone_ttl = 10; 205 206 // Output only. The realtime, informational statistics for a queue. In order 207 // to receive the statistics the caller should include this field in the 208 // FieldMask. 209 QueueStats stats = 16 [(google.api.field_behavior) = OUTPUT_ONLY]; 210} 211 212// Rate limits. 213// 214// This message determines the maximum rate that tasks can be dispatched by a 215// queue, regardless of whether the dispatch is a first task attempt or a retry. 216// 217// Note: The debugging command, 218// [RunTask][google.cloud.tasks.v2beta2.CloudTasks.RunTask], will run a task 219// even if the queue has reached its 220// [RateLimits][google.cloud.tasks.v2beta2.RateLimits]. 221message RateLimits { 222 // The maximum rate at which tasks are dispatched from this queue. 223 // 224 // If unspecified when the queue is created, Cloud Tasks will pick the 225 // default. 226 // 227 // * For [App Engine queues][google.cloud.tasks.v2beta2.AppEngineHttpTarget], 228 // the maximum allowed value 229 // is 500. 230 // * This field is output only for [pull 231 // queues][google.cloud.tasks.v2beta2.PullTarget]. In addition to the 232 // `max_tasks_dispatched_per_second` limit, a maximum of 10 QPS of 233 // [LeaseTasks][google.cloud.tasks.v2beta2.CloudTasks.LeaseTasks] requests 234 // are allowed per pull queue. 235 // 236 // 237 // This field has the same meaning as 238 // [rate in 239 // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#rate). 240 double max_tasks_dispatched_per_second = 1; 241 242 // The max burst size. 243 // 244 // Max burst size limits how fast tasks in queue are processed when 245 // many tasks are in the queue and the rate is high. This field 246 // allows the queue to have a high rate so processing starts shortly 247 // after a task is enqueued, but still limits resource usage when 248 // many tasks are enqueued in a short period of time. 249 // 250 // The [token bucket](https://wikipedia.org/wiki/Token_Bucket) 251 // algorithm is used to control the rate of task dispatches. Each 252 // queue has a token bucket that holds tokens, up to the maximum 253 // specified by `max_burst_size`. Each time a task is dispatched, a 254 // token is removed from the bucket. Tasks will be dispatched until 255 // the queue's bucket runs out of tokens. The bucket will be 256 // continuously refilled with new tokens based on 257 // [max_dispatches_per_second][RateLimits.max_dispatches_per_second]. 258 // 259 // The default value of `max_burst_size` is picked by Cloud Tasks 260 // based on the value of 261 // [max_dispatches_per_second][RateLimits.max_dispatches_per_second]. 262 // 263 // The maximum value of `max_burst_size` is 500. 264 // 265 // For App Engine queues that were created or updated using 266 // `queue.yaml/xml`, `max_burst_size` is equal to 267 // [bucket_size](https://cloud.google.com/appengine/docs/standard/python/config/queueref#bucket_size). 268 // If 269 // [UpdateQueue][google.cloud.tasks.v2beta2.CloudTasks.UpdateQueue] is called 270 // on a queue without explicitly setting a value for `max_burst_size`, 271 // `max_burst_size` value will get updated if 272 // [UpdateQueue][google.cloud.tasks.v2beta2.CloudTasks.UpdateQueue] is 273 // updating [max_dispatches_per_second][RateLimits.max_dispatches_per_second]. 274 // 275 int32 max_burst_size = 2; 276 277 // The maximum number of concurrent tasks that Cloud Tasks allows 278 // to be dispatched for this queue. After this threshold has been 279 // reached, Cloud Tasks stops dispatching tasks until the number of 280 // concurrent requests decreases. 281 // 282 // If unspecified when the queue is created, Cloud Tasks will pick the 283 // default. 284 // 285 // 286 // The maximum allowed value is 5,000. 287 // 288 // This field is output only for 289 // [pull queues][google.cloud.tasks.v2beta2.PullTarget] and always -1, which 290 // indicates no limit. No other queue types can have `max_concurrent_tasks` 291 // set to -1. 292 // 293 // 294 // This field has the same meaning as 295 // [max_concurrent_requests in 296 // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#max_concurrent_requests). 297 int32 max_concurrent_tasks = 3; 298} 299 300// Retry config. 301// 302// These settings determine how a failed task attempt is retried. 303message RetryConfig { 304 // Number of attempts per task. 305 // 306 // If unspecified when the queue is created, Cloud Tasks will pick the 307 // default. 308 // 309 // 310 // 311 // This field has the same meaning as 312 // [task_retry_limit in 313 // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). 314 oneof num_attempts { 315 // The maximum number of attempts for a task. 316 // 317 // Cloud Tasks will attempt the task `max_attempts` times (that 318 // is, if the first attempt fails, then there will be 319 // `max_attempts - 1` retries). Must be > 0. 320 int32 max_attempts = 1; 321 322 // If true, then the number of attempts is unlimited. 323 bool unlimited_attempts = 2; 324 } 325 326 // If positive, `max_retry_duration` specifies the time limit for 327 // retrying a failed task, measured from when the task was first 328 // attempted. Once `max_retry_duration` time has passed *and* the 329 // task has been attempted 330 // [max_attempts][google.cloud.tasks.v2beta2.RetryConfig.max_attempts] times, 331 // no further attempts will be made and the task will be deleted. 332 // 333 // If zero, then the task age is unlimited. 334 // 335 // If unspecified when the queue is created, Cloud Tasks will pick the 336 // default. 337 // 338 // This field is output only for [pull 339 // queues][google.cloud.tasks.v2beta2.PullTarget]. 340 // 341 // 342 // `max_retry_duration` will be truncated to the nearest second. 343 // 344 // This field has the same meaning as 345 // [task_age_limit in 346 // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). 347 google.protobuf.Duration max_retry_duration = 3; 348 349 // A task will be [scheduled][google.cloud.tasks.v2beta2.Task.schedule_time] 350 // for retry between 351 // [min_backoff][google.cloud.tasks.v2beta2.RetryConfig.min_backoff] and 352 // [max_backoff][google.cloud.tasks.v2beta2.RetryConfig.max_backoff] duration 353 // after it fails, if the queue's 354 // [RetryConfig][google.cloud.tasks.v2beta2.RetryConfig] specifies that the 355 // task should be retried. 356 // 357 // If unspecified when the queue is created, Cloud Tasks will pick the 358 // default. 359 // 360 // This field is output only for [pull 361 // queues][google.cloud.tasks.v2beta2.PullTarget]. 362 // 363 // 364 // `min_backoff` will be truncated to the nearest second. 365 // 366 // This field has the same meaning as 367 // [min_backoff_seconds in 368 // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). 369 google.protobuf.Duration min_backoff = 4; 370 371 // A task will be [scheduled][google.cloud.tasks.v2beta2.Task.schedule_time] 372 // for retry between 373 // [min_backoff][google.cloud.tasks.v2beta2.RetryConfig.min_backoff] and 374 // [max_backoff][google.cloud.tasks.v2beta2.RetryConfig.max_backoff] duration 375 // after it fails, if the queue's 376 // [RetryConfig][google.cloud.tasks.v2beta2.RetryConfig] specifies that the 377 // task should be retried. 378 // 379 // If unspecified when the queue is created, Cloud Tasks will pick the 380 // default. 381 // 382 // This field is output only for [pull 383 // queues][google.cloud.tasks.v2beta2.PullTarget]. 384 // 385 // 386 // `max_backoff` will be truncated to the nearest second. 387 // 388 // This field has the same meaning as 389 // [max_backoff_seconds in 390 // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). 391 google.protobuf.Duration max_backoff = 5; 392 393 // The time between retries will double `max_doublings` times. 394 // 395 // A task's retry interval starts at 396 // [min_backoff][google.cloud.tasks.v2beta2.RetryConfig.min_backoff], then 397 // doubles `max_doublings` times, then increases linearly, and finally retries 398 // at intervals of 399 // [max_backoff][google.cloud.tasks.v2beta2.RetryConfig.max_backoff] up to 400 // [max_attempts][google.cloud.tasks.v2beta2.RetryConfig.max_attempts] times. 401 // 402 // For example, if 403 // [min_backoff][google.cloud.tasks.v2beta2.RetryConfig.min_backoff] is 10s, 404 // [max_backoff][google.cloud.tasks.v2beta2.RetryConfig.max_backoff] is 300s, 405 // and `max_doublings` is 3, then the a task will first be retried in 10s. The 406 // retry interval will double three times, and then increase linearly by 2^3 * 407 // 10s. Finally, the task will retry at intervals of 408 // [max_backoff][google.cloud.tasks.v2beta2.RetryConfig.max_backoff] until the 409 // task has been attempted 410 // [max_attempts][google.cloud.tasks.v2beta2.RetryConfig.max_attempts] times. 411 // Thus, the requests will retry at 10s, 20s, 40s, 80s, 160s, 240s, 300s, 412 // 300s, .... 413 // 414 // If unspecified when the queue is created, Cloud Tasks will pick the 415 // default. 416 // 417 // This field is output only for [pull 418 // queues][google.cloud.tasks.v2beta2.PullTarget]. 419 // 420 // 421 // This field has the same meaning as 422 // [max_doublings in 423 // queue.yaml/xml](https://cloud.google.com/appengine/docs/standard/python/config/queueref#retry_parameters). 424 int32 max_doublings = 6; 425} 426 427// Statistics for a queue. 428message QueueStats { 429 // Output only. An estimation of the number of tasks in the queue, that is, 430 // the tasks in the queue that haven't been executed, the tasks in the queue 431 // which the queue has dispatched but has not yet received a reply for, and 432 // the failed tasks that the queue is retrying. 433 int64 tasks_count = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; 434 435 // Output only. An estimation of the nearest time in the future where a task 436 // in the queue is scheduled to be executed. 437 google.protobuf.Timestamp oldest_estimated_arrival_time = 2 438 [(google.api.field_behavior) = OUTPUT_ONLY]; 439 440 // Output only. The number of tasks that the queue has dispatched and received 441 // a reply for during the last minute. This variable counts both successful 442 // and non-successful executions. 443 int64 executed_last_minute_count = 3 444 [(google.api.field_behavior) = OUTPUT_ONLY]; 445 446 // Output only. The number of requests that the queue has dispatched but has 447 // not received a reply for yet. 448 int64 concurrent_dispatches_count = 4 449 [(google.api.field_behavior) = OUTPUT_ONLY]; 450 451 // Output only. The current maximum number of tasks per second executed by the 452 // queue. The maximum value of this variable is controlled by the RateLimits 453 // of the Queue. However, this value could be less to avoid overloading the 454 // endpoints tasks in the queue are targeting. 455 double effective_execution_rate = 5 456 [(google.api.field_behavior) = OUTPUT_ONLY]; 457} 458