Permissions API Page for Plugins

[Inscrutable]

We need a walk-through of the use of the Permissions API on the page source/plugins/permissions. Best PR gets an imaginary cookie.

[Douglas776589]

how do you help

[Inscrutable]

To help with the documentation, please submit your proposed changes in a Pull Request. If we like the look of your work, we'll merge it. If not, we'll tell you why.

[gabizou]

Well, Permissions hasn't been accepted yet, so whoever is writing documentation would probably need to wait to do so.

[boformer]

API is now ready. I will work on this next weekend.

[ryantheleach]

Made any progress? (was looking at what was missing on the permissions page and was thinking of starting a draft or at least making notes on what should be covered)

[RobertHerhold]

@ryantheleach Go ahead. I don't think anybody is working on it currently.

[ryantheleach]

SpongePowered/SpongeAPI@81bba65

Permission Descriptions have made it into the API.

[ryantheleach]

related: #136

[ryantheleach]

Some musings and definitions that I wrote while thinking about what needs to be covered to understand permissions in their entirety.

What is a permission?

A permission, is a right to do some action. They are represented as a permission node, together with a tristate value.

A permission "node" is a permission id. they are in the form of exampleplugin.command.use

Subjects are things that have rights / permissions assigned to them, and have an ever changing context (they are contextual) usually these are users or players, but could be templates or groups.

A context can be of any number of things, A world a player is in, the current dimension, the hostname they are connected to, the region a player is in, their gamemode, anything that provides a contextCalculator can be a context. Contexts can be used by a PermissionsService to aid decision making in whether a subject has a given permission.

A permission check, is a test to see if a subject, has the right to perform an action at the present time, in a given context.

A tristate value, is a value of true, false or undefined.

A tristate value of true grants the subject a permission, false will deny it. Undefined varies, but usually implies that a fallback of some sort will happen, according to rules in the implementation of the permissions service.

Is setting a permission to undefined it the same as clearing a permission?
What is a parent?

A SubjectCollection is simply a collection of subjects, examples of which is the collection of all Users, a Collection of groups, a subset of groups and or users.

A PermissionsDescription is a hint to the PermissionsService on who should have what permission by default, it also contains a Text description which aids end users, and where possible should contain a ClickAction link to documentation.

A NodeTree is a tree representation of a stored hierarchy of permissions.

The dot seperators of a permission node usually represent a tree structure, so that granting exampleplugin.command to true with exampleplugin.command.use undefined would cause a permissions check of exampleplugin.command.use to inherit exampleplugin.command.use to true. However this depends on the implementation of the permissions service.

An Option is a setting stored by the Permissions Service. They can be affected by context, and are assigned to subjects, usually following similar rules to permission nodes inheritance. They are stored as Strings.

Sponges default implementation of permissions checks to see what level of OP a player is in, and assigns roles (Which roles? just admin? what about staff?) as appropriate. There is no reason for a plugin to check OP directly, instead they should create a permission check for a permission node and document that. OP's will pass this by default, and may be denied it depending on alternate PermissionService implementations.

[ghost]

The dot seperators of a permission node usually represent a tree structure, so that granting exampleplugin.command to true with exampleplugin.command.use undefined would cause a permissions check of exampleplugin.command.use to inherit exampleplugin.command.use to true. However this depends on the implementation of the permissions service.

AFAIK It does not. That's the defined way how Permissions should work and any PermissionService treating it otherwise violates the API contract.

[ryantheleach]

? Are you referring to the roles that the PermissionsDescription has?

If the end user disagrees with how a plugin publishes the permissions they should absolutely be able to override it, meaning that the PermissionsService is free to override and that it's merely a hint to what should happen, and not the end result.

[ghost]

wow it was late when I wrote that. Quoted the wrong paragraph. Original comment was fixed

[Inscrutable]

With luck we may get some traction on this ancient issue from this.

[ST-DDT]

I'm not sure whether I should wait for that issue to be resolved, but I would offer my help to create the page. Should I wait or shall I create the documentation in parallel?

[Tzky]

I'd say that's up to you. If you're willing to start right now, just go ahead and open a PR.

[Inscrutable]

The Docs are here to describe the way it is, so feel free to begin anytime. People need to get to grips with the current API, warts and all. If changes happen, they'll belong in a later revision.

[Tzky]

Well, i'd say that the PR will target 5.0.0 anyways, as we're on our way to a 5.0.0 release. So the latest changes do matter in this case.