Raisu Developer Guide

repositories {
    maven("https://jitpack.io")
}

dependencies {
    implementation("com.github.Reddishye.raisu:raisu-paper:v1.0.0")
}

public final class MyPlugin extends JavaPlugin {

    private Raisu raisu;

    @Override
    public void onEnable() {
        raisu = PaperRaisu.create(this);
    }

    public void onDebugCommand() {
        EncodeConfig config = EncodeConfig.builder()
                .provider(PasteProvider.PASTES_DEV)
                .build();

        String shortcode = raisu.encode(raisu.snapshot(), config);
        getLogger().info("Debug snapshot: https://yoursite.com/view#" + shortcode);
    }
}

raisu = SpigotRaisu.create(this);   // same API, no raisu:performance category

RaisuPlatform platform = new RaisuPlatform() {
    @Override public String serverVersion() { return "MyApp 1.0"; }
};

Raisu raisu = Raisu.create(platform);

Category myCategory = Category.builder()
        .id("my:info")
        .name(Component.text("My Info"))
        .icon("📦")
        .priority(10)
        .add(/* component */)
        .build();

raisu.register(myCategory);

raisu.registerProvider("my:stats", () -> {
    int activeTasks = scheduler.getActiveTasks();
    return Category.builder()
            .id("my:stats")
            .name(Component.text("Task Stats"))
            .icon("⚙️")
            .priority(10)
            .add(/* KV, Table, etc. */)
            .build();
});

raisu = PaperRaisu.builder(this)
        // Add your own alongside the defaults:
        .addCategory(myStaticCategory)
        .addProvider("my:economy", () -> buildEconomyCategory())
        // Or start from scratch (disables all raisu:* built-ins):
        // .excludeDefaultCategories()
        .build();

import com.redactado.raisu.core.component.*;

new KeyValueImpl("Server TPS", "19.95")
new TextImpl("Everything looks healthy.")
new ProgressBarImpl("Memory", usedMb, maxMb)
new TableImpl(List.of("Name", "Value"), rows)
new ListImpl(List.of("item1", "item2"))
new GraphImpl("TPS History", dataPoints)     // dataPoints = LinkedHashMap
new TreeImpl(new TreeNodeImpl("root", children))

// Quick — includes all registered categories and providers:
Snapshot snap = raisu.snapshot();

// Manual — build exactly what you want:
Snapshot snap = raisu.snapshotBuilder()
        .serverVersion("MyApp 2.0")
        .javaVersion(System.getProperty("java.version"))
        .addCategory(myCategory)
        .build();

EncodeConfig config = EncodeConfig.builder()
        .provider(PasteProvider.PASTES_DEV)   // or HASTEBIN
        .build();

String shortcode = raisu.encode(snap, config);
// Share as: https://yoursite.com/view#<shortcode>

raisu.unregister("my:info");           // remove static category
raisu.unregisterProvider("my:stats");  // remove dynamic provider

public interface RaisuPlatform {
    String serverVersion();                        // required
    default String javaVersion()  { ... }          // optional override
    default String platformName() { ... }          // optional override
    default Logger logger()       { ... }          // optional override
    default void logInfo(String msg)    { ... }    // derived from logger()
    default void logWarning(String msg) { ... }    // derived from logger()
}

GET /api/snapshot?code=AABB...

{
  "version": 2,
  "timestamp": 1734123456789,
  "serverVersion": "Paper 1.21.4",
  "javaVersion": "21.0.3",
  "categories": [
    {
      "id": "raisu:system",
      "name": "{"text":"System"}",
      "icon": "💻",
      "priority": 0,
      "components": [
        {
          "type": "KEY_VALUE",
          "data": { "key": "OS", "value": "Linux 6.1.0" }
        },
        {
          "type": "STAT",
          "data": {
            "label": "Uptime",
            "value": "14",
            "unit": "days",
            "trend": null,
            "description": null
          }
        }
      ]
    }
  ]
}

// RAISU — MACHINE-READABLE LIBRARY SUMMARY
// =========================================
// Library: Raisu
// Type: Java/Kotlin library for Minecraft server debug snapshots
// Language: Java 17+ (primary API), Kotlin-friendly
// Repository: JVM — Gradle/Maven

// PURPOSE:
// Raisu lets you capture structured server state as a "snapshot" —
// a collection of named categories, each containing typed data
// components. The snapshot is serialized (MessagePack), encrypted
// (AES-128-CBC), uploaded to a paste service, and shared as a
// compact base64url shortcode. The companion web frontend decrypts
// and renders it entirely in the browser (no server-side rendering).

// INTEGRATION POINTS:
// - PaperRaisu.create(plugin)   → Paper/Spigot plugin entry point
// - SpigotRaisu.create(plugin)  → Spigot/Bukkit entry point
// - Raisu.create(platform)      → Standalone / custom platform
// - raisu.snapshot()            → Collect all registered categories
// - raisu.encode(snap, config)  → Serialize, encrypt, upload → shortcode
// - raisu.register(category)    → Register a static Category
// - raisu.registerProvider(id, () -> category) → Register a dynamic provider

// GRADLE DEPENDENCY (Paper):
// implementation("com.redactado:raisu-paper:1.0.0-SNAPSHOT")

// PASTE PROVIDERS:
// PasteProvider.PASTES_DEV  → https://api.pastes.dev
// PasteProvider.HASTEBIN    → https://hastebin.com

// SHORTCODE FORMAT (base64url):
// byte[0]          = provider ID (0=pastes.dev, 1=hastebin)
// byte[1]          = paste key length
// byte[2..2+kLen]  = paste key (ASCII)
// byte[2+kLen..]   = raw AES-128 key (16 bytes)

