<?php

namespace interfaces;

use InvalidArgumentException;
use RuntimeException;

interface minio_uploads_i
{
    /**
     * Generate a pre-signed URL for uploading a file to the MinIO server.
     * @param string $objectName The name of the object in the bucket.
     * @param int $expiry The expiry time in seconds for the pre-signed URL.
     * @return string The pre-signed URL for uploading the file.
     * @note This method generates a pre-signed URL that can be used to upload a file to the specified bucket in the MinIO server.
     * @note The pre-signed URL is valid for the specified expiry time.
     * @throws InvalidArgumentException if the bucket name or object name is not valid.
     * @throws RuntimeException if the pre-signed URL generation fails.
     * @see requireValidFileName() - This method should be used to ensure that the file name is valid before proceeding with the upload.
     * @see isValidFileName() - This method should be used to check if the file name is valid before proceeding with the upload.
     * @see requireValidFilePath() - This method should be used to ensure that the file path is valid before proceeding with the upload.
     * @see isValidFilePath() - This method should be used to check if the file path is valid before proceeding with the upload.
     * @note The pre-signed URL can be used to upload files directly to the MinIO server without needing to authenticate the user.
     */
    public function generatePresignedUrl(
        string $objectName,
        int $expiry = 3600
    ): string;

    // Validation methods for file names and paths
    /**
     * Is the file name valid?
     * @param string $fileName The name of the file to validate.
     * @return bool True if the file name is valid, false otherwise.
     * @note This method checks if the file name meets the criteria for valid uploads.
     * @see requireValidFileName() - This method should be used to ensure that the file name is valid before proceeding with any operations.
     */
    public function isValidFileName(string $fileName): bool;
    /**
     * Is the file path valid?
     * @param string $filePath The path of the file to validate.
     * @return bool True if the file path is valid, false otherwise.
     * @note This method checks if the file path meets the criteria for valid uploads.
     * @see requireValidFilePath() - This method should be used to ensure that the file path is valid before proceeding with any operations.
     */
    public function isValidFilePath(string $filePath): bool;
    /**
     * Require the file name to be valid.
     * @param string $fileName The name of the file to validate.
     * @return void
     * @note This method throws an exception if the file name is not valid.
     * @throws InvalidArgumentException if the file name is not valid.
     * @throws RuntimeException if the file name is not accessible or does not exist.
     * @note This ensures that the file name meets the criteria for valid uploads.
     * @see isValidFileName() - This method should be used to check if the file name is valid before proceeding with any operations.
     */
    public function requireValidFileName(string $fileName): void;
    /**
     * Require the file path to be valid.
     * @param string $filePath The path of the file to validate.
     * @return void
     * @note This method throws an exception if the file path is not valid.
     * @note It ensures that the file path meets the criteria for valid uploads.
     * @throws InvalidArgumentException if the file path is not valid.
     * @throws RuntimeException if the file path is not accessible or does not exist.
     * @see isValidFilePath() - This method should be used to check if the file path is valid before proceeding with any operations.
     */
    public function requireValidFilePath(string $filePath): void;
}