v0.4.15: split per-video vs total cache cap; auto-augment legacy config

- max_preload_mb is now strictly the per-video download cap (default raised
  to 2048 MB so a single 4K short clip fits without hitting the wall).
- New max_cache_mb knob caps total client-side cache directory size
  (default 750 MB, sized for ~50 short FHD clips). Enforced cooperatively
  at start of each /videoPreload download and during the read loop so a
  late-arriving large clip can't blow past the cap.
- VideoPlayerConfig.load() now detects missing keys (max_preload_mb,
  max_cache_mb, render_distance_blocks) and rewrites the file once with
  defaults filled in, so existing servers pick up new options without
  having to delete config/video_player.json.
- CachePolicyPayload now carries (maxPerVideoBytes, maxCacheBytes,
  renderDistanceBlocks); StreamCodec order: VAR_LONG, VAR_LONG, VAR_INT.
- Client receiver wires both caps into VideoCache; chat errors distinguish
  "단일 영상 NMB 초과" vs "전체 캐시 NMB 초과".
- Add dist/ to .gitignore (release artifacts uploaded to Gitea, never
  committed).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.gitignore

@@ -1,5 +1,6 @@
 .gradle/
 build/
+dist/
 out/
 .idea/
 .vscode/

gradle.properties

@@ -5,7 +5,7 @@ org.gradle.configuration-cache=false
 
 # Mod
 mod_id=video_player
-mod_version=0.4.13
+mod_version=0.4.15
 maven_group=com.ejclaw.videoplayer
 archives_base_name=video_player
 

src/main/java/com/ejclaw/videoplayer/VideoPlayerConfig.java

