Add PostNetworkSyncEvent

api/src/main/java/net/luckperms/api/event/log/LogReceiveEvent.java

@@ -33,7 +33,11 @@ import org.checkerframework.checker.nullness.qual.NonNull;
 import java.util.UUID;
 
 /**
- * Called when a log entry is received via the MessagingService
+ * Called when a log entry is received via the MessagingService.
+ *
+ * <p>Note: listening to this event is the same as listening to the {@link LogBroadcastEvent}
+ * and filtering for {@link LogBroadcastEvent#getOrigin() origin} =
+ * {@link net.luckperms.api.event.log.LogBroadcastEvent.Origin#REMOTE REMOTE}.</p>
  */
 public interface LogReceiveEvent extends LuckPermsEvent {
 

api/src/main/java/net/luckperms/api/event/sync/PostNetworkSyncEvent.java

@@ -0,0 +1,82 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  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 net.luckperms.api.event.sync;
+
+import net.luckperms.api.event.LuckPermsEvent;
+import net.luckperms.api.event.type.Cancellable;
+import net.luckperms.api.event.util.Param;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+import java.util.UUID;
+
+/**
+ * Called after a network synchronisation task has been completed.
+ *
+ * <p>Note: the generic {@link PostSyncEvent} will also be called for {@link SyncType#FULL full syncs}.</p>
+ *
+ * @since 5.5
+ */
+public interface PostNetworkSyncEvent extends LuckPermsEvent {
+
+    /**
+     * Gets the ID of the sync request
+     *
+     * @return the id of the sync request
+     */
+    @Param(0)
+    @NonNull UUID getSyncId();
+
+    /**
+     * Gets the sync type.
+     *
+     * @return the sync type
+     */
+    @Param(1)
+    @NonNull SyncType getType();
+
+    /**
+     * Gets if a sync occurred.
+     *
+     * <p>For {@link SyncType} = {@link SyncType#FULL FULL}, this method always returns true.</p>
+     *
+     * <p>For {@link SyncType} = {@link SyncType#SPECIFIC_USER SPECIFIC_USER}, this method returns true if the
+     * user in question was online/loaded in memory at the time, and false otherwise.</p>
+     *
+     * @return if a sync occurred
+     */
+    @Param(2)
+    boolean didSyncOccur();
+
+    /**
+     * Gets the unique id of the specific user that has been synced, if applicable.
+     *
+     * @return the unique id of the specific user
+     */
+    @Param(3)
+    @Nullable UUID getSpecificUserUniqueId();
+
+}

api/src/main/java/net/luckperms/api/event/sync/PostSyncEvent.java

@@ -28,7 +28,10 @@ package net.luckperms.api.event.sync;
 import net.luckperms.api.event.LuckPermsEvent;
 
 /**
- * Called when an sync task has been completed
+ * Called after a full synchronisation task has been completed.
+ *
+ * <p>Note: this event is also called after synchronisations that were triggered over the network.
+ * In other words, this event will be called in addition to {@link PostNetworkSyncEvent}.</p>
  */
 public interface PostSyncEvent extends LuckPermsEvent {
 

api/src/main/java/net/luckperms/api/event/sync/PreNetworkSyncEvent.java

@@ -29,11 +29,15 @@ import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.type.Cancellable;
 import net.luckperms.api.event.util.Param;
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
 
 import java.util.UUID;
 
 /**
- * Called before a received network sync task runs
+ * Called after a request for synchronisation has been received via the messaging service,
+ * but before it has actually been completed.
+ *
+ * <p>Note: the generic {@link PreSyncEvent} will also be called for {@link SyncType#FULL full syncs}.</p>
  */
 public interface PreNetworkSyncEvent extends LuckPermsEvent, Cancellable {
 
@@ -45,4 +49,22 @@ public interface PreNetworkSyncEvent extends LuckPermsEvent, Cancellable {
     @Param(0)
     @NonNull UUID getSyncId();
 
+    /**
+     * Gets the sync type.
+     *
+     * @return the sync type
+     * @since 5.5
+     */
+    @Param(1)
+    @NonNull SyncType getType();
+
+    /**
+     * Gets the unique id of the specific user that will be synced, if applicable.
+     *
+     * @return the unique id of the specific user
+     * @since 5.5
+     */
+    @Param(2)
+    @Nullable UUID getSpecificUserUniqueId();
+
 }

api/src/main/java/net/luckperms/api/event/sync/PreSyncEvent.java

@@ -29,7 +29,10 @@ import net.luckperms.api.event.LuckPermsEvent;
 import net.luckperms.api.event.type.Cancellable;
 
 /**
- * Called before a sync task runs
+ * Called just before a full synchronisation task runs.
+ *
+ * <p>Note: this event is also called before synchronisations that were triggered over the network.
+ * In other words, this event will be called in addition to {@link PreNetworkSyncEvent}.</p>
  */
 public interface PreSyncEvent extends LuckPermsEvent, Cancellable {
 

api/src/main/java/net/luckperms/api/event/sync/SyncType.java

@@ -0,0 +1,45 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  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 net.luckperms.api.event.sync;
+
+/**
+ * Represents the type of synchronisation task.
+ *
+ * @since 5.5
+ */
+public enum SyncType {
+
+    /**
+     * A full sync will be performed - all groups, users and tracks
+     */
+    FULL,
+
+    /**
+     * Only a specific user will be synced
+     */
+    SPECIFIC_USER
+
+}