<?php

declare(strict_types=1);

namespace App\Services\Uploads;

use Carbon\CarbonImmutable;

/**
 * Issues short-lived URLs the browser can upload straight to, and answers
 * questions about what actually landed.
 *
 * Behind a contract so the flow can be tested without credentials, and so a
 * move from R2 to S3 or anywhere else is one binding.
 */
interface DirectUploadSigner
{
    public function sign(string $key, string $mime, CarbonImmutable $expiresAt): SignedUpload;

    /** Whether an object is really there. Never trust the client's word. */
    public function exists(string $key): bool;

    /** Size in bytes of a stored object, or null if it is not there. */
    public function sizeOf(string $key): ?int;

    public function delete(string $key): void;

    /** A short-lived URL for reading a private object back. */
    public function temporaryReadUrl(string $key, CarbonImmutable $expiresAt): string;

    public function disk(): string;
}
