feat(plugins): add Velocity proxy and Fabric/Forge/NeoForge/Paper integration mods

# Felis server-side plugins

These are the in-cluster and edge plugins for Felis. Every module **except the

lobby** ships the in-game first leg of the §10 account-link flow: a player who is already online

(so Mojang has verified their UUID) runs `/link`; the plugin asks felis-api to

mint a one-time code for that UUID and shows it in chat. The player then enters

the code on the web panel → **Account** page (the second leg), which binds the

code to their logged-in account. The web side is already built.

The **Velocity** module additionally carries the §11 domain-autostart routing

loop — recognizing each server's subdomain, registering backends dynamically,

waking a sleeping target and holding the player until it is ready. It is a full

proxy plugin, not just `/link`; see **[Velocity routing](#velocity-routing-§11)**

below. The Fabric / Forge / NeoForge mods are `/link`-only.

The **Paper** module is different in kind: it is the §12 lobby UI face. It ships

**no** `/link` and holds **no** felis-api token — it only paints the `/menu`

(and `/server`) chest GUI and speaks the `felis:control` plugin-message channel

to Velocity, which is the only side that ever talks to felis-api. See

**[Lobby menu](#lobby-menu-§12)** below.

| Module             | Platform                    | Target                              | Jar                          |

| ------------------ | --------------------------- | ----------------------------------- | ---------------------------- |

| `velocity/`        | Velocity proxy plugin       | velocity-api 3.3.0-SNAPSHOT         | `felis-velocity-0.2.0.jar`   |

| `fabric/`          | Fabric server mod           | MC 1.20.1 / fabric-loader 0.16.x    | `felis-fabric-0.1.0.jar`     |

| `forge/`           | Forge server mod            | MC 1.20.1 / Forge 47.3.0            | `felis-forge-0.1.0.jar`      |

| `neoforge/`        | NeoForge server mod         | MC 1.20.4 / NeoForge 20.4.251       | `felis-neoforge-0.1.0.jar`   |

| `paper/`           | Paper server plugin (lobby) | paper-api 1.21.4-R0.1-SNAPSHOT      | `felis-paper-0.1.0.jar`      |

| `shared/`          | *(not built on its own)*    | —                                   | source compiled into each    |

## Architecture

Each platform is an **independent** Gradle build with its own `settings.gradle`,

not one root project mixing loader plugins (the loader Gradle plugins have

conflicting Gradle-version requirements — see below). The platform-neutral link

core lives in `shared/src/main/java` and is pulled into every module via:

```groovy

sourceSets { main { java { srcDir '../shared/src/main/java' } } }

```

The core (`best.lolicon.felis.link`) has **zero third-party dependencies** — it

uses the JDK's `java.net.http.HttpClient` and a small hand-written JSON parser —

so there is nothing to shade and each jar is self-contained.

- `LinkClient` — `POST {apiBaseUrl}/api/v1/internal/account/link/code` with

  `Authorization: Bearer <service-token>` and body `{"mc_uuid":"<uuid>"}`;

  `201 → {code, expires_at}`, otherwise the `{error:{code,message}}` envelope.

- `LinkConfigLoader` — reads `FELIS_API_BASE_URL` / `FELIS_SERVICE_TOKEN` (env

  wins) or a `felis-link.properties` file written as a commented template on

  first run. **The API URL and service token are deployment inputs and are never

  compiled in.**

Threading: the command runs on the server thread; the HTTP call is dispatched to

a daemon single-thread executor and the reply is hopped back onto the server

thread, so a slow felis-api never stalls the tick loop. If config is missing the

plugin loads but never registers `/link`, so the server runs un-crippled.

All three mods use **official Mojang mappings**, so the MC class/method names are

identical across Fabric/Forge/NeoForge and the command handler is uniform; only

the `@Mod`/event-bus/config-dir glue differs per loader.

## Velocity routing (§11)

Velocity sits on the player-facing edge, off-cluster, so it is where

domain-autostart routing lives. Beyond `/link`, the Velocity plugin recognizes

each felis server by its subdomain, registers backends into Velocity's dynamic

server registry, and decides — per join — whether to send the player straight in,

wake a sleeping server and park them, or ask them to reconnect. It drives §9 wake

and §11 routing over the felis-api **internal** face (service-token auth), and

additionally terminates the `felis:control` plugin-message channel that backs the

§12 lobby menu — translating each lobby frame into the same wake/claim/status

calls, against the player's connection-derived identity rather than anything the

lobby claims. See **[Lobby menu](#lobby-menu-§12)** below.

Two preconditions gate routing, **each fails safe** (routing turns off, `/link`

keeps working):

- **online mode** — `online-mode=true` in `velocity.toml`. The autostartPolicy

  and allowlist gates trust Mojang-verified UUIDs; under offline mode the plugin

  refuses to route on spoofable identities and logs an error.

- **root-domain** — the deployment zone (e.g. `mc.example.net`). This is the only

  place the zone enters the proxy and is **never compiled in**; without it,

  host-based routing has nothing to match and stays off.

What it does when routing is active:

| Surface | Behavior |

| ------- | -------- |

| Backend registry | Polls `GET /api/v1/servers` every 15 s and reconciles Velocity's dynamic registry. A failed poll **keeps existing registrations** — a control-plane blip never deregisters live backends. Addresses are registered *unresolved* (a sleeping backend's Service DNS may not resolve yet). |

| Join (`PlayerChooseInitialServerEvent`) | Resolves `subdomain.<root-domain>` → server. **Ready** → send straight in. **Not ready + lobby** → park in the lobby, wake, and transfer when ready. **Not ready + no lobby** → disconnect with a "reconnect shortly" message, still firing the wake so the reconnect lands faster. |

| Waiting queue | One scheduled drain every 2 s polls status once per distinct waited-on server; a waiter drops out on transfer, on the player leaving, or after a 120 s timeout. |

| Wake gate | The wake is `POST /api/v1/internal/servers/{name}/wake` keyed on the player's online-mode UUID. **403** (policy refused) tells the player and stops; **429** (wake already in flight) keeps waiting. |

| Server-list ping (`ProxyPingEvent`) | Answers from the cached lifecycle view with a phase-aware MOTD (online / starting / sleeping) — **read-only, never wakes** anything. Mirroring each backend's own MOTD by background-pinging ready servers is a later slice. |

| Join report (`ServerConnectedEvent`) | Reports real joins to a felis backend via `POST …/join-event`, so the reaper sees activity and the player is auto-added to the server allowlist. |

| `/felis`, `/felis list` | Operator status: online-mode, root-domain, lobby, and the known server set with phase/ready. |

Velocity-only config keys (read from the same `felis-link.properties` / env as

`/link`; env wins):

| Key | Env | Meaning |

| --- | --- | ------- |

| `root-domain`  | `FELIS_ROOT_DOMAIN`  | Routing zone, e.g. `mc.example.net`. Unset → routing off. |

| `lobby-server` | `FELIS_LOBBY_SERVER` | A `velocity.toml` static server to park players in while a backend wakes. Unset → players are asked to reconnect instead. Its name must not collide with a felis server name. |

## Lobby menu (§12)

The `paper/` module is the lobby's player-facing face for §27 scenario 10

(`/menu → plugin msg → velocity → api → 共用等待队列 → ready 后 Connect`). It runs

on the Paper lobby server and gives players a chest GUI instead of a command

line: `/menu` (alias `/server`) opens a grid of one tile per configured server,

and clicking a tile wakes, claims, or joins that backend.

**Pure UI face.** The lobby holds no felis-api token, opens no HTTP connection,

and keeps no waiting queue. Every action it takes is a single frame on the

`felis:control` plugin-message channel; every piece of state it shows arrives as

a frame on the same channel. Velocity (the `ControlChannel`, above) is the only

side that talks to felis-api. This is enforced **physically** by the build, not

just by convention: the module's `sourceSets` include-filter compiles in only the

paper package plus the three codec classes, so the lobby jar contains exactly

five classes —

```

best/lolicon/felis/link/Control.class        (channel framing)

best/lolicon/felis/link/ControlFrame.class   (the frame model)

best/lolicon/felis/link/Json.class           (codec)

best/lolicon/felis/paper/FelisPaperPlugin.class

best/lolicon/felis/paper/MenuHolder.class

```

— and **no** `FelisApiClient`, `LinkClient`, or token-config class. If a codec

class ever grew a dependency on the API client, compilation would fail here

rather than silently widen the lobby's reach.

**Frames.** Upstream (lobby → velocity) carries `WakeRequest`, `ClaimRequest`,

and `StatusQuery`; downstream (velocity → lobby) carries `StatusUpdate`,

`TransferReady`, and `Error`. Opening the menu paints a grey "loading" tile per

server and fires a `StatusQuery` for each; the proxy answers with `StatusUpdate`

frames that repaint each tile by phase + ownership.

**Anti-spoof (§14).** The `player` field a lobby puts in a frame is **not**

trusted. Velocity derives the acting player and UUID from the `ServerConnection`

the plugin message arrived on, and the server-side autostartPolicy / ownership

gates authorize against that verified identity. The frame's `server` field is the

trusted payload — it only names *which* tile was clicked. A fully compromised

lobby therefore cannot act as another player or reach the API directly.

**Button rules** (the tile a click sends depends on the last `StatusUpdate`):

| Tile state | Label | Frame sent |

| ---------- | ----- | ---------- |

| ownerless + stopped (`claimable`) | **Claim & Start** | `ClaimRequest{server}` |

| owned + running (`ready`)         | **Join**          | `WakeRequest{server}` |

| owned + stopped                   | **Wake**          | `WakeRequest{server}` |

"Join" and "Wake" are the **same** upstream frame (`WakeRequest`) — only the

label differs; the proxy treats a wake of an already-running owned server as a

join. A refusal comes back as an `Error` frame (`not_linked` / `quota_exceeded` /

`already_claimed` → a friendly message), which is the only place a claim/quota/

policy failure surfaces to the player; readiness arrives as `TransferReady` just

before the proxy Connects them.

> **Status.** This slice is **code-complete and compile-verified** (paper jar

> builds green on a Java-21 toolchain; the velocity end compiles the full shared

> tree; the wire codec round-trips). It is **not** live-verified — there is no

> running Paper + Velocity + real players in this environment — so §27 scenario 10

> stays **FAIL (live-unverified)** in the spec matrix until it can be exercised

> end-to-end on a real deployment.

## Building

The platforms need different Gradle versions (a real, measured constraint, not a

preference):

| Module      | Gradle      | Why                                                              |

| ----------- | ----------- | --------------------------------------------------------------- |

| `velocity`  | 9.5.1 (system) | plain `java` plugin — no loader Gradle plugin                |

| `fabric`    | 8.8 (wrapper)  | loom 1.7.4 uses `Problems.forNamespace`, removed in Gradle 9 |

| `forge`     | 8.8 (wrapper)  | ForgeGradle 6 is Gradle-8-only                               |

| `neoforge`  | 8.14 (wrapper) | NeoGradle 7.1.38 requires Gradle API ≥ 8.14                  |

| `paper`     | 9.5.1 (system), **JDK 21 toolchain** | plain `java` plugin, but paper-api 1.21.4 is published for Java 21, so it declares a `JavaLanguageVersion.of(21)` toolchain — Gradle picks a detected JDK 21 to compile regardless of which JDK runs Gradle |

```bash

# Velocity — system Gradle is fine

gradle -p plugins/velocity build

# Paper — system Gradle too, but it compiles on a Java-21 toolchain (see table)

gradle -p plugins/paper build

# Fabric / Forge / NeoForge — use the per-module wrapper

plugins/fabric/gradlew   -p plugins/fabric   build

plugins/forge/gradlew    -p plugins/forge    build

plugins/neoforge/gradlew -p plugins/neoforge build

```

Requires JDK 17 — **except `paper`, which needs a Java-21 toolchain available to

Gradle** (paper-api 1.21.4 is a Java-21 artifact; the rest of the suite is Java

17). The first build of each mod downloads and remaps/decompiles Minecraft, so it

takes a few minutes; subsequent builds are fast. Jars land in each module's

`build/libs/`.

## Deploying

Drop the matching jar into the server/proxy mods or plugins directory, start

once to generate `config/felis-link.properties` (or `plugins/felis-link/…` on

Velocity), then set `api-base-url` and `service-token` — or provide

`FELIS_API_BASE_URL` and `FELIS_SERVICE_TOKEN` in the environment, which take

precedence. The service token is the same one felis-api compares for its

internal endpoints; treat it as a secret.

On **Velocity**, also set `root-domain` (and optionally `lobby-server`) in the

same file to turn on §11 routing, and make sure `online-mode=true` in

`velocity.toml` — without either, the proxy still serves `/link` but routing

stays off (see **[Velocity routing](#velocity-routing-§11)**). The config dir is

`plugins/felis-link/` because the plugin id is `felis-link` (kept stable across

the 0.1 → 0.2 jar so existing config carries over).

On the **Paper lobby** there is no token to set, because the lobby never talks to

felis-api. Drop `felis-paper-…jar` into `plugins/`, start once to generate

`plugins/FelisPaper/config.yml`, and list the felis server names (the CRD

`metadata.name`, not the display title) you want as tiles under `servers:`. The

lobby must sit behind the same Velocity proxy as the backends — it reaches the

control plane only through the proxy's `felis:control` terminus — so it needs no

`api-base-url` and no `service-token` of its own.

plugins {

    id 'fabric-loom' version '1.7.4'

    id 'java'

}

group = 'best.lolicon.felis'

version = '0.1.0'

// MC 1.20.1 is a Java-17 line — the ceiling this JDK can build.

java {

    sourceCompatibility = JavaVersion.VERSION_17

    targetCompatibility = JavaVersion.VERSION_17

}

repositories {

    mavenCentral()

    maven {

        name = 'Fabric'

        url = 'https://maven.fabricmc.net/'

    }

}

dependencies {

    minecraft 'com.mojang:minecraft:1.20.1'

    // Official Mojang mappings keep MC class/method names identical to the

    // Forge/NeoForge modules, so the command handlers stay near-uniform.

    mappings loom.officialMojangMappings()

    modImplementation 'net.fabricmc:fabric-loader:0.16.5'

    // fabric-command-api-v2 (CommandRegistrationCallback) ships in fabric-api.

    modImplementation 'net.fabricmc.fabric-api:fabric-api:0.92.2+1.20.1'

}

// The zero-dependency link core is compiled straight into the remapped jar.

sourceSets {

    main {

        java {

            srcDir '../shared/src/main/java'

        }

    }

}

tasks.withType(JavaCompile).configureEach {

    options.encoding = 'UTF-8'

}

distributionBase=GRADLE_USER_HOME

distributionPath=wrapper/dists

distributionUrl=https\://services.gradle.org/distributions/gradle-8.8-bin.zip

networkTimeout=10000

retries=0

retryBackOffMs=500

validateDistributionUrl=true

zipStoreBase=GRADLE_USER_HOME

zipStorePath=wrapper/dists

#!/bin/sh

#

# Copyright © 2015 the original authors.

#

# Licensed under the Apache License, Version 2.0 (the "License");

# you may not use this file except in compliance with the License.

# You may obtain a copy of the License at

#

#      https://www.apache.org/licenses/LICENSE-2.0

#

# Unless required by applicable law or agreed to in writing, software

# distributed under the License is distributed on an "AS IS" BASIS,

# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

# See the License for the specific language governing permissions and

# limitations under the License.

#

# SPDX-License-Identifier: Apache-2.0

#

##############################################################################

#

#   Gradle start up script for POSIX generated by Gradle.

#

#   Important for running:

#

#   (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is

#       noncompliant, but you have some other compliant shell such as ksh or

#       bash, then to run this script, type that shell name before the whole

#       command line, like:

#

#           ksh Gradle

#

#       Busybox and similar reduced shells will NOT work, because this script

#       requires all of these POSIX shell features:

#         * functions;

#         * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,

#           «${var#prefix}», «${var%suffix}», and «$( cmd )»;

#         * compound commands having a testable exit status, especially «case»;

#         * various built-in commands including «command», «set», and «ulimit».

#

#   Important for patching:

#

#   (2) This script targets any POSIX shell, so it avoids extensions provided

#       by Bash, Ksh, etc; in particular arrays are avoided.

#

#       The "traditional" practice of packing multiple parameters into a

#       space-separated string is a well documented source of bugs and security

#       problems, so this is (mostly) avoided, by progressively accumulating

#       options in "$@", and eventually passing that to Java.

#

#       Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,

#       and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;

#       see the in-line comments for details.

#

#       There are tweaks for specific operating systems such as AIX, CygWin,

#       Darwin, MinGW, and NonStop.

#

#   (3) This script is generated from the Groovy template

#       https://github.com/gradle/gradle/blob/3d91ce3b8caaf77ad09f381f43615b715b53f72c/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt

#       within the Gradle project.

#

#       You can find Gradle at https://github.com/gradle/gradle/.

#

##############################################################################

# Attempt to set APP_HOME

# Resolve links: $0 may be a link

app_path=$0

# Need this for daisy-chained symlinks.

while

    APP_HOME=${app_path%"${app_path##*/}"}  # leaves a trailing /; empty if no leading path

    [ -h "$app_path" ]

do

    ls=$( ls -ld "$app_path" )

    link=${ls#*' -> '}

    case $link in             #(

      /*)   app_path=$link ;; #(

      *)    app_path=$APP_HOME$link ;;

    esac

done

# This is normally unused

# shellcheck disable=SC2034

APP_BASE_NAME=${0##*/}

# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)

APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s\n' "$PWD" ) || exit

# Use the maximum available, or set MAX_FD != -1 to use that value.

MAX_FD=maximum

warn () {

    echo "$*"

} >&2

die () {

    echo

    echo "$*"

    echo

    exit 1

} >&2

# OS specific support (must be 'true' or 'false').

cygwin=false

msys=false

darwin=false

nonstop=false

case "$( uname )" in                #(

  CYGWIN* )         cygwin=true  ;; #(

  Darwin* )         darwin=true  ;; #(

  MSYS* | MINGW* )  msys=true    ;; #(

  NONSTOP* )        nonstop=true ;;

