Skip to content

docs(core): clarify super endpoint metadata contract#56

Merged
robinbraemer merged 2 commits into
mainfrom
fm/connect-java-pr13-close-refresh-k8
Jul 13, 2026
Merged

docs(core): clarify super endpoint metadata contract#56
robinbraemer merged 2 commits into
mainfrom
fm/connect-java-pr13-close-refresh-k8

Conversation

@robinbraemer

Copy link
Copy Markdown
Member

Intent

Validate committed Connect-Java docs-only correction at 7e123f1. Scope is strictly README.md plus core/src/main/resources/config.yml and proxy-config.yml. Remove unsupported public API and endpoint-control promises while preserving super-endpoints as WatchService parent metadata. Do not add API/runtime/release/production changes, do not touch the separate connect website repository, and do not use --yes.

What Changed

  • Document super-endpoints as optional WatchService parent metadata sent through Connect-Endpoint-Parents in both configuration templates and ConnectConfig Javadoc.
  • Remove unsupported claims that Connect Java exposes public APIs for controlling endpoints or players.

Risk Assessment

✅ Low: The docs-only change is tightly scoped, accurately matches the implementation, and the previously conflicting Javadoc is now aligned with the config templates.

Testing

Scoped to test/evidence only: inspected the exact diff, exercised config-to-WatchService behavior end-to-end, ran targeted config tests, built and inspected all release JARs, compared runtime semantics, rendered the corrected JavaDoc, and cleaned the worktree; all change-specific checks passed, with one unrelated pre-existing :core:javadoc failure noted.

Evidence: WatchService parent-header handshake
Configured server input:
endpoint: docs-evidence
allow-offline-mode-players: false
super-endpoints:
  - pvp-endpoint
  - someones-hub
metrics:
  disabled: true
  uuid: 00000000-0000-0000-0000-000000000000
config-version: 1

Observed WatchService WebSocket handshake:
GET / HTTP/1.1
Connect-Endpoint: docs-evidence
Connect-Endpoint-Parents: pvp-endpoint, someones-hub

Result: each configured super-endpoint was transmitted as parent metadata.
No endpoint-control operation was invoked or exposed.
Evidence: Packaged documentation audit
Connect Java target: 341da45479f0a0c7d75c2d704c7eba649c44ff21

README claim audit
------------------
No matches were found for the removed unsupported promises:
- "There will be public APIs available"
- "manage your connected endpoints"
- "authorized to control this endpoint"
- "disconnect players from this endpoint"
- "send messages to players"

Packaged artifact identity
----------------------------
8a4c9a017a48e619bcca3113fda0070bda64d544a51e6f0dc606fdde3e55783e  connect-spigot.jar
5941cda189842db0e0c4eb4198deaa354cbd8d16d257a83dabf18d83fffcf383  connect-velocity.jar
d63e0d2de0c06fcd998cb5b2b2ddae1727d247da930f937f7ff794509469358e  connect-bungee.jar

connect-spigot.jar!/config.yml
--------------------------------
# Optional parent endpoint names sent to WatchService as Connect-Endpoint-Parents.
# This plugin does not expose a public endpoint-control API.
#
# You can add as many super endpoint names as you want.
#super-endpoints:
#  - pvp-endpoint
#  - someones-hub

connect-velocity.jar!/proxy-config.yml
----------------------------------------
# Optional parent endpoint names sent to WatchService as Connect-Endpoint-Parents.
# This plugin does not expose a public endpoint-control API.
#
# You can add as many super endpoint names as you want.
#super-endpoints:
#  - pvp-endpoint
#  - someones-hub

connect-bungee.jar!/proxy-config.yml
--------------------------------------
# Optional parent endpoint names sent to WatchService as Connect-Endpoint-Parents.
# This plugin does not expose a public endpoint-control API.
#
# You can add as many super endpoint names as you want.
#super-endpoints:
#  - pvp-endpoint
#  - someones-hub

