From c76ea5b434f5de517e37b54a828486a6dd045781 Mon Sep 17 00:00:00 2001 From: Dylan Garvis Date: Sat, 8 Aug 2026 12:31:15 -0400 Subject: [PATCH] docs(design): add user story knowledge bundle --- design/index.md | 16 +++++++++++ design/log.md | 12 +++++++++ design/user-stories/index.md | 16 +++++++++++ .../us-001-configure-event-producer.md | 24 +++++++++++++++++ .../us-002-produce-standard-cloud-events.md | 25 +++++++++++++++++ .../us-003-capture-player-activity.md | 26 ++++++++++++++++++ .../us-004-capture-player-snapshots.md | 27 +++++++++++++++++++ .../us-005-deliver-events-durably.md | 27 +++++++++++++++++++ .../us-006-build-and-release-plugin.md | 25 +++++++++++++++++ 9 files changed, 198 insertions(+) create mode 100644 design/index.md create mode 100644 design/log.md create mode 100644 design/user-stories/index.md create mode 100644 design/user-stories/us-001-configure-event-producer.md create mode 100644 design/user-stories/us-002-produce-standard-cloud-events.md create mode 100644 design/user-stories/us-003-capture-player-activity.md create mode 100644 design/user-stories/us-004-capture-player-snapshots.md create mode 100644 design/user-stories/us-005-deliver-events-durably.md create mode 100644 design/user-stories/us-006-build-and-release-plugin.md diff --git a/design/index.md b/design/index.md new file mode 100644 index 0000000..3a3a674 --- /dev/null +++ b/design/index.md @@ -0,0 +1,16 @@ +--- +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) diff --git a/design/log.md b/design/log.md new file mode 100644 index 0000000..8b042c7 --- /dev/null +++ b/design/log.md @@ -0,0 +1,12 @@ +--- +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. diff --git a/design/user-stories/index.md b/design/user-stories/index.md new file mode 100644 index 0000000..4d8b9f7 --- /dev/null +++ b/design/user-stories/index.md @@ -0,0 +1,16 @@ +--- +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). diff --git a/design/user-stories/us-001-configure-event-producer.md b/design/user-stories/us-001-configure-event-producer.md new file mode 100644 index 0000000..9a8b2cc --- /dev/null +++ b/design/user-stories/us-001-configure-event-producer.md @@ -0,0 +1,24 @@ +--- +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) diff --git a/design/user-stories/us-002-produce-standard-cloud-events.md b/design/user-stories/us-002-produce-standard-cloud-events.md new file mode 100644 index 0000000..221a5e6 --- /dev/null +++ b/design/user-stories/us-002-produce-standard-cloud-events.md @@ -0,0 +1,25 @@ +--- +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) diff --git a/design/user-stories/us-003-capture-player-activity.md b/design/user-stories/us-003-capture-player-activity.md new file mode 100644 index 0000000..31292db --- /dev/null +++ b/design/user-stories/us-003-capture-player-activity.md @@ -0,0 +1,26 @@ +--- +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) diff --git a/design/user-stories/us-004-capture-player-snapshots.md b/design/user-stories/us-004-capture-player-snapshots.md new file mode 100644 index 0000000..4f4764c --- /dev/null +++ b/design/user-stories/us-004-capture-player-snapshots.md @@ -0,0 +1,27 @@ +--- +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] 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) diff --git a/design/user-stories/us-005-deliver-events-durably.md b/design/user-stories/us-005-deliver-events-durably.md new file mode 100644 index 0000000..f2a0263 --- /dev/null +++ b/design/user-stories/us-005-deliver-events-durably.md @@ -0,0 +1,27 @@ +--- +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) diff --git a/design/user-stories/us-006-build-and-release-plugin.md b/design/user-stories/us-006-build-and-release-plugin.md new file mode 100644 index 0000000..0a3ab97 --- /dev/null +++ b/design/user-stories/us-006-build-and-release-plugin.md @@ -0,0 +1,25 @@ +--- +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)