Expiring Relationships

A common use case is to model relationships that expire after a certain time. This is useful for granting temporary access to a resource.

Until now, caveats were the recommended way to support time-bound permissions, but that has some limitations:

• It requires clients to provide the now timestamp. This is additional complexity for clients.
• Expired caveats are not automatically garbage collected. This can lead to many caveated relationships in the system and increase the costs of loading and evaluating those into the runtime.

SpiceDB supports expiring relationships, which lets users define relationships that expire at a given time.

Schema Use

Expiring relationships follow a similar use to caveated subject types. The novelty here is that users need to enable the feature using the use clause. This is to disambiguate a caveat named expiration from the new expiration feature.

To enable expiration in your schema, add a use expiration clause to the top of the file. Then the relations subject to expiration are marked using <type> with expiration:

use expiration
 
definition folder {}
 
definition resource {
    relation folder: folder with expiration
}

API Use

The expiration of a relationship is on a per-relationship basis (opens in a new tab) at write time, using WriteRelationships or BulkImportRelationships APIs. The expiration is denoted with the OptionalExpiresAt field in the relationship.

WriteRelationshipsRequest {
  Updates: [
    RelationshipUpdate{
      Operation: CREATE
      Relationship: {
        Resource: {
            ObjectType: "resource",
            ObjectId: "someresource",
        },
        Relation: "viewer",
        Subject: {
            ObjectType: "user",
            ObjectId: "sarah",
        },
        OptionalExpiresAt: "2022-12-31T23:59:59Z"
      }
    }
  ]
}

Garbage Collection

As soon as a relationship expires, it will no longer be used in permission checks. However, the row is not deleted right then, but rather is subject to garbage collection.

Reclaiming expiring relationships is governed by the same mechanism (and flags) as the deletion of the history of relationship changes that powers SpiceDB's own MVCC (Multi-Version Concurrency Control) and heavily depends on the datastore chosen.

• Datastores like Spanner and CockroachDB have built-in support for expiring SQL rows, so the database does Garbage Collection. In both cases, expired relationships will be reclaimed after 24 hours, which can't be changed without directly manipulating the SQL schema.
• Datastores like Postgres and MySQL support it using the same GC job that reclaims old relationship versions, which runs every 5 minutes. Unlike Spanner and CockroachDB, you can govern the GC window with the corresponding flags. Relationships will be reclaimed after 24 hours by default.

Migrating Off Of Expiration With Caveats

If you implemented expiration using caveats, this section describes migrating to the new expiration feature.

1. Rename your caveat if you had named it expiration

2. Add the new subject type to your relation, and also add a combination where both are used:

   caveat ttl(timeout duration, now string, timeout_creation_timestamp string) {
      timestamp(now) - timestamp(timeout_creation_timestamp) < timeout
   }
    
   definition folder {}
    
   definition resource {
       relation folder: folder with ttl
   }

   Becomes:

   use expiration
    
   caveat ttl(timeout duration, now string, timeout_creation_timestamp string) {
      timestamp(now) - timestamp(timeout_creation_timestamp) < timeout
   }
    
   definition folder {}
    
   definition resource {
       relation folder: folder with ttl | folder with expiration | folder with ttl and expiration
   }

3. Migrate all relationships to use both the caveat and the new expiration. This is needed because only one relationship is allowed for a resource/permission/subject combination.

4. Validate that the new expiration feature works as expected by not providing the context for evaluating the ttl caveat.

5. Once validated, migrate completely to the new expiration feature by writing all relationships with only expiration and without caveat.

6. Drop the caveat from your schema once the migration is completed

   use expiration
    
   definition folder {}
    
   definition resource {
       relation folder: folder with expiration
   }