@@ -49,11 +49,22 @@ public final class VideoPlayerConfig {
 
     private static final String FILE_NAME = "video_player.json";
 
-    private static final int DEFAULT_MAX_PRELOAD_MB = 1024;
+    /**
+     * Default per-video download cap in MB. Sized to allow a single 4K short clip
+     * (≈25 Mbps × 60 s ≈ 190 MB, with headroom for higher-bitrate sources). Per-video
+     * cap is intentionally separate from the total-cache cap below.
+     */
+    private static final int DEFAULT_MAX_PRELOAD_MB = 2048;
+    /**
+     * Default total-cache cap in MB. Sized to comfortably fit ~50 short FHD clips:
+     * FHD H.264 at ~5 Mbps × 20 s ≈ 12.5 MB, so 50 × 15 MB ≈ 750 MB with headroom.
+     */
+    private static final int DEFAULT_MAX_CACHE_MB = 750;
     /** Default render-distance cap for video anchors, in blocks. 128 = the legacy hard-coded value. */
     private static final int DEFAULT_RENDER_DISTANCE = 128;
 
     private static volatile int    maxPreloadMb = DEFAULT_MAX_PRELOAD_MB;
+    private static volatile int    maxCacheMb   = DEFAULT_MAX_CACHE_MB;
     private static volatile int    renderDistanceBlocks = DEFAULT_RENDER_DISTANCE;
     private static volatile List<String> preloadUrls = Collections.emptyList();
     /** Insertion-ordered name → url. Mutated only under the class monitor. */
@@ -68,6 +79,7 @@ public final class VideoPlayerConfig {
                 VideoPlayerMod.LOG.info("[{}] created default config at {}",
                     VideoPlayerMod.MOD_ID, path);
                 maxPreloadMb = DEFAULT_MAX_PRELOAD_MB;
+                maxCacheMb = DEFAULT_MAX_CACHE_MB;
                 preloadUrls = Collections.emptyList();
                 CACHE_ENTRIES.clear();
                 return;
@@ -75,21 +87,41 @@ public final class VideoPlayerConfig {
             String raw = Files.readString(path, StandardCharsets.UTF_8);
             JsonObject json = JsonParser.parseString(raw).getAsJsonObject();
 
-            // max_preload_mb (sanity-clamped to [16, 16384] so a typo can't brick a client)
+            // Track whether any expected key was missing; if so, we rewrite the file at the
+            // end so users don't have to delete their config to pick up new options.
+            boolean augmented = false;
+
+            // max_preload_mb (per-video cap, sanity-clamped to [16, 16384])
             int cap = DEFAULT_MAX_PRELOAD_MB;
             if (json.has("max_preload_mb") && json.get("max_preload_mb").isJsonPrimitive()
                     && json.get("max_preload_mb").getAsJsonPrimitive().isNumber()) {
                 cap = json.get("max_preload_mb").getAsInt();
+            } else {
+                augmented = true;
             }
             if (cap < 16) cap = 16;
             if (cap > 16384) cap = 16384;
             maxPreloadMb = cap;
 
+            // max_cache_mb (total-cache cap, sanity-clamped to [16, 65536])
+            int total = DEFAULT_MAX_CACHE_MB;
+            if (json.has("max_cache_mb") && json.get("max_cache_mb").isJsonPrimitive()
+                    && json.get("max_cache_mb").getAsJsonPrimitive().isNumber()) {
+                total = json.get("max_cache_mb").getAsInt();
+            } else {
+                augmented = true;
+            }
+            if (total < 16) total = 16;
+            if (total > 65536) total = 65536;
+            maxCacheMb = total;
+
             // render_distance_blocks (sanity-clamped to [16, 2048])
             int rd = DEFAULT_RENDER_DISTANCE;
             if (json.has("render_distance_blocks") && json.get("render_distance_blocks").isJsonPrimitive()
                     && json.get("render_distance_blocks").getAsJsonPrimitive().isNumber()) {
                 rd = json.get("render_distance_blocks").getAsInt();
+            } else {
+                augmented = true;
             }
             if (rd < 16)   rd = 16;
             if (rd > 2048) rd = 2048;
@@ -129,12 +161,23 @@ public final class VideoPlayerConfig {
             }
 
             VideoPlayerMod.LOG.info(
-                "[{}] config loaded: cap={} MB, render={} blocks, preload_urls={}, cache_entries={}",
+                "[{}] config loaded: per-video={} MB, total-cache={} MB, render={} blocks, "
-                VideoPlayerMod.MOD_ID, maxPreloadMb, renderDistanceBlocks, urls.size(), CACHE_ENTRIES.size());
+                    + "preload_urls={}, cache_entries={}",
+                VideoPlayerMod.MOD_ID, maxPreloadMb, maxCacheMb, renderDistanceBlocks,
+                urls.size(), CACHE_ENTRIES.size());
+
+            // Auto-augment: rewrite the file once so missing keys appear after a mod update.
+            if (augmented) {
+                VideoPlayerMod.LOG.info(
+                    "[{}] config missing one or more keys — rewriting with defaults filled in",
+                    VideoPlayerMod.MOD_ID);
+                save();
+            }
         } catch (Throwable t) {
             VideoPlayerMod.LOG.warn("[{}] failed to read config {}: {} — using defaults",
                 VideoPlayerMod.MOD_ID, path, t.toString());
             maxPreloadMb = DEFAULT_MAX_PRELOAD_MB;
+            maxCacheMb = DEFAULT_MAX_CACHE_MB;
             renderDistanceBlocks = DEFAULT_RENDER_DISTANCE;
             preloadUrls = Collections.emptyList();
             CACHE_ENTRIES.clear();
@@ -149,6 +192,12 @@ public final class VideoPlayerConfig {
     /** Same value in bytes. */
     public static long maxPreloadBytes() { return (long) maxPreloadMb * 1024L * 1024L; }
 
+    /** Hard cap on the client-side total cache directory, in MB. */
+    public static int maxCacheMb() { return maxCacheMb; }
+
+    /** Same value in bytes. */
+    public static long maxCacheBytes() { return (long) maxCacheMb * 1024L * 1024L; }
+
     /** Anchor BE view-distance cap, in blocks. */
     public static int renderDistanceBlocks() { return renderDistanceBlocks; }
 
@@ -198,6 +247,18 @@ public final class VideoPlayerConfig {
         return removed;
     }
 
+    /**
+     * Drop every named cache entry and return the URLs that were registered so the caller
+     * can broadcast {@code DeleteCachePayload} for each. Persists on any non-empty removal.
+     */
+    public static synchronized java.util.List<String> clearCacheEntries() {
+        if (CACHE_ENTRIES.isEmpty()) return java.util.Collections.emptyList();
+        java.util.List<String> urls = new java.util.ArrayList<>(CACHE_ENTRIES.values());
+        CACHE_ENTRIES.clear();
+        save();
+        return urls;
+    }
+
     // -- io ----------------------------------------------------------------------------------
 
     private static Path configPath() {
@@ -217,10 +278,12 @@ public final class VideoPlayerConfig {
         JsonObject root = new JsonObject();
         root.addProperty("_comment",
             "max_preload_mb: per-video download cap (each client). "
+                + "max_cache_mb: total cache directory cap (each client). "
                 + "render_distance_blocks: max distance at which a video anchor still renders. "
                 + "preload_urls: HTTP(S) videos auto-pushed to every player on join (no name). "
                 + "cache_entries: named entries managed by /videoCache add|list|remove.");
         root.addProperty("max_preload_mb", DEFAULT_MAX_PRELOAD_MB);
+        root.addProperty("max_cache_mb", DEFAULT_MAX_CACHE_MB);
         root.addProperty("render_distance_blocks", DEFAULT_RENDER_DISTANCE);
         root.add("preload_urls", new JsonArray());
         root.add("cache_entries", new JsonArray());

src/main/java/com/ejclaw/videoplayer/VideoPlayerMod.java

@@ -50,6 +50,7 @@ public class VideoPlayerMod implements ModInitializer {
             var player = handler.getPlayer();
             ServerPlayNetworking.send(player, new CachePolicyPayload(
                 VideoPlayerConfig.maxPreloadBytes(),
+                VideoPlayerConfig.maxCacheBytes(),
                 VideoPlayerConfig.renderDistanceBlocks()));
 
             int sent = 0;

src/main/java/com/ejclaw/videoplayer/client/net/ClientNetworking.java

@@ -44,10 +44,12 @@ public final class ClientNetworking {
             VideoCache.preload(payload.url());
         });
 
-        // Server tells us the per-video download cap (bytes). Must arrive before PreloadPayload
+        // Server tells us the per-video and total-cache download caps (bytes). Must arrive
-        // (the server sends policy first on JOIN), so we don't accidentally use the stale default.
+        // before PreloadPayload (server sends policy first on JOIN) so we don't use stale
+        // defaults.
         ClientPlayNetworking.registerGlobalReceiver(CachePolicyPayload.TYPE, (payload, context) -> {
-            VideoCache.setMaxBytes(payload.maxBytes());
+            VideoCache.setMaxBytes(payload.maxPerVideoBytes());
+            VideoCache.setMaxCacheBytes(payload.maxCacheBytes());
             ClientPolicy.setRenderDistanceBlocks(payload.renderDistanceBlocks());
         });
 

src/main/java/com/ejclaw/videoplayer/client/playback/VideoCache.java

@@ -42,18 +42,36 @@ public final class VideoCache {
     private static final Set<String> IN_FLIGHT = ConcurrentHashMap.newKeySet();
 
     /**
-     * Hard ceiling on a single preload, in bytes. Default 1 GB so a fresh client without a
+     * Hard ceiling on a single preload, in bytes. Default 2 GB sized to allow a single 4K
-     * policy packet (e.g. integrated server, dev test) still has a sensible cap. Overridden by
+     * short clip; overridden per-session by {@link com.ejclaw.videoplayer.net.CachePolicyPayload}
-     * {@link com.ejclaw.videoplayer.net.CachePolicyPayload} on join.
+     * on join, which carries the server's {@code max_preload_mb} config value.
      */
-    private static volatile long MAX_BYTES = 1024L * 1024 * 1024;
+    private static volatile long MAX_BYTES = 2048L * 1024 * 1024;
+
+    /**
+     * Hard ceiling on the total cache directory size, in bytes. Default 750 MB sized to fit
+     * ~50 short FHD clips; overridden per-session by {@link com.ejclaw.videoplayer.net.CachePolicyPayload}
+     * on join, which carries the server's {@code max_cache_mb} config value. Enforced
+     * cooperatively at the start of each download — running cache + new download must stay
+     * within this cap.
+     */
+    private static volatile long MAX_CACHE_BYTES = 750L * 1024 * 1024;
 
     /** Server-driven override of the per-video cap. */
     public static void setMaxBytes(long bytes) {
         if (bytes < 16L * 1024 * 1024)   bytes = 16L * 1024 * 1024;
         if (bytes > 16L * 1024 * 1024 * 1024) bytes = 16L * 1024 * 1024 * 1024;
         MAX_BYTES = bytes;
-        VideoPlayerMod.LOG.info("[{}] preload cap set to {} MB",
+        VideoPlayerMod.LOG.info("[{}] per-video preload cap set to {} MB",
+            VideoPlayerMod.MOD_ID, bytes / (1024 * 1024));
+    }
+
+    /** Server-driven override of the total-cache cap. */
+    public static void setMaxCacheBytes(long bytes) {
+        if (bytes < 16L * 1024 * 1024)   bytes = 16L * 1024 * 1024;
+        if (bytes > 64L * 1024 * 1024 * 1024) bytes = 64L * 1024 * 1024 * 1024;
+        MAX_CACHE_BYTES = bytes;
+        VideoPlayerMod.LOG.info("[{}] total-cache cap set to {} MB",
             VideoPlayerMod.MOD_ID, bytes / (1024 * 1024));
     }
 
@@ -151,6 +169,22 @@ public final class VideoCache {
                 return;
             }
 
+            // Total-cache check: refuse to start if the cache directory is already at the cap.
+            // We re-check during the read loop too, since other downloads may be in flight in
+            // parallel. {@code existingCacheBytes} excludes our own .part (which we just wrote 0
+            // bytes to / haven't created yet).
+            long existingCacheBytes = cacheDirSize(cacheDir, partPath);
+            if (existingCacheBytes >= MAX_CACHE_BYTES) {
+                long capMb = MAX_CACHE_BYTES / (1024 * 1024);
+                long usedMb = existingCacheBytes / (1024 * 1024);
+                VideoPlayerMod.LOG.warn(
+                    "[{}] preload: total-cache cap reached ({}/{} MB); aborting {}",
+                    VideoPlayerMod.MOD_ID, usedMb, capMb, url);
+                notifyChat("[videopreload] 실패 (전체 캐시 " + capMb + "MB 초과 / 현재 "
+                    + usedMb + "MB): " + url, ChatFormatting.RED);
+                return;
+            }
+
             URLConnection raw = URI.create(url).toURL().openConnection();
             raw.setConnectTimeout(10_000);
             raw.setReadTimeout(30_000);
@@ -176,10 +210,22 @@ public final class VideoCache {
                     if (total > MAX_BYTES) {
                         long capMb = MAX_BYTES / (1024 * 1024);
                         VideoPlayerMod.LOG.warn(
-                            "[{}] preload: {} exceeded {} MB cap; aborting",
+                            "[{}] preload: {} exceeded per-video {} MB cap; aborting",
                             VideoPlayerMod.MOD_ID, url, capMb);
                         try { Files.deleteIfExists(partPath); } catch (Throwable ignored) {}
-                        notifyChat("[videopreload] 실패 (" + capMb + "MB 초과): " + url, ChatFormatting.RED);
+                        notifyChat("[videopreload] 실패 (단일 영상 " + capMb + "MB 초과): " + url,
+                            ChatFormatting.RED);
+                        return;
+                    }
+                    if (existingCacheBytes + total > MAX_CACHE_BYTES) {
+                        long capMb = MAX_CACHE_BYTES / (1024 * 1024);
+                        long usedMb = (existingCacheBytes + total) / (1024 * 1024);
+                        VideoPlayerMod.LOG.warn(
+                            "[{}] preload: total-cache cap exceeded ({}>{} MB); aborting {}",
+                            VideoPlayerMod.MOD_ID, usedMb, capMb, url);
+                        try { Files.deleteIfExists(partPath); } catch (Throwable ignored) {}
+                        notifyChat("[videopreload] 실패 (전체 캐시 " + capMb + "MB 초과): " + url,
+                            ChatFormatting.RED);
                         return;
                     }
                     out.write(buf, 0, n);
@@ -213,6 +259,32 @@ public final class VideoCache {
         });
     }
 
+    /**
+     * Sum of regular-file sizes under {@code dir}, skipping {@code excludePart} (the .part file
+     * for the in-flight download — we account for that via the running {@code total} counter).
+     * Best-effort: errors collapse to 0 so a transient FS hiccup doesn't strand a download.
+     */
+    private static long cacheDirSize(Path dir, Path excludePart) {
+        if (dir == null) return 0L;
+        try {
+            if (!Files.isDirectory(dir)) return 0L;
+            final long[] sum = { 0L };
+            try (var stream = Files.newDirectoryStream(dir)) {
+                for (Path p : stream) {
+                    if (excludePart != null && p.equals(excludePart)) continue;
+                    try {
+                        if (Files.isRegularFile(p)) sum[0] += Files.size(p);
+                    } catch (Throwable ignored) {}
+                }
+            }
+            return sum[0];
+        } catch (Throwable t) {
+            VideoPlayerMod.LOG.warn("[{}] cacheDirSize failed: {}",
+                VideoPlayerMod.MOD_ID, t.toString());
+            return 0L;
+        }
+    }
+
     private static Path cacheDir() {
         Minecraft mc = Minecraft.getInstance();
         if (mc == null || mc.gameDirectory == null) return null;

src/main/java/com/ejclaw/videoplayer/command/VideoCacheCommand.java

@@ -52,7 +52,9 @@ public final class VideoCacheCommand {
                 .executes(VideoCacheCommand::runList))
             .then(Commands.literal("remove")
                 .then(Commands.argument("name", StringArgumentType.word())
-                    .executes(VideoCacheCommand::runRemove)));
+                    .executes(VideoCacheCommand::runRemove)))
+            .then(Commands.literal("clear")
+                .executes(VideoCacheCommand::runClear));
     }
 
     private static int runAdd(CommandContext<CommandSourceStack> ctx) throws CommandSyntaxException {
@@ -123,6 +125,30 @@ public final class VideoCacheCommand {
         return entries.size();
     }
 
+    private static int runClear(CommandContext<CommandSourceStack> ctx) {
+        CommandSourceStack src = ctx.getSource();
+        java.util.List<String> urls = VideoPlayerConfig.clearCacheEntries();
+        if (urls.isEmpty()) {
+            src.sendSuccess(() -> Component.literal("[videocache] 저장된 항목이 없습니다")
+                .withStyle(ChatFormatting.GRAY), false);
+            return 0;
+        }
+        MinecraftServer server = src.getServer();
+        int clients = 0;
+        for (ServerPlayer p : PlayerLookup.all(server)) {
+            for (String url : urls) {
+                ServerPlayNetworking.send(p, new DeleteCachePayload(url));
+            }
+            clients++;
+        }
+        final int sentFinal = clients;
+        final int countFinal = urls.size();
+        src.sendSuccess(() -> Component.literal(
+            "[videocache] 전체 삭제: " + countFinal + "개 항목"
+                + "  (" + sentFinal + " 클라이언트에 cache_delete 전송)"), false);
+        return countFinal;
+    }
+
     private static int runRemove(CommandContext<CommandSourceStack> ctx) throws CommandSyntaxException {
         CommandSourceStack src = ctx.getSource();
         String name = StringArgumentType.getString(ctx, "name").trim();

src/main/java/com/ejclaw/videoplayer/net/CachePolicyPayload.java

@@ -9,15 +9,18 @@ import net.minecraft.resources.Identifier;
 
 /**
  * S2C — broadcasts the server-configured client-side policy bundle on join, before any
- * {@link PreloadPayload}. Currently carries: {@code maxBytes} (per-video download cap) and
+ * {@link PreloadPayload}. Carries: {@code maxPerVideoBytes} (per-video download cap),
- * {@code renderDistanceBlocks} (anchor BE view-distance cap).
+ * {@code maxCacheBytes} (total-cache directory cap), and {@code renderDistanceBlocks}
+ * (anchor BE view-distance cap).
  */
-public record CachePolicyPayload(long maxBytes, int renderDistanceBlocks) implements CustomPacketPayload {
+public record CachePolicyPayload(long maxPerVideoBytes, long maxCacheBytes, int renderDistanceBlocks)
+        implements CustomPacketPayload {
     public static final CustomPacketPayload.Type<CachePolicyPayload> TYPE =
         new CustomPacketPayload.Type<>(Identifier.fromNamespaceAndPath(VideoPlayerMod.MOD_ID, "cache_policy"));
 
     public static final StreamCodec<RegistryFriendlyByteBuf, CachePolicyPayload> CODEC = StreamCodec.composite(
-        ByteBufCodecs.VAR_LONG, CachePolicyPayload::maxBytes,
+        ByteBufCodecs.VAR_LONG, CachePolicyPayload::maxPerVideoBytes,
+        ByteBufCodecs.VAR_LONG, CachePolicyPayload::maxCacheBytes,
         ByteBufCodecs.VAR_INT,  CachePolicyPayload::renderDistanceBlocks,
         CachePolicyPayload::new
     );