From ed49809c3dfa30da3194537f033f3d40e4b9b6d4 Mon Sep 17 00:00:00 2001 From: ecordell Date: Tue, 17 Nov 2026 14:54:53 -0500 Subject: [PATCH] Add OPERATION_EXPIRE and an opt-in Watch kind for expirations Watch currently excludes relationships that were removed because they expired, so a Watch consumer cannot tell that access ended. Datastores that record expirations as changes can now report them. - RelationshipUpdate.Operation gets OPERATION_EXPIRE = 4. - WatchKind gets WATCH_KIND_INCLUDE_RELATIONSHIP_EXPIRATIONS = 4. Watch reports OPERATION_EXPIRE only when the request asks for it, so existing clients never receive an enum value they do not know. - WriteRelationshipsRequest rejects OPERATION_EXPIRE with a protovalidate CEL rule. protoc-gen-validate cannot express this check, so servers that use it must reject the operation themselves. --- authzed/api/v1/core.proto | 6 ++++++ authzed/api/v1/permission_service.proto | 6 ++++++ authzed/api/v1/watch_service.proto | 10 +++++++++- docs/apidocs.swagger.json | 12 +++++++----- 4 files changed, 28 insertions(+), 6 deletions(-) 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",