using System.Threading;
using System.Threading.Tasks;

namespace GB5Shared.Vault
{
    /// <summary>
    /// Reads and writes secrets in HashiCorp Vault's KV v2 engine.
    /// <para>
    /// This is the only supported way for any GB5 module to touch Vault — no module should
    /// hold its own <c>IVaultClient</c> or Vault token. Register via
    /// <see cref="VaultServiceExtensions.AddGB5Vault"/> and inject <see cref="IVaultService"/>.
    /// </para>
    /// <para>Example: <c>var password = await vaultService.GetSecretAsync("gpaypass");</c></para>
    /// </summary>
    public interface IVaultService
    {
        /// <summary>
        /// Reads the secret stored at <paramref name="key"/>. Results are cached in-process
        /// (see <see cref="VaultOptions.CacheTtlSeconds"/>) to avoid hammering Vault.
        /// </summary>
        /// <exception cref="GB5Exception.VaultOperationException">
        /// The secret does not exist, or the Vault operation failed after retries.
        /// </exception>
        Task<string> GetSecretAsync(string key, CancellationToken ct = default);

        /// <summary>
        /// Stores <paramref name="value"/> at <paramref name="key"/>, creating or updating it.
        /// </summary>
        /// <exception cref="GB5Exception.VaultOperationException">
        /// The Vault operation failed after retries.
        /// </exception>
        Task SetSecretAsync(string key, string value, CancellationToken ct = default);
    }
}