GH-1428 Add punishment system

buildSrc/src/main/kotlin/Versions.kt

@@ -26,8 +26,6 @@ object Versions {
     const val GUAVA = "33.6.0-jre"
     const val GSON = "2.14.0"
 
-    const val EXPRESSIBLE = "1.3.6"
-    const val PANDA_UTILITIES = "0.5.3-alpha"
     const val APACHE_COMMONS = "2.22.0"
 
     const val TRIUMPH_GUI = "3.1.13"

docker-compose.yml

@@ -0,0 +1,15 @@
+services:
+  postgres:
+    image: postgres:16
+    container_name: eternalcore-postgres
+    environment:
+      POSTGRES_DB: eternalcore
+      POSTGRES_USER: eternalcore
+      POSTGRES_PASSWORD: eternalcore
+    ports:
+      - "5432:5432"
+    volumes:
+      - eternalcore-postgres-data:/var/lib/postgresql/data
+
+volumes:
+  eternalcore-postgres-data:

eternalcore-api-example/build.gradle.kts

@@ -40,7 +40,7 @@ bukkit {
 }
 
 java {
-    toolchain.languageVersion.set(JavaLanguageVersion.of(21))
+    toolchain.languageVersion.set(JavaLanguageVersion.of(25))
 }
 
 tasks.withType<JavaCompile> {

eternalcore-api/src/main/java/com/eternalcode/core/feature/punishment/Punishment.java

@@ -0,0 +1,76 @@
+package com.eternalcode.core.feature.punishment;
+
+import java.time.Instant;
+import java.util.Optional;
+import java.util.UUID;
+
+/**
+ * Common read-only view of every punishment domain (ban, ip ban, mute, warn, kick).
+ * Status is derived, never stored: see {@link PunishmentStatus#resolve(Instant, Instant, Instant)}.
+ */
+public interface Punishment {
+
+    UUID id();
+
+    PunishmentTarget target();
+
+    PunishmentTarget operator();
+
+    String reason();
+
+    Instant createdAt();
+
+    /**
+     * @return moment when punishment expires, null = permanent
+     */
+    Instant expiresAt();
+
+    /**
+     * @return revocation details, null = not revoked
+     */
+    Revocation revocation();
+
+    default Optional<Instant> expiresAtOptional() {
+        return Optional.ofNullable(this.expiresAt());
+    }
+
+    default Optional<Revocation> revocationOptional() {
+        return Optional.ofNullable(this.revocation());
+    }
+
+    default boolean isPermanent() {
+        return this.expiresAt() == null;
+    }
+
+    default PunishmentStatus status(Instant now) {
+        Revocation revocation = this.revocation();
+        Instant revokedAt = revocation == null ? null : revocation.revokedAt();
+
+        return PunishmentStatus.resolve(this.expiresAt(), revokedAt, now);
+    }
+
+    default PunishmentStatus status() {
+        return this.status(Instant.now());
+    }
+
+    default boolean isActive(Instant now) {
+        return this.status(now) == PunishmentStatus.ACTIVE;
+    }
+
+    default boolean isActive() {
+        return this.isActive(Instant.now());
+    }
+
+    /**
+     * Fail-fast validation shared by all punishment records.
+     */
+    static void validate(Instant createdAt, Instant expiresAt, Revocation revocation) {
+        if (expiresAt != null && expiresAt.isBefore(createdAt)) {
+            throw new IllegalArgumentException("expiresAt cannot be before createdAt");
+        }
+
+        if (revocation != null && revocation.revokedAt().isBefore(createdAt)) {
+            throw new IllegalArgumentException("revokedAt cannot be before createdAt");
+        }
+    }
+}

eternalcore-api/src/main/java/com/eternalcode/core/feature/punishment/PunishmentStatus.java

@@ -0,0 +1,27 @@
+package com.eternalcode.core.feature.punishment;
+
+import java.time.Instant;
+
+public enum PunishmentStatus {
+
+    ACTIVE,
+    EXPIRED,
+    REVOKED,
+    INSTANT;
+
+    public static PunishmentStatus resolve(Instant expiresAt, Instant revokedAt, Instant now) {
+        boolean revokedBeforeExpiry = revokedAt != null && (expiresAt == null || revokedAt.isBefore(expiresAt));
+
+        if (revokedBeforeExpiry) {
+            return REVOKED;
+        }
+
+        boolean expired = expiresAt != null && !now.isBefore(expiresAt);
+
+        if (expired) {
+            return EXPIRED;
+        }
+
+        return ACTIVE;
+    }
+}

eternalcore-api/src/main/java/com/eternalcode/core/feature/punishment/PunishmentTarget.java

@@ -0,0 +1,47 @@
+package com.eternalcode.core.feature.punishment;
+
+import java.util.UUID;
+import org.bukkit.OfflinePlayer;
+import org.bukkit.command.CommandSender;
+import org.bukkit.entity.Player;
+
+public record PunishmentTarget(UUID uuid, String name) {
+
+    public static final UUID CONSOLE_UUID = UUID.nameUUIDFromBytes("CONSOLE_UUID".getBytes());
+
+    public static PunishmentTarget of(OfflinePlayer player) {
+        String name = player.getName();
+
+        if (name == null) {
+            throw new IllegalArgumentException("Player " + player.getUniqueId() + " has no known name - resolve the player before punishing");
+        }
+
+        return new PunishmentTarget(player.getUniqueId(), name);
+    }
+
+    public static PunishmentTarget of(Player player) {
+        return new PunishmentTarget(player.getUniqueId(), player.getName());
+    }
+
+    public static PunishmentTarget of(CommandSender sender) {
+        if (sender instanceof Player player) {
+            return of(player);
+        }
+
+        return new PunishmentTarget(CONSOLE_UUID, sender.getName());
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj) {
+            return true;
+        }
+
+        return obj instanceof PunishmentTarget other && this.uuid.equals(other.uuid);
+    }
+
+    @Override
+    public int hashCode() {
+        return this.uuid.hashCode();
+    }
+}

eternalcore-api/src/main/java/com/eternalcode/core/feature/punishment/Revocation.java

@@ -0,0 +1,9 @@
+package com.eternalcode.core.feature.punishment;
+
+import java.time.Instant;
+
+/**
+ * Describes who and when revoked a punishment (unban, unmute, ...).
+ */
+public record Revocation(PunishmentTarget revokedBy, Instant revokedAt) {
+}

eternalcore-api/src/main/java/com/eternalcode/core/feature/punishment/ban/Ban.java

@@ -0,0 +1,33 @@
+package com.eternalcode.core.feature.punishment.ban;
+
+import com.eternalcode.core.feature.punishment.Punishment;
+import com.eternalcode.core.feature.punishment.PunishmentTarget;
+import com.eternalcode.core.feature.punishment.Revocation;
+
+import java.time.Instant;
+import java.util.UUID;
+
+/**
+ * Immutable ban of a single player account.
+ *
+ * @param expiresAt  null = permanent
+ * @param revocation null = not revoked
+ */
+public record Ban(
+    UUID id,
+    PunishmentTarget target,
+    PunishmentTarget operator,
+    String reason,
+    Instant createdAt,
+    Instant expiresAt,
+    Revocation revocation
+) implements Punishment {
+
+    public Ban {
+        Punishment.validate(createdAt, expiresAt, revocation);
+    }
+
+    public static Ban issue(PunishmentTarget target, PunishmentTarget operator, String reason, Instant expiresAt) {
+        return new Ban(UUID.randomUUID(), target, operator, reason, Instant.now(), expiresAt, null);
+    }
+}

eternalcore-api/src/main/java/com/eternalcode/core/feature/punishment/ban/BanService.java

@@ -0,0 +1,29 @@
+package com.eternalcode.core.feature.punishment.ban;
+
+import com.eternalcode.core.feature.punishment.PunishmentTarget;
+
+import net.kyori.adventure.text.Component;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+
+public interface BanService {
+
+    /**
+     * Blocking, must not be called from the main thread.
+     */
+    Ban ban(PunishmentTarget target, PunishmentTarget operator, String reason, Instant expiresAt, List<Component> kickMessage);
+
+    /**
+     * Blocking, must not be called from the main thread.
+     */
+    void unban(PunishmentTarget target, PunishmentTarget operator);
+
+    boolean isBanned(UUID targetUuid);
+
+    Optional<Ban> getActiveBan(UUID targetUuid);
+
+    List<Ban> activeBans();
+}

eternalcore-api/src/main/java/com/eternalcode/core/feature/punishment/banip/BanIp.java

@@ -0,0 +1,34 @@
+package com.eternalcode.core.feature.punishment.banip;
+
+import com.eternalcode.core.feature.punishment.Punishment;
+import com.eternalcode.core.feature.punishment.PunishmentTarget;
+import com.eternalcode.core.feature.punishment.Revocation;
+
+import java.time.Instant;
+import java.util.UUID;
+
+/**
+ * Immutable ban of an IP address. {@code target} is the player the ban was issued for.
+ *
+ * @param expiresAt  null = permanent
+ * @param revocation null = not revoked
+ */
+public record BanIp(
+    UUID id,
+    String ip,
+    PunishmentTarget target,
+    PunishmentTarget operator,
+    String reason,
+    Instant createdAt,
+    Instant expiresAt,
+    Revocation revocation
+) implements Punishment {
+
+    public BanIp {
+        Punishment.validate(createdAt, expiresAt, revocation);
+    }
+
+    public static BanIp issue(String ip, PunishmentTarget target, PunishmentTarget operator, String reason, Instant expiresAt) {
+        return new BanIp(UUID.randomUUID(), ip, target, operator, reason, Instant.now(), expiresAt, null);
+    }
+}

eternalcore-api/src/main/java/com/eternalcode/core/feature/punishment/banip/BanIpService.java

@@ -0,0 +1,26 @@
+package com.eternalcode.core.feature.punishment.banip;
+
+import com.eternalcode.core.feature.punishment.PunishmentTarget;
+
+import net.kyori.adventure.text.Component;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.Optional;
+
+public interface BanIpService {
+
+    /**
+     * Blocking, must not be called from the main thread.
+     */
+    BanIp banIp(String ip, PunishmentTarget target, PunishmentTarget operator, String reason, Instant expiresAt, List<Component> kickMessage);
+
+    /**
+     * Blocking, must not be called from the main thread.
+     */
+    void unbanIp(String ip, PunishmentTarget operator);
+
+    boolean isIpBanned(String ip);
+
+    Optional<BanIp> getActiveIpBan(String ip);
+}

eternalcore-api/src/main/java/com/eternalcode/core/feature/punishment/kick/Kick.java

@@ -0,0 +1,44 @@
+package com.eternalcode.core.feature.punishment.kick;
+
+import com.eternalcode.core.feature.punishment.Punishment;
+import com.eternalcode.core.feature.punishment.PunishmentStatus;
+import com.eternalcode.core.feature.punishment.PunishmentTarget;
+import com.eternalcode.core.feature.punishment.Revocation;
+
+import java.time.Instant;
+import java.util.UUID;
+
+/**
+ * Immutable kick. Kick is instantaneous: it never expires and cannot be revoked,
+ * its status is always {@link PunishmentStatus#INSTANT}.
+ *
+ * @param massKick true when the kick was part of /kickall
+ */
+public record Kick(
+    UUID id,
+    PunishmentTarget target,
+    PunishmentTarget operator,
+    String reason,
+    Instant createdAt,
+    boolean massKick
+) implements Punishment {
+
+    public static Kick issue(PunishmentTarget target, PunishmentTarget operator, String reason, boolean massKick) {
+        return new Kick(UUID.randomUUID(), target, operator, reason, Instant.now(), massKick);
+    }
+
+    @Override
+    public Instant expiresAt() {
+        return null;
+    }
+
+    @Override
+    public Revocation revocation() {
+        return null;
+    }
+
+    @Override
+    public PunishmentStatus status(Instant now) {
+        return PunishmentStatus.INSTANT;
+    }
+}

eternalcore-api/src/main/java/com/eternalcode/core/feature/punishment/kick/KickService.java

@@ -0,0 +1,15 @@
+package com.eternalcode.core.feature.punishment.kick;
+
+import com.eternalcode.core.feature.punishment.PunishmentTarget;
+
+import net.kyori.adventure.text.Component;
+
+import java.util.List;
+
+public interface KickService {
+
+    /**
+     * Blocking, must not be called from the main thread.
+     */
+    Kick kick(PunishmentTarget target, PunishmentTarget operator, String reason, List<Component> kickMessage, boolean massKick);
+}