diff --git a/authzed/api/v1/core.proto b/authzed/api/v1/core.proto index 71d7797..a0cfcf0 100644 --- a/authzed/api/v1/core.proto +++ b/authzed/api/v1/core.proto @@ -153,12 +153,18 @@ message Cursor { // // DELETE will delete the relationship. If the relationship does not exist, // this operation will no-op. +// +// EXPIRE is never valid in a write. It appears only in WatchResponse, which +// reports it when a relationship was removed because its optional_expires_at +// passed, and only if the WatchRequest asked for +// WATCH_KIND_INCLUDE_RELATIONSHIP_EXPIRATIONS. message RelationshipUpdate { enum Operation { OPERATION_UNSPECIFIED = 0; OPERATION_CREATE = 1; OPERATION_TOUCH = 2; OPERATION_DELETE = 3; + OPERATION_EXPIRE = 4; } Operation operation = 1 [ (validate.rules).enum = { diff --git a/authzed/api/v1/permission_service.proto b/authzed/api/v1/permission_service.proto index 960dd29..18cb7d9 100644 --- a/authzed/api/v1/permission_service.proto +++ b/authzed/api/v1/permission_service.proto @@ -388,6 +388,12 @@ message Precondition { // the write will be committed. All updates will be applied transactionally, // and if any preconditions fail, the entire transaction will be reverted. message WriteRelationshipsRequest { + option (buf.validate.message).cel = { + id: "write_relationships_no_expire" + message: "OPERATION_EXPIRE is only reported by Watch and cannot be written" + expression: "this.updates.all(u, u.operation != 4)" + }; + repeated RelationshipUpdate updates = 1 [(validate.rules).repeated.items.message.required = true]; repeated Precondition optional_preconditions = 2 [(validate.rules).repeated.items.message.required = true]; // To be bounded by configuration diff --git a/authzed/api/v1/watch_service.proto b/authzed/api/v1/watch_service.proto index 0fba97b..d69c931 100644 --- a/authzed/api/v1/watch_service.proto +++ b/authzed/api/v1/watch_service.proto @@ -32,6 +32,12 @@ enum WatchKind { WATCH_KIND_INCLUDE_RELATIONSHIP_UPDATES = 1; WATCH_KIND_INCLUDE_SCHEMA_UPDATES = 2; WATCH_KIND_INCLUDE_CHECKPOINTS = 3; + // Include an OPERATION_EXPIRE update for each relationship that was removed + // because its optional_expires_at passed. The update is reported at the + // revision where the server removed the relationship, which is at or after + // its expiration time. Servers that do not record expirations as changes + // return no such updates. + WATCH_KIND_INCLUDE_RELATIONSHIP_EXPIRATIONS = 4; } // WatchRequest specifies what mutations to watch for, and an optional start point for when to start @@ -78,7 +84,9 @@ message WatchRequest { } // WatchResponse contains all mutation events in ascending timestamp order. -// This excludes relationships that were deleted because they expired. +// Relationships that were removed because they expired are excluded, unless +// the request includes WATCH_KIND_INCLUDE_RELATIONSHIP_EXPIRATIONS; then each +// is reported as an OPERATION_EXPIRE update. // The response includes a field that can be used to resume // watching from that point. message WatchResponse { diff --git a/docs/apidocs.swagger.json b/docs/apidocs.swagger.json index 922436f..31d0715 100644 --- a/docs/apidocs.swagger.json +++ b/docs/apidocs.swagger.json @@ -3052,7 +3052,7 @@ "$ref": "#/definitions/Relationship" } }, - "description": "RelationshipUpdate is used for mutating a single relationship within the\nservice.\n\nCREATE will create the relationship only if it doesn't exist, and error\notherwise.\n\nTOUCH will upsert the relationship, and will not error if it\nalready exists.\n\nDELETE will delete the relationship. If the relationship does not exist,\nthis operation will no-op." + "description": "RelationshipUpdate is used for mutating a single relationship within the\nservice.\n\nCREATE will create the relationship only if it doesn't exist, and error\notherwise.\n\nTOUCH will upsert the relationship, and will not error if it\nalready exists.\n\nDELETE will delete the relationship. If the relationship does not exist,\nthis operation will no-op.\n\nEXPIRE is never valid in a write. It appears only in WatchResponse, which\nreports it when a relationship was removed because its optional_expires_at\npassed, and only if the WatchRequest asked for\nWATCH_KIND_INCLUDE_RELATIONSHIP_EXPIRATIONS." }, "RelationshipUpdate.Operation": { "type": "string", @@ -3060,7 +3060,8 @@ "OPERATION_UNSPECIFIED", "OPERATION_CREATE", "OPERATION_TOUCH", - "OPERATION_DELETE" + "OPERATION_DELETE", + "OPERATION_EXPIRE" ], "default": "OPERATION_UNSPECIFIED" }, @@ -3187,10 +3188,11 @@ "WATCH_KIND_UNSPECIFIED", "WATCH_KIND_INCLUDE_RELATIONSHIP_UPDATES", "WATCH_KIND_INCLUDE_SCHEMA_UPDATES", - "WATCH_KIND_INCLUDE_CHECKPOINTS" + "WATCH_KIND_INCLUDE_CHECKPOINTS", + "WATCH_KIND_INCLUDE_RELATIONSHIP_EXPIRATIONS" ], "default": "WATCH_KIND_UNSPECIFIED", - "title": "- WATCH_KIND_UNSPECIFIED: Default, just relationship updates (for backwards compatibility)" + "description": " - WATCH_KIND_UNSPECIFIED: Default, just relationship updates (for backwards compatibility)\n - WATCH_KIND_INCLUDE_RELATIONSHIP_EXPIRATIONS: Include an OPERATION_EXPIRE update for each relationship that was removed\nbecause its optional_expires_at passed. The update is reported at the\nrevision where the server removed the relationship, which is at or after\nits expiration time. Servers that do not record expirations as changes\nreturn no such updates." }, "WatchPermissionSetsResponse": { "type": "object", @@ -3293,7 +3295,7 @@ "description": "full_revision_metadata contains all transaction metadata given to SpiceDB during the\nrevision that produced the changes in this response. Some datastores (such as CockroachDB)\ncan \"merge\" multiple transactions into a single revision (if the changes occurred concurrently),\nso this field is a list of all transaction metadata seen during the revision." } }, - "description": "WatchResponse contains all mutation events in ascending timestamp order.\nThis excludes relationships that were deleted because they expired.\nThe response includes a field that can be used to resume\nwatching from that point." + "description": "WatchResponse contains all mutation events in ascending timestamp order.\nRelationships that were removed because they expired are excluded, unless\nthe request includes WATCH_KIND_INCLUDE_RELATIONSHIP_EXPIRATIONS; then each\nis reported as an OPERATION_EXPIRE update.\nThe response includes a field that can be used to resume\nwatching from that point." }, "WatchedPermission": { "type": "object",