Verification result
-------------------
The embedded config.yml and proxy-config.yml bytes in every built plugin JAR exactly match
the corresponding source templates. The unsupported claims are absent, while the documented
super-endpoints examples remain present as WatchService parent metadata.
Evidence: Rendered ConnectConfig JavaDoc
<!DOCTYPE HTML>
<html lang="en">
<head>
<!-- Generated by javadoc (21) on Mon Jul 13 10:44:54 CEST 2026 -->
<title>ConnectConfig</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="dc.created" content="2026-07-13">
<meta name="description" content="declaration: package: com.minekube.connect.config, class: ConnectConfig">
<meta name="generator" content="javadoc/ClassWriterImpl">
<link rel="stylesheet" type="text/css" href="../../../../stylesheet.css" title="Style">
<link rel="stylesheet" type="text/css" href="../../../../script-dir/jquery-ui.min.css" title="Style">
<script type="text/javascript" src="../../../../script.js"></script>
<script type="text/javascript" src="../../../../script-dir/jquery-3.7.1.min.js"></script>
<script type="text/javascript" src="../../../../script-dir/jquery-ui.min.js"></script>
</head>
<body class="class-declaration-page">
<script type="text/javascript">var pathtoroot = "../../../../";
loadScripts(document, 'script');</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<div class="flex-box">
<header role="banner" class="flex-header">
<nav role="navigation">
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="top-nav" id="navbar-top"><button id="navbar-toggle-button" aria-controls="navbar-top" aria-expanded="false" aria-label="Toggle navigation links"><span class="nav-bar-toggle-icon">&nbsp;</span><span class="nav-bar-toggle-icon">&nbsp;</span><span class="nav-bar-toggle-icon">&nbsp;</span></button>
<div class="skip-nav"><a href="#skip-navbar-top" title="Skip navigation links">Skip navigation links</a></div>
<ul id="navbar-top-firstrow" class="nav-list" title="Navigation">
<li><a href="package-summary.html">Package</a></li>
<li class="nav-bar-cell1-rev">Class</li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../index-all.html">Index</a></li>
<li><a href="../../../../help-doc.html#class">Help</a></li>
</ul>
<ul class="sub-nav-list-small">
<li>
<p>Summary:</p>
<ul>
<li><a href="#nested-class-summary">Nested</a></li>
<li><a href="#field-summary">Field</a></li>
<li><a href="#constructor-summary">Constr</a></li>
<li><a href="#method-summary">Method</a></li>
</ul>
</li>
<li>
<p>Detail:</p>
<ul>
<li><a href="#field-detail">Field</a></li>
<li><a href="#constructor-detail">Constr</a></li>
<li><a href="#method-detail">Method</a></li>
</ul>
</li>
</ul>
</div>
<div class="sub-nav">
<div id="navbar-sub-list">
<ul class="sub-nav-list">
<li>Summary:&nbsp;</li>
<li><a href="#nested-class-summary">Nested</a>&nbsp;|&nbsp;</li>
<li><a href="#field-summary">Field</a>&nbsp;|&nbsp;</li>
<li><a href="#constructor-summary">Constr</a>&nbsp;|&nbsp;</li>
<li><a href="#method-summary">Method</a></li>
</ul>
<ul class="sub-nav-list">
<li>Detail:&nbsp;</li>
<li><a href="#field-detail">Field</a>&nbsp;|&nbsp;</li>
<li><a href="#constructor-detail">Constr</a>&nbsp;|&nbsp;</li>
<li><a href="#method-detail">Method</a></li>
</ul>
</div>
<div class="nav-list-search"><a href="../../../../search.html">SEARCH</a>
<input type="text" id="search-input" disabled placeholder="Search">
<input type="reset" id="reset-button" disabled value="reset">
</div>
</div>
<!-- ========= END OF TOP NAVBAR ========= -->
<span class="skip-nav" id="skip-navbar-top"></span></nav>
</header>
<div class="flex-content">
<main role="main">
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="sub-title"><span class="package-label-in-type">Package</span>&nbsp;<a href="package-summary.html">com.minekube.connect.config</a></div>
<h1 title="Class ConnectConfig" class="title">Class ConnectConfig</h1>
</div>
<div class="inheritance" title="Inheritance Tree"><a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Object.html" title="class or interface in java.lang" class="external-link">java.lang.Object</a>
<div class="inheritance">com.minekube.connect.config.ConnectConfig</div>
</div>
<section class="class-description" id="class-description">
<hr>
<div class="type-signature"><span class="modifiers">public class </span><span class="element-name type-name-label">ConnectConfig</span>
<span class="extends-implements">extends <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Object.html" title="class or interface in java.lang" class="external-link">Object</a></span></div>
<div class="block">The global configuration file used in every platform. Some platforms have their own addition to
 the global configuration like <code>ProxyConnectConfig</code> for the proxies.</div>
