feat: introduce unstable Actor API [skip ci]

[salmart-dev]

Summary

Introduce the concept of actors, characterised by their properties and used to build a shared vocabulary apps can use to transport, accept and return [actor + identity] information without necessarily having to deal with the implementation details of their backends.

Structure

IActor interface

namespace NCU\Actor;

interface IActor {
        // a stable identifier representing the actor type, useful for storing a reference to the actor
	public function getTypeIdentifier(): string;
}

Actor characteristics

Actors should be characterised by their properties in a generalised way, so that consumers can narrow on them, without necessarily having to deal with the details of the implementation.

// an actor that is identifiable via an identifier (e.g. cloud ID, user ID, email)
interface IIdentifiableActor extends IActor {
    public function getId(): string;
}

// an actor whose account resides in the local instance
interface ILocalAccountActor extends IIdentifiableActor {}

// an actor that is not a user, but has system access: e.g. cron command, background job
interface ISystemActor extends IActor {}

In the future, this could be used to describe a bot actor with system-wide access, or acting on behalf of a user. This can also generalise to AI agents.

Code using this vocabulary could then write API that is able to deal with different actor types that fit certain characteristics.

Example:

public function getAvailableItems(IActor $actor) {
  if (!$actor instanceof IdentifiableActor) {
    // non-identifiable actors are not supported
    throw new Exception('This API supports only identifiable actors (users, guests)');
  }

  if (!$actor instanceof ILocalAccountActor) {
    // only actors known by the current instance are supported
    throw new Exception('Non-local users are not supported by this API');
  }
}

Baseline actors

An initial set of actors is provided in this implementation. Consumers should prefer narrowing on the interfaces rather than on concrete types. An exception to this rule is when a consumer needs to support one specific actor type, as new actor additions do not introduce ambiguities in existing code in this case.

namespace NCU\Actor\Actors;

final class UserActor implements ILocalAccountActor { /* a known user */ }
final class FederatedUserActor implements IIdentifiableActor { /* user whose identity authority is not on the current instance */ }
final class SystemActor implements IActor { /* cron jobs, occ commands */ }
final class AnonymousActor implements IActor { /* an actor that has no identifier (e.g. request from public API) */ }

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Screenshots before/after for front-end changes
• Documentation (manuals or wiki) has been updated or is not required
• Backports requested where applicable (ex: critical bugfixes)
• Labels added where applicable (ex: bug/enhancement, 3. to review, feature component)
• Milestone added for target branch/version (ex: 32.x for stable32)

AI (if applicable)

• The content of this PR was partly or fully generated using AI