refactor: infrastructure

api-files/server-version-types.json

@@ -14,10 +14,10 @@
     ],
     "environmentVariables": {},
     "defaultFiles": {
-      "config/paper-global.yml": "https://api.redicloud.dev/v2/files/%branch%/%build%/api-files/defaultFiles/paper-global.yml",
-      "server.properties": "https://api.redicloud.dev/v2/files/%branch%/%build%/api-files/defaultFiles/server.properties",
-      "bukkit.yml": "https://api.redicloud.dev/v2/files/%branch%/%build%/api-files/defaultFiles/bukkit.yml",
-      "spigot.yml": "https://api.redicloud.dev/v2/files/%branch%/%build%/api-files/defaultFiles/spigot.yml"
+      "config/paper-global.yml": "https://raw.githubusercontent.com/RediCloud/cloud-v2/%branch%/api-files/defaultFiles/paper-global.yml",
+      "server.properties": "https://raw.githubusercontent.com/RediCloud/cloud-v2/%branch%/api-files/defaultFiles/server.properties",
+      "bukkit.yml": "https://raw.githubusercontent.com/RediCloud/cloud-v2/%branch%/api-files/defaultFiles/bukkit.yml",
+      "spigot.yml": "https://raw.githubusercontent.com/RediCloud/cloud-v2/%branch%/api-files/defaultFiles/spigot.yml"
     },
     "fileEdits": {
       "server.properties": {
@@ -49,9 +49,9 @@
     ],
     "environmentVariables": {},
     "defaultFiles": {
-      "server.properties": "https://api.redicloud.dev/v2/files/%branch%/%build%/api-files/defaultFiles/server.properties",
-      "bukkit.yml": "https://api.redicloud.dev/v2/files/%branch%/%build%/api-files/defaultFiles/bukkit.yml",
-      "spigot.yml": "https://api.redicloud.dev/v2/files/%branch%/%build%/api-files/defaultFiles/spigot.yml"
+      "server.properties": "https://raw.githubusercontent.com/RediCloud/cloud-v2/%branch%/api-files/defaultFiles/server.properties",
+      "bukkit.yml": "https://raw.githubusercontent.com/RediCloud/cloud-v2/%branch%/api-files/defaultFiles/bukkit.yml",
+      "spigot.yml": "https://raw.githubusercontent.com/RediCloud/cloud-v2/%branch%/api-files/defaultFiles/spigot.yml"
     },
     "fileEdits": {
       "server.properties": {
@@ -75,8 +75,8 @@
     "programParameters": [],
     "environmentVariables": {},
     "defaultFiles": {
-      "velocity.toml": "https://api.redicloud.dev/v2/files/%branch%/%build%/api-files/defaultFiles/velocity.toml",
-      "forwarding.secret": "https://api.redicloud.dev/v2/files/%branch%/%build%/api-files/defaultFiles/forwarding.secret"
+      "velocity.toml": "https://raw.githubusercontent.com/RediCloud/cloud-v2/%branch%/api-files/defaultFiles/velocity.toml",
+      "forwarding.secret": "https://raw.githubusercontent.com/RediCloud/cloud-v2/%branch%/api-files/defaultFiles/forwarding.secret"
     },
     "fileEdits": {
       "velocity.toml": {
@@ -102,7 +102,7 @@
     "programParameters": [],
     "environmentVariables": {},
     "defaultFiles": {
-      "config.yml": "https://api.redicloud.dev/v2/files/%branch%/%build%/api-files/defaultFiles/config.yml"
+      "config.yml": "https://raw.githubusercontent.com/RediCloud/cloud-v2/%branch%/api-files/defaultFiles/config.yml"
     },
     "fileEdits": {
       "config.yml": {
@@ -124,7 +124,7 @@
     "programParameters": [],
     "environmentVariables": {},
     "defaultFiles": {
-      "config.yml": "https://api.redicloud.dev/v2/files/%branch%/%build%/api-files/defaultFiles/config.yml"
+      "config.yml": "https://raw.githubusercontent.com/RediCloud/cloud-v2/%branch%/api-files/defaultFiles/config.yml"
     },
     "fileEdits": {
       "config.yml": {
@@ -152,7 +152,7 @@
     ],
     "environmentVariables": {},
     "defaultFiles": {
-      "server.properties": "https://api.redicloud.dev/v2/files/%branch%/%build%/api-files/defaultFiles/server.properties"
+      "server.properties": "https://raw.githubusercontent.com/RediCloud/cloud-v2/%branch%/api-files/defaultFiles/server.properties"
     },
     "fileEdits": {
       "server.properties": {

apis/base-api/src/main/kotlin/dev/redicloud/api/cache/IClusterCacheObject.kt

@@ -0,0 +1,11 @@
+package dev.redicloud.api.cache
+
+import java.io.Serializable
+
+/**
+ * Marker interface for objects that can be stored in a cluster-wide cache.
+ *
+ * Entity classes in the repository layer implement this interface to indicate
+ * they support cross-node caching with TTL-based invalidation.
+ */
+interface IClusterCacheObject : Serializable

apis/base-api/src/main/kotlin/dev/redicloud/api/console/ICloudConsole.kt

@@ -0,0 +1,44 @@
+package dev.redicloud.api.console
+
+import dev.redicloud.api.commands.ICommandManager
+
+/**
+ * Simplified console interface for cloud modules.
+ *
+ * Provides basic console output and command management. Obtain an instance
+ * via Guice injection. The concrete implementation uses JLine3 for
+ * terminal I/O and is only active on node services.
+ */
+interface ICloudConsole {
+
+    /** The command manager for registering and handling console commands. */
+    val commandManager: ICommandManager<*>
+
+    /**
+     * Writes a line to the console if printing is enabled.
+     *
+     * @param text the text to write (supports color codes with `§`)
+     * @return this console instance
+     */
+    fun writeLine(text: String): ICloudConsole
+
+    /**
+     * Writes a line to the console regardless of the printing state.
+     *
+     * @param text the text to write (supports color codes with `§`)
+     * @return this console instance
+     */
+    fun forceWriteLine(text: String): ICloudConsole
+
+    /** Clears the console screen. */
+    fun clearScreen()
+
+    /** Enables command input processing. */
+    fun enableCommands()
+
+    /** Disables command input processing. */
+    fun disableCommands()
+
+    /** Returns whether the console supports ANSI color codes. */
+    fun hasColorSupport(): Boolean
+}

apis/base-api/src/main/kotlin/dev/redicloud/api/tasks/ICloudTask.kt

@@ -0,0 +1,39 @@
+package dev.redicloud.api.tasks
+
+import java.util.UUID
+
+/**
+ * Represents a schedulable cloud task that can be registered with [ICloudTaskManager].
+ *
+ * Tasks define work to be executed on various triggers (instant, delayed, periodic,
+ * event-based, or packet-based) via [ICloudTaskExecutorBuilder].
+ */
+interface ICloudTask {
+
+    /** Unique identifier for this task. */
+    val id: UUID
+
+    /**
+     * Executes the task logic.
+     *
+     * @return `true` if the task should be automatically canceled after execution,
+     *         `false` to keep the task active for further executions.
+     */
+    suspend fun execute(): Boolean
+
+    /** Returns whether this task has been canceled. */
+    fun isCanceled(): Boolean
+
+    /** Returns whether this task has been started by a [ICloudTaskManager]. */
+    fun isStarted(): Boolean
+
+    /** Cancels this task and all its executors. */
+    fun cancel()
+
+    /**
+     * Registers a callback that is invoked when the task finishes.
+     *
+     * @param block the callback to invoke on finish
+     */
+    fun onFinished(block: () -> Unit)
+}

apis/base-api/src/main/kotlin/dev/redicloud/api/tasks/ICloudTaskExecutorBuilder.kt

@@ -0,0 +1,95 @@
+package dev.redicloud.api.tasks
+
+import dev.redicloud.api.events.CloudEvent
+import dev.redicloud.api.packets.AbstractPacket
+import kotlin.reflect.KClass
+import kotlin.time.Duration
+
+/**
+ * Builder for configuring execution triggers on a [ICloudTask].
+ *
+ * Supports multiple trigger types that can be combined:
+ * - [instant] -- execute immediately
+ * - [delay] -- execute after a delay
+ * - [atTime] -- execute at a specific timestamp
+ * - [period] -- execute periodically
+ * - [event] -- execute when a [CloudEvent] fires
+ * - [packet] -- execute when a packet is received
+ *
+ * Call [register] to finalize and start the task.
+ */
+interface ICloudTaskExecutorBuilder {
+
+    /**
+     * Sets the task to be executed.
+     *
+     * @param task the task instance
+     * @return this builder
+     */
+    fun task(task: ICloudTask): ICloudTaskExecutorBuilder
+
+    /**
+     * Adds an instant executor that runs the task immediately upon registration.
+     *
+     * @return this builder
+     */
+    fun instant(): ICloudTaskExecutorBuilder
+
+    /**
+     * Adds an executor that runs the task at a specific timestamp.
+     *
+     * @param atTime the Unix timestamp (milliseconds) at which to execute
+     * @return this builder
+     * @throws IllegalArgumentException if [atTime] is in the past
+     */
+    fun atTime(atTime: Long): ICloudTaskExecutorBuilder
+
+    /**
+     * Adds an executor that runs the task after a delay.
+     *
+     * @param delay the delay in milliseconds
+     * @return this builder
+     */
+    fun delay(delay: Long): ICloudTaskExecutorBuilder
+
+    /**
+     * Adds an executor that runs the task after a delay.
+     *
+     * @param duration the delay duration
+     * @return this builder
+     */
+    fun delay(duration: Duration): ICloudTaskExecutorBuilder
+
+    /**
+     * Adds a periodic executor that runs the task at a fixed interval.
+     *
+     * @param period the interval between executions
+     * @param maxExecutions the maximum number of executions, or `-1` for unlimited
+     * @return this builder
+     */
+    fun period(period: Duration, maxExecutions: Int = -1): ICloudTaskExecutorBuilder
+
+    /**
+     * Adds an event-based executor that runs the task when the specified event fires.
+     *
+     * @param eventClazz the event class to listen for
+     * @return this builder
+     */
+    fun event(eventClazz: KClass<out CloudEvent>): ICloudTaskExecutorBuilder
+
+    /**
+     * Adds a packet-based executor that runs the task when the specified packet is received.
+     *
+     * @param packetClazz the packet class to listen for
+     * @return this builder
+     */
+    fun packet(packetClazz: KClass<out AbstractPacket>): ICloudTaskExecutorBuilder
+
+    /**
+     * Registers the task with all configured executors and starts execution.
+     *
+     * @return the registered task
+     * @throws IllegalStateException if no task or executors have been set
+     */
+    fun register(): ICloudTask
+}

apis/base-api/src/main/kotlin/dev/redicloud/api/tasks/ICloudTaskManager.kt

@@ -0,0 +1,43 @@
+package dev.redicloud.api.tasks
+
+import java.util.UUID
+
+/**
+ * Manages the lifecycle of [ICloudTask] instances.
+ *
+ * Provides registration, unregistration, and a builder API for configuring
+ * task execution triggers. Obtain an instance via Guice injection.
+ */
+interface ICloudTaskManager {
+
+    /**
+     * Registers and starts a task.
+     *
+     * @param task the task to register
+     * @return the unique ID of the registered task
+     * @throws IllegalArgumentException if a task with the same ID is already registered
+     */
+    fun register(task: ICloudTask): UUID
+
+    /**
+     * Unregisters and cancels a task by its ID.
+     *
+     * @param id the unique ID of the task
+     * @return the unregistered task, or `null` if not found
+     */
+    fun unregister(id: UUID): ICloudTask?
+
+    /**
+     * Unregisters and cancels a task.
+     *
+     * @param task the task to unregister
+     * @return the unregistered task, or `null` if not found
+     */
+    fun unregister(task: ICloudTask): ICloudTask?
+
+    /** Returns all currently registered tasks. */
+    fun getTasks(): List<ICloudTask>
+
+    /** Creates a new builder for configuring and registering a task with executors. */
+    fun builder(): ICloudTaskExecutorBuilder
+}

apis/base-api/src/main/kotlin/dev/redicloud/api/version/IVersionHandlerListener.kt

@@ -0,0 +1,69 @@
+package dev.redicloud.api.version
+
+/**
+ * Listener for server version handler lifecycle events.
+ *
+ * Implementations receive callbacks during download, patch, and connector
+ * operations. This decouples the data/repository layer from the presentation
+ * layer -- the console module provides a concrete implementation that
+ * displays progress animations.
+ *
+ * Obtain an instance via Guice injection on node services.
+ */
+interface IVersionHandlerListener {
+
+    /**
+     * Called when a server version download starts.
+     *
+     * @param version the version being downloaded
+     */
+    fun onDownloadStart(version: ICloudServerVersion)
+
+    /**
+     * Called when a server version download completes.
+     *
+     * @param version the version that was downloaded
+     * @param error `true` if the download failed
+     */
+    fun onDownloadComplete(version: ICloudServerVersion, error: Boolean)
+
+    /**
+     * Called when a server version patch starts.
+     *
+     * @param version the version being patched
+     */
+    fun onPatchStart(version: ICloudServerVersion)
+
+    /**
+     * Called when a server version patch completes.
+     *
+     * @param version the version that was patched
+     * @param error `true` if the patch failed
+     */
+    fun onPatchComplete(version: ICloudServerVersion, error: Boolean)
+
+    /**
+     * Called when a subprocess is started during patching.
+     *
+     * Implementations may capture the process output for display.
+     *
+     * @param name a descriptive name for the process (e.g. `"patch_paper-1.20"`)
+     * @param process the running subprocess
+     */
+    fun onProcessStart(name: String, process: Process)
+
+    /**
+     * Called when a connector download starts.
+     *
+     * @param versionType the server version type whose connector is being downloaded
+     */
+    fun onConnectorDownloadStart(versionType: ICloudServerVersionType)
+
+    /**
+     * Called when a connector download completes.
+     *
+     * @param versionType the server version type whose connector was downloaded
+     * @param error `true` if the download failed
+     */
+    fun onConnectorDownloadComplete(versionType: ICloudServerVersionType, error: Boolean)
+}