feat: support relation and object deprecation

[kartikaysaxena]

Related: #2396

This PR adds support for relation-level deprecation in schemas.

• Relations can now be annotated with a @deprecated(...) directive to indicate they are deprecated.
• When a relationship is written to a deprecated relation:
  • A warning or error is generated, depending on the specified deprecation level.
  • In the current implementation, writes fail when an error deprecation is configured.
• Deprecation is associated with the immediately following relation in the definition.
• A flag is to be passed to enable this feature, namely --enable-experimental-relationship-deprecation along with use directive.

Example:

use deprecation

definition user {}

definition resource {
  @deprecated(warn)
  relation viewer: user

  @deprecated(error)
  relation admin: user
}

Note

Each relation has an enum DeprecationType assigned to them, if unspecified it defaults to DEPRECATED_TYPE_UNSPECIFIED

[codecov]

Codecov Report

Attention: Patch coverage is 71.70418% with 88 lines in your changes missing coverage. Please review.

Project coverage is 77.39%. Comparing base (f05b700) to head (f436b79).

Files with missing lines	Patch %	Lines
pkg/schemadsl/parser/parser.go	58.98%	23 Missing and 9 partials ⚠️
pkg/schemadsl/compiler/translator.go	72.92%	18 Missing and 8 partials ⚠️
internal/services/v1/relationships.go	59.65%	20 Missing and 3 partials ⚠️
internal/services/shared/errors.go	75.00%	3 Missing ⚠️
pkg/namespace/builder.go	83.34%	2 Missing and 1 partial ⚠️
pkg/cmd/testserver/testserver.go	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2465      +/-   ##
==========================================
- Coverage   77.45%   77.39%   -0.06%     
==========================================
  Files         417      417              
  Lines       51091    51394     +303     
==========================================
+ Hits        39569    39769     +200     
- Misses       9032     9110      +78     
- Partials     2490     2515      +25     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[tstirrat15]

Left a couple of comments.

I'm also wondering about the behavior of these annotations more generally - what happens if you put this annotation on a permission instead of a relation? Should it have an effect?

[tstirrat15]

A general note on the approach: to the degree that we can, we want to avoid breaking folks' existing schemas. See what we did with expiration for an example of how we've worked around it with use directives - if we add this feature, it'll be with one of those use directives.

[tstirrat15]

We also need the composableschemadsl package to be updated accordingly.

[tstirrat15]

This isn't something that should live in the lexer - it should live in the parser.

Or at least my sense is that an @ should be a marker, and then the token after it should be a keyword, rather than the entire thing being marked as a keyword.

It's also going to relate to what I said above about the use directive.

[ecordell]

it might be worth looking at #202, which implemented generic decorators (but we didn't have a use case so never merged it)

[kartikaysaxena]

reworked the approach a little bit including the use directive just like how it was done for expiration feature, adding more comments for better review.

[josephschorr]

I wonder if we want to allow the deprecated annotation on each subject type vs the relation as a whole; I could see benefits to either. @ecordell thoughts?

[kartikaysaxena]

we may also support something like

use deprecation

definition user {}

definition resource {
  relation viewer: user
  relation admin: user
}

@deprecated(warn, user, "<comments about deprecation>")
@deprecated(error, admin, "<comments about deprecation>")

which can include both subjects and relations, this way deprecation can be more flexible and granular also including the comments about the deprecation.

Any thoughts @josephschorr @ecordell @tstirrat15 ?

[josephschorr]

This is also missing changes to the schema generator package and associated tests

[kartikaysaxena]

This is also missing changes to the schema generator package and associated tests

Updated the generator to accommodate deprecation and added some tests. I know you all are a bit busy, so feel free to take a look whenever you get the chance, thanks!

[vroldanbet]

I like it; let's add it and have it returned

Is the @ necessary at all?

[kartikaysaxena]

requesting for initial review, the deprecation support now looks like

use deprecation

definition user {}
definition superuser {}
definition anotheruser {}

definition platform {
	relation admin: user
	relation editor: superuser

	@deprecated(warn, “rel viewer is deprecated”)
	relation viewer: anotheruser
}

@deprecated(error, user, “user object is deprecated”)
@deprecated(warn, platform#editor, “this to deprecate a relation under a namespace”)

This adds support for deprecating relation inside a definition namespace for marking the immediate next relation as deprecated, for outside a namespace a relation can be marked deprecated as @deprecated(warn, platform#editor, “this to deprecate a relation under a namespace”) and an object by simply changing the relation with the object, example platform#editor -> user will mark user as deprecated, it works if the object is either defined as a subject or a resource in a WriteRelationship call.

(also would migrate this pr to a new branch if this branch looks messy after too many rebases)

[josephschorr]

requesting for initial review, the deprecation support now looks like

use deprecation

definition user {}
definition superuser {}
definition anotheruser {}

definition platform {
	relation admin: user
	relation editor: superuser

	@deprecated(warn, “rel viewer is deprecated”)
	relation viewer: anotheruser
}

@deprecated(error, user, “user object is deprecated”)
@deprecated(warn, platform#editor, “this to deprecate a relation under a namespace”)

This adds support for deprecating relation inside a definition namespace for marking the immediate next relation as deprecated, for outside a namespace a relation can be marked deprecated as @deprecated(warn, platform#editor, “this to deprecate a relation under a namespace”) and an object by simply changing the relation with the object, example platform#editor -> user will mark user as deprecated, it works if the object is either defined as a subject or a resource in a WriteRelationship call.

(also would migrate this pr to a new branch if this branch looks messy after too many rebases)

Sorry @kartikaysaxena, this is my bad at not being explicit: I liked the idea of being able to mark definitions as deprecated, but they should be done so by decorating the definition, not as a distinct line item:

@deprecated(error, “user object is deprecated”)
definition platform { ... }

[kartikaysaxena]

requesting for initial review, the deprecation support now looks like

use deprecation

definition user {}
definition superuser {}
definition anotheruser {}

definition platform {
	relation admin: user
	relation editor: superuser

	@deprecated(warn, “rel viewer is deprecated”)
	relation viewer: anotheruser
}

@deprecated(error, user, “user object is deprecated”)
@deprecated(warn, platform#editor, “this to deprecate a relation under a namespace”)

This adds support for deprecating relation inside a definition namespace for marking the immediate next relation as deprecated, for outside a namespace a relation can be marked deprecated as @deprecated(warn, platform#editor, “this to deprecate a relation under a namespace”) and an object by simply changing the relation with the object, example platform#editor -> user will mark user as deprecated, it works if the object is either defined as a subject or a resource in a WriteRelationship call.
(also would migrate this pr to a new branch if this branch looks messy after too many rebases)

Sorry @kartikaysaxena, this is my bad at not being explicit: I liked the idea of being able to mark definitions as deprecated, but they should be done so by decorating the definition, not as a distinct line item:

@deprecated(error, “user object is deprecated”)
definition platform { ... }

understood, this is implemented and superseded by #2504, mind taking a look?