</section>
<section class="summary">
<ul class="summary-list">
<!-- ======== NESTED CLASS SUMMARY ======== -->
<li>
<section class="nested-class-summary" id="nested-class-summary">
<h2>Nested Class Summary</h2>
<div class="caption"><span>Nested Classes</span></div>
<div class="summary-table three-column-summary">
<div class="table-header col-first">Modifier and Type</div>
<div class="table-header col-second">Class</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color"><code>static class&nbsp;</code></div>
<div class="col-second even-row-color"><code><a href="ConnectConfig.BedrockIdentityConfig.html" class="type-name-link" title="class in com.minekube.connect.config">ConnectConfig.BedrockIdentityConfig</a></code></div>
<div class="col-last even-row-color">&nbsp;</div>
<div class="col-first odd-row-color"><code>static class&nbsp;</code></div>
<div class="col-second odd-row-color"><code><a href="ConnectConfig.MetricsConfig.html" class="type-name-link" title="class in com.minekube.connect.config">ConnectConfig.MetricsConfig</a></code></div>
<div class="col-last odd-row-color">&nbsp;</div>
</div>
</section>
</li>
<!-- =========== FIELD SUMMARY =========== -->
<li>
<section class="field-summary" id="field-summary">
<h2>Field Summary</h2>
<div class="caption"><span>Fields</span></div>
<div class="summary-table three-column-summary">
<div class="table-header col-first">Modifier and Type</div>
<div class="table-header col-second">Field</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color"><code>private <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Boolean.html" title="class or interface in java.lang" class="external-link">Boolean</a></code></div>
<div class="col-second even-row-color"><code><a href="#allowOfflineModePlayers" class="member-name-link">allowOfflineModePlayers</a></code></div>
<div class="col-last even-row-color">
<div class="block">Whether cracked players should be allowed to join.</div>
</div>
<div class="col-first odd-row-color"><code>private <a href="ConnectConfig.BedrockIdentityConfig.html" title="class in com.minekube.connect.config">ConnectConfig.BedrockIdentityConfig</a></code></div>
<div class="col-second odd-row-color"><code><a href="#bedrockIdentity" class="member-name-link">bedrockIdentity</a></code></div>
<div class="col-last odd-row-color">
<div class="block">Verification settings for Moxy-signed Bedrock identity envelopes.</div>
</div>
<div class="col-first even-row-color"><code>private int</code></div>
<div class="col-second even-row-color"><code><a href="#configVersion" class="member-name-link">configVersion</a></code></div>
<div class="col-last even-row-color">&nbsp;</div>
<div class="col-first odd-row-color"><code>private boolean</code></div>
<div class="col-second odd-row-color"><code><a href="#debug" class="member-name-link">debug</a></code></div>
<div class="col-last odd-row-color">&nbsp;</div>
<div class="col-first even-row-color"><code>private <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/String.html" title="class or interface in java.lang" class="external-link">String</a></code></div>
<div class="col-second even-row-color"><code><a href="#defaultLocale" class="member-name-link">defaultLocale</a></code></div>
<div class="col-last even-row-color">&nbsp;</div>
<div class="col-first odd-row-color"><code>private final <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/String.html"

... [12383 bytes truncated] ...

</span>&nbsp;<span class="return-type"><a href="ConnectConfig.MetricsConfig.html" title="class in com.minekube.connect.config">ConnectConfig.MetricsConfig</a></span>&nbsp;<span class="element-name">metrics</span></div>
</section>
</li>
<li>
<section class="detail" id="debug">
<h3>debug</h3>
<div class="member-signature"><span class="modifiers">private</span>&nbsp;<span class="return-type">boolean</span>&nbsp;<span class="element-name">debug</span></div>
</section>
</li>
<li>
<section class="detail" id="configVersion">
<h3>configVersion</h3>
<div class="member-signature"><span class="modifiers">private</span>&nbsp;<span class="return-type">int</span>&nbsp;<span class="element-name">configVersion</span></div>
</section>
</li>
<li>
<section class="detail" id="endpoint">
<h3>endpoint</h3>
<div class="member-signature"><span class="modifiers">private final</span>&nbsp;<span class="return-type"><a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/String.html" title="class or interface in java.lang" class="external-link">String</a></span>&nbsp;<span class="element-name">endpoint</span></div>
<div class="block">The endpoint name of this instance that is registered when calling the watch service for
 listening for sessions for this endpoint.</div>
</section>
</li>
<li>
<section class="detail" id="allowOfflineModePlayers">
<h3>allowOfflineModePlayers</h3>
<div class="member-signature"><span class="modifiers">private</span>&nbsp;<span class="return-type"><a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Boolean.html" title="class or interface in java.lang" class="external-link">Boolean</a></span>&nbsp;<span class="element-name">allowOfflineModePlayers</span></div>
<div class="block">Whether cracked players should be allowed to join.
 If not set, Connect will automatically detect if the server allows cracked players.</div>
