Interface SecretsProvider

All Known Implementing Classes:
BaseSecretsProvider, InMemorySecretsProvider, SecretCache, VaultSecretsProvider

public interface SecretsProvider
Uniform secrets API shared by every secrets service (SPEC section 3). Missing secrets are Optional.empty(); require(java.lang.String, codes.grow.packages.vault.secrets.GetOptions) and delete(java.lang.String, codes.grow.packages.vault.secrets.DeleteOptions) raise NotFoundException.

Every I/O method has an …Async variant returning CompletableFuture; the defaults run the blocking method on a shared daemon executor (asyncExecutor()).

  • Field Details

  • Method Details

    • get

      Reads a secret.
      Parameters:
      name - full secret name
      opts - version / path
      Returns:
      the value, or empty when missing
    • getAll

      Map<String,SecretValue> getAll(String path)
      Returns every secret directly under path (not recursive), sorted by name.
      Parameters:
      path - folder / prefix; empty for the root
      Returns:
      full name to value
    • list

      List<SecretMetadata> list(String prefixOrPath)
      Lists secrets (names and metadata, never values) sorted by name.
      Parameters:
      prefixOrPath - prefix or folder; empty for the root
      Returns:
      the metadata
    • set

      String set(String name, Object value, SetOptions opts)
      Writes a secret. A String is stored as UTF-8, byte[] as is, SecretValue / Secret by their content, anything else JSON-encoded.
      Parameters:
      name - full secret name
      value - the value
      opts - path / cas / tags / description
      Returns:
      the new version, or "" when the service has no versions
    • delete

      void delete(String name, DeleteOptions opts)
      Deletes a secret.
      Parameters:
      name - full secret name
      opts - path / versions / permanent
      Throws:
      NotFoundException - when the secret does not exist
    • metadata

      Optional<SecretMetadata> metadata(String name, GetOptions opts)
      Reads a secret's metadata.
      Parameters:
      name - full secret name
      opts - version / path
      Returns:
      the metadata, or empty when missing
    • watch

      WatchHandle watch(String name, Duration interval, WatchListener listener, WatchOptions opts)
      Polls a secret and reports changes (version, or SHA-256 of the value when unversioned), including deletion. Errors go to WatchOptions.onError() and polling continues.
      Parameters:
      name - full secret name
      interval - polling interval
      listener - change callback
      opts - error callback
      Returns:
      the handle; close() of the provider stops every watch
    • asyncExecutor

      default Executor asyncExecutor()
      Returns the executor of the default …Async methods.
      Returns:
      a shared daemon executor
    • get

      default Optional<SecretValue> get(String name)
      Reads the latest version of a secret.
      Parameters:
      name - full secret name
      Returns:
      the value, or empty
    • getString

      default Optional<String> getString(String name, GetOptions opts)
      Reads a secret as UTF-8 text.
      Parameters:
      name - full secret name
      opts - version / path
      Returns:
      the text, or empty
      Throws:
      ValidationException - when the value is binary
    • getString

      default Optional<String> getString(String name)
      Reads a secret as UTF-8 text.
      Parameters:
      name - full secret name
      Returns:
      the text, or empty
    • getJson

      default <T> Optional<T> getJson(String name, Class<T> type, GetOptions opts)
      Reads a secret as JSON.
      Type Parameters:
      T - target type
      Parameters:
      name - full secret name
      type - target class (JsonNode.class or Object.class for any JSON)
      opts - version / path
      Returns:
      the decoded value, or empty
      Throws:
      ValidationException - when the value is not JSON
    • getJson

      default <T> Optional<T> getJson(String name, Class<T> type)
      Reads a secret as JSON.
      Type Parameters:
      T - target type
      Parameters:
      name - full secret name
      type - target class
      Returns:
      the decoded value, or empty
    • getJson

      default <T> Optional<T> getJson(String name, com.fasterxml.jackson.core.type.TypeReference<T> type, GetOptions opts)
      Reads a secret as JSON into a generic type.
      Type Parameters:
      T - target type
      Parameters:
      name - full secret name
      type - target type reference
      opts - version / path
      Returns:
      the decoded value, or empty
    • getNumber

      default Optional<Double> getNumber(String name, GetOptions opts)
      Reads a secret as a number (JSON number syntax, surrounding whitespace ignored).
      Parameters:
      name - full secret name
      opts - version / path
      Returns:
      the number, or empty
      Throws:
      ValidationException - when the value is not a number
    • getNumber

      default Optional<Double> getNumber(String name)
      Reads a secret as a number.
      Parameters:
      name - full secret name
      Returns:
      the number, or empty
    • getBool

      default Optional<Boolean> getBool(String name, GetOptions opts)
      Reads a secret as a boolean (true/false/1/0/yes/no/on/off, case-insensitive).
      Parameters:
      name - full secret name
      opts - version / path
      Returns:
      the boolean, or empty
      Throws:
      ValidationException - when the value is not a boolean
    • getBool

      default Optional<Boolean> getBool(String name)
      Reads a secret as a boolean.
      Parameters:
      name - full secret name
      Returns:
      the boolean, or empty
    • require

      default SecretValue require(String name, GetOptions opts)
      Reads a secret that must exist.
      Parameters:
      name - full secret name
      opts - version / path
      Returns:
      the value
      Throws:
      NotFoundException - when missing
    • require

      default SecretValue require(String name)
      Reads a secret that must exist.
      Parameters:
      name - full secret name
      Returns:
      the value
    • exists

      default boolean exists(String name, GetOptions opts)
      Returns whether a secret exists.
      Parameters:
      name - full secret name
      opts - version / path
      Returns:
      true when present
    • exists

      default boolean exists(String name)
      Returns whether a secret exists.
      Parameters:
      name - full secret name
      Returns:
      true when present
    • getMany

      default Map<String,SecretValue> getMany(List<String> names, GetOptions opts)
      Reads several secrets; missing names are omitted, order follows the request.
      Parameters:
      names - full secret names
      opts - version / path applied to each
      Returns:
      name to value
    • getMany

      default Map<String,SecretValue> getMany(List<String> names)
      Reads several secrets.
      Parameters:
      names - full secret names
      Returns:
      name to value
    • list

      default List<SecretMetadata> list()
      Lists every secret at the root.
      Returns:
      the metadata sorted by name
    • set

      default String set(String name, Object value)
      Writes a secret with default options.
      Parameters:
      name - full secret name
      value - the value (see set(String, Object, SetOptions))
      Returns:
      the new version or ""
    • delete

      default void delete(String name)
      Deletes a secret with default options.
      Parameters:
      name - full secret name
    • metadata

      default Optional<SecretMetadata> metadata(String name)
      Reads the latest metadata of a secret.
      Parameters:
      name - full secret name
      Returns:
      the metadata, or empty
    • loadEnv

      default Map<String,String> loadEnv(String path, LoadEnvOptions opts)
      Sets one variable per secret directly under path. Java cannot change the process environment: variables become system properties (or LoadEnvOptions.target()). The name is the secret name relative to path, upper-cased, every character outside [A-Z0-9_] replaced by _, prefixed with LoadEnvOptions.prefix().
      Parameters:
      path - folder / prefix
      opts - override / prefix / target
      Returns:
      variable name to secret name for every variable set (never values)
    • loadEnv

      default Map<String,String> loadEnv(Map<String,String> mapping, LoadEnvOptions opts)
      Sets each variable from its secret (envName → secretName).
      Parameters:
      mapping - variable name to secret name
      opts - override / target
      Returns:
      variable name to secret name for every variable set
      Throws:
      NotFoundException - when a secret is missing (nothing is set then)
    • watch

      default WatchHandle watch(String name, Duration interval, WatchListener listener)
      Polls a secret without an error callback.
      Parameters:
      name - full secret name
      interval - polling interval
      listener - change callback
      Returns:
      the handle
    • getAsync

      default CompletableFuture<Optional<SecretValue>> getAsync(String name, GetOptions opts)
      Parameters:
      name - full secret name
      opts - version / path
      Returns:
      a future with the value or empty
    • getStringAsync

      default CompletableFuture<Optional<String>> getStringAsync(String name, GetOptions opts)
      Parameters:
      name - full secret name
      opts - version / path
      Returns:
      a future with the text or empty
    • getJsonAsync

      default <T> CompletableFuture<Optional<T>> getJsonAsync(String name, Class<T> type, GetOptions opts)
      Type Parameters:
      T - target type
      Parameters:
      name - full secret name
      type - target class
      opts - version / path
      Returns:
      a future with the decoded value or empty
    • getNumberAsync

      default CompletableFuture<Optional<Double>> getNumberAsync(String name, GetOptions opts)
      Parameters:
      name - full secret name
      opts - version / path
      Returns:
      a future with the number or empty
    • getBoolAsync

      default CompletableFuture<Optional<Boolean>> getBoolAsync(String name, GetOptions opts)
      Parameters:
      name - full secret name
      opts - version / path
      Returns:
      a future with the boolean or empty
    • requireAsync

      default CompletableFuture<SecretValue> requireAsync(String name, GetOptions opts)
      Parameters:
      name - full secret name
      opts - version / path
      Returns:
      a future with the value, failed with NotFoundException when missing
    • existsAsync

      default CompletableFuture<Boolean> existsAsync(String name, GetOptions opts)
      Parameters:
      name - full secret name
      opts - version / path
      Returns:
      a future with the flag
    • getManyAsync

      default CompletableFuture<Map<String,SecretValue>> getManyAsync(List<String> names, GetOptions opts)
      Parameters:
      names - full secret names
      opts - version / path
      Returns:
      a future with the map
    • getAllAsync

      default CompletableFuture<Map<String,SecretValue>> getAllAsync(String path)
      Asynchronous getAll(String).
      Parameters:
      path - folder / prefix
      Returns:
      a future with the map
    • listAsync

      default CompletableFuture<List<SecretMetadata>> listAsync(String prefixOrPath)
      Asynchronous list(String).
      Parameters:
      prefixOrPath - prefix or folder
      Returns:
      a future with the metadata
    • setAsync

      default CompletableFuture<String> setAsync(String name, Object value, SetOptions opts)
      Parameters:
      name - full secret name
      value - the value
      opts - options
      Returns:
      a future with the new version
    • deleteAsync

      default CompletableFuture<Void> deleteAsync(String name, DeleteOptions opts)
      Parameters:
      name - full secret name
      opts - options
      Returns:
      a future completed when deleted
    • metadataAsync

      default CompletableFuture<Optional<SecretMetadata>> metadataAsync(String name, GetOptions opts)
      Parameters:
      name - full secret name
      opts - version / path
      Returns:
      a future with the metadata or empty