Expiring Relationships

A common use-case is to model relationships that expire after a certain amount of time. This is useful to grant temporary access to a resource.

Until now, caveats was 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 a large number of caveats in the system and increasing cost for loading those into the runtime and evaluating them.

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

Schema Use

Expiring relationships follow a similar use to caveated subject types. The novelty here is that, in order to disambiguate between a caveat named expiration and the native expiration feature, users would need to add a use clause to the schema definition to enable the feature.

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

API Use

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 as part of 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

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 Garbage Collection is done by the database itself. In both cases, expired relationships will be reclaimed after 24 hours, and that 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 Expirationg With Caveats

If you implemented expiration using caveats, this section describes the process to migrate 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 add also 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 combination of resource/permission/subject.
4. Validate that the new expiration feature works as expected by not providing the needed context for the evaluation of the ttl caveat.
5. Once validated, migrate completely to the new expiration feature by writting all relationships with only expiration and without caveat.
6. Drop the caveat from your schema once migration is completed

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