<?php

declare(strict_types=1);

namespace App\Framework\LiveComponents\Attributes;

use Attribute;

/**
 * Action Attribute - Marks a method as a LiveComponent action
 *
 * Only methods with this attribute can be called as actions from the client.
 * This provides explicit action allow-list security.
 *
 * Usage:
 * ```php
 * final readonly class CounterComponent implements LiveComponentContract
 * {
 *     #[Action]
 *     public function increment(): ComponentData
 *     {
 *         // Action logic
 *     }
 *
 *     #[Action(description: 'Decrement counter by specified amount')]
 *     public function decrement(int $by = 1): ComponentData
 *     {
 *         // Action logic
 *     }
 *
 *     // ❌ NOT an action - cannot be called from client
 *     public function internalMethod(): void
 *     {
 *         // Internal logic
 *     }
 * }
 * ```
 *
 * Security Benefits:
 * - Explicit allow-list: Only marked methods are callable
 * - Prevents calling framework methods (getId, getData, getRenderData)
 * - Prevents calling lifecycle hooks (onMount, onUpdate, onDestroy)
 * - Makes action surface area visible
 * - Integrates with error messages (list available actions)
 */
#[Attribute(Attribute::TARGET_METHOD)]
final readonly class Action
{
    public function __construct(
        /**
         * Optional description of what this action does
         * Used for documentation and error messages
         */
        public ?string $description = null,

        /**
         * Optional rate limit for this specific action (requests per minute)
         * Overrides component-level rate limit
         */
        public ?int $rateLimit = null,

        /**
         * Optional cache TTL for idempotent actions
         * Enables automatic deduplication based on idempotency key
         */
        public ?int $idempotencyTTL = null
    ) {
    }
}
