Implement asynchronous services and configuration management for DemocracyLib

.github/workflows/build.yml

@@ -0,0 +1,38 @@
+name: Build DemocracyLib
+
+on:
+  push:
+    branches: [ "framework", "master" ]
+  pull_request:
+    branches: [ "framework", "master" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+          cache: 'gradle'
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Run Unit Tests
+        run: ./gradlew :democracy-lib:test
+
+      - name: Build Shadow JAR
+        run: ./gradlew :democracy-lib:shadowJar
+
+      - name: Upload Build Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: DemocracyLib-DevBuild
+          path: democracy-lib/build/libs/*-all.jar
+          retention-days: 5

.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up JDK
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: gradle
+
+      - name: Validate Gradle wrapper
+        uses: gradle/wrapper-validation-action@v2
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Build & test
+        run: ./gradlew test

bridge-contract/build.gradle.kts

@@ -0,0 +1,22 @@
+plugins {
+    id("java-library")
+}
+
+group = "net.democracycraft"
+version = "1.0.0"
+
+java {
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(21))
+    }
+    withSourcesJar()
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    // No external dependencies required for SOURCE-retention annotations.
+}
+

bridge-contract/src/main/java/net/democracycraft/democracyLib/api/bootstrap/contract/BridgeAnchorKey.java

@@ -0,0 +1,21 @@
+package net.democracycraft.democracyLib.api.bootstrap.contract;
+
+import java.lang.annotation.*;
+
+/**
+ * Marks a String constant as a shared JVM anchor key.
+ * <p>
+ * This annotation is intended for build-time contract generation.
+ */
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.SOURCE)
+public @interface BridgeAnchorKey {
+
+    BridgeStability stability() default BridgeStability.STABLE_ID;
+
+    /**
+     * Optional logical id for the key (distinct from the actual String value).
+     */
+    String id() default "";
+}
+

bridge-contract/src/main/java/net/democracycraft/democracyLib/api/bootstrap/contract/BridgeApi.java

@@ -0,0 +1,19 @@
+package net.democracycraft.democracyLib.api.bootstrap.contract;
+
+import java.lang.annotation.*;
+
+/**
+ * Marks a type as part of the reflection bridge surface.
+ * <p>
+ * This annotation is intended for build-time contract generation.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.SOURCE)
+public @interface BridgeApi {
+
+    /**
+     * Stable logical namespace for the API. Prefer an enum to avoid typos.
+     */
+    BridgeNamespace value();
+}
+

bridge-contract/src/main/java/net/democracycraft/democracyLib/api/bootstrap/contract/BridgeContractVersion.java

@@ -0,0 +1,14 @@
+package net.democracycraft.democracyLib.api.bootstrap.contract;
+
+import java.lang.annotation.*;
+
+/**
+ * Declares the intended bridge contract protocol version for build-time validation and contract generation.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.SOURCE)
+public @interface BridgeContractVersion {
+
+    int value();
+}
+

bridge-contract/src/main/java/net/democracycraft/democracyLib/api/bootstrap/contract/BridgeMethod.java

@@ -0,0 +1,32 @@
+package net.democracycraft.democracyLib.api.bootstrap.contract;
+
+import java.lang.annotation.*;
+
+/**
+ * Marks a method as bridgeable across classloaders.
+ * <p>
+ * This annotation is intended for build-time contract generation.
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.SOURCE)
+public @interface BridgeMethod {
+
+    BridgeSide side() default BridgeSide.FOLLOWER_TO_LEADER;
+
+    BridgeStability stability() default BridgeStability.DERIVED_ID;
+
+    /**
+     * Optional explicit method id. Only used when {@link #stability()} is {@link BridgeStability#STABLE_ID}.
+     */
+    String id() default "";
+
+    OverloadPolicy overloads() default OverloadPolicy.ALLOW;
+
+    SignaturePolicy signature() default SignaturePolicy.FULL_SIGNATURE;
+
+    /**
+     * Protocol version this method became available.
+     */
+    int sinceProtocol() default 1;
+}
+

bridge-contract/src/main/java/net/democracycraft/democracyLib/api/bootstrap/contract/BridgeNamespace.java

@@ -0,0 +1,10 @@
+package net.democracycraft.democracyLib.api.bootstrap.contract;
+
+/**
+ * Stable namespaces for bridgeable APIs.
+ */
+public enum BridgeNamespace {
+    DEMOCRACY_LIB_API,
+    DEMOCRACY_SERVICE_MANAGER,
+    DEMOCRACY_CONFIG_MANAGER
+}

bridge-contract/src/main/java/net/democracycraft/democracyLib/api/bootstrap/contract/BridgeOverloadKey.java

@@ -0,0 +1,16 @@
+package net.democracycraft.democracyLib.api.bootstrap.contract;
+
+import java.lang.annotation.*;
+
+/**
+ * Optional human-friendly key for overloaded methods.
+ * <p>
+ * If present, the generated id can incorporate this key instead of raw parameter type names.
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.SOURCE)
+public @interface BridgeOverloadKey {
+
+    String value();
+}
+

bridge-contract/src/main/java/net/democracycraft/democracyLib/api/bootstrap/contract/BridgeSide.java

@@ -0,0 +1,11 @@
+package net.democracycraft.democracyLib.api.bootstrap.contract;
+
+/**
+ * Intended call direction for a bridgeable method.
+ */
+public enum BridgeSide {
+    FOLLOWER_TO_LEADER,
+    LEADER_INTERNAL,
+    BOTH
+}
+

bridge-contract/src/main/java/net/democracycraft/democracyLib/api/bootstrap/contract/BridgeStability.java

@@ -0,0 +1,17 @@
+package net.democracycraft.democracyLib.api.bootstrap.contract;
+
+/**
+ * How ids are produced for the bridge contract.
+ */
+public enum BridgeStability {
+    /**
+     * The id is explicitly provided and remains stable across renames.
+     */
+    STABLE_ID,
+
+    /**
+     * The id is derived from the method signature.
+     */
+    DERIVED_ID
+}
+

bridge-contract/src/main/java/net/democracycraft/democracyLib/api/bootstrap/contract/OverloadPolicy.java

@@ -0,0 +1,10 @@
+package net.democracycraft.democracyLib.api.bootstrap.contract;
+
+/**
+ * How the contract generator should handle overloaded methods.
+ */
+public enum OverloadPolicy {
+    ALLOW,
+    ERROR
+}
+

bridge-contract/src/main/java/net/democracycraft/democracyLib/api/bootstrap/contract/SignaturePolicy.java

@@ -0,0 +1,16 @@
+package net.democracycraft.democracyLib.api.bootstrap.contract;
+
+/**
+ * How strictly methods should be identified.
+ */
+public enum SignaturePolicy {
+    /**
+     * Identify methods by name + parameter count only (not recommended).
+     */
+    ARITY_ONLY,
+
+    /**
+     * Identify methods by full parameter type list.
+     */
+    FULL_SIGNATURE
+}

bridge-processor/build.gradle.kts

@@ -0,0 +1,20 @@
+plugins {
+    id("java-library")
+}
+
+group = "net.democracycraft"
+version = "1.0.0"
+
+java {
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(21))
+    }
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation(project(":bridge-contract"))
+}