<?php

namespace NoahVet\Reef\Domain\Security\Policy;

/**
 * Defines a policy that computes and syncs permission grants for a subject to the IAM.
 *
 * @template T of object
 */
interface PolicyInterface
{
    public function getName(): string;

    /**
     * Returns a stable string identifier for the subject (used as IAM "subject" key).
     *
     * @param T $subject
     *
     * @return non-empty-string
     */
    public function subjectToString(object $subject): string;

    /**
     * Returns a hash representing the current state of the subject's grants.
     * If the etag matches what the IAM has stored, the sync is skipped.
     *
     * @param T $subject
     *
     * @return non-empty-string
     */
    public function computeEtag(object $subject): string;

    /**
     * Computes the full set of permission grants for the subject.
     *
     * @param T $subject
     */
    public function apply(object $subject): PolicyResult;

    /**
     * Returns true if this policy handles the given subject type.
     *
     * @psalm-assert-if-true T $subject
     */
    public function canHandle(object $subject): bool;
}
