stage2/lw: Abstract away from always installing Essential

(Note that all changes talked about in this commit only apply to
EssentialLoader for LaunchWrapper. Not to EssentialLoader for
ModLauncher or Fabric, those continue operating as they used to.)

This commit rewrites most of Essential Loader for LaunchWrapper to no
longer always implicitly install Essential and instead provide a more
general dependency loading/negotiating mechanism (similar to
fabric-loader's Jar-in-Jar mechanism) useable by third-party mods via a
`essential.mod.json` metadata file.

To this end, this commit practically removes stage1 on LaunchWrapper
because stage1 necessarily interacts with Essential infra to
download/update stage2 and with the Essential mod to ask the user for
permission to do so.
Instead stage2 now has a self-update mechanism where if it finds a more
recent stage2 in any of the discovered jars (e.g. the downloaded
Essential jar), it will re-launch into that newer stage2.
Additionally, this also removes the concept of a pinned stage2 and
instead always includes the stage2 jar inside the stage1 jar. This also
allows using the existing stage1 update mechansim (dropping a file in a
specific location) to permanently update stage1 and therefore stage2 to
a new version on next boot (e.g. if we want to update the Downloading
gui).

To support Essential's auto-updating feature (as well as similar
third-party ones), in addition to plain inner jars, the
`essenital.mod.json` metadata file also supports loading a specific
class from the jar to generate additional dependency specifications.
This class can then e.g. download a newer version of the mod and emit a
dependency specification which points at it.

Author: Johni0702

.github/workflows/publish-stage2.yml

@@ -20,7 +20,7 @@ jobs:
             17
 
       - name: Build
-        run: ./gradlew :stage2:{launchwrapper,fabric,modlauncher{8,9}}:build --stacktrace
+        run: ./gradlew :stage2:{launchwrapper-legacy,fabric,modlauncher{8,9}}:build --stacktrace
 
       - name: Upload Artifacts
         uses: actions/upload-artifact@v4

docs/container-mods.md

@@ -109,6 +109,8 @@ overridePinnedVersion=1.2.0.12
 ## Pinning stage2
 
 Stage2 can be pinned as well.
+(But only on Fabric and ModLauncher. On LaunchWrapper the stage2 jar is already included in the stage1 jar and cannot
+be updated independently.)
 
 Instead of an `essential-loader.properties` file at the root of the container mod, the file must be placed at
 `gg/essential/loader/stage1/stage2.properties`.

docs/stages.md

@@ -74,18 +74,10 @@ download fails (assuming the host mod has no hard dependency on Essential).
 
 ### LaunchWrapper
 
-On LaunchWrapper, it additionally:
-- instructs Forge to scan the host mod jar for regular mods (ordinarily Forge would not check for mods in a jar that
-  already contained a Tweaker).
-- if the jar declares a CoreMod, loads it (Forge will not load CoreMods from jars that already contained a Tweaker)
-- chain load the Mixin Tweaker if the host mod declares a `MixinConfigs` attribute and the Mixin Tweaker is not yet
-  loaded or scheduled (you can only have one Tweaker declared, you can't have Mixin and Essential Tweaker, so we load
-  the Mixin one for you if you need it)
-- load the host mod's declared mixin configs (Mixin only automatically loads these for mods declaring the Mixin Tweaker)
-
-Stage1 on LaunchWrapper currently does not need to ensure that only a single instance of stage2 is loaded because stage0
-actually puts it in the Launch class loader rather than its own isolated class loader for legacy reasons.
-So all stage0 instances are talking to the same stage1 class and a simple static field is enough to ensure uniqueness.
+On LaunchWrapper, it is even simpler: The stage2 jar file is embedded in the stage1 jar file, so stage1 simply extracts
+that (no update checks, downloads, or anything), and then jumps to it like stage0 did.
+
+Stage1 used to do a lot more on LaunchWrapper, but all this functionality has since been moved to stage2.
 
 ### Fabric
 

integrationTest/launchwrapper/build.gradle

@@ -133,11 +133,15 @@ def includeMixin(AbstractArchiveTask task, Configuration mixin) {
     }
 }
 
