From 0dc7cfe2e59679d63bf56df78cbb72f10a804b89 Mon Sep 17 00:00:00 2001 From: Luke Sneeringer Date: Mon, 12 Jul 2021 14:53:17 -0700 Subject: [PATCH 1/3] =?UTF-8?q?feat:=20AIP-214=20=E2=80=93=20Resource=20ex?= =?UTF-8?q?piration?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- aip/general/0214/aip.md.j2 | 39 +++++++++++++++++++++++++++++ aip/general/0214/aip.yaml | 7 ++++++ aip/general/0214/expiry.oas.yaml | 26 ++++++++++++++++++++ aip/general/0214/expiry.proto | 42 ++++++++++++++++++++++++++++++++ 4 files changed, 114 insertions(+) create mode 100644 aip/general/0214/aip.md.j2 create mode 100644 aip/general/0214/aip.yaml create mode 100644 aip/general/0214/expiry.oas.yaml create mode 100644 aip/general/0214/expiry.proto diff --git a/aip/general/0214/aip.md.j2 b/aip/general/0214/aip.md.j2 new file mode 100644 index 00000000..9c625876 --- /dev/null +++ b/aip/general/0214/aip.md.j2 @@ -0,0 +1,39 @@ +# Resource expiration + +Customers often want to provide the time that a given resource or attribute of +a resource is no longer useful or should be deleted. Currently we recommend +that customers do this by specifying an exact "expiration time" into a +`expire_time` field with a timestamp type; however, this adds additional strain +on the user when they want to specify a relative time offset until expiration +rather than a specific time until expiration. + +Furthermore, the world understands the concept of a "time-to-live", often +abbreviated to TTL, but the typical format of this field (an integer, measured +in seconds) results in a sub-par experience when using an auto-generated client +library. + +## Guidance + +Services wishing to convey an expiration **must** rely on a timestamp field +called `expire_time`. Services wishing to allow a relative expiration time +**must** define a `oneof` called `expiration` (or `{something}_expiration`) +containing both the `expire_time` field and a separate [duration][aip-142] +field called `ttl`, the latter marked as input only: + +{% tab proto %} + +{% sample 'expiry.proto', 'message Book' %} + +{% tab oas %} + +{% sample 'expiry.oas.yaml', 'schema' %} + +{% endtabs %} + +Services **must** always return the expiration time in the `expire_time` field +and leave the `ttl` field blank when retrieving the resource. + +Services that rely on the specific semantics of a "time to live" (e.g., DNS +which must represent the TTL as an integer) **may** use an `int64 ttl` field +(and **should** provide an [aip.dev/not-precedent][aip-200] comment in this +case). diff --git a/aip/general/0214/aip.yaml b/aip/general/0214/aip.yaml new file mode 100644 index 00000000..7f367c86 --- /dev/null +++ b/aip/general/0214/aip.yaml @@ -0,0 +1,7 @@ +--- +id: 214 +state: approved +created: 2018-06-19 +placement: + category: design-patterns + order: 120 diff --git a/aip/general/0214/expiry.oas.yaml b/aip/general/0214/expiry.oas.yaml new file mode 100644 index 00000000..16cdd8be --- /dev/null +++ b/aip/general/0214/expiry.oas.yaml @@ -0,0 +1,26 @@ +--- +openapi: 3.0.3 +info: + title: Library + version: 1.0.0 +components: + schema: + Book: + description: This book will self-destruct. + properties: + name: + type: string + description: | + The name of the book. + Format: publishers/{publisher}/books/{book} + expire_time: + type: string + format: date-time + description: | + Timestamp in UTC of when this resource is considered expired. + This is *always* provided on output, regardless of what was sent + on input. + ttl_seconds: + type: integer + description: The TTL for this resource. + writeOnly: true diff --git a/aip/general/0214/expiry.proto b/aip/general/0214/expiry.proto new file mode 100644 index 00000000..5240fba0 --- /dev/null +++ b/aip/general/0214/expiry.proto @@ -0,0 +1,42 @@ +// Copyright 2021 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +import "google/api/field_behavior.proto"; +import "google/api/resource.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; + +// This book will self-destruct. +message Book { + option (google.api.resource) = { + type: "library.googleapis.com/Book" + pattern: "publishers/{publisher}/books/{book}" + }; + + // The name of the resource; the format is: ... + string name = 1; + + oneof expiration { + // Timestamp in UTC of when this resource is considered expired. + // This is *always* provided on output, regardless of what was sent + // on input. + google.protobuf.Timestamp expire_time = 2; + + // Input only. The TTL for this resource. + google.protobuf.Duration ttl = 3 + [(google.api.field_behavior) = INPUT_ONLY]; + } +} From ab39dabef1e48e48ea70dcfdcc8cf6c09061f7ed Mon Sep 17 00:00:00 2001 From: Ross Hamilton Date: Tue, 2 Nov 2021 10:45:17 -0600 Subject: [PATCH 2/3] updates to resource expiration to clarify that the AIP is about resources that expire, and not about the TTL or expiration time of a cached message. --- aip/general/0214/aip.md.j2 | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/aip/general/0214/aip.md.j2 b/aip/general/0214/aip.md.j2 index 9c625876..cd112efa 100644 --- a/aip/general/0214/aip.md.j2 +++ b/aip/general/0214/aip.md.j2 @@ -1,16 +1,21 @@ # Resource expiration -Customers often want to provide the time that a given resource or attribute of -a resource is no longer useful or should be deleted. Currently we recommend -that customers do this by specifying an exact "expiration time" into a -`expire_time` field with a timestamp type; however, this adds additional strain -on the user when they want to specify a relative time offset until expiration -rather than a specific time until expiration. - -Furthermore, the world understands the concept of a "time-to-live", often -abbreviated to TTL, but the typical format of this field (an integer, measured -in seconds) results in a sub-par experience when using an auto-generated client -library. +Sometimes it is necessary for a resource to have a defined lifespan. At the end +of this lifespan, the resource expires but may still be accessible from the +server. This "expiration time" may be defined by a customer, or determined by +the server at the time of creation. Regardless of how the source of this time, +we recommend it is communicated via the `expire_time` property. + +The `expire_time` of a resource is not meant to replace the `Cache-Control` +header to communicate client-side or CDN caching. The lifespan of a resource +refers to the time it spends in a valid or actionable state, such as a +certificate or an auction. + +For some resources, a relative time offset may be more appropriate than a date. +Furthermore, the world understands the concept of a "time-to-live", often +abbreviated to TTL. However, the typical format of this field (an integer, +measured in seconds) results in a sub-par experience when using an +auto-generated client library. ## Guidance From c253d7014935cef04e3b887152fabf6822cda050 Mon Sep 17 00:00:00 2001 From: Ross Hamilton Date: Tue, 9 Nov 2021 10:14:46 -0700 Subject: [PATCH 3/3] re-writing guidance based on feedback. Making the introduction more readable. --- aip/general/0214/aip.md.j2 | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/aip/general/0214/aip.md.j2 b/aip/general/0214/aip.md.j2 index cd112efa..9798c378 100644 --- a/aip/general/0214/aip.md.j2 +++ b/aip/general/0214/aip.md.j2 @@ -2,20 +2,22 @@ Sometimes it is necessary for a resource to have a defined lifespan. At the end of this lifespan, the resource expires but may still be accessible from the -server. This "expiration time" may be defined by a customer, or determined by -the server at the time of creation. Regardless of how the source of this time, -we recommend it is communicated via the `expire_time` property. - -The `expire_time` of a resource is not meant to replace the `Cache-Control` -header to communicate client-side or CDN caching. The lifespan of a resource -refers to the time it spends in a valid or actionable state, such as a -certificate or an auction. - -For some resources, a relative time offset may be more appropriate than a date. -Furthermore, the world understands the concept of a "time-to-live", often -abbreviated to TTL. However, the typical format of this field (an integer, -measured in seconds) results in a sub-par experience when using an -auto-generated client library. +server. The duration or end of this lifespan may be controled by an API client, +or determined by the server at the time of creation. Lifespans can be defined +as an absolute time value or as a relative time offset. An absolute time value +stored in the `expire_time` field is preferred. + +The `expire_time` of a resource is not intended to be a replacement for the `Cache-Control` header used to communicate client-side or CDN caching +recommendations. The lifespan of a resource refers to the time it spends in a +valid or actionable state, such as how long a certificate is valid, or how long +an auction is active. + +For some resources, a relative time offset may be more appropriate than an +absolute time value. Furthermore, the world understands the concept of a +"time-to-live", often abbreviated to TTL. However, the typical format of this +field (an integer, measured in seconds) results in a sub-par experience when +using an auto-generated client library. Nonetheless, a `ttl` field may be used +in conjunction with the `expire_time` field. ## Guidance