</section>
</li>
<li>
<section class="detail" id="bedrockIdentity">
<h3>bedrockIdentity</h3>
<div class="member-signature"><span class="modifiers">private</span>&nbsp;<span class="return-type"><a href="ConnectConfig.BedrockIdentityConfig.html" title="class in com.minekube.connect.config">ConnectConfig.BedrockIdentityConfig</a></span>&nbsp;<span class="element-name">bedrockIdentity</span></div>
<div class="block">Verification settings for Moxy-signed Bedrock identity envelopes.</div>
</section>
</li>
<li>
<section class="detail" id="superEndpoints">
<h3>superEndpoints</h3>
<div class="member-signature"><span class="modifiers">private</span>&nbsp;<span class="return-type"><a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/List.html" title="class or interface in java.util" class="external-link">List</a>&lt;<a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/String.html" title="class or interface in java.lang" class="external-link">String</a>&gt;</span>&nbsp;<span class="element-name">superEndpoints</span></div>
<div class="block">Optional parent endpoint names sent to WatchService as Connect-Endpoint-Parents.
 Connect Java does not expose a public endpoint-control API.</div>
</section>
</li>
<li>
<section class="detail" id="ENDPOINT_ENV">
<h3>ENDPOINT_ENV</h3>
<div class="member-signature"><span class="modifiers">private static final</span>&nbsp;<span class="return-type"><a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/String.html" title="class or interface in java.lang" class="external-link">String</a></span>&nbsp;<span class="element-name">ENDPOINT_ENV</span></div>
</section>
</li>
</ul>
</section>
</li>
<!-- ========= CONSTRUCTOR DETAIL ======== -->
<li>
<section class="constructor-details" id="constructor-detail">
<h2>Constructor Details</h2>
<ul class="member-list">
<li>
<section class="detail" id="&lt;init&gt;()">
<h3>ConnectConfig</h3>
<div class="member-signature"><span class="modifiers">public</span>&nbsp;<span class="element-name">ConnectConfig</span>()</div>
</section>
</li>
</ul>
</section>
</li>
<!-- ============ METHOD DETAIL ========== -->
<li>
<section class="method-details" id="method-detail">
<h2>Method Details</h2>
<ul class="member-list">
<li>
<section class="detail" id="getEndpoint()">
<h3>getEndpoint</h3>
<div class="member-signature"><span class="modifiers">public</span>&nbsp;<span class="return-type"><a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/String.html" title="class or interface in java.lang" class="external-link">String</a></span>&nbsp;<span class="element-name">getEndpoint</span>()</div>
</section>
</li>
<li>
<section class="detail" id="isProxy()">
<h3>isProxy</h3>
<div class="member-signature"><span class="modifiers">public</span>&nbsp;<span class="return-type">boolean</span>&nbsp;<span class="element-name">isProxy</span>()</div>
</section>
</li>
<li>
<section class="detail" id="getDefaultLocale()">
<h3>getDefaultLocale</h3>
<div class="member-signature"><span class="modifiers">public</span>&nbsp;<span class="return-type"><a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/String.html" title="class or interface in java.lang" class="external-link">String</a></span>&nbsp;<span class="element-name">getDefaultLocale</span>()</div>
</section>
</li>
<li>
<section class="detail" id="getMetrics()">
<h3>getMetrics</h3>
<div class="member-signature"><span class="modifiers">public</span>&nbsp;<span class="return-type"><a href="ConnectConfig.MetricsConfig.html" title="class in com.minekube.connect.config">ConnectConfig.MetricsConfig</a></span>&nbsp;<span class="element-name">getMetrics</span>()</div>
</section>
</li>
<li>
<section class="detail" id="isDebug()">
<h3>isDebug</h3>
<div class="member-signature"><span class="modifiers">public</span>&nbsp;<span class="return-type">boolean</span>&nbsp;<span class="element-name">isDebug</span>()</div>
</section>
</li>
<li>
<section class="detail" id="getConfigVersion()">
<h3>getConfigVersion</h3>
<div class="member-signature"><span class="modifiers">public</span>&nbsp;<span class="return-type">int</span>&nbsp;<span class="element-name">getConfigVersion</span>()</div>
</section>
</li>
<li>
<section class="detail" id="getAllowOfflineModePlayers()">
<h3>getAllowOfflineModePlayers</h3>
<div class="member-signature"><span class="modifiers">public</span>&nbsp;<span class="return-type"><a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Boolean.html" title="class or interface in java.lang" class="external-link">Boolean</a></span>&nbsp;<span class="element-name">getAllowOfflineModePlayers</span>()</div>
<div class="block">Whether cracked players should be allowed to join.
 If not set, Connect will automatically detect if the server allows cracked players.</div>
