feat: support the .dispatch_deadline property. (#160)

googleapis · Jan 26, 2019 · bdc515b · bdc515b
1 parent 4ee70ea
commit bdc515b
Show file tree

Hide file tree

Showing 34 changed files with 191 additions and 94 deletions.
diff --git a/packages/google-cloud-tasks/protos/google/cloud/tasks/v2beta3/queue.proto b/packages/google-cloud-tasks/protos/google/cloud/tasks/v2beta3/queue.proto
@@ -55,9 +55,11 @@ message Queue {
     // The queue is disabled.
     //
     // A queue becomes `DISABLED` when
-    // [queue.yaml](https://cloud.google.com/appengine/docs/python/config/queueref) or
-    // [queue.xml](https://cloud.google.com/appengine/docs/standard/java/config/queueref) is uploaded
-    // which does not contain the queue. You cannot directly disable a queue.
+    // [queue.yaml](https://cloud.google.com/appengine/docs/python/config/queueref)
+    // or
+    // [queue.xml](https://cloud.google.com/appengine/docs/standard/java/config/queueref)
+    // is uploaded which does not contain the queue. You cannot directly disable
+    // a queue.
     //
     // When a queue is disabled, tasks can still be added to a queue
     // but the tasks are not dispatched.
@@ -87,26 +89,17 @@ message Queue {
   //   hyphens (-). The maximum length is 100 characters.
   string name = 1;
 
-  // Caller-specified and required in [CreateQueue][google.cloud.tasks.v2beta3.CloudTasks.CreateQueue][],
-  // after which the queue config type becomes output only, though fields within
-  // the config are mutable.
-  //
-  // The queue's type.
-  //
-  // The type applies to all tasks in the queue.
   oneof queue_type {
-    // App Engine HTTP queue.
-    //
-    // An App Engine queue is a queue that has an [AppEngineHttpQueue][google.cloud.tasks.v2beta3.AppEngineHttpQueue] type.
+    // [AppEngineHttpQueue][google.cloud.tasks.v2beta3.AppEngineHttpQueue] settings apply only to
+    // [App Engine tasks][google.cloud.tasks.v2beta3.AppEngineHttpRequest] in this queue.
     AppEngineHttpQueue app_engine_http_queue = 3;
   }
 
   // Rate limits for task dispatches.
   //
-  // [rate_limits][google.cloud.tasks.v2beta3.Queue.rate_limits] and
-  // [retry_config][google.cloud.tasks.v2beta3.Queue.retry_config] are related because they both
-  // control task attempts however they control how tasks are
-  // attempted in different ways:
+  // [rate_limits][google.cloud.tasks.v2beta3.Queue.rate_limits] and [retry_config][google.cloud.tasks.v2beta3.Queue.retry_config] are
+  // related because they both control task attempts. However they control task
+  // attempts in different ways:
   //
   // * [rate_limits][google.cloud.tasks.v2beta3.Queue.rate_limits] controls the total rate of
   //   dispatches from a queue (i.e. all traffic dispatched from the
@@ -116,6 +109,16 @@ message Queue {
   //   particular a task after its first attempt fails. That is,
   //   [retry_config][google.cloud.tasks.v2beta3.Queue.retry_config] controls task retries (the
   //   second attempt, third attempt, etc).
+  //
+  // The queue's actual dispatch rate is the result of:
+  //
+  // * Number of tasks in the queue
+  // * User-specified throttling: [rate limits][Queue.RateLimits]
+  //   [retry configuration][Queue.RetryConfig], and the
+  //   [queue's state][google.cloud.tasks.v2beta3.Queue.state].
+  // * System throttling due to `429` (Too Many Requests) or `503` (Service
+  //   Unavailable) responses from the worker, high error rates, or to smooth
+  //   sudden large traffic spikes.
   RateLimits rate_limits = 4;
 
   // Settings that determine the retry behavior.

diff --git a/packages/google-cloud-tasks/protos/google/cloud/tasks/v2beta3/target.proto b/packages/google-cloud-tasks/protos/google/cloud/tasks/v2beta3/target.proto
@@ -68,6 +68,11 @@ message AppEngineHttpQueue {
 // [How Requests are Routed](https://cloud.google.com/appengine/docs/standard/python/how-requests-are-routed)
 // and how routing is affected by
 // [dispatch files](https://cloud.google.com/appengine/docs/python/config/dispatchref).
+// Traffic is encrypted during transport and never leaves Google datacenters.
+// Because this traffic is carried over a communication mechanism internal to
+// Google, you cannot explicitly set the protocol (for example, HTTP or HTTPS).
+// The request to the handler, however, will appear to have used the HTTP
+// protocol.
 //
 // The [AppEngineRouting][google.cloud.tasks.v2beta3.AppEngineRouting] used to construct the URL that the task is
 // delivered to can be set at the queue-level or task-level:
@@ -84,6 +89,14 @@ message AppEngineHttpQueue {
 // * `url =` [host][google.cloud.tasks.v2beta3.AppEngineRouting.host] `+`
 //   [relative_uri][google.cloud.tasks.v2beta3.AppEngineHttpRequest.relative_uri]
 //
+// Tasks can be dispatched to secure app handlers, unsecure app handlers, and
+// URIs restricted with
+// [`login: admin`](https://cloud.google.com/appengine/docs/standard/python/config/appref).
+// Because tasks are not run as any user, they cannot be dispatched to URIs
+// restricted with
+// [`login: required`](https://cloud.google.com/appengine/docs/standard/python/config/appref)
+// Task dispatches also do not follow redirects.
+//
 // The task attempt has succeeded if the app's request handler returns
 // an HTTP response code in the range [`200` - `299`]. `503` is
 // considered an App Engine system error instead of an application
@@ -171,14 +184,8 @@ message AppEngineHttpRequest {
 
 // App Engine Routing.
 //
-// Specifies the target URI. Since this target type dispatches tasks to secure
-// app handlers, unsecure app handlers, and URIs restricted with
-// [`login: admin`](https://cloud.google.com/appengine/docs/standard/python/config/appref)
-// the protocol (for example, HTTP or HTTPS) cannot be explictly specified.
-// Task dispatches do not follow redirects and cannot target URI paths
-// restricted with
-// [`login: required`](https://cloud.google.com/appengine/docs/standard/python/config/appref)
-// because tasks are not run as any user.
+// Defines routing characteristics specific to App Engine - service, version,
+// and instance.
 //
 // For more information about services, versions, and instances see
 // [An Overview of App Engine](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine),
@@ -266,4 +273,10 @@ enum HttpMethod {
 
   // HTTP DELETE
   DELETE = 5;
+
+  // HTTP PATCH
+  PATCH = 6;
+
+  // HTTP OPTIONS
+  OPTIONS = 7;
 }
diff --git a/packages/google-cloud-tasks/protos/google/cloud/tasks/v2beta3/task.proto b/packages/google-cloud-tasks/protos/google/cloud/tasks/v2beta3/task.proto
@@ -19,6 +19,7 @@ package google.cloud.tasks.v2beta3;
 
 import "google/api/annotations.proto";
 import "google/cloud/tasks/v2beta3/target.proto";
+import "google/protobuf/duration.proto";
 import "google/protobuf/timestamp.proto";
 import "google/rpc/status.proto";
 
@@ -80,15 +81,9 @@ message Task {
   //   hyphens (-), or underscores (_). The maximum length is 500 characters.
   string name = 1;
 
-  // Required.
-  //
-  // The task's payload is used by the task's target to process the task.
-  // A payload is valid only if it is compatible with the queue's target.
+  // Required. The message to send to the worker.
   oneof payload_type {
-    // App Engine HTTP request that is sent to the task's target. Can
-    // be set only if
-    // [app_engine_http_queue][google.cloud.tasks.v2beta3.Queue.app_engine_http_queue] is set
-    // on the queue.
+    // HTTP request that is sent to the App Engine app handler.
     //
     // An App Engine task is a task that has [AppEngineHttpRequest][google.cloud.tasks.v2beta3.AppEngineHttpRequest] set.
     AppEngineHttpRequest app_engine_http_request = 3;
@@ -106,6 +101,36 @@ message Task {
   // `create_time` will be truncated to the nearest second.
   google.protobuf.Timestamp create_time = 5;
 
+  // The deadline for requests sent to the worker. If the worker does not
+  // respond by this deadline then the request is cancelled and the attempt
+  // is marked as a `DEADLINE_EXCEEDED` failure. Cloud Tasks will retry the
+  // task according to the [RetryConfig][google.cloud.tasks.v2beta3.RetryConfig].
+  //
+  // Note that when the request is cancelled, Cloud Tasks will stop listing for
+  // the response, but whether the worker stops processing depends on the
+  // worker. For example, if the worker is stuck, it may not react to cancelled
+  // requests.
+  //
+  // The default and maximum values depend on the type of request:
+  //
+  //
+  // * For [App Engine tasks][google.cloud.tasks.v2beta3.AppEngineHttpRequest], 0 indicates that the
+  //   request has the default deadline. The default deadline depends on the
+  //   [scaling type](https://cloud.google.com/appengine/docs/standard/go/how-instances-are-managed#instance_scaling)
+  //   of the service: 10 minutes for standard apps with automatic scaling, 24
+  //   hours for standard apps with manual and basic scaling, and 60 minutes for
+  //   flex apps. If the request deadline is set, it must be in the interval [15
+  //   seconds, 24 hours 15 seconds]. Regardless of the task's
+  //   `dispatch_deadline`, the app handler will not run for longer than than
+  //   the service's timeout. We recommend setting the `dispatch_deadline` to
+  //   at most a few seconds more than the app handler's timeout. For more
+  //   information see
+  //   [Timeouts](https://cloud.google.com/tasks/docs/creating-appengine-handlers#timeouts).
+  //
+  // `dispatch_deadline` will be truncated to the nearest millisecond. The
+  // deadline is an approximate deadline.
+  google.protobuf.Duration dispatch_deadline = 12;
+
   // Output only. The number of attempts dispatched.
   //
   // This count includes tasks which have been dispatched but haven't
@@ -146,7 +171,7 @@ message Attempt {
   // `response_time` will be truncated to the nearest microsecond.
   google.protobuf.Timestamp response_time = 3;
 
-  // Output only. The response from the target for this attempt.
+  // Output only. The response from the worker for this attempt.
   //
   // If `response_time` is unset, then the task has not been attempted or is
   // currently running and the `response_status` field is meaningless.

diff --git a/packages/google-cloud-tasks/src/v2beta2/cloud_tasks_client.js b/packages/google-cloud-tasks/src/v2beta2/cloud_tasks_client.js
@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2019 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

diff --git a/packages/google-cloud-tasks/src/v2beta2/doc/google/cloud/tasks/v2beta2/doc_cloudtasks.js b/packages/google-cloud-tasks/src/v2beta2/doc/google/cloud/tasks/v2beta2/doc_cloudtasks.js
@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2019 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

diff --git a/packages/google-cloud-tasks/src/v2beta2/doc/google/cloud/tasks/v2beta2/doc_queue.js b/packages/google-cloud-tasks/src/v2beta2/doc/google/cloud/tasks/v2beta2/doc_queue.js
@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2019 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

diff --git a/packages/google-cloud-tasks/src/v2beta2/doc/google/cloud/tasks/v2beta2/doc_target.js b/packages/google-cloud-tasks/src/v2beta2/doc/google/cloud/tasks/v2beta2/doc_target.js
@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2019 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

diff --git a/packages/google-cloud-tasks/src/v2beta2/doc/google/cloud/tasks/v2beta2/doc_task.js b/packages/google-cloud-tasks/src/v2beta2/doc/google/cloud/tasks/v2beta2/doc_task.js
@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2019 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

diff --git a/packages/google-cloud-tasks/src/v2beta2/doc/google/iam/v1/doc_iam_policy.js b/packages/google-cloud-tasks/src/v2beta2/doc/google/iam/v1/doc_iam_policy.js
@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2019 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

diff --git a/packages/google-cloud-tasks/src/v2beta2/doc/google/iam/v1/doc_policy.js b/packages/google-cloud-tasks/src/v2beta2/doc/google/iam/v1/doc_policy.js
@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2019 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

diff --git a/packages/google-cloud-tasks/src/v2beta2/doc/google/protobuf/doc_any.js b/packages/google-cloud-tasks/src/v2beta2/doc/google/protobuf/doc_any.js
@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2019 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

diff --git a/packages/google-cloud-tasks/src/v2beta2/doc/google/protobuf/doc_duration.js b/packages/google-cloud-tasks/src/v2beta2/doc/google/protobuf/doc_duration.js
@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2019 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

diff --git a/packages/google-cloud-tasks/src/v2beta2/doc/google/protobuf/doc_empty.js b/packages/google-cloud-tasks/src/v2beta2/doc/google/protobuf/doc_empty.js
@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2019 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

diff --git a/packages/google-cloud-tasks/src/v2beta2/doc/google/protobuf/doc_field_mask.js b/packages/google-cloud-tasks/src/v2beta2/doc/google/protobuf/doc_field_mask.js
@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2019 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

diff --git a/packages/google-cloud-tasks/src/v2beta2/doc/google/protobuf/doc_timestamp.js b/packages/google-cloud-tasks/src/v2beta2/doc/google/protobuf/doc_timestamp.js
@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2019 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

diff --git a/packages/google-cloud-tasks/src/v2beta2/doc/google/rpc/doc_status.js b/packages/google-cloud-tasks/src/v2beta2/doc/google/rpc/doc_status.js
@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2019 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

diff --git a/packages/google-cloud-tasks/src/v2beta2/index.js b/packages/google-cloud-tasks/src/v2beta2/index.js
@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2019 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

diff --git a/packages/google-cloud-tasks/src/v2beta3/cloud_tasks_client.js b/packages/google-cloud-tasks/src/v2beta3/cloud_tasks_client.js
@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2019 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

diff --git a/packages/google-cloud-tasks/src/v2beta3/doc/google/cloud/tasks/v2beta3/doc_cloudtasks.js b/packages/google-cloud-tasks/src/v2beta3/doc/google/cloud/tasks/v2beta3/doc_cloudtasks.js
@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2019 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

diff --git a/packages/google-cloud-tasks/src/v2beta3/doc/google/cloud/tasks/v2beta3/doc_queue.js b/packages/google-cloud-tasks/src/v2beta3/doc/google/cloud/tasks/v2beta3/doc_queue.js
@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2019 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -41,19 +41,17 @@
  *     hyphens (-). The maximum length is 100 characters.
  *
  * @property {Object} appEngineHttpQueue
- *   App Engine HTTP queue.
- *
- *   An App Engine queue is a queue that has an AppEngineHttpQueue type.
+ *   AppEngineHttpQueue settings apply only to
+ *   App Engine tasks in this queue.
  *
  *   This object should have the same structure as [AppEngineHttpQueue]{@link google.cloud.tasks.v2beta3.AppEngineHttpQueue}
  *
  * @property {Object} rateLimits
  *   Rate limits for task dispatches.
  *
- *   rate_limits and
- *   retry_config are related because they both
- *   control task attempts however they control how tasks are
- *   attempted in different ways:
+ *   rate_limits and retry_config are
+ *   related because they both control task attempts. However they control task
+ *   attempts in different ways:
  *
  *   * rate_limits controls the total rate of
  *     dispatches from a queue (i.e. all traffic dispatched from the
@@ -64,6 +62,16 @@
  *     retry_config controls task retries (the
  *     second attempt, third attempt, etc).
  *
+ *   The queue's actual dispatch rate is the result of:
+ *
+ *   * Number of tasks in the queue
+ *   * User-specified throttling: rate limits
+ *     retry configuration, and the
+ *     queue's state.
+ *   * System throttling due to `429` (Too Many Requests) or `503` (Service
+ *     Unavailable) responses from the worker, high error rates, or to smooth
+ *     sudden large traffic spikes.
+ *
  *   This object should have the same structure as [RateLimits]{@link google.cloud.tasks.v2beta3.RateLimits}
  *
  * @property {Object} retryConfig
@@ -147,9 +155,11 @@ const Queue = {
      * The queue is disabled.
      *
      * A queue becomes `DISABLED` when
-     * [queue.yaml](https://cloud.google.com/appengine/docs/python/config/queueref) or
-     * [queue.xml](https://cloud.google.com/appengine/docs/standard/java/config/queueref) is uploaded
-     * which does not contain the queue. You cannot directly disable a queue.
+     * [queue.yaml](https://cloud.google.com/appengine/docs/python/config/queueref)
+     * or
+     * [queue.xml](https://cloud.google.com/appengine/docs/standard/java/config/queueref)
+     * is uploaded which does not contain the queue. You cannot directly disable
+     * a queue.
      *
      * When a queue is disabled, tasks can still be added to a queue
      * but the tasks are not dispatched.