Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 dmg
|
c1a958337f | ||
|
dmg
|
591c0c5ec2 | ||
|
dmg
|
ee3b4eca35 | ||
|
dmg
|
9f3f27bb45 |
No files matched your search
@@ -17,7 +17,7 @@ jobs:
|
||||
uses: actions/setup-java@v4
|
||||
with:
|
||||
distribution: temurin
|
||||
java-version: 17
|
||||
java-version: 25
|
||||
cache: gradle
|
||||
|
||||
- name: Validate conventional commits
|
||||
@@ -35,6 +35,6 @@ jobs:
|
||||
- name: Upload development artifact
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: spigot-event-producer-${{ github.sha }}
|
||||
name: purpur-event-producer-${{ github.sha }}
|
||||
path: build/libs/*.jar
|
||||
if-no-files-found: error
|
||||
@@ -21,7 +21,7 @@ jobs:
|
||||
uses: actions/setup-java@v4
|
||||
with:
|
||||
distribution: temurin
|
||||
java-version: 17
|
||||
java-version: 25
|
||||
cache: gradle
|
||||
|
||||
- name: Set up Node.js
|
||||
@@ -86,8 +86,8 @@ jobs:
|
||||
if: steps.release.outputs.created == 'true'
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: spigot-event-producer-${{ steps.release.outputs.version }}
|
||||
path: build/libs/spigot-event-producer-${{ steps.release.outputs.version }}.jar
|
||||
name: purpur-event-producer-${{ steps.release.outputs.version }}
|
||||
path: build/libs/purpur-event-producer-${{ steps.release.outputs.version }}.jar
|
||||
if-no-files-found: error
|
||||
|
||||
- name: Create Gitea release and upload plugin
|
||||
@@ -101,7 +101,7 @@ jobs:
|
||||
PREVIOUS_TAG: ${{ steps.previous_tag.outputs.value }}
|
||||
run: |
|
||||
api_url="${GITEA_SERVER_URL}/api/v1"
|
||||
jar="build/libs/spigot-event-producer-${VERSION}.jar"
|
||||
jar="build/libs/purpur-event-producer-${VERSION}.jar"
|
||||
export RELEASE_BODY
|
||||
if [ -n "$PREVIOUS_TAG" ]; then
|
||||
RELEASE_BODY=$(git log --pretty='format:- %s (%h)' "${PREVIOUS_TAG}..HEAD")
|
||||
@@ -138,4 +138,4 @@ jobs:
|
||||
-H "Authorization: token ${GITEA_TOKEN}" \
|
||||
-H "Content-Type: application/octet-stream" \
|
||||
--data-binary "@${jar}" \
|
||||
"${api_url}/repos/${REPOSITORY}/releases/${release_id}/assets?name=spigot-event-producer-${VERSION}.jar"
|
||||
"${api_url}/repos/${REPOSITORY}/releases/${release_id}/assets?name=purpur-event-producer-${VERSION}.jar"
|
||||
@@ -0,0 +1,9 @@
|
||||
# purpur-event-producer agent entrypoint
|
||||
|
||||
The canonical stories, engineering guidance, and **all process documents** are in the private [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/index.md).
|
||||
|
||||
Before work, read the sibling `../somc-okf/index.md`, `../somc-okf/processes/index.md`, `../somc-okf/projects/purpur-event-producer/index.md`, `engineering.md` in that project section, and relevant `../somc-okf/user-stories/purpur-event-producer/` stories. Also follow the parent workspace `AGENTS.md` when present.
|
||||
|
||||
For standalone checkouts, start at the [project page](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/purpur-event-producer/index.md) and [shared process](https://git.garvis.dev/dmg/somc-okf/src/branch/main/processes/development.md). Obtain wiki access before feature work; do not recreate a local knowledge bundle. Source builds do not require private wiki access.
|
||||
|
||||
Development follows [Development cycle](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/development-cycle.md): approved stories, failing tests, passing implementation, verification, then source/wiki commit and push. GitOps updates are committed locally **without pushing**; only [Do release](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/do-release.md) authorizes a reviewed GitOps push.
|
||||
@@ -1,22 +1,26 @@
|
||||
# Spigot Event Producer
|
||||
# Purpur Event Producer
|
||||
|
||||
A Spigot 26.2 plugin that records Minecraft activity as CloudEvents 1.0, persists it in a local SQLite outbox, and sends newline-delimited batches to `game-ingest-server`.
|
||||
A Purpur 26.3 plugin that records Minecraft activity as CloudEvents 1.0, persists it in a local SQLite outbox, and sends newline-delimited batches to `game-ingest-server`.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Spigot 26.2
|
||||
- Java 17 or newer
|
||||
- Purpur 26.3 build 2651
|
||||
- Java 25
|
||||
- Network access to the ingest endpoint
|
||||
|
||||
The repository, checkout and new artifacts use `purpur-event-producer`. Runtime `SpigotEventProducer`, Java entrypoint/packages, existing configuration/server UUID and `plugins/SpigotEventProducer/event-outbox.sqlite3` remain unchanged, as do CloudEvent types/source/payloads and delivery semantics. The SQLite driver stays bundled. Replace the old JAR rather than installing both distributions. Old tags/assets remain available; new releases no longer support Java 17.
|
||||
|
||||
## Build and install
|
||||
|
||||
```bash
|
||||
./gradlew clean test jar
|
||||
cp build/libs/spigot-event-producer-0.1.0-SNAPSHOT.jar /path/to/server/plugins/
|
||||
./gradlew clean check jar
|
||||
cp build/libs/purpur-event-producer-0.1.0-SNAPSHOT.jar /path/to/server/plugins/
|
||||
```
|
||||
|
||||
Start the Minecraft server once to create `plugins/SpigotEventProducer/config.yml`. Set a meaningful, stable `server-name`. When `server-id` is empty, the plugin generates and persists a UUID. Do not reuse that generated UUID on another server.
|
||||
|
||||
The full verification command compiles against Purpur API `26.3.build.2651-stable`, downloads and SHA-256 verifies the exact Purpur 26.3 build-2651 runtime, and loads, enables, and disables the packaged entrypoint on that runtime. Its isolated lifecycle check uses temporary configuration, a loopback-only unreachable ingest URL and a real SQLite outbox; it verifies generated server-UUID ownership plus durable startup/shutdown CloudEvents without contacting the configured production service. The suite also covers event/privacy contracts, outbox delivery, registry/statistic behavior, Java 25 bytecode, plugin metadata, shaded JDBC services, and API/server/ProtocolLib/test exclusions. This automated native boundary is not a live-server or real-ingest test.
|
||||
|
||||
The default ingest endpoint is:
|
||||
|
||||
```text
|
||||
@@ -52,7 +56,7 @@ Public chat events contain the complete message text.
|
||||
|
||||
Private-message events recognize `/msg`, `/message`, `/tell`, `/w`, `/whisper`, `/pm`, `/reply`, and `/r`, including namespaced variants such as `/minecraft:tell`. Explicit commands contain the destination token. Reply commands set `reply: true` and omit the recipient so downstream processing can infer it from earlier ordered events. The event also reports whether the command was cancelled.
|
||||
|
||||
Spigot has no universal private-message event. Commands implemented with unrelated aliases or entirely custom plugin logic will not be recognized until their syntax is added. A recognized command event reports observation of the command, not guaranteed delivery to its recipient.
|
||||
The Bukkit-compatible server API has no universal private-message event. Commands implemented with unrelated aliases or entirely custom plugin logic will not be recognized until their syntax is added. A recognized command event reports observation of the command, not guaranteed delivery to its recipient.
|
||||
|
||||
### Location snapshots
|
||||
|
||||
@@ -114,7 +118,7 @@ Gitea Actions runs the Gradle checks for every push and pull request and stores
|
||||
- `feat:` creates a minor release;
|
||||
- a breaking-change footer or `!` creates a major release.
|
||||
|
||||
A successful release creates a `vX.Y.Z` tag and attaches `spigot-event-producer-X.Y.Z.jar` permanently to the corresponding Gitea Release. The release workflow requires a repository secret named `RELEASE_TOKEN` with repository contents write permission.
|
||||
A successful release creates a `vX.Y.Z` tag and attaches `purpur-event-producer-X.Y.Z.jar` permanently to the corresponding Gitea Release. The release workflow requires a repository secret named `RELEASE_TOKEN` with repository contents write permission.
|
||||
|
||||
For a local versioned build:
|
||||
|
||||
|
||||
+65
-4
@@ -1,3 +1,6 @@
|
||||
import java.net.URI
|
||||
import java.security.MessageDigest
|
||||
|
||||
plugins {
|
||||
java
|
||||
}
|
||||
@@ -9,12 +12,12 @@ version = providers.gradleProperty("releaseVersion")
|
||||
|
||||
repositories {
|
||||
mavenCentral()
|
||||
maven("https://hub.spigotmc.org/nexus/content/repositories/snapshots/")
|
||||
maven("https://repo.purpurmc.org/snapshots/")
|
||||
}
|
||||
|
||||
java {
|
||||
toolchain {
|
||||
languageVersion = JavaLanguageVersion.of(17)
|
||||
languageVersion = JavaLanguageVersion.of(25)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -23,10 +26,10 @@ tasks.withType<JavaCompile>().configureEach {
|
||||
}
|
||||
|
||||
dependencies {
|
||||
compileOnly("org.spigotmc:spigot-api:26.2-R0.1-SNAPSHOT")
|
||||
compileOnly("org.purpurmc.purpur:purpur-api:26.3.build.2651-stable")
|
||||
implementation("org.xerial:sqlite-jdbc:3.50.3.0")
|
||||
|
||||
testImplementation("org.spigotmc:spigot-api:26.2-R0.1-SNAPSHOT")
|
||||
testImplementation("org.purpurmc.purpur:purpur-api:26.3.build.2651-stable")
|
||||
testImplementation(platform("org.junit:junit-bom:5.13.4"))
|
||||
testImplementation("org.junit.jupiter:junit-jupiter")
|
||||
testRuntimeOnly("org.junit.platform:junit-platform-launcher")
|
||||
@@ -34,8 +37,66 @@ dependencies {
|
||||
|
||||
tasks.test {
|
||||
useJUnitPlatform()
|
||||
dependsOn(tasks.jar)
|
||||
systemProperty("distribution.jar", tasks.jar.get().archiveFile.get().asFile.absolutePath)
|
||||
systemProperty("distribution.version", project.version.toString())
|
||||
}
|
||||
|
||||
val nativeRuntime = layout.buildDirectory.dir("native-runtime")
|
||||
val downloadNativeRuntime = tasks.register("downloadNativeRuntime") {
|
||||
val launcher = nativeRuntime.map { it.file("purpur-26.3-2651.jar") }
|
||||
outputs.file(launcher)
|
||||
doLast {
|
||||
val file = launcher.get().asFile
|
||||
file.parentFile.mkdirs()
|
||||
val connection = URI("https://api.purpurmc.org/v2/purpur/26.3/2651/download")
|
||||
.toURL().openConnection()
|
||||
connection.connectTimeout = 30_000
|
||||
connection.readTimeout = 120_000
|
||||
val bytes = connection.getInputStream().use { it.readBytes() }
|
||||
val digest = MessageDigest.getInstance("SHA-256")
|
||||
.digest(bytes).joinToString("") { "%02x".format(it) }
|
||||
check(digest == "0677c1febecfbc2e5b0a7f76abd647b70a1f38d3cbdf3dd6a82e401b4262a598") {
|
||||
"Purpur 2651 checksum mismatch"
|
||||
}
|
||||
file.writeBytes(bytes)
|
||||
}
|
||||
}
|
||||
val prepareNativeRuntime = tasks.register<JavaExec>("prepareNativeRuntime") {
|
||||
dependsOn(downloadNativeRuntime)
|
||||
javaLauncher = javaToolchains.launcherFor { languageVersion = JavaLanguageVersion.of(25) }
|
||||
classpath = files(nativeRuntime.map { it.file("purpur-26.3-2651.jar") })
|
||||
mainClass = "io.papermc.paperclip.Main"
|
||||
jvmArgs("-Dpaperclip.patchonly=true")
|
||||
workingDir(nativeRuntime)
|
||||
outputs.dir(nativeRuntime.map { it.dir("versions") })
|
||||
outputs.dir(nativeRuntime.map { it.dir("libraries") })
|
||||
}
|
||||
val nativeTest = sourceSets.create("nativeTest")
|
||||
dependencies {
|
||||
add(nativeTest.implementationConfigurationName, platform("org.junit:junit-bom:5.13.4"))
|
||||
add(nativeTest.implementationConfigurationName, "org.junit.jupiter:junit-jupiter")
|
||||
add(nativeTest.implementationConfigurationName, "org.mockito:mockito-core:5.18.0")
|
||||
add(nativeTest.runtimeOnlyConfigurationName, "org.junit.platform:junit-platform-launcher")
|
||||
}
|
||||
val nativeRuntimeJars = files(fileTree(nativeRuntime) {
|
||||
include("versions/**/*.jar", "libraries/**/*.jar")
|
||||
}).builtBy(prepareNativeRuntime)
|
||||
nativeTest.compileClasspath += sourceSets.main.get().output + nativeRuntimeJars
|
||||
nativeTest.runtimeClasspath += sourceSets.main.get().runtimeClasspath + nativeRuntimeJars
|
||||
val nativeLifecycleTest = tasks.register<Test>("nativeLifecycleTest") {
|
||||
description = "Loads, enables, and disables the packaged plugin on the pinned Purpur runtime"
|
||||
dependsOn(tasks.jar)
|
||||
testClassesDirs = nativeTest.output.classesDirs
|
||||
classpath = nativeTest.runtimeClasspath
|
||||
useJUnitPlatform()
|
||||
maxHeapSize = "1G"
|
||||
workingDir(nativeRuntime)
|
||||
systemProperty("distribution.jar", tasks.jar.get().archiveFile.get().asFile.absolutePath)
|
||||
systemProperty("distribution.version", project.version.toString())
|
||||
}
|
||||
tasks.check { dependsOn(nativeLifecycleTest) }
|
||||
|
||||
val pluginVersion = version
|
||||
|
||||
tasks.processResources {
|
||||
|
||||
@@ -1,16 +0,0 @@
|
||||
---
|
||||
type: Index
|
||||
title: Spigot Event Producer Design
|
||||
description: Entry point for the Spigot Event Producer OKF knowledge bundle.
|
||||
okf_version: "0.1"
|
||||
---
|
||||
|
||||
# Spigot Event Producer Design
|
||||
|
||||
This bundle documents the user-visible and operational behavior of the Spigot plugin that captures Minecraft activity and delivers it as CloudEvents.
|
||||
|
||||
## Explore
|
||||
|
||||
- [User stories](user-stories/index.md)
|
||||
- [Design log](log.md)
|
||||
- [Project README](../README.md)
|
||||
@@ -1,13 +0,0 @@
|
||||
---
|
||||
type: Log
|
||||
title: Design Log
|
||||
description: Chronological record of material changes to the design knowledge bundle.
|
||||
---
|
||||
|
||||
# Design Log
|
||||
|
||||
## 2026-08-08
|
||||
|
||||
- Established the OKF v0.1 design bundle.
|
||||
- Documented the existing configuration, event production, activity capture, snapshots, durable delivery, and release workflows as user stories.
|
||||
- Made snapshot collection skip Bukkit registry entries whose keys are unavailable.
|
||||
@@ -1,16 +0,0 @@
|
||||
---
|
||||
type: Index
|
||||
title: User Stories
|
||||
description: Catalog of user stories for the Spigot Event Producer.
|
||||
---
|
||||
|
||||
# User Stories
|
||||
|
||||
1. [US-001: Configure the event producer](us-001-configure-event-producer.md)
|
||||
2. [US-002: Produce standard CloudEvents](us-002-produce-standard-cloud-events.md)
|
||||
3. [US-003: Capture player and server activity](us-003-capture-player-activity.md)
|
||||
4. [US-004: Capture periodic player snapshots](us-004-capture-player-snapshots.md)
|
||||
5. [US-005: Deliver events durably](us-005-deliver-events-durably.md)
|
||||
6. [US-006: Build and release the plugin](us-006-build-and-release-plugin.md)
|
||||
|
||||
Return to the [design index](../index.md).
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-001: Configure the event producer"
|
||||
description: Allow a server operator to identify a Minecraft server and tune event capture and delivery safely.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-001: Configure the event producer
|
||||
|
||||
As a **Minecraft server operator**, I want to configure the producer for my server and ingest service so that emitted events are identifiable and fit my operating limits.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] A human-readable server name and stable server UUID can be configured.
|
||||
- [x] When no server UUID is supplied, the plugin generates one and persists it for later starts.
|
||||
- [x] The ingest URL, send interval, snapshot interval, HTTP timeout, batch limits, dispatch thresholds, statistic chunk size, and per-tick statistic budget are configurable.
|
||||
- [x] Blank required values, non-positive limits, overlong server names, invalid UUIDs, and statistic chunks without sufficient batch headroom prevent initialization.
|
||||
- [x] Initialization errors are logged and leave the plugin disabled rather than partially running.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-002: Produce standard CloudEvents](us-002-produce-standard-cloud-events.md)
|
||||
- [US-005: Deliver events durably](us-005-deliver-events-durably.md)
|
||||
- [Configuration reference](../../README.md#configuration)
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-002: Produce standard CloudEvents"
|
||||
description: Represent captured Minecraft activity as consistently identifiable CloudEvents 1.0 records.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-002: Produce standard CloudEvents
|
||||
|
||||
As an **event consumer**, I want Minecraft activity represented by a consistent CloudEvents envelope so that I can process records from multiple servers and players reliably.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] Every record is a structured CloudEvents 1.0 JSON object with a unique stable event ID, UTC time, source, type, and JSON content type.
|
||||
- [x] Event types use the `games.dmg.minecraft.*` namespace.
|
||||
- [x] Every event includes the stable server ID, server name, and game version as extensions and in its data.
|
||||
- [x] Player events include the player UUID as an extension and include the player UUID and current name in their data.
|
||||
- [x] An event retains the same ID and payload while it is retried from the outbox.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-001: Configure the event producer](us-001-configure-event-producer.md)
|
||||
- [US-003: Capture player and server activity](us-003-capture-player-activity.md)
|
||||
- [US-004: Capture periodic player snapshots](us-004-capture-player-snapshots.md)
|
||||
- [Event reference](../../README.md#events)
|
||||
@@ -1,26 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-003: Capture player and server activity"
|
||||
description: Record server lifecycle, player sessions, public chat, and recognized private messages.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-003: Capture player and server activity
|
||||
|
||||
As a **server analyst**, I want significant server and player activity captured so that I can reconstruct participation and communication activity downstream.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] Plugin startup and shutdown produce server lifecycle events.
|
||||
- [x] Player joins and quits produce events with player identity.
|
||||
- [x] Non-cancelled public chat produces an event containing the complete message and whether the Bukkit event was asynchronous.
|
||||
- [x] Recognized explicit private-message commands capture the command, recipient token, and complete message.
|
||||
- [x] Recognized reply commands are marked as replies and omit a recipient.
|
||||
- [x] Private-message observations report whether the underlying command was cancelled.
|
||||
- [x] Standard aliases and namespaced variants documented by the project are recognized.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-002: Produce standard CloudEvents](us-002-produce-standard-cloud-events.md)
|
||||
- [US-005: Deliver events durably](us-005-deliver-events-durably.md)
|
||||
- [Chat and private-message behavior](../../README.md#chat-and-private-messages)
|
||||
@@ -1,29 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-004: Capture periodic player snapshots"
|
||||
description: Periodically capture player location and comprehensive Bukkit statistics without monopolizing a server tick.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-004: Capture periodic player snapshots
|
||||
|
||||
As a **server analyst**, I want periodic player location and statistic snapshots so that I can analyze movement and gameplay progression over time.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] Each configured interval captures every online player's world identity, coordinates, orientation, game mode, and biome.
|
||||
- [x] Registry-backed snapshot values use Bukkit's stable `Keyed` contract so collection remains compatible with the supported Purpur runtime.
|
||||
- [x] Unkeyed registry entries such as `EntityType.UNKNOWN` are skipped without throwing or interrupting snapshot collection.
|
||||
- [x] Every Bukkit untyped, block, item, and entity statistic combination accepted by Bukkit is captured, including zero values.
|
||||
- [x] Invalid statistic subtype combinations are skipped without stopping the snapshot.
|
||||
- [x] Statistic reads are spread across ticks according to a configurable operation budget and run through Bukkit scheduling.
|
||||
- [x] A player is not queued for a second statistic capture while an earlier capture remains queued or active.
|
||||
- [x] Statistics are partitioned by category and configured JSON size, with shared snapshot metadata and one-based part information.
|
||||
- [x] Empty statistic categories still emit an explicit part.
|
||||
- [x] Offline players are removed safely from queued or active capture work.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-001: Configure the event producer](us-001-configure-event-producer.md)
|
||||
- [US-002: Produce standard CloudEvents](us-002-produce-standard-cloud-events.md)
|
||||
- [Snapshot behavior](../../README.md#location-snapshots)
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-005: Deliver events durably"
|
||||
description: Persist events locally and deliver ordered, bounded batches without blocking the Minecraft server thread.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-005: Deliver events durably
|
||||
|
||||
As a **server operator**, I want captured events buffered durably and retried after ingest failures so that temporary outages do not silently lose activity.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] Events are persisted in an ordered local SQLite outbox before delivery.
|
||||
- [x] Persistence and HTTP delivery use dedicated workers rather than performing SQLite or network work on the Bukkit server thread.
|
||||
- [x] Delivery uses newline-delimited JSON batches bounded by configured event and byte limits.
|
||||
- [x] Delivery is requested periodically and may also be requested when an event-count or byte threshold is reached.
|
||||
- [x] Events are acknowledged and removed only after the ingest endpoint returns HTTP `202 Accepted`.
|
||||
- [x] Failed deliveries remain in the outbox and are retried with bounded exponential backoff.
|
||||
- [x] Stable event IDs provide at-least-once delivery semantics suitable for downstream deduplication.
|
||||
- [x] Shutdown waits for the shutdown event to be persisted and drains pending persistence work before closing the outbox.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-001: Configure the event producer](us-001-configure-event-producer.md)
|
||||
- [US-002: Produce standard CloudEvents](us-002-produce-standard-cloud-events.md)
|
||||
- [Delivery and durability](../../README.md#delivery-and-durability)
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-006: Build and release the plugin"
|
||||
description: Give maintainers repeatable Java builds, automated verification, and versioned Gitea releases.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-006: Build and release the plugin
|
||||
|
||||
As a **plugin maintainer**, I want automated builds and releases so that tested, correctly versioned plugin artifacts can be distributed consistently.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] The Gradle project compiles against Java 17 and the supported Spigot API.
|
||||
- [x] Automated tests run as part of the Gradle check lifecycle.
|
||||
- [x] Pushes and pull requests build and test the plugin in Gitea Actions.
|
||||
- [x] Pull requests validate conventional commit messages.
|
||||
- [x] CI stores a development JAR as a workflow artifact.
|
||||
- [x] Main-branch conventional commits drive semantic versioning.
|
||||
- [x] A successful release builds a versioned JAR and attaches it to the corresponding Gitea release.
|
||||
|
||||
## Related
|
||||
|
||||
- [Build and release documentation](../../README.md#releases)
|
||||
- [User-story catalog](index.md)
|
||||
+1
-1
@@ -1 +1 @@
|
||||
rootProject.name = "spigot-event-producer"
|
||||
rootProject.name = "purpur-event-producer"
|
||||
@@ -1,6 +1,6 @@
|
||||
name: SpigotEventProducer
|
||||
version: '${version}'
|
||||
main: games.dmg.spigotevents.SpigotEventProducerPlugin
|
||||
api-version: '26.2'
|
||||
api-version: '26.3'
|
||||
author: dmg.games
|
||||
description: Writes Minecraft CloudEvents to a durable outbox and delivers them to game-ingest-server.
|
||||
@@ -0,0 +1,256 @@
|
||||
package games.dmg.spigotevents;
|
||||
|
||||
import static org.junit.jupiter.api.Assertions.*;
|
||||
import static org.mockito.Mockito.*;
|
||||
|
||||
import com.google.gson.JsonParser;
|
||||
import io.papermc.paper.plugin.configuration.PluginMeta;
|
||||
import io.papermc.paper.plugin.provider.classloader.ConfiguredPluginClassLoader;
|
||||
import io.papermc.paper.plugin.provider.classloader.PluginClassLoaderGroup;
|
||||
import java.lang.reflect.Proxy;
|
||||
import java.net.URL;
|
||||
import java.net.URLClassLoader;
|
||||
import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
import java.sql.DriverManager;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.UUID;
|
||||
import java.util.jar.JarFile;
|
||||
import java.util.logging.Logger;
|
||||
import org.bukkit.Bukkit;
|
||||
import org.bukkit.Server;
|
||||
import org.bukkit.event.Listener;
|
||||
import org.bukkit.plugin.PluginDescriptionFile;
|
||||
import org.bukkit.plugin.PluginManager;
|
||||
import org.bukkit.plugin.java.JavaPlugin;
|
||||
import org.bukkit.scheduler.BukkitScheduler;
|
||||
import org.bukkit.scheduler.BukkitTask;
|
||||
import org.junit.jupiter.api.BeforeAll;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.junit.jupiter.api.io.TempDir;
|
||||
import org.mockito.MockedStatic;
|
||||
|
||||
/** Exercises the packaged entrypoint through Purpur's native plugin lifecycle. */
|
||||
class EventProducerLifecycleNativeTest {
|
||||
@TempDir Path temporaryDirectory;
|
||||
|
||||
@BeforeAll
|
||||
static void bootstrap() throws Exception {
|
||||
NativeRuntime.bootstrap();
|
||||
}
|
||||
|
||||
@Test
|
||||
void packagedPluginOwnsOneServerIdentityAndDurableLifecycleEvents() throws Exception {
|
||||
Path dataDirectory = temporaryDirectory.resolve("SpigotEventProducer");
|
||||
Files.createDirectories(dataDirectory);
|
||||
Files.writeString(dataDirectory.resolve("config.yml"), """
|
||||
server-name: "native-lifecycle"
|
||||
server-id: ""
|
||||
ingest-url: "http://127.0.0.1:1/events"
|
||||
send-interval-seconds: 86400
|
||||
snapshot-interval-seconds: 86400
|
||||
http-timeout-seconds: 1
|
||||
batch:
|
||||
max-events: 1000
|
||||
max-bytes: 900000
|
||||
dispatch-threshold:
|
||||
events: 1000
|
||||
bytes: 900000
|
||||
statistics:
|
||||
chunk-json-bytes: 200000
|
||||
operations-per-tick: 1000
|
||||
""");
|
||||
|
||||
List<Class<?>> listenerTypes = new ArrayList<>();
|
||||
List<BukkitTask> scheduledTasks = new ArrayList<>();
|
||||
PluginManager manager = port(PluginManager.class, (name, arguments) -> switch (name) {
|
||||
case "registerEvents" -> {
|
||||
listenerTypes.add(((Listener) arguments[0]).getClass());
|
||||
yield null;
|
||||
}
|
||||
case "disablePlugin" -> throw new AssertionError("Native lifecycle initialization failed");
|
||||
default -> throw new AssertionError("Unexpected plugin-manager call " + name);
|
||||
});
|
||||
BukkitScheduler scheduler = port(BukkitScheduler.class, (name, arguments) -> switch (name) {
|
||||
case "runTaskTimer" -> {
|
||||
BukkitTask task = mock(BukkitTask.class);
|
||||
scheduledTasks.add(task);
|
||||
yield task;
|
||||
}
|
||||
default -> throw new AssertionError("Unexpected scheduler call " + name);
|
||||
});
|
||||
Server server = port(Server.class, (name, arguments) -> switch (name) {
|
||||
case "getPluginManager" -> manager;
|
||||
case "getScheduler" -> scheduler;
|
||||
case "getOnlinePlayers" -> List.of();
|
||||
case "getLogger" -> Logger.getLogger("EventProducer lifecycle fixture");
|
||||
case "getWarningState" -> org.bukkit.Warning.WarningState.DEFAULT;
|
||||
case "getName" -> "Purpur";
|
||||
case "getVersion" -> "Purpur 2651 (MC: 26.3)";
|
||||
case "getMinecraftVersion" -> "26.3";
|
||||
case "getBukkitVersion" -> "26.3-R0.1-SNAPSHOT";
|
||||
case "isPrimaryThread" -> true;
|
||||
default -> throw new AssertionError("Unexpected server call " + name);
|
||||
});
|
||||
|
||||
try (MockedStatic<Bukkit> platform = mockStatic(Bukkit.class, call -> switch (call.getMethod().getName()) {
|
||||
case "getServer" -> server;
|
||||
case "getScheduler" -> scheduler;
|
||||
case "getOnlinePlayers" -> List.of();
|
||||
case "getPlayer" -> null;
|
||||
case "getLogger" -> Logger.getLogger("EventProducer lifecycle fixture");
|
||||
case "getVersion" -> "Purpur 2651 (MC: 26.3)";
|
||||
case "getMinecraftVersion" -> "26.3";
|
||||
case "getBukkitVersion" -> "26.3-R0.1-SNAPSHOT";
|
||||
case "isPrimaryThread" -> true;
|
||||
default -> call.callRealMethod();
|
||||
});
|
||||
var loader = new Loader(server, dataDirectory)) {
|
||||
JavaPlugin plugin = (JavaPlugin) loader.loadClass(
|
||||
"games.dmg.spigotevents.SpigotEventProducerPlugin").getConstructor().newInstance();
|
||||
|
||||
assertEquals("SpigotEventProducer", plugin.getName());
|
||||
assertEquals("26.3", loader.getConfiguration().getAPIVersion());
|
||||
assertFalse(plugin.isEnabled());
|
||||
plugin.setEnabled(true);
|
||||
try {
|
||||
assertTrue(plugin.isEnabled());
|
||||
assertEquals(List.of("GameEventListener"), listenerTypes.stream()
|
||||
.map(Class::getSimpleName).toList());
|
||||
assertEquals(2, scheduledTasks.size());
|
||||
assertTrue(Files.isRegularFile(dataDirectory.resolve("event-outbox.sqlite3")));
|
||||
} finally {
|
||||
plugin.setEnabled(false);
|
||||
}
|
||||
assertFalse(plugin.isEnabled());
|
||||
for (BukkitTask task : scheduledTasks) {
|
||||
verify(task).cancel();
|
||||
}
|
||||
}
|
||||
|
||||
var saved = org.bukkit.configuration.file.YamlConfiguration.loadConfiguration(
|
||||
dataDirectory.resolve("config.yml").toFile());
|
||||
UUID serverId = UUID.fromString(saved.getString("server-id"));
|
||||
assertEquals("native-lifecycle", saved.getString("server-name"));
|
||||
assertEquals("http://127.0.0.1:1/events", saved.getString("ingest-url"));
|
||||
|
||||
List<String> payloads = new ArrayList<>();
|
||||
try (var connection = DriverManager.getConnection(
|
||||
"jdbc:sqlite:" + dataDirectory.resolve("event-outbox.sqlite3").toAbsolutePath())) {
|
||||
try (var result = connection.createStatement().executeQuery(
|
||||
"SELECT payload FROM pending_events ORDER BY sequence")) {
|
||||
while (result.next()) {
|
||||
payloads.add(result.getString(1));
|
||||
}
|
||||
}
|
||||
var columns = new java.util.LinkedHashSet<String>();
|
||||
try (var result = connection.createStatement().executeQuery(
|
||||
"PRAGMA table_info(pending_events)")) {
|
||||
while (result.next()) {
|
||||
columns.add(result.getString("name"));
|
||||
}
|
||||
}
|
||||
assertEquals(java.util.Set.of(
|
||||
"sequence", "event_id", "payload", "byte_size", "created_at"), columns);
|
||||
}
|
||||
assertEquals(2, payloads.size());
|
||||
assertEquals(List.of(
|
||||
"games.dmg.minecraft.server.started",
|
||||
"games.dmg.minecraft.server.stopped"), payloads.stream()
|
||||
.map(JsonParser::parseString)
|
||||
.map(value -> value.getAsJsonObject().get("type").getAsString())
|
||||
.toList());
|
||||
for (String payload : payloads) {
|
||||
var event = JsonParser.parseString(payload).getAsJsonObject();
|
||||
assertEquals("1.0", event.get("specversion").getAsString());
|
||||
assertEquals("urn:minecraft-server:" + serverId, event.get("source").getAsString());
|
||||
assertEquals(serverId.toString(), event.get("serverid").getAsString());
|
||||
assertEquals("native-lifecycle", event.get("servername").getAsString());
|
||||
assertEquals("26.3", event.get("gameversion").getAsString());
|
||||
assertFalse(event.has("playerid"));
|
||||
}
|
||||
assertTrue(noLiveEventWorker());
|
||||
}
|
||||
|
||||
private static boolean noLiveEventWorker() {
|
||||
return Thread.getAllStackTraces().keySet().stream().noneMatch(thread -> thread.isAlive()
|
||||
&& (thread.getName().equals("spigot-event-persistence")
|
||||
|| thread.getName().equals("spigot-event-delivery")));
|
||||
}
|
||||
|
||||
static final class Loader extends URLClassLoader implements ConfiguredPluginClassLoader {
|
||||
private static final String PACKAGE = "games.dmg.spigotevents.";
|
||||
private final Server server;
|
||||
private final Path dataDirectory;
|
||||
private final Path jar = Path.of(System.getProperty("distribution.jar"));
|
||||
private final PluginDescriptionFile description;
|
||||
private JavaPlugin plugin;
|
||||
|
||||
Loader(Server server, Path dataDirectory) throws Exception {
|
||||
super(new URL[] {Path.of(System.getProperty("distribution.jar")).toUri().toURL()},
|
||||
EventProducerLifecycleNativeTest.class.getClassLoader());
|
||||
this.server = server;
|
||||
this.dataDirectory = dataDirectory;
|
||||
try (var archive = new JarFile(jar.toFile());
|
||||
var input = archive.getInputStream(archive.getJarEntry("plugin.yml"))) {
|
||||
description = new PluginDescriptionFile(input);
|
||||
}
|
||||
}
|
||||
|
||||
@Override
|
||||
protected Class<?> loadClass(String name, boolean resolve) throws ClassNotFoundException {
|
||||
synchronized (getClassLoadingLock(name)) {
|
||||
if (!name.startsWith(PACKAGE) || name.equals(getClass().getName())) {
|
||||
return super.loadClass(name, resolve);
|
||||
}
|
||||
Class<?> loaded = findLoadedClass(name);
|
||||
if (loaded == null) {
|
||||
loaded = findClass(name);
|
||||
}
|
||||
if (resolve) {
|
||||
resolveClass(loaded);
|
||||
}
|
||||
return loaded;
|
||||
}
|
||||
}
|
||||
|
||||
@Override
|
||||
public Class<?> loadClass(String name, boolean resolve, boolean global, boolean libraries)
|
||||
throws ClassNotFoundException {
|
||||
return loadClass(name, resolve);
|
||||
}
|
||||
|
||||
@Override public PluginMeta getConfiguration() { return description; }
|
||||
@Override public JavaPlugin getPlugin() { return plugin; }
|
||||
@Override public PluginClassLoaderGroup getGroup() { return null; }
|
||||
|
||||
@Override
|
||||
public void init(JavaPlugin created) {
|
||||
plugin = created;
|
||||
created.init(server, description, dataDirectory.toFile(), jar.toFile(), this, description,
|
||||
Logger.getLogger("EventProducer lifecycle fixture"));
|
||||
}
|
||||
}
|
||||
|
||||
@FunctionalInterface
|
||||
interface Call {
|
||||
Object invoke(String name, Object[] arguments);
|
||||
}
|
||||
|
||||
static <T> T port(Class<T> type, Call call) {
|
||||
return type.cast(Proxy.newProxyInstance(type.getClassLoader(), new Class<?>[] {type},
|
||||
(object, method, arguments) -> {
|
||||
Object[] values = arguments == null ? new Object[0] : arguments;
|
||||
if (method.getDeclaringClass() == Object.class) {
|
||||
return switch (method.getName()) {
|
||||
case "equals" -> object == values[0];
|
||||
case "hashCode" -> System.identityHashCode(object);
|
||||
case "toString" -> "Lifecycle port " + type.getSimpleName();
|
||||
default -> throw new AssertionError(method.getName());
|
||||
};
|
||||
}
|
||||
return call.invoke(method.getName(), values);
|
||||
}));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,76 @@
|
||||
package games.dmg.spigotevents;
|
||||
|
||||
import java.util.List;
|
||||
import java.util.stream.Stream;
|
||||
import net.minecraft.SharedConstants;
|
||||
import net.minecraft.commands.Commands;
|
||||
import net.minecraft.core.HolderLookup;
|
||||
import net.minecraft.core.LayeredRegistryAccess;
|
||||
import net.minecraft.core.Registry;
|
||||
import net.minecraft.core.RegistryAccess;
|
||||
import net.minecraft.resources.Identifier;
|
||||
import net.minecraft.resources.RegistryDataLoader;
|
||||
import net.minecraft.server.Bootstrap;
|
||||
import net.minecraft.server.MinecraftServer;
|
||||
import net.minecraft.server.RegistryLayer;
|
||||
import net.minecraft.server.ReloadableServerResources;
|
||||
import net.minecraft.server.packs.PackType;
|
||||
import net.minecraft.server.packs.repository.ServerPacksSource;
|
||||
import net.minecraft.server.packs.resources.MultiPackResourceManager;
|
||||
import net.minecraft.server.permissions.LevelBasedPermissionSet;
|
||||
import net.minecraft.tags.TagLoader;
|
||||
import net.minecraft.util.Util;
|
||||
import net.minecraft.world.flag.FeatureFlags;
|
||||
import net.minecraft.world.level.DataPackConfig;
|
||||
import net.minecraft.world.level.WorldDataConfiguration;
|
||||
import org.bukkit.craftbukkit.CraftRegistry;
|
||||
|
||||
/** Loads vanilla registries, tags, and components for native statistic discovery. */
|
||||
final class NativeRuntime {
|
||||
private static boolean initialized;
|
||||
|
||||
private NativeRuntime() {}
|
||||
|
||||
static synchronized void bootstrap() throws Exception {
|
||||
if (initialized) {
|
||||
return;
|
||||
}
|
||||
SharedConstants.tryDetectVersion();
|
||||
Bootstrap.bootStrap();
|
||||
var flags = FeatureFlags.VANILLA_SET;
|
||||
var packs = ServerPacksSource.createVanillaTrustedRepository();
|
||||
MinecraftServer.configurePackRepository(packs, new WorldDataConfiguration(new DataPackConfig(
|
||||
FeatureFlags.REGISTRY.toNames(flags).stream().map(Identifier::getPath).toList(), List.of()),
|
||||
flags), true, false);
|
||||
try (var resources = new MultiPackResourceManager(PackType.SERVER_DATA, packs.openAllSelected())) {
|
||||
LayeredRegistryAccess<RegistryLayer> layers = RegistryLayer.createRegistryAccess();
|
||||
List<Registry.PendingTags<?>> tags = TagLoader.loadTagsForExistingRegistries(
|
||||
resources, layers.getLayer(RegistryLayer.STATIC));
|
||||
List<HolderLookup.RegistryLookup<?>> lookups = TagLoader.buildUpdatedLookups(
|
||||
layers.getAccessForLoading(RegistryLayer.WORLD), tags);
|
||||
RegistryAccess.Frozen world = RegistryDataLoader.load(
|
||||
resources, lookups, RegistryDataLoader.WORLD_REGISTRIES,
|
||||
Util.backgroundExecutor()).join();
|
||||
layers = layers.replaceFrom(RegistryLayer.WORLD, world);
|
||||
RegistryAccess.Frozen dimensions = RegistryDataLoader.load(
|
||||
resources,
|
||||
Stream.concat(lookups.stream(), world.listRegistries()).toList(),
|
||||
RegistryDataLoader.DIMENSION_REGISTRIES,
|
||||
Util.backgroundExecutor()).join();
|
||||
layers = layers.replaceFrom(RegistryLayer.DIMENSIONS, dimensions);
|
||||
Class.forName(org.bukkit.Registry.class.getName());
|
||||
var datapack = ReloadableServerResources.loadResources(
|
||||
resources,
|
||||
layers,
|
||||
tags,
|
||||
flags,
|
||||
Commands.CommandSelection.DEDICATED,
|
||||
LevelBasedPermissionSet.ALL_PERMISSIONS,
|
||||
Util.backgroundExecutor(),
|
||||
Runnable::run).join();
|
||||
datapack.updateComponentsAndStaticRegistryTags();
|
||||
CraftRegistry.setMinecraftRegistry(layers.compositeAccess().freeze());
|
||||
}
|
||||
initialized = true;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,74 @@
|
||||
package games.dmg.spigotevents;
|
||||
|
||||
import static org.junit.jupiter.api.Assertions.*;
|
||||
|
||||
import java.io.DataInputStream;
|
||||
import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
import java.util.Map;
|
||||
import java.util.jar.JarFile;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.yaml.snakeyaml.Yaml;
|
||||
|
||||
class PurpurDistributionTest {
|
||||
@Test
|
||||
void packagesNewNameWithoutChangingRuntimeIdentityOrBundlingTheApi() throws Exception {
|
||||
Path artifact = Path.of(System.getProperty("distribution.jar"));
|
||||
String version = System.getProperty("distribution.version");
|
||||
assertEquals("purpur-event-producer-" + version + ".jar", artifact.getFileName().toString());
|
||||
try (var jar = new JarFile(artifact.toFile())) {
|
||||
Map<?, ?> metadata = new Yaml().load(jar.getInputStream(jar.getJarEntry("plugin.yml")));
|
||||
assertEquals(version, metadata.get("version"));
|
||||
assertEquals("SpigotEventProducer", metadata.get("name"), "Retain the data directory and persistent namespace");
|
||||
assertEquals("games.dmg.spigotevents.SpigotEventProducerPlugin", metadata.get("main"));
|
||||
assertEquals("26.3", metadata.get("api-version"));
|
||||
assertFalse(metadata.containsKey("permissions"));
|
||||
assertFalse(metadata.containsKey("commands"));
|
||||
assertFalse(metadata.containsKey("depend"));
|
||||
assertFalse(metadata.containsKey("softdepend"));
|
||||
assertNotNull(jar.getJarEntry("org/sqlite/JDBC.class"), "The SQLite driver must remain bundled");
|
||||
assertNotNull(jar.getJarEntry("META-INF/services/java.sql.Driver"));
|
||||
assertEquals("true", jar.getManifest().getMainAttributes().getValue("Multi-Release"));
|
||||
assertFalse(jar.stream().anyMatch(entry -> entry.getName().startsWith("org/bukkit/")
|
||||
|| entry.getName().startsWith("org/purpurmc/")
|
||||
|| entry.getName().startsWith("io/papermc/")
|
||||
|| entry.getName().startsWith("net/minecraft/")
|
||||
|| entry.getName().startsWith("com/destroystokyo/")
|
||||
|| entry.getName().startsWith("com/comphenix/protocol/")
|
||||
|| entry.getName().endsWith("Test.class")));
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
void pluginBytecodeTargetsJava25() throws Exception {
|
||||
try (var jar = new JarFile(System.getProperty("distribution.jar"))) {
|
||||
var pluginClasses = jar.stream()
|
||||
.filter(entry -> entry.getName().startsWith("games/dmg/spigotevents/")
|
||||
&& entry.getName().endsWith(".class"))
|
||||
.toList();
|
||||
assertFalse(pluginClasses.isEmpty());
|
||||
for (var entry : pluginClasses) {
|
||||
try (var bytecode = new DataInputStream(jar.getInputStream(entry))) {
|
||||
assertEquals(0xCAFEBABE, bytecode.readInt(), entry.getName());
|
||||
bytecode.readUnsignedShort();
|
||||
assertEquals(69, bytecode.readUnsignedShort(), entry.getName());
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
void releaseAndCiAgreeWithThePurpurDistributionNameAndToolchain() throws Exception {
|
||||
String build = Files.readString(Path.of("build.gradle.kts"));
|
||||
assertTrue(build.contains("purpur-api:26.3.build.2651-stable"));
|
||||
assertTrue(build.contains("https://api.purpurmc.org/v2/purpur/26.3/2651/download"));
|
||||
assertTrue(build.contains("0677c1febecfbc2e5b0a7f76abd647b70a1f38d3cbdf3dd6a82e401b4262a598"));
|
||||
assertFalse(build.contains("org.spigotmc:spigot-api"));
|
||||
for (String workflow : new String[] {"ci.yml", "release.yml"}) {
|
||||
String content = Files.readString(Path.of(".gitea/workflows", workflow));
|
||||
assertTrue(content.contains("java-version: 25"));
|
||||
assertTrue(content.contains("purpur-event-producer-"), workflow);
|
||||
assertFalse(content.contains("spigot-event-producer-"), workflow);
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user