</section>
</li>
<li>
<section class="detail" id="getBedrockIdentity()">
<h3>getBedrockIdentity</h3>
<div class="member-signature"><span class="modifiers">public</span>&nbsp;<span class="return-type"><a href="ConnectConfig.BedrockIdentityConfig.html" title="class in com.minekube.connect.config">ConnectConfig.BedrockIdentityConfig</a></span>&nbsp;<span class="element-name">getBedrockIdentity</span>()</div>
<div class="block">Verification settings for Moxy-signed Bedrock identity envelopes.</div>
</section>
</li>
<li>
<section class="detail" id="getSuperEndpoints()">
<h3>getSuperEndpoints</h3>
<div class="member-signature"><span class="modifiers">public</span>&nbsp;<span class="return-type"><a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/List.html" title="class or interface in java.util" class="external-link">List</a>&lt;<a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/String.html" title="class or interface in java.lang" class="external-link">String</a>&gt;</span>&nbsp;<span class="element-name">getSuperEndpoints</span>()</div>
<div class="block">Optional parent endpoint names sent to WatchService as Connect-Endpoint-Parents.
 Connect Java does not expose a public endpoint-control API.</div>
</section>
</li>
</ul>
</section>
</li>
</ul>
</section>
<!-- ========= END OF CLASS DATA ========= -->
</main>
</div>
</div>
</body>
</html>
- Outcome: ⚠️ 1 warning across 1 run (9m55s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed ✅
  • ⚠️ core/src/main/resources/config.yml:11 - This correction leaves the opposite contract in ConnectConfig Javadoc (lines 63–66), which still claims super endpoints authorize player-control operations. Update that documentation too, or explicitly accept the conflicting public source documentation to preserve the three-file scope.

🔧 Fix: Align super-endpoint Javadoc with parent metadata contract
✅ Re-checked - no issues remain.

⚠️ **Test** - 1 warning
  • ⚠️ core/src/main/java/com/minekube/connect/util/ReflectionUtils.java:286 - The repository-wide :core:javadoc task fails on unchanged pre-existing documentation errors: malformed &lt;T&gt; tags in ReflectionUtils and an unresolved Velocity Property link in Utils. Neither file differs from the base commit, and targeted ConnectConfig JavaDoc rendering succeeds, so this does not invalidate the tested change.
  • git diff --name-status a5297786e557d1adde5d73025b31304c4d688142 341da45479f0a0c7d75c2d704c7eba649c44ff21 and full relevant-file diff inspection
  • CONNECT_WATCH_URL=ws://127.0.0.1:38137 CONNECT_EVIDENCE_PORT=38137 CONNECT_EVIDENCE_TEST_SRC=/var/folders/1y/cjgf53nj31n_dxsspqnjfjvc0000gn/T/no-mistakes-evidence/01KXD948G20CX9105PP9EARM52/test-src CONNECT_EVIDENCE_FILE=/var/folders/1y/cjgf53nj31n_dxsspqnjfjvc0000gn/T/no-mistakes-evidence/01KXD948G20CX9105PP9EARM52/watch-parent-headers.txt ./gradlew --no-daemon -I /var/folders/1y/cjgf53nj31n_dxsspqnjfjvc0000gn/T/no-mistakes-evidence/01KXD948G20CX9105PP9EARM52/external-test.init.gradle :core:test --tests com.minekube.connect.watch.SuperEndpointParentMetadataEvidenceTest --rerun-tasks
  • ./gradlew --no-daemon :core:test --tests com.minekube.connect.config.ConfigLoaderTest :spigot:shadowJar :velocity:shadowJar :bungee:shadowJar --rerun-tasks
  • Byte-for-byte cmp of config.yml and proxy-config.yml against copies embedded in all three built plugin JARs, plus rg audit for removed unsupported claims
  • Comment-stripped base/target diff comparisons for both YAML templates and ConnectConfig.java
  • javadoc -quiet -private -d <evidence>/connect-config-javadoc -classpath core/build/classes/java/main:api/build/classes/java/main core/build/generated/sources/delombok/java/main/com/minekube/connect/config/ConnectConfig.java
  • ./gradlew --no-daemon :core:javadoc --rerun-tasks via the combined verification command; failed only on unchanged pre-existing JavaDoc errors
  • ./gradlew --no-daemon clean and final git status --porcelain=v1 --untracked-files=all
✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

@robinbraemer robinbraemer merged commit 9946252 into main Jul 13, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant