Add options lookups for offline players

USAGE.md

@@ -125,6 +125,21 @@ Optional<Integer> value = Options.get(source, "balance", Integer::parseInt);
 int value = Options.get(source, "balance", 0, Integer::parseInt);
 ```
 
+#### Getting options for a (potentially) offline player
+Option requests for offline players can be made using the players unique id (UUID). The result is returned as a [CompletableFuture](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/CompletableFuture.html).
+```java
+UUID uuid = ...;
+Options.get(uuid, "prefix").thenAcceptAsync(prefix -> {
+    // Do something with the result
+});
+```
+
+To simplify checks **not** made on the server thread, you can use `join()`.
+```java
+UUID uuid = ...;
+Optional<String> prefix = Options.get(uuid, "prefix").join();
+```
+
 ## Usage (providing permissions)
 
 Just register a listener for the `PermissionCheckEvent`.
@@ -138,12 +153,16 @@ PermissionCheckEvent.EVENT.register((source, permission) -> {
 });
 ```
 
+If your plugin also supports lookups for offline players, register a listener for the `OfflinePermissionCheckEvent`.
+
 ```java
 OfflinePermissionCheckEvent.EVENT.register((uuid, permission) -> {
-    if (isSuperAdmin(uuid)) {
-        return CompletableFuture.completedFuture(TriState.TRUE);
-    }
-    return CompletableFuture.completedFuture(TriState.DEFAULT);
+    return CompletableFuture.supplyAsync(() -> {
+        if (isSuperAdmin(uuid)) {
+            return TriState.TRUE;
+        }
+        return TriState.DEFAULT;
+    });
 });
 ```
 
