feat: support relation 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 78.26087% with 30 lines in your changes missing coverage. Please review.

Project coverage is 77.39%. Comparing base (ce04edc) to head (2855726).

Files with missing lines	Patch %	Lines
internal/services/v1/relationships.go	70.00%	7 Missing and 2 partials ⚠️
pkg/schemadsl/parser/parser.go	66.67%	6 Missing and 3 partials ⚠️
pkg/schemadsl/compiler/translator.go	63.64%	6 Missing and 2 partials ⚠️
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.39%   77.39%   -0.00%     
==========================================
  Files         416      416              
  Lines       50888    51023     +135     
==========================================
+ Hits        39381    39482     +101     
- Misses       9024     9048      +24     
- Partials     2483     2493      +10     

☔ 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 ?