// PAYLOAD SCHEMA (MessagePack map, pseudo-TypeScript notation)
// ============================================================

interface Payload {
  version: int            // 0 (absent=legacy), 1, 2
  timestamp: long         // Unix epoch ms
  serverVersion: string   // e.g. "Paper 1.21.4"
  javaVersion: string     // e.g. "21.0.3"
  categories: Category[]  // ordered by priority asc
}

interface Category {
  id: string              // e.g. "raisu:system", "my:custom"
  name: string            // Adventure Component JSON or plain string
  icon: string            // emoji character
  priority: int           // lower = appears first
  components: Component[] // ordered array of component objects
}

interface Component {
  type: string            // wire type constant (see below)
  data: object            // type-specific payload (see Component Reference)
}

// CATEGORY NAME FORMATS (Adventure Component JSON):
// Plain string:  "My Category"
// JSON string:   ""My Category""
// Object:        {"text": "My Category"}
// Array:         [{"text": "My Category"}]

// SHORTCODE DECODE (TypeScript/browser)
function decodeShortcode(shortcode: string): { providerId, pasteKey, aesKey } {
  // 1. base64url → bytes (replace - with +, _ with /)
  // 2. bytes[0]  = provider ID
  // 3. bytes[1]  = paste key byte length (kLen)
  // 4. bytes[2..2+kLen] = UTF-8 paste key
  // 5. bytes[2+kLen..]  = raw 16-byte AES-128 key
}

// DECRYPTION (WebCrypto)
// algorithm: AES-CBC
// key length: 128 bits (16 bytes)
// IV: first 16 bytes of the encrypted blob
// ciphertext: remaining bytes after IV

// ── V1 COMPONENT TYPES ───────────────────────────────────────────────────────

KEY_VALUE    { key: string, value: string }
TEXT         { content: string }
TABLE        { headers: string[], rows: string[][] }
LIST         { items: string[] }
PROGRESS_BAR { label: string, current: double, max: double }
GRAPH        { title: string, dataPoints: Map<string, double> }  // ordered map
TREE         { root: TreeNode }
// TreeNode: { label: string, children: TreeNode[] }

// ── V2 SHARED ENUMS ──────────────────────────────────────────────────────────
// All serialized as their .name() string (uppercase).

// Severity: DEFAULT | INFO | SUCCESS | WARNING | ERROR
// Gap:      NONE | SMALL | MEDIUM | LARGE
// Alignment: START | CENTER | END | STRETCH

// ── V2 LAYOUT TYPES ──────────────────────────────────────────────────────────
// Layout containers hold children: Component[]. Nesting is fully supported.
// "children" is the wire field name (NOT "components").

COLUMN { alignment: Alignment, gap: Gap, children: Component[] }
ROW    { alignment: Alignment, gap: Gap, wrap: boolean, children: Component[] }
GRID   { columns: int, gap: Gap, children: Component[] }       // columns: 1..4
PANEL  { title: string, collapsible: boolean, collapsed: boolean, children: Component[] }

// ── V2 DISPLAY TYPES ─────────────────────────────────────────────────────────
// "?" = nullable — packed as msgpack nil when absent.
// Map header size is always fixed (same number of keys regardless of nulls).

BADGE      { text: string, severity: Severity }
STAT       { label: string, value: string, unit: string|nil, trend: double|nil, description: string|nil }
           // trend: positive = up (green), negative = down (red), null = hidden
ALERT      { severity: Severity, title: string|nil, message: string }
CODE_BLOCK { content: string, language: string }
LOG_VIEW   { entries: LogEntry[] }
           // LogEntry: { timestamp: int64 (epoch ms), severity: Severity, message: string }
TIMELINE   { events: TimelineEvent[] }
           // TimelineEvent: { label: string, description: string, timestamp: int64 (epoch ms) }
SPARKLINE  { label: string, values: double[], unit: string|nil }  // oldest → newest
GAUGE      { label: string, current: double, max: double, unit: string|nil }
           // min is always 0; pct = current / max
LINK       { label: string, url: string }
           // http/https URLs are opened in a new tab automatically
IFRAME     { url: string, title: string|nil, height: int|nil }
           // height defaults to 400 px; frame is sandboxed

// ── GAUGE COLOUR THRESHOLDS ───────────────────────────────────────────────────
// pct = current / max
// pct > 0.80 → red   (critical)
// pct > 0.60 → amber (warning)
// else       → violet (normal)

// ── LOG_VIEW SEVERITY COLOURS ─────────────────────────────────────────────────
// ERROR   → red-400
// WARNING → amber-400
// SUCCESS → emerald-400
// INFO    → blue-400
// DEFAULT → zinc-400

{
  "version": 2,
  "timestamp": 1700000000000,
  "serverVersion": "Paper 1.21.4",
  "javaVersion": "21.0.3",
  "categories": [
    {
      "id": "my:status",
      "name": "Server Status",
      "icon": "🖥️",
      "priority": 1,
      "components": [
        { "type": "BADGE",  "data": { "text": "Online", "severity": "SUCCESS" } },
        { "type": "STAT",   "data": { "label": "Players", "value": "42", "unit": null, "trend": 3.0, "description": null } },
        { "type": "GAUGE",  "data": { "label": "Heap", "current": 512, "max": 2048, "unit": "MB" } },
        { "type": "ALERT",  "data": { "severity": "WARNING", "title": null, "message": "High GC pressure detected." } }
      ]
    }
  ]
}