esac

# Determine the Java command to use to start the JVM.

if [ -n "$JAVA_HOME" ] ; then

    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then

        # IBM's JDK on AIX uses strange locations for the executables

        JAVACMD=$JAVA_HOME/jre/sh/java

    else

        JAVACMD=$JAVA_HOME/bin/java

    fi

    if [ ! -x "$JAVACMD" ] ; then

        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME

Please set the JAVA_HOME variable in your environment to match the

location of your Java installation."

    fi

else

    JAVACMD=java

    if ! command -v java >/dev/null 2>&1

    then

        die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.

Please set the JAVA_HOME variable in your environment to match the

location of your Java installation."

    fi

fi

# Increase the maximum file descriptors if we can.

if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then

    case $MAX_FD in #(

      max*)

        # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.

        # shellcheck disable=SC2039,SC3045

        MAX_FD=$( ulimit -H -n ) ||

            warn "Could not query maximum file descriptor limit"

    esac

    case $MAX_FD in  #(

      '' | soft) :;; #(

      *)

        # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.

        # shellcheck disable=SC2039,SC3045

        ulimit -n "$MAX_FD" ||

            warn "Could not set maximum file descriptor limit to $MAX_FD"

    esac

fi

# Collect all arguments for the java command, stacking in reverse order:

#   * args from the command line

#   * the main class name

#   * -classpath

#   * -D...appname settings

#   * --module-path (only if needed)

#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.

# For Cygwin or MSYS, switch paths to Windows format before running java

if "$cygwin" || "$msys" ; then

    APP_HOME=$( cygpath --path --mixed "$APP_HOME" )

    JAVACMD=$( cygpath --unix "$JAVACMD" )

    # Now convert the arguments - kludge to limit ourselves to /bin/sh

    for arg do

        if

            case $arg in                                #(

              -*)   false ;;                            # don't mess with options #(

              /?*)  t=${arg#/} t=/${t%%/*}              # looks like a POSIX filepath

                    [ -e "$t" ] ;;                      #(

              *)    false ;;

            esac

        then

            arg=$( cygpath --path --ignore --mixed "$arg" )

        fi

        # Roll the args list around exactly as many times as the number of

        # args, so each arg winds up back in the position where it started, but

        # possibly modified.

        #

        # NB: a `for` loop captures its iteration list before it begins, so

        # changing the positional parameters here affects neither the number of

        # iterations, nor the values presented in `arg`.

        shift                   # remove old arg

        set -- "$@" "$arg"      # push replacement arg

    done

fi

# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.

DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'

# Collect all arguments for the java command:

#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,

#     and any embedded shellness will be escaped.

#   * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be

#     treated as '${Hostname}' itself on the command line.

set -- \

        "-Dorg.gradle.appname=$APP_BASE_NAME" \

        -jar "$APP_HOME/gradle/wrapper/gradle-wrapper.jar" \

        "$@"

# Stop when "xargs" is not available.

if ! command -v xargs >/dev/null 2>&1

then

    die "xargs is not available"

fi

# Use "xargs" to parse quoted args.

#

# With -n1 it outputs one arg per line, with the quotes and backslashes removed.

#

# In Bash we could simply go:

#

#   readarray ARGS < <( xargs -n1 <<<"$var" ) &&

#   set -- "${ARGS[@]}" "$@"

#

# but POSIX shell has neither arrays nor command substitution, so instead we

# post-process each arg (as a line of input to sed) to backslash-escape any

# character that might be a shell metacharacter, then use eval to reverse

# that process (while maintaining the separation between arguments), and wrap

# the whole thing up as a single "set" statement.

#

# This will of course break if any of these variables contains a newline or

# an unmatched quote.

#

eval "set -- $(

        printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |

        xargs -n1 |

        sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' |

        tr '\n' ' '

    )" '"$@"'

exec "$JAVACMD" "$@"