-def configureExampleModJar = { String tweaker, Configuration mixin = null -> return { AbstractArchiveTask task ->
+def configureExampleModJar = { String tweaker, Configuration mixin = null, excludes = null -> return { AbstractArchiveTask task ->
     archiveBaseName.set(task.name)
     from(sourceSets.exampleMod.output)
     dependsOn(configurations.exampleModRuntimeClasspath)
-    from({ configurations.exampleModRuntimeClasspath.collect { zipTree(it) } })
+    from({ configurations.exampleModRuntimeClasspath.collect { zipTree(it) } }) {
+        if (excludes != null) {
+            excludes()
+        }
+    }
 
     manifest {
         attributes "FMLCorePlugin": "com.example.mod.ExampleCoreMod",
@@ -203,39 +207,49 @@ tasks.register("exampleRelocatedModJar", com.github.jengelman.gradle.plugins.sha
     def stage2Task = tasks.register("stage2V${i}Jar", Jar) {
         archiveBaseName.set(name)
         from(evaluationDependsOn(':stage2:launchwrapper').tasks.jar.archiveFile.map { zipTree(it) })
-        // Dummy attribute so they all have different hashes
         manifest {
+            attributes "Name": "gg/essential/loader/stage2/"
             attributes "Implementation-Version": "$i"
         }
     }
+    def stage1Task = tasks.register("stage1V${i}Jar", Jar) {
+        archiveBaseName.set(name)
+        from(evaluationDependsOn(':stage1:launchwrapper').tasks.jar.archiveFile.map { zipTree(it) }) {
+            exclude("gg/essential/loader/stage1/stage2.jar")
+        }
+        from(stage2Task.flatMap { it.archiveFile }) {
+            into("gg/essential/loader/stage1")
+            rename { "stage2.jar" }
+        }
+        manifest {
+            attributes("Name": "gg/essential/loader/stage1/")
+            attributes "Implementation-Version": "${i}"
+        }
+    }
     def stage3Task = tasks.register("stage3V${i}Jar", Jar) {
         archiveBaseName.set(name)
         from(tasks.essentialJar.archiveFile.map { zipTree(it) })
-        manifest {
-            // Dummy attribute so they all have different hashes
-            attributes "Implementation-Version": "$i"
-            // For stage3 version 4+, we add an explicit requirement on stage2 version 4
-            if (i >= 4) {
-                attributes "Requires-Essential-Stage2-Version": "4"
-            }
+        from(stage1Task.flatMap { it.archiveFile }) {
+            into("gg/essential/loader/stage0")
+            rename { "stage1.jar" }
         }
     }
     tasks.register("exampleBundledModJar$i", Jar) {
-        def configure = configureExampleModJar("com.example.mod.tweaker.ExampleModTweaker")
+        def configure = configureExampleModJar("com.example.mod.tweaker.ExampleModTweaker", null, {
+            exclude("gg/essential/loader/stage0/stage1.jar")
+        })
         configure.delegate = delegate
         configure(it)
 
-        def stage2Jar = stage2Task.get().archiveFile
-        def stage3Jar = stage3Task.get().archiveFile
-        from(stage2Jar) {
-            rename { "bundled-stage2-${i}.jar" }
+        from(stage1Task.flatMap { it.archiveFile }) {
+            into("gg/essential/loader/stage0")
+            rename { "stage1.jar" }
         }
+
+        def stage3Jar = stage3Task.get().archiveFile
         from(stage3Jar) {
             rename { "bundled-essential-${i}.jar" }
         }
-        from(file("../essential-loader-stage2.properties")) {
-            expand(["pinnedFileMd5": { stage2Jar.get().asFile.bytes.md5() }, version: i])
-        }
         from(file("../essential-loader.properties")) {
             expand(["pinnedFileMd5": { stage3Jar.get().asFile.bytes.md5() }, "version": i])
         }

integrationTest/launchwrapper/src/main/java/gg/essential/loader/stage1/Stage1DevEnvTests.java

@@ -16,6 +16,7 @@ private IsolatedLaunch newDevLaunch(Installation installation) throws Exception
         isolatedLaunch.addToClasspath(Paths.get("build", "classes", "java", "exampleMod").toUri().toURL());
         isolatedLaunch.addArg("--tweakClass", "gg.essential.loader.stage0.EssentialSetupTweaker");
         isolatedLaunch.setProperty("fml.coreMods.load", "com.example.mod.ExampleCoreMod");
+        isolatedLaunch.setProperty("essential.loader.installEssentialMod", "true");
         return isolatedLaunch;
     }
 

integrationTest/launchwrapper/src/main/java/gg/essential/loader/stage2/RelaunchTests.java

@@ -53,7 +53,6 @@ public void testRelaunchOfInitPhaseMixin(Installation installation, String outer
         assertTrue(isolatedLaunch.getModLoadState("mixin"), "Example mixin plugin ran");
         assertTrue(isolatedLaunch.getModLoadState("coreMod"), "Example CoreMod ran");
         assertTrue(isolatedLaunch.getModLoadState("mod"), "Example Mod ran");
-        assertTrue(isolatedLaunch.isEssentialLoaded(), "Essential loaded");
     }
 
     private IsolatedLaunch newDevLaunch(Installation installation, String...javaArgs) throws IOException {
@@ -113,7 +112,6 @@ public void testRelaunchArgs_UnknownMain(Installation installation) throws Excep
         IsolatedLaunch isolatedLaunch = newDevLaunch(installation, "some.unknown.launcher.Main");
         isolatedLaunch.launch();
 
-        assertTrue(isolatedLaunch.isEssentialLoaded(), "Essential loaded");
         assertTrue(isolatedLaunch.getModLoadState("coreMod"), "Example CoreMod ran");
         assertTrue(isolatedLaunch.getModLoadState("mod"), "Example Mod ran");
         assertTrue(isolatedLaunch.getModLoadState("relaunched"), "Re-launched");
@@ -132,7 +130,6 @@ public void testRelaunchArgs_LaunchWrapper(Installation installation) throws Exc
         isolatedLaunch.launch();
 
         installation.assertModLaunched(isolatedLaunch);
-        assertTrue(isolatedLaunch.isEssentialLoaded(), "Essential loaded");
         assertTrue(isolatedLaunch.getModLoadState("relaunched"), "Re-launched");
 
         // For LaunchWrapper we should be able to fully recover everything
@@ -149,7 +146,6 @@ public void testRelaunchArgs_GradleStart(Installation installation) throws Excep
         isolatedLaunch.launch();
 
         installation.assertModLaunched(isolatedLaunch);
-        assertTrue(isolatedLaunch.isEssentialLoaded(), "Essential loaded");
         assertTrue(isolatedLaunch.getModLoadState("relaunched"), "Re-launched");
 
         // For GradleStart we should be able to effectively recover everything but not cleanly
@@ -175,7 +171,6 @@ public void testRelaunchArgs_DevLaunchInjector(Installation installation) throws
         isolatedLaunch.launch();
 
         installation.assertModLaunched(isolatedLaunch);
-        assertTrue(isolatedLaunch.isEssentialLoaded(), "Essential loaded");
         assertTrue(isolatedLaunch.getModLoadState("relaunched"), "Re-launched");
 
         // For DLI we should be able to fully recover everything

integrationTest/launchwrapper/src/main/java/gg/essential/loader/stage1/Stage1MixinTests.java renamed to integrationTest/launchwrapper/src/main/java/gg/essential/loader/stage2/Stage2MixinTests.java

@@ -1,4 +1,4 @@
-package gg.essential.loader.stage1;
+package gg.essential.loader.stage2;
 
 import gg.essential.loader.fixtures.Installation;
 import gg.essential.loader.fixtures.IsolatedLaunch;
@@ -8,7 +8,7 @@
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
-public class Stage1MixinTests {
+public class Stage2MixinTests {
     @Test
     public void testMultipleCustomTweakerModsWithMixin07(Installation installation) throws Exception {
         testMultipleCustomTweakerModsWithMixin(installation, "07");

integrationTest/launchwrapper/src/main/java/gg/essential/loader/stage2/Stage2Tests.java

@@ -14,8 +14,6 @@
 import static java.nio.file.StandardCopyOption.REPLACE_EXISTING;
 import static org.apache.commons.codec.digest.DigestUtils.md5Hex;
 import static org.junit.jupiter.api.Assertions.assertEquals;
-import static org.junit.jupiter.api.Assertions.assertNull;
-import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 public class Stage2Tests {
@@ -118,17 +116,7 @@ public void testUpdateRequiringNewerStage2(Installation installation) throws Exc
         Files.copy(withBranch(installation.stage3Meta, "4"), installation.stage3Meta, REPLACE_EXISTING);
         writeProps(installation.stage2ConfigFile, props("pendingUpdateVersion=4", "pendingUpdateResolution=true"));
         IsolatedLaunch secondLaunch = installation.launchFML();
-        assertEquals("2", secondLaunch.getProperty("essential.stage2.version"));
-        assertNull(secondLaunch.getProperty("essential.version"));
-        assertThrows(ClassNotFoundException.class, () -> secondLaunch.getClass("sun.gg.essential.LoadState"));
-
-        // Make available a newer stage2 version
-        // We make available version 5 even though stage3 only requires version 4; we expect it to upgrade straight to 5
-        Files.copy(withBranch(installation.stage2Meta, "5"), installation.stage2Meta, REPLACE_EXISTING);
-
-        // Restart to complete upgrade
-        IsolatedLaunch thirdLaunch = installation.launchFML();
-        assertEquals("5", thirdLaunch.getProperty("essential.stage2.version"));
-        assertEquals("4", thirdLaunch.getProperty("essential.version"));
+        assertEquals("4", secondLaunch.getProperty("essential.stage2.version"));
+        assertEquals("4", secondLaunch.getProperty("essential.version"));
     }
 }

settings.gradle.kts

@@ -19,6 +19,7 @@ include(":stage1:modlauncher9")
 include(":stage2:common")
 include(":stage2:fabric")
 include(":stage2:launchwrapper")
+include(":stage2:launchwrapper-legacy")
 include(":stage2:modlauncher")
 include(":stage2:modlauncher8")
 include(":stage2:modlauncher9")

stage0/launchwrapper/build.gradle

@@ -1,3 +1,10 @@
 dependencies {
     compileOnly("net.minecraft:launchwrapper:1.12")
 }
+
+jar {
+    manifest {
+        // See Loader#isRawStage0
+        attributes("ImplicitlyDependsOnEssential": "false")
+    }
+}