@@ -159,3 +178,16 @@ OptionRequestEvent.EVENT.register((source, key) -> {
     return Optional.empty();
 });
 ```
+
+If your plugin also supports lookups for offline players, register a listener for the `OfflineOptionRequestEvent`.
+
+```java
+OfflineOptionRequestEvent.EVENT.register((uuid, key) -> {
+    if (key.equals("balance")) {
+        return CompletableFuture.supplyAsync(() -> {
+            return Optional.of(getPlayerBalance(uuid).toString());
+        });
+    }
+    return CompletableFuture.completedFuture(Optional.empty());
+});
+```

src/main/java/me/lucko/fabric/api/permissions/v0/OfflineOptionRequestEvent.java

@@ -0,0 +1,57 @@
+/*
+ * This file is part of fabric-permissions-api, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <[email protected]>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package me.lucko.fabric.api.permissions.v0;
+
+import net.fabricmc.fabric.api.event.Event;
+import net.fabricmc.fabric.api.event.EventFactory;
+import net.fabricmc.fabric.api.util.TriState;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.Optional;
+import java.util.UUID;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Simple option request event for (potentially) offline players.
+ */
+public interface OfflineOptionRequestEvent {
+
+    Event<OfflineOptionRequestEvent> EVENT = EventFactory.createArrayBacked(OfflineOptionRequestEvent.class, (callbacks) -> (uuid, key) -> {
+        CompletableFuture<Optional<String>> res = CompletableFuture.completedFuture(null);
+        for (OfflineOptionRequestEvent callback : callbacks) {
+            res = res.thenCompose(value -> {
+                if (value.isPresent()) {
+                    return CompletableFuture.completedFuture(value);
+                }
+                return callback.onOptionRequest(uuid, key);
+            });
+        }
+        return res;
+    });
+
+    @NotNull CompletableFuture<Optional<String>> onOptionRequest(@NotNull UUID uuid, @NotNull String key);
+
+}

src/main/java/me/lucko/fabric/api/permissions/v0/Options.java

@@ -25,6 +25,7 @@
 
 package me.lucko.fabric.api.permissions.v0;
 
+import com.mojang.authlib.GameProfile;
 import net.minecraft.command.CommandSource;
 import net.minecraft.entity.Entity;
 
@@ -33,6 +34,8 @@
 
 import java.util.Objects;
 import java.util.Optional;
+import java.util.UUID;
+import java.util.concurrent.CompletableFuture;
 import java.util.function.Function;
 
 /**
@@ -203,5 +206,169 @@ static <T> T get(@NotNull Entity entity, @NotNull String key, T defaultValue, @N
         Objects.requireNonNull(entity, "entity");
         return get(entity.getCommandSource(), key, defaultValue, valueTransformer);
     }
+
+    /**
+     * Gets the value of an option for the given (potentially) offline player.
+     *
+     * @param uuid the uuid of the player
+     * @param key the option key
+     * @return the option value
+     */
+    static @NotNull CompletableFuture<Optional<String>> get(@NotNull UUID uuid, @NotNull String key) {
+        Objects.requireNonNull(uuid, "uuid");
+        Objects.requireNonNull(key, "key");
+        return OfflineOptionRequestEvent.EVENT.invoker().onOptionRequest(uuid, key);
+    }
+
+    /**
+     * Gets the value of an option for the given player, falling back to the {@code defaultValue}
+     * if nothing is returned from the provider.
+     *
+     * @param uuid the uuid of the player
+     * @param key the option key
+     * @param defaultValue the default value to use if nothing is returned
+     * @return the option value
+     */
+    @Contract("_, _, !null -> !null")
+    static CompletableFuture<String> get(@NotNull UUID uuid, @NotNull String key, String defaultValue) {
+        return get(uuid, key).thenApply(opt -> opt.orElse(defaultValue));
+    }
+
+    /**
+     * Gets the value of an option for the given player, and runs it through the given {@code valueTransformer}.
+     *
+     * <p>If nothing is returned from the provider, an {@link Optional#empty() empty optional} is returned.
+     * (the transformer will never be passed a null argument)</p>
+     *
+     * <p>The transformer is allowed to throw {@link IllegalArgumentException} or return null. This
+     * will also result in an {@link Optional#empty() empty optional} being returned.</p>
+     *
+     * <p>For example, to parse and return an integer meta value, use:</p>
+     * <p><blockquote><pre>
+     *     get(uuid, "my-int-value", Integer::parseInt).orElse(0);
+     * </pre></blockquote>
+     *
+     * @param uuid the uuid of the player
+     * @param key the option key
+     * @param valueTransformer the transformer used to transform the value
+     * @param <T> the type of the transformed result
+     * @return the transformed option value
+     */
+    static <T> @NotNull CompletableFuture<Optional<T>> get(@NotNull UUID uuid, @NotNull String key, @NotNull Function<String, ? extends T> valueTransformer) {
+        return get(uuid, key).thenApply(opt -> opt.flatMap(value -> {
+            try {
+                return Optional.ofNullable(valueTransformer.apply(value));
+            } catch (IllegalArgumentException e) {
+                return Optional.empty();
+            }
+        }));
+    }
+
+    /**
+     * Gets the value of an option for the given player, runs it through the given {@code valueTransformer},
+     * and falls back to the {@code defaultValue} if nothing is returned.
+     *
+     * <p>If nothing is returned from the provider, the {@code defaultValue} is returned.
+     * (the transformer will never be passed a null argument)</p>
+     *
+     * <p>The transformer is allowed to throw {@link IllegalArgumentException} or return null. This
+     * will also result in the {@code defaultValue} being returned.</p>
+     *
+     * <p>For example, to parse and return an integer meta value, use:</p>
+     * <p><blockquote><pre>
+     *     get(uuid, "my-int-value", 0, Integer::parseInt);
+     * </pre></blockquote>
+     *
+     * @param uuid the uuid of the player
+     * @param key the option key
+     * @param defaultValue the default value
+     * @param valueTransformer the transformer used to transform the value
+     * @param <T> the type of the transformed result
+     * @return the transformed option value
+     */
+    @Contract("_, _, !null, _ -> !null")
+    static <T> CompletableFuture<T> get(@NotNull UUID uuid, @NotNull String key, T defaultValue, @NotNull Function<String, ? extends T> valueTransformer) {
+        return Options.<T>get(uuid, key, valueTransformer).thenApply(opt -> opt.orElse(defaultValue));
+    }
+
+    /**
+     * Gets the value of an option for the given (potentially) offline player.
+     *
+     * @param profile the player profile
+     * @param key the option key
+     * @return the option value
+     */
+    static @NotNull CompletableFuture<Optional<String>> get(@NotNull GameProfile profile, @NotNull String key) {
+        Objects.requireNonNull(profile, "profile");
+        return get(profile.getId(), key);
+    }
+
+    /**
+     * Gets the value of an option for the given player, falling back to the {@code defaultValue}
+     * if nothing is returned from the provider.
+     *
+     * @param profile the player profile
+     * @param key the option key
+     * @param defaultValue the default value to use if nothing is returned
+     * @return the option value
+     */
+    @Contract("_, _, !null -> !null")
+    static CompletableFuture<String> get(@NotNull GameProfile profile, @NotNull String key, String defaultValue) {
+        Objects.requireNonNull(profile, "profile");
+        return get(profile.getId(), key, defaultValue);
+    }
+
+    /**
+     * Gets the value of an option for the given player, and runs it through the given {@code valueTransformer}.
+     *
+     * <p>If nothing is returned from the provider, an {@link Optional#empty() empty optional} is returned.
+     * (the transformer will never be passed a null argument)</p>
+     *
+     * <p>The transformer is allowed to throw {@link IllegalArgumentException} or return null. This
+     * will also result in an {@link Optional#empty() empty optional} being returned.</p>
+     *
+     * <p>For example, to parse and return an integer meta value, use:</p>
+     * <p><blockquote><pre>
+     *     get(uuid, "my-int-value", Integer::parseInt).orElse(0);
+     * </pre></blockquote>
+     *
+     * @param profile the player profile
+     * @param key the option key
+     * @param valueTransformer the transformer used to transform the value
+     * @param <T> the type of the transformed result
+     * @return the transformed option value
+     */
+    static <T> @NotNull CompletableFuture<Optional<T>> get(@NotNull GameProfile profile, @NotNull String key, @NotNull Function<String, ? extends T> valueTransformer) {
+        Objects.requireNonNull(profile, "profile");
+        return get(profile.getId(), key, valueTransformer);
+    }
+
+    /**
+     * Gets the value of an option for the given player, runs it through the given {@code valueTransformer},
+     * and falls back to the {@code defaultValue} if nothing is returned.
+     *
+     * <p>If nothing is returned from the provider, the {@code defaultValue} is returned.
+     * (the transformer will never be passed a null argument)</p>
+     *
+     * <p>The transformer is allowed to throw {@link IllegalArgumentException} or return null. This
+     * will also result in the {@code defaultValue} being returned.</p>
+     *
+     * <p>For example, to parse and return an integer meta value, use:</p>
+     * <p><blockquote><pre>
+     *     get(uuid, "my-int-value", 0, Integer::parseInt);
+     * </pre></blockquote>
+     *
+     * @param profile the player profile
+     * @param key the option key
+     * @param defaultValue the default value
+     * @param valueTransformer the transformer used to transform the value
+     * @param <T> the type of the transformed result
+     * @return the transformed option value
+     */
+    @Contract("_, _, !null, _ -> !null")
+    static <T> CompletableFuture<T> get(@NotNull GameProfile profile, @NotNull String key, T defaultValue, @NotNull Function<String, ? extends T> valueTransformer) {
+        Objects.requireNonNull(profile, "profile");
+        return get(profile.getId(), key, defaultValue, valueTransformer);
+    }
 
 }

src/main/java/me/lucko/fabric/api/permissions/v0/Permissions.java

@@ -191,7 +191,7 @@ static boolean check(@NotNull Entity entity, @NotNull String permission) {
     /**
      * Gets the {@link TriState state} of a {@code permission} for the given (potentially) offline player.
      *
-     * @param uuid the player uuid
+     * @param uuid the uuid of the player
      * @param permission the permission
      * @return the state of the permission
      */
@@ -205,7 +205,7 @@ static boolean check(@NotNull Entity entity, @NotNull String permission) {
      * Performs a permission check, falling back to the {@code defaultValue} if the resultant
      * state is {@link TriState#DEFAULT}.
      *
-     * @param uuid the player to perform the check for
+     * @param uuid the uuid of the player to perform the check for
      * @param permission the permission to check
      * @param defaultValue the default value to use if nothing has been set
      * @return the result of the permission check
@@ -218,7 +218,7 @@ static CompletableFuture<Boolean> check(@NotNull UUID uuid, @NotNull String perm
      * Performs a permission check, falling back to {@code false} if the resultant state
      * is {@link TriState#DEFAULT}.
      *
-     * @param uuid the source to perform the check for
+     * @param uuid the uuid of the player to perform the check for
      * @param permission the permission to check
      * @return the result of the permission check
      */