feat(AIP-148): introduce purge_time (#1169)

expire_time for both soft resource purge time and
resource expire time (when it will not be useful) could
cause user confusion as to whether the resource is soft-deletable
or has an expiration.

splitting the fields resolves the issue.

---------

Co-authored-by: Noah Dietz <noahdietz@users.noreply.github.com>
Co-authored-by: Angie Lin <angielin@google.com>

Author: 3 people

aip/general/0148.md

@@ -100,17 +100,23 @@ Resources that support soft delete (AIP-164) **should** provide this field.
 
 #### expire_time
 
-The `google.protobuf.Timestamp expire_time` field **should** usually represent
-the time when a soft deleted resource will be purged from the system. It
-**may** be used for similar forms of expiration as described in AIP-214.
-Resources that support soft delete **should** include this field.
+The `google.protobuf.Timestamp expire_time` field **should** represent the time
+that a given resource or resource attribute is no longer useful or valid (e.g. a
+rotating security key). It **may** be used for similar forms of expiration as
+described in AIP-214.
 
-In some situations, it can be difficult to provide an exact `expire_time`
-value, because of implementation dependencies. Services **may** provide an
-`expire_time` value that is inexact, but the resource **must not** be expired
-from the system before that time.
+Services **may** provide an `expire_time` value that is inexact, but the
+resource **must not** expire before that time.
 
-Resources that support soft delete (AIP-164) **should** provide this field.
+#### purge_time
+
+The `google.protobuf.Timestamp purge_time` field **should** represent the time
+when a soft deleted resource will be purged from the system (see AIP-164).
+It **may** be used for similar forms of expiration as described in AIP-214.
+Resources that support soft delete **should** include this field.
+
+Services **may** provide a `purge_time` value that is inexact, but the resource
+**must not** be purged from the system before that time.
 
 ## Further reading
 
@@ -122,8 +128,14 @@ Resources that support soft delete (AIP-164) **should** provide this field.
 - For the `validate_only` field, see AIP-163.
 - For fields related to soft delete and undelete, see AIP-164.
 
+## History
+
+Before 2023-07, `purge_time` for soft-deleted resources was also called
+`expire_time`. `purge_time` was introduced to reduce user confusion.
+
 ## Changelog
 
+- **2023-07-13**: Introduce the term `purge_time`.
 - **2021-04-06**: Require output only field behavior for `uid` and `delete_time`
   fields.
 

aip/general/0164.md

@@ -24,7 +24,7 @@ mark the resource as having been deleted, but not completely remove it from the
 system. If the method behaves this way, it **should** return the updated
 resource instead of `google.protobuf.Empty`.
 
-Resources that support soft delete **should** have an `expire_time` field as
+Resources that support soft delete **should** have a `purge_time` field as
 described in AIP-148. Additionally, resources **should** include a `DELETED`
 state value if the resource includes a `state` field (AIP-216).
 
@@ -160,6 +160,7 @@ resource is not deleted, the service **must** respond with `ALREADY_EXISTS`
 
 ## Changelog
 
+- **2023-07-13**: Renamed overloaded `expire_time` to `purge_time`.
 - **2021-07-12**: Added error behavior when soft deleting a deleted resource.
 - **2021-07-12**: Clarified that `ALREADY_EXISTS` errors apply to `Undelete`.
 - **2021-07-12**: Changed the `expire_time` field to "should" for consistency

aip/general/0214.md

@@ -9,12 +9,12 @@ placement:
 
 # 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
-`google.protobuf.Timestamp expire_time` field; 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.
+Customers often want to provide the time that a given resource or resource
+attribute is no longer useful or valid (e.g. a rotating security key). Currently
+we recommend that customers do this by specifying an exact "expiration time"
+into a `google.protobuf.Timestamp expire_time` field; 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
@@ -55,9 +55,11 @@ message ExpiringResource {
 }
 ```
 
-## Alternatives considered
+## Rationale
 
-### A new standard field called `ttl`
+### Alternatives considered
+
+#### A new standard field called `ttl`
 
 We considered allowing a standard field called `ttl` as an alternative way of
 defining the expiration, however doing so would require that API services
@@ -66,7 +68,7 @@ potentially cause problems with the read-modify-write lifecycle where a
 resource is being processed for some time, and effectively has its life
 extended as a result of that processing time.
 
-### Always use `expire_time`
+#### Always use `expire_time`
 
 This is the current state of the world with a few exceptions. In this scenario,
 we could potentially push the computation of `now + ttl = expire_time` into