From e8863363c90bb544944e3c53fe7e39dd1f85205c Mon Sep 17 00:00:00 2001 From: Ben Date: Thu, 10 Sep 2026 10:17:45 -0600 Subject: [PATCH 1/8] docs: add HTTP proxy transport development guide --- .wikijs/navigation.json | 10 ++ VotingPlugin/Proxy-Setups.md | 1 + VotingPlugin/proxy-method-HTTP.md | 182 ++++++++++++++++++++++++++++++ sidebar.md | 1 + 4 files changed, 194 insertions(+) create mode 100644 VotingPlugin/proxy-method-HTTP.md diff --git a/.wikijs/navigation.json b/.wikijs/navigation.json index 71d210e..04dbf23 100644 --- a/.wikijs/navigation.json +++ b/.wikijs/navigation.json @@ -165,6 +165,16 @@ "visibilityMode": "all", "visibilityGroups": [] }, + { + "id": "c847024d-f7ea-4df5-a2d6-51b5ad8b18df", + "kind": "link", + "label": "HTTP Proxy Transport", + "icon": "mdi-chevron-right", + "targetType": "page", + "target": "/en/VotingPlugin/proxy-method-HTTP", + "visibilityMode": "all", + "visibilityGroups": [] + }, { "id": "251cebdd-779c-4750-b750-57e3e0aebfa0", "kind": "divider", diff --git a/VotingPlugin/Proxy-Setups.md b/VotingPlugin/Proxy-Setups.md index c3e9a34..4942aab 100644 --- a/VotingPlugin/Proxy-Setups.md +++ b/VotingPlugin/Proxy-Setups.md @@ -36,6 +36,7 @@ VotingPlugin supports multiple communication methods between your **proxy (Bunge | Method | Description | |--------|-------------| | [PLUGINMESSAGING](Proxy-method-PLUGINMESSAGING) | Uses the proxy plugin-message channel; this is the 7.1.1 release default. | +| [HTTP](proxy-method-HTTP) | Development-only transport using one proxy TLS listener and outbound mutually authenticated backend connections. VotingPlugin 7.1.1 does not include it. | | [REDIS](proxy-method-REDIS) | Uses a private Redis service for cross-server messages. | | [MQTT](proxy-method-MQTT) | Uses an MQTT broker for cross-server messages. | | [SOCKETS](proxy-method-SOCKETS) | Uses direct TCP socket connections and requires explicit peer addresses, secrets, and firewall rules. | diff --git a/VotingPlugin/proxy-method-HTTP.md b/VotingPlugin/proxy-method-HTTP.md new file mode 100644 index 0000000..83aa044 --- /dev/null +++ b/VotingPlugin/proxy-method-HTTP.md @@ -0,0 +1,182 @@ +--- +title: HTTP Proxy Transport +description: Connect VotingPlugin backends to one secure proxy listener without opening a port on every backend +published: true +date: 2026-09-10T00:00:00.000Z +tags: +editor: markdown +dateCreated: 2026-09-02T00:00:00.000Z +--- + +# HTTP Proxy Transport + +> **Development-build feature:** `BungeeMethod: HTTP` is not available in the latest public VotingPlugin release, **7.1.1**. This page currently requires the unmerged [VotingPlugin PR #1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`058e8e7a`](https://github.com/BenCodez/VotingPlugin/commit/058e8e7aa9ffecdd2026faff2ce1d1a3e3445f80) or later. Release users do not have the `HTTP` method, its configuration keys, or its proxy commands. +{.is-warning} + +The HTTP proxy method gives every backend an **outbound**, encrypted connection to one HTTPS listener on the BungeeCord or Velocity proxy. Only the proxy listener port needs to be reachable. Backend servers do not expose an HTTP transport port. + +HTTP transports VotingPlugin's normal proxy messages. It does not receive public Votifier votes, replace VotifierPlus, change player UUID handling, or change reward and offline-vote rules. Configure the public vote listener and VotingPlugin vote sites normally. + +## Architecture + +```mermaid +flowchart LR + V[Vote site] -->|Votifier vote| L[VotifierPlus listener] + L --> P[VotingPlugin on proxy] + P -->|One TLS 1.3 listener| E[Public endpoint and proxy port] + B1[Backend: lobby] -->|Outbound HTTPS + client certificate| E + B2[Backend: survival] -->|Outbound HTTPS + client certificate| E + B3[Other backends] -->|Outbound HTTPS + client certificate| E +``` + +The proxy generates a private certificate authority, proxy identity, and short-lived enrollment codes. Each backend enrolls once and receives a client identity bound to its configured `Server` name. + +## Before you start + +- Install the same compatible VotingPlugin build on the proxy and every backend. +- Give every backend a unique, stable `Server` value in `BungeeSettings.yml`. +- Choose one hostname that resolves to the proxy from every backend. +- Allow one TCP port to the proxy listener. Do not open an HTTP transport port on a backend. +- Ensure the listener can terminate TLS itself. A reverse proxy or CDN must not terminate this connection because mutual TLS is part of the protocol. +- Back up the proxy and backend VotingPlugin data folders before changing methods. + +Use a TCP/L4 proxy only when it passes the TLS connection through unchanged. For an Internet-facing listener, also use host or provider firewall controls; the application cannot absorb a volumetric link or TCP flood. + +## Configure the proxy + +In the proxy's `bungeeconfig.yml`, select HTTP and configure its listener: + +```yaml +BungeeMethod: HTTP + +HTTP: + Host: '0.0.0.0' + Port: 1297 + PublicEndpoint: 'https://proxy.example.com:1297/' +``` + +- `Host` is the local interface on which VotingPlugin listens. Use a narrower address when the network design permits it. +- `Port` defaults to `1297` in the development configuration. +- `PublicEndpoint` has no usable default. Set the HTTPS origin that every backend can reach directly. + +`PublicEndpoint` must point to this VotingPlugin listener. Do not use an HTTP URL, a path below the origin, embedded credentials, a fragment, or a TLS-terminating CDN/reverse proxy. + +Restart the proxy after selecting the method or changing listener settings. + +## Enroll each backend + +On the running proxy, create a separate code for the exact backend name: + +```text +/votingpluginproxy httpcode lobby-1 +``` + +Connection codes expire after 15 minutes, work once, and are bound to one backend name. Treat a fresh code like a temporary password: send it privately and do not place it in public logs, tickets, screenshots, or chat rooms. + +The proxy command requires `votingpluginproxy.admin`. Velocity also registers the short `/vpp` alias; use `/votingpluginproxy` in portable instructions for both proxy platforms. + +On that backend, set the same method and paste its code into `BungeeSettings.yml`: + +```yaml +UseBungeecord: true +Server: lobby-1 +BungeeMethod: HTTP + +HTTP: + ConnectionCode: 'paste-code-here' +``` + +Restart the backend. After enrollment succeeds, remove `ConnectionCode` from the configuration and restart normally. The generated client identity remains in the backend's VotingPlugin data folder and is reused automatically. + +Repeat the process with a new code for every backend. Never reuse one backend's code, data folder, or client identity on another server. + +## Verify the setup + +1. Confirm the proxy reports the HTTP method without listener or endpoint errors. +2. Confirm each backend enrolls under its exact configured `Server` name. +3. Remove the temporary connection code after successful enrollment. +4. Run the proxy status command and confirm every expected backend responds. +5. Send a real test vote through the public Votifier listener. +6. Test an online player and an offline player, then verify the normal cache and reward behavior on the intended backend servers. +7. Restart the proxy and one backend to verify that enrolled identities and pending deliveries recover. + +A successful HTTP connection test does not prove that a vote site, Votifier token, vote-site mapping, database, reward, or player-name policy is correct. Always finish with a real end-to-end vote. + +## Delivery and offline behavior + +- Proxy-to-backend messages remain in a bounded, owner-only durable proxy queue until the backend acknowledgement is durably applied. +- The backend journals callback states so a completed callback can be acknowledged after restart without automatically running it twice. +- A callback interrupted at an ambiguous point is quarantined for operator investigation instead of being automatically replayed or silently acknowledged. +- Backend-to-proxy delivery retains VotingPlugin's existing bounded in-process retry behavior; application vote caching remains responsible for vote durability in that direction. +- `SendVotesToAllServers`, `BlockedServers`, `WhiteListedServers`, `WaitForUserOnline`, dedicated-proxy presence, offline caching, UUID mode, and `BedrockPlayerPrefix` keep their existing meanings. + +HTTP does not make duplicate backend names safe. Every backend must have a unique `Server` value, including Bedrock-enabled networks where name prefixes can otherwise create confusing identity collisions. + +## Certificates and renewal + +- Normal traffic requires TLS 1.3 and a backend client certificate bound to its canonical server identity. +- Enrollment pins the generated private authority and proxy identity while retaining hostname verification. +- Proxy and backend leaf certificates renew automatically during their pre-expiry window; routine renewal does not require a new connection code. +- Keys, pins, credentials, revocation data, queues, and delivery state are stored within VotingPlugin data folders using atomic, owner-only files where supported. + +Keep the proxy's HTTP data directory private and backed up. It contains the transport authority and durable delivery state. Do not copy a backend credential directory between servers. + +## Revoke or replace a backend + +If a backend host or its private identity may be compromised, revoke it on the proxy before enrolling a replacement: + +```text +/votingpluginproxy httprevoke lobby-1 +``` + +Generate a new code, install it only on the intended replacement backend, and restart that backend. A genuinely new code requests re-enrollment even when old local credential files still exist. + +## Migrate from another proxy method + +1. Update the proxy and every backend to the same compatible build. +2. Record the current method and its settings so rollback is possible. +3. Configure and restart the proxy with `BungeeMethod: HTTP`. +4. Open only the selected proxy TCP port. +5. Enroll and restart each backend with its own code. +6. Test status, online votes, offline votes, restarts, and failure recovery. +7. Remove temporary connection codes after enrollment. + +Only one `BungeeMethod` is active. Do not assume the previous Redis, MQTT, MySQL, sockets, or plugin-messaging transport remains a fallback. + +To roll back, select the previous method on the proxy and every backend, restore its required settings, and restart all participating instances. Keep the HTTP authority data private even when the method is inactive, or retire it according to your backup and credential policy. + +## Control WebUI compatibility + +Compatible development code can validate HTTP prerequisites during a coordinated proxy-method change. Manual configuration remains the authoritative recovery path. Do not expect released VotingPlugin 7.1.1 or an older Control connector to advertise or manage the HTTP method. + +Before using Control to switch a live network, verify that its connected proxy and every selected backend advertise compatible HTTP capabilities, review the generated preview, and retain console access for rollback. + +## Troubleshooting + +| Symptom | Check | +| --- | --- | +| Proxy reports that HTTP is not running | Confirm `BungeeMethod`, `Host`, `Port`, and `PublicEndpoint`, then restart the proxy. | +| `httpcode` fails | Confirm the listener started and `PublicEndpoint` is a valid directly reachable HTTPS origin with a valid port. | +| Backend cannot enroll | Confirm the code is unexpired, unused, and bound to the backend's exact unique `Server` name. Generate a fresh code when uncertain. | +| Backend repeatedly presents an old identity | Revoke the old backend, generate a genuinely new code, and restart with that new code. | +| TLS or hostname verification fails | Confirm DNS, the exact public hostname, time synchronization, and that no TLS-terminating proxy or CDN is replacing the listener certificate. | +| Proxy reports incomplete or missing HTTP TLS identity files | Restore the complete proxy HTTP data directory from a trusted backup. Do not delete or regenerate only part of the identity once enrollment or durable outgoing state exists; the transport refuses to replace its authority silently. | +| Connection works but votes do not | Check VotifierPlus, vote-site service mapping, proxy routing, blocked/allowed servers, player identity rules, storage, and reward configuration. | +| Votes appear delayed | Check backend reachability and queue pressure. The connector uses bounded long polling and backpressure rather than unbounded queues. | +| Delivery remains quarantined after a crash | Investigate whether the reward callback may have run before deciding how to reconcile it. Do not blindly replay an ambiguous reward. | + +## Related pages + +- [Proxy Setups](Proxy-Setups) +- [Dedicated Voting Proxy](Dedicated-Voting-Proxy) +- [PLUGINMESSAGING](Proxy-method-PLUGINMESSAGING) +- [Redis](proxy-method-REDIS) +- [Votifier Troubleshooting](Votifier-Troubleshooting) +- [Online and Offline Mode](Online-Offline-Mode) + +## Source references + +- [VotingPlugin HTTP transport PR #1594](https://github.com/BenCodez/VotingPlugin/pull/1594) +- [Development HTTP transport guide](https://github.com/BenCodez/VotingPlugin/blob/codex/http-transport/docs/http-transport.md) +- [Development proxy configuration](https://github.com/BenCodez/VotingPlugin/blob/codex/http-transport/VotingPlugin/src/main/resources/bungeeconfig.yml) +- [Development backend configuration](https://github.com/BenCodez/VotingPlugin/blob/codex/http-transport/VotingPlugin/src/main/resources/BungeeSettings.yml) diff --git a/sidebar.md b/sidebar.md index b5facd3..5f4c068 100644 --- a/sidebar.md +++ b/sidebar.md @@ -31,6 +31,7 @@ dateCreated: 2026-01-27T00:14:29.606Z ### Proxy Methods - [PLUGINMESSAGING](https://github.com/BenCodez/VotingPlugin/wiki/Proxy-method-PLUGINMESSAGING) +- [HTTP](https://github.com/BenCodez/VotingPlugin/wiki/proxy-method-HTTP) - [REDIS](https://github.com/BenCodez/VotingPlugin/wiki/proxy-method-REDIS) - [MQTT](https://github.com/BenCodez/VotingPlugin/wiki/proxy-method-MQTT) - [SOCKETS](https://github.com/BenCodez/VotingPlugin/wiki/proxy-method-SOCKETS) From 40ead6bb76f825e47b1dcee23077c5b4b9c7c296 Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 11 Sep 2026 15:50:25 -0600 Subject: [PATCH 2/8] docs: refresh HTTP transport development baseline --- VotingPlugin/proxy-method-HTTP.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/VotingPlugin/proxy-method-HTTP.md b/VotingPlugin/proxy-method-HTTP.md index 83aa044..fab9dc3 100644 --- a/VotingPlugin/proxy-method-HTTP.md +++ b/VotingPlugin/proxy-method-HTTP.md @@ -2,7 +2,7 @@ title: HTTP Proxy Transport description: Connect VotingPlugin backends to one secure proxy listener without opening a port on every backend published: true -date: 2026-09-10T00:00:00.000Z +date: 2026-09-11T00:00:00.000Z tags: editor: markdown dateCreated: 2026-09-02T00:00:00.000Z @@ -10,7 +10,7 @@ dateCreated: 2026-09-02T00:00:00.000Z # HTTP Proxy Transport -> **Development-build feature:** `BungeeMethod: HTTP` is not available in the latest public VotingPlugin release, **7.1.1**. This page currently requires the unmerged [VotingPlugin PR #1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`058e8e7a`](https://github.com/BenCodez/VotingPlugin/commit/058e8e7aa9ffecdd2026faff2ce1d1a3e3445f80) or later. Release users do not have the `HTTP` method, its configuration keys, or its proxy commands. +> **Development-build feature:** `BungeeMethod: HTTP` is not available in the latest public VotingPlugin release, **7.1.1**. This page currently requires the unmerged [VotingPlugin PR #1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`0da1c460`](https://github.com/BenCodez/VotingPlugin/commit/0da1c46084bc0aaf5345af00e3e54696d9b2a830) or later. Release users do not have the `HTTP` method, its configuration keys, or its proxy commands. {.is-warning} The HTTP proxy method gives every backend an **outbound**, encrypted connection to one HTTPS listener on the BungeeCord or Velocity proxy. Only the proxy listener port needs to be reachable. Backend servers do not expose an HTTP transport port. From b9d88f3ab6a1903ca4451d5931166d519d4780ef Mon Sep 17 00:00:00 2001 From: Ben Date: Sat, 12 Sep 2026 15:21:18 -0600 Subject: [PATCH 3/8] docs: refresh HTTP transport compatibility baseline --- VotingPlugin/proxy-method-HTTP.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/VotingPlugin/proxy-method-HTTP.md b/VotingPlugin/proxy-method-HTTP.md index fab9dc3..f84e8fb 100644 --- a/VotingPlugin/proxy-method-HTTP.md +++ b/VotingPlugin/proxy-method-HTTP.md @@ -2,7 +2,7 @@ title: HTTP Proxy Transport description: Connect VotingPlugin backends to one secure proxy listener without opening a port on every backend published: true -date: 2026-09-11T00:00:00.000Z +date: 2026-09-12T00:00:00.000Z tags: editor: markdown dateCreated: 2026-09-02T00:00:00.000Z @@ -10,7 +10,7 @@ dateCreated: 2026-09-02T00:00:00.000Z # HTTP Proxy Transport -> **Development-build feature:** `BungeeMethod: HTTP` is not available in the latest public VotingPlugin release, **7.1.1**. This page currently requires the unmerged [VotingPlugin PR #1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`0da1c460`](https://github.com/BenCodez/VotingPlugin/commit/0da1c46084bc0aaf5345af00e3e54696d9b2a830) or later. Release users do not have the `HTTP` method, its configuration keys, or its proxy commands. +> **Development-build feature:** `BungeeMethod: HTTP` is not available in the latest public VotingPlugin release, **7.1.1**. This page currently requires the unmerged [VotingPlugin PR #1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`fa9f1a58`](https://github.com/BenCodez/VotingPlugin/commit/fa9f1a582f856cb74c3a73aaccece7abfa5f57d5) or later. Release users do not have the `HTTP` method, its configuration keys, or its proxy commands. {.is-warning} The HTTP proxy method gives every backend an **outbound**, encrypted connection to one HTTPS listener on the BungeeCord or Velocity proxy. Only the proxy listener port needs to be reachable. Backend servers do not expose an HTTP transport port. @@ -147,9 +147,9 @@ To roll back, select the previous method on the proxy and every backend, restore ## Control WebUI compatibility -Compatible development code can validate HTTP prerequisites during a coordinated proxy-method change. Manual configuration remains the authoritative recovery path. Do not expect released VotingPlugin 7.1.1 or an older Control connector to advertise or manage the HTTP method. +The current public Control release, **v0.1.7**, does not offer `HTTP` through its `config.proxy-method.v1` workflow. Configure this development transport manually; do not use Control to switch a live network to or from HTTP yet. -Before using Control to switch a live network, verify that its connected proxy and every selected backend advertise compatible HTTP capabilities, review the generated preview, and retain console access for rollback. +A future coordinated Control version must explicitly advertise HTTP compatibility and validate the proxy and every selected backend before the method can be switched safely through the WebUI. Retain console access and external backups for rollback even after that support becomes available. ## Troubleshooting From bc47c81ff7c738d92190c382971219a498468c16 Mon Sep 17 00:00:00 2001 From: Ben Date: Sun, 13 Sep 2026 15:26:12 -0600 Subject: [PATCH 4/8] docs: track coordinated HTTP Control support --- VotingPlugin/proxy-method-HTTP.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/VotingPlugin/proxy-method-HTTP.md b/VotingPlugin/proxy-method-HTTP.md index f84e8fb..d8abb9d 100644 --- a/VotingPlugin/proxy-method-HTTP.md +++ b/VotingPlugin/proxy-method-HTTP.md @@ -2,7 +2,7 @@ title: HTTP Proxy Transport description: Connect VotingPlugin backends to one secure proxy listener without opening a port on every backend published: true -date: 2026-09-12T00:00:00.000Z +date: 2026-09-13T00:00:00.000Z tags: editor: markdown dateCreated: 2026-09-02T00:00:00.000Z @@ -10,7 +10,7 @@ dateCreated: 2026-09-02T00:00:00.000Z # HTTP Proxy Transport -> **Development-build feature:** `BungeeMethod: HTTP` is not available in the latest public VotingPlugin release, **7.1.1**. This page currently requires the unmerged [VotingPlugin PR #1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`fa9f1a58`](https://github.com/BenCodez/VotingPlugin/commit/fa9f1a582f856cb74c3a73aaccece7abfa5f57d5) or later. Release users do not have the `HTTP` method, its configuration keys, or its proxy commands. +> **Development-build feature:** `BungeeMethod: HTTP` is not available in the latest public VotingPlugin release, **7.1.1**. This page currently requires the unmerged [VotingPlugin PR #1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`3acae789`](https://github.com/BenCodez/VotingPlugin/commit/3acae789142d712da87e690297e3177629075376) or later. Release users do not have the `HTTP` method, its configuration keys, or its proxy commands. {.is-warning} The HTTP proxy method gives every backend an **outbound**, encrypted connection to one HTTPS listener on the BungeeCord or Velocity proxy. Only the proxy listener port needs to be reachable. Backend servers do not expose an HTTP transport port. @@ -147,9 +147,9 @@ To roll back, select the previous method on the proxy and every backend, restore ## Control WebUI compatibility -The current public Control release, **v0.1.7**, does not offer `HTTP` through its `config.proxy-method.v1` workflow. Configure this development transport manually; do not use Control to switch a live network to or from HTTP yet. +The current public Control release, **v0.1.7**, does not offer `HTTP` through its `config.proxy-method.v1` workflow. Configure this development transport manually; do not use released Control to switch a live network to or from HTTP. -A future coordinated Control version must explicitly advertise HTTP compatibility and validate the proxy and every selected backend before the method can be switched safely through the WebUI. Retain console access and external backups for rollback even after that support becomes available. +Active [Control PR #13](https://github.com/BenCodez/VotingPlugin-Control/pull/13) and VotingPlugin PR #1594 introduce a negotiated `config.proxy-method.v2` workflow for HTTP. That pairing remains unmerged and unreleased. Wait for compatible public releases on both sides, then verify that the proxy and every selected backend advertise v2 before using the WebUI. Retain console access and external backups for rollback. ## Troubleshooting From 62715d8b69b93d800f03048c14ed094a05566698 Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 14 Sep 2026 15:17:07 -0600 Subject: [PATCH 5/8] docs: refresh HTTP transport development baseline --- VotingPlugin/proxy-method-HTTP.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/VotingPlugin/proxy-method-HTTP.md b/VotingPlugin/proxy-method-HTTP.md index d8abb9d..e6d58f7 100644 --- a/VotingPlugin/proxy-method-HTTP.md +++ b/VotingPlugin/proxy-method-HTTP.md @@ -2,7 +2,7 @@ title: HTTP Proxy Transport description: Connect VotingPlugin backends to one secure proxy listener without opening a port on every backend published: true -date: 2026-09-13T00:00:00.000Z +date: 2026-09-14T00:00:00.000Z tags: editor: markdown dateCreated: 2026-09-02T00:00:00.000Z @@ -10,7 +10,7 @@ dateCreated: 2026-09-02T00:00:00.000Z # HTTP Proxy Transport -> **Development-build feature:** `BungeeMethod: HTTP` is not available in the latest public VotingPlugin release, **7.1.1**. This page currently requires the unmerged [VotingPlugin PR #1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`3acae789`](https://github.com/BenCodez/VotingPlugin/commit/3acae789142d712da87e690297e3177629075376) or later. Release users do not have the `HTTP` method, its configuration keys, or its proxy commands. +> **Development-build feature:** `BungeeMethod: HTTP` is not available in the latest public VotingPlugin release, **7.1.1**. This page currently requires the unmerged [VotingPlugin PR #1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`2e49dd66`](https://github.com/BenCodez/VotingPlugin/commit/2e49dd66699aefe24a572416053c9954e6e864e4) or later. Release users do not have the `HTTP` method, its configuration keys, or its proxy commands. {.is-warning} The HTTP proxy method gives every backend an **outbound**, encrypted connection to one HTTPS listener on the BungeeCord or Velocity proxy. Only the proxy listener port needs to be reachable. Backend servers do not expose an HTTP transport port. From e1fd6bc5072285f1d91f2091682f913450ebeae5 Mon Sep 17 00:00:00 2001 From: Ben Date: Wed, 16 Sep 2026 19:06:21 -0600 Subject: [PATCH 6/8] docs: update Control v0.1.8 compatibility --- VotingPlugin/Control-WebUI.md | 28 ++++++++++++++-------------- VotingPlugin/proxy-method-HTTP.md | 6 +++--- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/VotingPlugin/Control-WebUI.md b/VotingPlugin/Control-WebUI.md index 2713462..4718456 100644 --- a/VotingPlugin/Control-WebUI.md +++ b/VotingPlugin/Control-WebUI.md @@ -2,7 +2,7 @@ title: VotingPlugin Control WebUI description: Install, enroll, manage, and inspect a VotingPlugin network through the optional Control WebUI published: true -date: 2026-09-15T00:00:00.000Z +date: 2026-09-16T00:00:00.000Z tags: editor: markdown dateCreated: 2026-08-31T00:00:00.000Z @@ -10,19 +10,19 @@ dateCreated: 2026-08-31T00:00:00.000Z # VotingPlugin Control WebUI -> **Development-build feature:** Control integration is not available in the latest public VotingPlugin release, **7.1.1**. Unless a section is marked as later active development, the management and inspection suite described here requires a `7.1.2-SNAPSHOT` build containing merged commit [`034e39aa`](https://github.com/BenCodez/VotingPlugin/commit/034e39aae5890db249a51109fa0ee2d2561b7142) or later and [VotingPlugin-Control v0.1.7](https://github.com/BenCodez/VotingPlugin-Control/releases/tag/v0.1.7). Release users do not have the VotingPlugin connector or hosting settings yet. Details may change before VotingPlugin 7.1.2 is released. +> **Development-build feature:** Control integration is not available in the latest public VotingPlugin release, **7.1.1**. Unless a section requires a later development build, the management and inspection suite described here requires a `7.1.2-SNAPSHOT` build containing merged commit [`034e39aa`](https://github.com/BenCodez/VotingPlugin/commit/034e39aae5890db249a51109fa0ee2d2561b7142) or later and [VotingPlugin-Control v0.1.8](https://github.com/BenCodez/VotingPlugin-Control/releases/tag/v0.1.8). Release users do not have the VotingPlugin connector or hosting settings yet. Details may change before VotingPlugin 7.1.2 is released. {.is-warning} VotingPlugin Control is an optional, local-first management application for a VotingPlugin network. Its WebUI can show enrolled proxies and backends, coordinate reviewed configuration changes, and request bounded read-only diagnostics from capable backend nodes. Control does **not** receive votes or replace VotingPlugin's existing proxy communication method. Voting continues normally if Control is stopped, slow, unavailable, or disabled. -## Active development after Control v0.1.7 +## Control v0.1.8 compatibility boundary -> **Not available in Control v0.1.7:** Automatic selected-server loading and negotiated HTTP proxy-method switching are merged into Control development by [PR #13](https://github.com/BenCodez/VotingPlugin-Control/pull/13). The private VotingPlugin artifact store and VotingPlugin JAR staging remain proposed by stacked Control PRs [#14](https://github.com/BenCodez/VotingPlugin-Control/pull/14) and [#15](https://github.com/BenCodez/VotingPlugin-Control/pull/15). Their node-side capabilities require the unmerged VotingPlugin PR [#1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`72d5183d`](https://github.com/BenCodez/VotingPlugin/commit/72d5183de1837082dd30173bbd203e45d9189d4c) or later. These workflows remain unreleased; do not rely on them until compatible public releases exist. +> **VotingPlugin 7.1.1 is not compatible with these workflows:** Control v0.1.8 includes automatic selected-server loading, negotiated HTTP proxy-method switching, a private VotingPlugin artifact store, and VotingPlugin JAR staging. Their node-side capabilities require the unmerged VotingPlugin PR [#1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`72d5183d`](https://github.com/BenCodez/VotingPlugin/commit/72d5183de1837082dd30173bbd203e45d9189d4c) or later. Installing Control v0.1.8 alone does not add those capabilities to release VotingPlugin nodes; wait for a compatible public VotingPlugin release. {.is-warning} -The proposed stack adds these bounded workflows without changing Control's role in vote processing: +Control v0.1.8 adds these bounded workflows without changing Control's role in vote processing: - Selecting a server automatically loads its current settings, clears stale editor state, and rereads confirmed state after an apply. - HTTP method selection uses negotiated `config.proxy-method.v2`; older nodes remain connected but are excluded from HTTP previews and applies. @@ -30,7 +30,7 @@ The proposed stack adds these bounded workflows without changing Control's role - Staging verifies the artifact identity and SHA-256, reports per-node results, and ends at `RESTART_REQUIRED`. Control does not reload or restart a Minecraft process automatically. - A retry creates a new operation for currently eligible failed targets; it does not replay successful targets implicitly. -Continue using manual VotingPlugin updates and manual HTTP configuration until compatible public releases are available. +Continue using manual VotingPlugin updates and manual HTTP configuration unless every selected node runs a compatible development build and advertises the required capability. For production networks, wait for a compatible public VotingPlugin release. ## Architecture @@ -238,15 +238,15 @@ Transport tests request a bounded check through a node's existing VotingPlugin c Coordinated proxy-method switching validates capabilities and current topology, previews the proposed changes, and applies only after approval. All participating nodes must support the selected method and its required configuration. Take external backups before a network-wide transport migration. -Control v0.1.7 supports `MYSQL`, `PLUGINMESSAGING`, `REDIS`, `MQTT`, and `SOCKETS` through `config.proxy-method.v1`. HTTP is not a v1 option. The active post-v0.1.7 stack uses `config.proxy-method.v2` for HTTP and excludes nodes that do not advertise that exact capability. +Control v0.1.8 retains `MYSQL`, `PLUGINMESSAGING`, `REDIS`, `MQTT`, and `SOCKETS` through `config.proxy-method.v1` and adds negotiated `config.proxy-method.v2` for HTTP. HTTP is not a v1 option. Nodes that do not advertise the exact v2 capability are excluded from HTTP previews and applies; VotingPlugin 7.1.1 does not advertise it. ### VotingPlugin update staging -The active post-v0.1.7 stack proposes a **Plugin update** workspace. It accepts one bounded VotingPlugin JAR, verifies the embedded plugin identity, stores it by SHA-256, and shows which connected nodes currently advertise `plugin.deploy.v1` before an operation is created. +Control v0.1.8 provides a **Plugin update** workspace. It accepts one bounded VotingPlugin JAR, verifies the embedded plugin identity, stores it by SHA-256, and shows which connected nodes currently advertise `plugin.deploy.v1` before an operation is created. VotingPlugin 7.1.1 does not advertise that capability. Each selected node downloads the exact verified artifact through a session- and attempt-bound lease, stages it for the next process start, and reports either `RESTART_REQUIRED` or a bounded failure. Control never hot reloads VotingPlugin, restarts a server, or turns a failed target into an automatic retry. Review the per-node result, then restart successful targets through the normal server-management process. -The proposed store is private and bounded to 32 artifacts and 512 MiB. Retained deployment history protects referenced artifacts from eviction. Treat uploaded JARs and the Control data directory as trusted administrative material and include them in the host's access-control and backup policy. +The store is private and bounded to 32 artifacts and 512 MiB. Retained deployment history protects referenced artifacts from eviction. Treat uploaded JARs and the Control data directory as trusted administrative material and include them in the host's access-control and backup policy. ## Safe change workflow @@ -315,7 +315,7 @@ VoteLog views contain retained **logged events**, not a complete packet or comma | VoteLog says enabled but unavailable | Restart VotingPlugin after enabling VoteLogging, then check database connectivity and table readability. | | Network Doctor is healthy but votes still fail | Run a real Votifier vote through the complete public listener and delivery path. Network Doctor is not a synthetic vote test. | | The hosted update rolled back | Inspect the hosted log and retained failed candidate. Do not bypass digest or health verification. | -| A VotingPlugin deployment says `RESTART_REQUIRED` | The JAR was staged successfully but is not active yet. Restart that node through the normal server-management process. This workflow is not available in Control v0.1.7. | +| A VotingPlugin deployment says `RESTART_REQUIRED` | The JAR was staged successfully but is not active yet. Restart that node through the normal server-management process. Control v0.1.8 provides this workflow, but VotingPlugin 7.1.1 lacks the required node capability. | ## Disable Control @@ -345,10 +345,10 @@ On a proxy, set `Control.Enabled: false` as well. Disabling or removing Control - [VotingPlugin Control connector implementation notes](https://github.com/BenCodez/VotingPlugin/blob/master/docs/control-connector.md) - [VotingPlugin Control management reference](https://github.com/BenCodez/VotingPlugin-Control/blob/main/docs/control-management.md) -- [VotingPlugin Control v0.1.7](https://github.com/BenCodez/VotingPlugin-Control/releases/tag/v0.1.7) -- [Automatic settings and HTTP v2 development merge (Control PR #13)](https://github.com/BenCodez/VotingPlugin-Control/pull/13) -- [Verified VotingPlugin artifact-store proposal (Control PR #14)](https://github.com/BenCodez/VotingPlugin-Control/pull/14) -- [VotingPlugin staging proposal (Control PR #15)](https://github.com/BenCodez/VotingPlugin-Control/pull/15) +- [VotingPlugin Control v0.1.8](https://github.com/BenCodez/VotingPlugin-Control/releases/tag/v0.1.8) +- [Automatic settings and HTTP v2 merge (Control PR #13)](https://github.com/BenCodez/VotingPlugin-Control/pull/13) +- [Verified VotingPlugin artifact-store merge (Control PR #14)](https://github.com/BenCodez/VotingPlugin-Control/pull/14) +- [VotingPlugin staging merge (Control PR #15)](https://github.com/BenCodez/VotingPlugin-Control/pull/15) - [VotingPlugin HTTP and deployment capabilities (PR #1594)](https://github.com/BenCodez/VotingPlugin/pull/1594) - [VotingPlugin proxy configuration management merge (PR #1596)](https://github.com/BenCodez/VotingPlugin/pull/1596) - [Development backend `Config.yml`](https://github.com/BenCodez/VotingPlugin/blob/master/VotingPlugin/src/main/resources/Config.yml) diff --git a/VotingPlugin/proxy-method-HTTP.md b/VotingPlugin/proxy-method-HTTP.md index f7e40fc..dc20c20 100644 --- a/VotingPlugin/proxy-method-HTTP.md +++ b/VotingPlugin/proxy-method-HTTP.md @@ -2,7 +2,7 @@ title: HTTP Proxy Transport description: Connect VotingPlugin backends to one secure proxy listener without opening a port on every backend published: true -date: 2026-09-15T00:00:00.000Z +date: 2026-09-16T00:00:00.000Z tags: editor: markdown dateCreated: 2026-09-02T00:00:00.000Z @@ -148,9 +148,9 @@ To roll back, select the previous method on the proxy and every backend, restore ## Control WebUI compatibility -The current public Control release, **v0.1.7**, does not offer `HTTP` through its `config.proxy-method.v1` workflow. Configure this development transport manually; do not use released Control to switch a live network to or from HTTP. +The current public Control release, **v0.1.8**, includes negotiated `config.proxy-method.v2` support for HTTP. The latest public VotingPlugin release, 7.1.1, does not advertise that capability and cannot use HTTP. Configure this development transport manually unless every selected node runs a compatible PR #1594 build. -Control [PR #13](https://github.com/BenCodez/VotingPlugin-Control/pull/13) is merged into Control development at [`39e0b31`](https://github.com/BenCodez/VotingPlugin-Control/commit/39e0b31077100d81f6da6261afd638b2df2eb645), while VotingPlugin PR #1594 provides the node-side `config.proxy-method.v2` workflow for HTTP. Both sides remain unreleased. Wait for compatible public releases, then verify that the proxy and every selected backend advertise v2 before using the WebUI. Retain console access and external backups for rollback. +Control [PR #13](https://github.com/BenCodez/VotingPlugin-Control/pull/13) is included in v0.1.8, while VotingPlugin PR #1594 provides the still-unreleased node-side `config.proxy-method.v2` workflow for HTTP. Verify that the proxy and every selected backend advertise v2 before using the WebUI. For production networks, wait for a compatible public VotingPlugin release. Retain console access and external backups for rollback. ## Troubleshooting From 01513bb9f359b5296231e66ab4605e0e41198ae7 Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 18 Sep 2026 18:51:34 -0600 Subject: [PATCH 7/8] docs: refresh deployment hardening guidance --- VotingPlugin/Control-WebUI.md | 9 +++++---- VotingPlugin/proxy-method-HTTP.md | 6 +++--- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/VotingPlugin/Control-WebUI.md b/VotingPlugin/Control-WebUI.md index 9cf4287..2ca74da 100644 --- a/VotingPlugin/Control-WebUI.md +++ b/VotingPlugin/Control-WebUI.md @@ -19,7 +19,7 @@ Control does **not** receive votes or replace VotingPlugin's existing proxy comm ## Control v0.1.9 compatibility boundary -> **VotingPlugin 7.1.1 is not compatible with these workflows:** Control v0.1.9 includes automatic selected-server loading, negotiated HTTP proxy-method switching, a private VotingPlugin artifact store, and VotingPlugin JAR staging. HTTP requires the unmerged VotingPlugin PR [#1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`72d5183d`](https://github.com/BenCodez/VotingPlugin/commit/72d5183de1837082dd30173bbd203e45d9189d4c) or later. Verified JAR staging requires VotingPlugin PR [#1609](https://github.com/BenCodez/VotingPlugin/pull/1609) at commit [`3dec1e26`](https://github.com/BenCodez/VotingPlugin/commit/3dec1e26270a2705c62fb8c85dffe4e8ea6d9602) or a compatible #1594 build that contains the same deployment service. Installing Control v0.1.9 alone does not add either capability to release VotingPlugin nodes; wait for compatible public VotingPlugin releases. +> **VotingPlugin 7.1.1 is not compatible with these workflows:** Control v0.1.9 includes automatic selected-server loading, negotiated HTTP proxy-method switching, a private VotingPlugin artifact store, and VotingPlugin JAR staging. HTTP requires the unmerged VotingPlugin PR [#1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`72d5183d`](https://github.com/BenCodez/VotingPlugin/commit/72d5183de1837082dd30173bbd203e45d9189d4c) or later. Verified JAR staging requires VotingPlugin PR [#1609](https://github.com/BenCodez/VotingPlugin/pull/1609) at commit [`a2b13812`](https://github.com/BenCodez/VotingPlugin/commit/a2b1381240bd1f8debd45ea3e63927aa2fb691c5) or a compatible #1594 build that contains the same hardened deployment service. Installing Control v0.1.9 alone does not add either capability to release VotingPlugin nodes; wait for compatible public VotingPlugin releases. {.is-warning} Control v0.1.9 includes these bounded workflows without changing Control's role in vote processing: @@ -27,6 +27,7 @@ Control v0.1.9 includes these bounded workflows without changing Control's role - Selecting a server automatically loads its current settings, clears stale editor state, and rereads confirmed state after an apply. - HTTP method selection uses negotiated `config.proxy-method.v2`; older nodes remain connected but are excluded from HTTP previews and applies. - An administrator can upload a VotingPlugin JAR into a private, content-addressed store and stage it only on selected nodes advertising `plugin.deploy.v1`. Install the first deployment-capable VotingPlugin build manually on each node; a node without the deployment endpoint cannot use Control to bootstrap that endpoint. +- Windows proxy nodes do not advertise deployment because the running proxy JAR cannot be replaced safely there. Update those proxy nodes manually. - Staging verifies the artifact identity and SHA-256, reports per-node results, and ends at `RESTART_REQUIRED`. Control does not reload or restart a Minecraft process automatically. - A retry creates a new operation for currently eligible failed targets; it does not replay successful targets implicitly. - The full YAML editor and guided configuration workflows now say that nothing has been saved after a successful preview, focus **Approve and apply** when it is available, and treat Ctrl/Command+S in the full YAML editor as preview-only. Proxy-method switching uses its separate preview and browser-confirmation flow. @@ -243,9 +244,9 @@ Control v0.1.9 retains `MYSQL`, `PLUGINMESSAGING`, `REDIS`, `MQTT`, and `SOCKETS ### VotingPlugin update staging -Control v0.1.9 provides a **Plugin update** workspace. It accepts one bounded VotingPlugin JAR, verifies the embedded plugin identity, stores it by SHA-256, and shows which connected nodes currently advertise `plugin.deploy.v1` before an operation is created. VotingPlugin 7.1.1 does not advertise that capability. Manually install a build containing VotingPlugin PR #1609 or a compatible #1594 build once on every intended node. A remote connector advertises deployment only when its Control endpoint uses HTTPS. The local HTTP exception requires Control to be hosted directly on that same node **and** the connector endpoint to use a loopback host such as `127.0.0.1` or `localhost`. After eligible nodes reconnect, Control can stage later VotingPlugin JARs. +Control v0.1.9 provides a **Plugin update** workspace. It accepts one bounded VotingPlugin JAR, verifies the embedded plugin identity, stores it by SHA-256, and shows which connected nodes currently advertise `plugin.deploy.v1` before an operation is created. VotingPlugin 7.1.1 does not advertise that capability. Manually install a build containing VotingPlugin PR #1609 at `a2b13812` or a compatible #1594 build once on every intended node. A remote connector advertises deployment only when its Control endpoint uses HTTPS. The local HTTP exception requires Control to be hosted directly on that same node **and** the connector endpoint to use a loopback host such as `127.0.0.1` or `localhost`. Windows proxy nodes remain ineligible and must be updated manually. After eligible nodes reconnect, Control can stage later VotingPlugin JARs. -Each selected node downloads the exact verified artifact through a session- and attempt-bound lease, stages it for the next process start, and reports either `RESTART_REQUIRED` or a bounded failure. Control never hot reloads VotingPlugin, restarts a server, or turns a failed target into an automatic retry. Review the per-node result, then restart successful targets through the normal server-management process. +Each selected node downloads the exact verified artifact through a session- and attempt-bound lease, stages it for the next process start, and reports either `RESTART_REQUIRED` or a bounded failure. Bukkit backends preserve the filename of the currently installed VotingPlugin JAR when placing the update in the server update folder. Control never hot reloads VotingPlugin, restarts a server, or turns a failed target into an automatic retry. Review the per-node result, then restart successful targets through the normal server-management process. The store is private and bounded to 32 artifacts and 512 MiB. Retained deployment history protects referenced artifacts from eviction. Treat uploaded JARs and the Control data directory as trusted administrative material and include them in the host's access-control and backup policy. @@ -317,7 +318,7 @@ VoteLog views contain retained **logged events**, not a complete packet or comma | VoteLog says enabled but unavailable | Restart VotingPlugin after enabling VoteLogging, then check database connectivity and table readability. | | Network Doctor is healthy but votes still fail | Run a real Votifier vote through the complete public listener and delivery path. Network Doctor is not a synthetic vote test. | | The hosted update rolled back | Inspect the hosted log and retained failed candidate. Do not bypass digest or health verification. | -| No connected node is eligible for a VotingPlugin deployment | VotingPlugin 7.1.1 lacks `plugin.deploy.v1`. Manually install a compatible build containing PR #1609 or the equivalent #1594 deployment service once, then reconnect the node. For a remote connector, also confirm that its Control endpoint uses HTTPS. Local HTTP is eligible only when Control is hosted directly on that node and the connector uses a loopback endpoint. | +| No connected node is eligible for a VotingPlugin deployment | VotingPlugin 7.1.1 lacks `plugin.deploy.v1`. Manually install a compatible build containing PR #1609 at `a2b13812` or the equivalent hardened #1594 deployment service once, then reconnect the node. For a remote connector, also confirm that its Control endpoint uses HTTPS. Local HTTP is eligible only when Control is hosted directly on that node and the connector uses a loopback endpoint. Windows proxy nodes are intentionally ineligible and require manual updates. | | A VotingPlugin deployment says `RESTART_REQUIRED` | The JAR was staged successfully but is not active yet. Restart that node through the normal server-management process. | ## Disable Control diff --git a/VotingPlugin/proxy-method-HTTP.md b/VotingPlugin/proxy-method-HTTP.md index e16b407..4f1a24f 100644 --- a/VotingPlugin/proxy-method-HTTP.md +++ b/VotingPlugin/proxy-method-HTTP.md @@ -178,6 +178,6 @@ Control [PR #13](https://github.com/BenCodez/VotingPlugin-Control/pull/13) is in ## Source references - [VotingPlugin HTTP transport PR #1594](https://github.com/BenCodez/VotingPlugin/pull/1594) -- [Development HTTP transport guide](https://github.com/BenCodez/VotingPlugin/blob/codex/http-transport/docs/http-transport.md) -- [Development proxy configuration](https://github.com/BenCodez/VotingPlugin/blob/codex/http-transport/VotingPlugin/src/main/resources/bungeeconfig.yml) -- [Development backend configuration](https://github.com/BenCodez/VotingPlugin/blob/codex/http-transport/VotingPlugin/src/main/resources/BungeeSettings.yml) +- [Development HTTP transport guide](https://github.com/BenCodez/VotingPlugin/blob/72d5183de1837082dd30173bbd203e45d9189d4c/docs/http-transport.md) +- [Development proxy configuration](https://github.com/BenCodez/VotingPlugin/blob/72d5183de1837082dd30173bbd203e45d9189d4c/VotingPlugin/src/main/resources/bungeeconfig.yml) +- [Development backend configuration](https://github.com/BenCodez/VotingPlugin/blob/72d5183de1837082dd30173bbd203e45d9189d4c/VotingPlugin/src/main/resources/BungeeSettings.yml) From 14fde2b069cc65bd21253522628f4449fea21c62 Mon Sep 17 00:00:00 2001 From: Ben Date: Sat, 19 Sep 2026 19:22:37 -0600 Subject: [PATCH 8/8] docs: refresh Control v1 release boundary --- VotingPlugin/Control-WebUI.md | 51 ++++++++++++++++++++++++------- VotingPlugin/proxy-method-HTTP.md | 14 ++++----- 2 files changed, 47 insertions(+), 18 deletions(-) diff --git a/VotingPlugin/Control-WebUI.md b/VotingPlugin/Control-WebUI.md index 2ca74da..daaefe3 100644 --- a/VotingPlugin/Control-WebUI.md +++ b/VotingPlugin/Control-WebUI.md @@ -2,7 +2,7 @@ title: VotingPlugin Control WebUI description: Install, enroll, manage, and inspect a VotingPlugin network through the optional Control WebUI published: true -date: 2026-09-18T00:00:00.000Z +date: 2026-09-19T00:00:00.000Z tags: editor: markdown dateCreated: 2026-08-31T00:00:00.000Z @@ -10,21 +10,23 @@ dateCreated: 2026-08-31T00:00:00.000Z # VotingPlugin Control WebUI -> **Development-build feature:** Control integration is not available in the latest public VotingPlugin release, **7.1.1**. Unless a section requires a later development build, the management and inspection suite described here requires a `7.1.2-SNAPSHOT` build containing merged commit [`034e39aa`](https://github.com/BenCodez/VotingPlugin/commit/034e39aae5890db249a51109fa0ee2d2561b7142) or later and [VotingPlugin-Control v0.1.9](https://github.com/BenCodez/VotingPlugin-Control/releases/tag/v0.1.9). Release users do not have the VotingPlugin connector or hosting settings yet. Details may change before VotingPlugin 7.1.2 is released. +> **Development-build feature:** Control integration is not available in the latest public VotingPlugin release, **7.1.1**. Unless a section requires a later development build, the management and inspection suite described here requires a `7.1.2-SNAPSHOT` build containing merged commit [`034e39aa`](https://github.com/BenCodez/VotingPlugin/commit/034e39aae5890db249a51109fa0ee2d2561b7142) or later and [VotingPlugin-Control v1.0.0](https://github.com/BenCodez/VotingPlugin-Control/releases/tag/v1.0.0). Release users do not have the VotingPlugin connector or hosting settings yet. Details may change before VotingPlugin 7.1.2 is released. {.is-warning} VotingPlugin Control is an optional, local-first management application for a VotingPlugin network. Its WebUI can show enrolled proxies and backends, coordinate reviewed configuration changes, and request bounded read-only diagnostics from capable backend nodes. Control does **not** receive votes or replace VotingPlugin's existing proxy communication method. Voting continues normally if Control is stopped, slow, unavailable, or disabled. -## Control v0.1.9 compatibility boundary +## Control v1.0.0 compatibility boundary -> **VotingPlugin 7.1.1 is not compatible with these workflows:** Control v0.1.9 includes automatic selected-server loading, negotiated HTTP proxy-method switching, a private VotingPlugin artifact store, and VotingPlugin JAR staging. HTTP requires the unmerged VotingPlugin PR [#1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`72d5183d`](https://github.com/BenCodez/VotingPlugin/commit/72d5183de1837082dd30173bbd203e45d9189d4c) or later. Verified JAR staging requires VotingPlugin PR [#1609](https://github.com/BenCodez/VotingPlugin/pull/1609) at commit [`a2b13812`](https://github.com/BenCodez/VotingPlugin/commit/a2b1381240bd1f8debd45ea3e63927aa2fb691c5) or a compatible #1594 build that contains the same hardened deployment service. Installing Control v0.1.9 alone does not add either capability to release VotingPlugin nodes; wait for compatible public VotingPlugin releases. +> **VotingPlugin 7.1.1 is not compatible with these workflows:** Control v1.0.0 includes the scope-first WebUI, visual General Settings, Vote Sites and Rewards editors, negotiated HTTP proxy-method switching, a private VotingPlugin artifact store, and VotingPlugin JAR staging. Existing named reward-file editing requires merged VotingPlugin commit [`4fd3b439`](https://github.com/BenCodez/VotingPlugin/commit/4fd3b4396c0c475f4adecfd6f1c70fa06d13c157) or later. HTTP currently requires unmerged VotingPlugin PR [#1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`bc9dac63`](https://github.com/BenCodez/VotingPlugin/commit/bc9dac6303626e1757e4b5570b6fba548399fd27) or later. Verified JAR staging requires VotingPlugin PR [#1609](https://github.com/BenCodez/VotingPlugin/pull/1609) at commit [`0c5b725b`](https://github.com/BenCodez/VotingPlugin/commit/0c5b725b1aa3862cb7577604222a9981985e4a82) or a compatible #1594 build containing the same hardened deployment service. Installing Control v1.0.0 alone does not add these capabilities to release VotingPlugin nodes; wait for compatible public VotingPlugin releases. {.is-warning} -Control v0.1.9 includes these bounded workflows without changing Control's role in vote processing: +Control v1.0.0 includes these bounded workflows without changing Control's role in vote processing: -- Selecting a server automatically loads its current settings, clears stale editor state, and rereads confirmed state after an apply. +- Home supports one-backend, persistent multi-backend, and separate Global Settings workspaces. Selecting or navigating a workspace never applies configuration. +- General Settings, Vote Sites, and Rewards read every selected capable backend independently, show mixed or partial state, preview only explicit edits against each target's own retained source, and reread confirmed state after apply. +- Existing inline Vote Site rewards support a bounded simple editor. Existing named `Rewards/.yml` files are available only when a node advertises `config.reward-files.v1`; the WebUI cannot create, delete, or browse arbitrary files. - HTTP method selection uses negotiated `config.proxy-method.v2`; older nodes remain connected but are excluded from HTTP previews and applies. - An administrator can upload a VotingPlugin JAR into a private, content-addressed store and stage it only on selected nodes advertising `plugin.deploy.v1`. Install the first deployment-capable VotingPlugin build manually on each node; a node without the deployment endpoint cannot use Control to bootstrap that endpoint. - Windows proxy nodes do not advertise deployment because the running proxy JAR cannot be replaced safely there. Update those proxy nodes manually. @@ -185,6 +187,28 @@ The WebUI is capability-driven. Select a node and check its accepted capabilitie Start on **Overview** after selecting a server or network context in the header. The dashboard combines bounded health cards, Attention Required items, topology, logged-service activity, and recent operations. A missing, malformed, or failed sub-inspection is shown as incomplete health data rather than a healthy result. Quick actions open the existing capability-gated setup, configuration, diagnostics, and inspection workflows; they do not apply fixes automatically. +### Scope-first workspaces + +Home lets an administrator choose one Bukkit backend, multiple Bukkit backends, or the separate Global Settings scope. Proxy nodes remain visible but are not Bukkit configuration targets. Opening one server's overview does not replace a multi-server workspace, and Global Settings does not mean every server. The current scope and selected IDs are kept only for the authenticated browser tab; preview tokens, configuration documents, and secrets are not stored there. + +General Settings, Vote Sites, and Rewards are workspace-aware editors. Each eligible backend is read separately, and the UI distinguishes same, mixed, missing, unsupported, and failed values. Editing a supported subset requires explicit acknowledgement. Each changed target receives its own revision-bound preview and one-time approval; there is no network-wide transaction. A partial apply stays visible per target, and successful targets are read again before their displayed state is treated as confirmed. + +Legacy guided presets, the reward builder, and Full YAML remain single-source tools. Inspecting a backend outside the selected workspace does not authorize editing it, and navigating between pages never stages a write. + +### Visual General Settings + +The curated editor exposes nine existing top-level `Config.yml` booleans: `ProcessRewards`, `AutoCreateVoteSites`, `ExtraAllSitesCheck`, `CountFakeVotes`, `DisableNoServiceSiteMessage`, `DisableUpdateChecking`, `UseVoteGUIMainCommand`, `CloseInventoryOnVote`, and `ExtraVoteShopCheck`. Missing or non-boolean values are not synthesized or normalized. Changing `DisableUpdateChecking` reloads the file but still requires a backend restart to reconcile the update-check scheduler. + +### Visual Vote Sites + +The Vote Sites editor manages the main `VoteSites.yml` only. For an exact site key it can edit `Enabled`, `Name`, `ServiceSite`, `VoteURL`, `VoteDelay`, `Priority`, `Hidden`, `DisplayItem.Material`, and `DisplayItem.Amount`, or explicitly add or remove a site. It preserves unrelated properties and inline rewards. A site key—not its display name or service matcher—is its identity. Split VoteSites files are not part of this visual editor. + +### Visual Rewards + +The Rewards workspace inventories inline and advanced reward scopes without flattening unsupported structures. Its bounded simple editor can create or remove an inline Vote Site reward, edit ordered commands, `Messages.Player`, `Messages.Broadcast`, scalar `Money` or `Chance`, and existing item `Material` or `Amount` leaves when their source shape is safe. Advanced structures such as `AdvancedPriority`, `Choices`, nested rewards, conditions, ranges, and unrecognized keys remain read-only in the visual view. For scopes in the managed `Config.yml`, `VoteSites.yml`, or `SpecialRewards.yml` files, use Full YAML when editing is required. + +Nodes advertising `config.reward-files.v1` can also inventory and edit the root of existing, directly contained named `Rewards/.yml` files. The feature does not create or delete named files, resolve references, provide Full YAML editing, or provide general filesystem access. Edit unsupported advanced structures in a named file manually with the server stopped or through the server's normal file-management workflow, then restart or reload VotingPlugin as appropriate. Older connectors continue to support the other editors but show named reward files as unsupported. + | Area | What it is for | Important boundary | | --- | --- | --- | | Overview | Bounded health cards, Attention Required, topology, logged-service activity, and recent operations | Read-only aggregation; incomplete checks cannot produce a fully healthy result | @@ -208,6 +232,8 @@ Capable backend nodes can expose these user-facing files: - `Shop.yml` - `BungeeSettings.yml` +Existing named `Rewards/.yml` files use the separate optional `config.reward-files.v1` capability. They are not added to the general managed-file browser. + A capable proxy node can expose its single `bungeeconfig.yml` file when it advertises `config.proxy-files.v1`. This does not enable arbitrary proxy file browsing. Saving this file reports that a proxy restart is required; it does not claim a full proxy hot reload. Reads mask password, secret, token, API-key, authorization, and webhook-secret paths. Leaving `__VOTINGPLUGIN_CONTROL_REDACTED__` unchanged preserves the node's current local value. A replacement secret can be submitted through an authenticated preview, but Control does not return or audit it. @@ -221,7 +247,7 @@ The current setup workflows cover: - automatic vote-site creation; - common operational settings; - VoteLogging state, retention, and main-connection selection; -- Vote Party basics, after the current enable-state behavior is finalized; +- Vote Party basics; explicitly changing the enabled state requires `config.quick-setup.v2`, while older v1 connectors are not sent that extension; - simple and structured rewards; - reward simulation before saving; - command suggestions for detected Essentials/EssentialsX, CMI, and LuckPerms installations. @@ -240,11 +266,11 @@ Transport tests request a bounded check through a node's existing VotingPlugin c Coordinated proxy-method switching validates capabilities and current topology, previews the proposed changes, and applies only after approval. All participating nodes must support the selected method and its required configuration. Take external backups before a network-wide transport migration. -Control v0.1.9 retains `MYSQL`, `PLUGINMESSAGING`, `REDIS`, `MQTT`, and `SOCKETS` through `config.proxy-method.v1` and includes negotiated `config.proxy-method.v2` for HTTP. HTTP is not a v1 option. Nodes that do not advertise the exact v2 capability are excluded from HTTP previews and applies; VotingPlugin 7.1.1 does not advertise it. +Control v1.0.0 retains `MYSQL`, `PLUGINMESSAGING`, `REDIS`, `MQTT`, and `SOCKETS` through `config.proxy-method.v1` and includes negotiated `config.proxy-method.v2` for HTTP. HTTP is not a v1 option. Nodes that do not advertise the exact v2 capability are excluded from HTTP previews and applies; VotingPlugin 7.1.1 does not advertise it. ### VotingPlugin update staging -Control v0.1.9 provides a **Plugin update** workspace. It accepts one bounded VotingPlugin JAR, verifies the embedded plugin identity, stores it by SHA-256, and shows which connected nodes currently advertise `plugin.deploy.v1` before an operation is created. VotingPlugin 7.1.1 does not advertise that capability. Manually install a build containing VotingPlugin PR #1609 at `a2b13812` or a compatible #1594 build once on every intended node. A remote connector advertises deployment only when its Control endpoint uses HTTPS. The local HTTP exception requires Control to be hosted directly on that same node **and** the connector endpoint to use a loopback host such as `127.0.0.1` or `localhost`. Windows proxy nodes remain ineligible and must be updated manually. After eligible nodes reconnect, Control can stage later VotingPlugin JARs. +Control v1.0.0 provides a **Plugin update** workspace. It accepts one bounded VotingPlugin JAR, verifies the embedded plugin identity, stores it by SHA-256, and shows which connected nodes currently advertise `plugin.deploy.v1` before an operation is created. VotingPlugin 7.1.1 does not advertise that capability. Manually install a build containing VotingPlugin PR #1609 at `0c5b725b` or a compatible #1594 build once on every intended node. A remote connector advertises deployment only when its Control endpoint uses HTTPS. The local HTTP exception requires Control to be hosted directly on that same node **and** the connector endpoint to use a loopback host such as `127.0.0.1` or `localhost`. Windows proxy nodes remain ineligible and must be updated manually. After eligible nodes reconnect, Control can stage later VotingPlugin JARs. Each selected node downloads the exact verified artifact through a session- and attempt-bound lease, stages it for the next process start, and reports either `RESTART_REQUIRED` or a bounded failure. Bukkit backends preserve the filename of the currently installed VotingPlugin JAR when placing the update in the server update folder. Control never hot reloads VotingPlugin, restarts a server, or turns a failed target into an automatic retry. Review the per-node result, then restart successful targets through the normal server-management process. @@ -318,7 +344,7 @@ VoteLog views contain retained **logged events**, not a complete packet or comma | VoteLog says enabled but unavailable | Restart VotingPlugin after enabling VoteLogging, then check database connectivity and table readability. | | Network Doctor is healthy but votes still fail | Run a real Votifier vote through the complete public listener and delivery path. Network Doctor is not a synthetic vote test. | | The hosted update rolled back | Inspect the hosted log and retained failed candidate. Do not bypass digest or health verification. | -| No connected node is eligible for a VotingPlugin deployment | VotingPlugin 7.1.1 lacks `plugin.deploy.v1`. Manually install a compatible build containing PR #1609 at `a2b13812` or the equivalent hardened #1594 deployment service once, then reconnect the node. For a remote connector, also confirm that its Control endpoint uses HTTPS. Local HTTP is eligible only when Control is hosted directly on that node and the connector uses a loopback endpoint. Windows proxy nodes are intentionally ineligible and require manual updates. | +| No connected node is eligible for a VotingPlugin deployment | VotingPlugin 7.1.1 lacks `plugin.deploy.v1`. Manually install a compatible build containing PR #1609 at `0c5b725b` or the equivalent hardened #1594 deployment service once, then reconnect the node. For a remote connector, also confirm that its Control endpoint uses HTTPS. Local HTTP is eligible only when Control is hosted directly on that node and the connector uses a loopback endpoint. Windows proxy nodes are intentionally ineligible and require manual updates. | | A VotingPlugin deployment says `RESTART_REQUIRED` | The JAR was staged successfully but is not active yet. Restart that node through the normal server-management process. | ## Disable Control @@ -349,11 +375,14 @@ On a proxy, set `Control.Enabled: false` as well. Disabling or removing Control - [VotingPlugin Control connector implementation notes](https://github.com/BenCodez/VotingPlugin/blob/master/docs/control-connector.md) - [VotingPlugin Control management reference](https://github.com/BenCodez/VotingPlugin-Control/blob/main/docs/control-management.md) -- [VotingPlugin Control v0.1.9](https://github.com/BenCodez/VotingPlugin-Control/releases/tag/v0.1.9) +- [VotingPlugin Control v1.0.0](https://github.com/BenCodez/VotingPlugin-Control/releases/tag/v1.0.0) - [Automatic settings and HTTP v2 merge (Control PR #13)](https://github.com/BenCodez/VotingPlugin-Control/pull/13) - [Verified VotingPlugin artifact-store merge (Control PR #14)](https://github.com/BenCodez/VotingPlugin-Control/pull/14) - [VotingPlugin staging merge (Control PR #15)](https://github.com/BenCodez/VotingPlugin-Control/pull/15) - [Explicit preview-to-apply workflow (Control PR #16)](https://github.com/BenCodez/VotingPlugin-Control/pull/16) +- [Verified staging bootstrap guidance (Control PR #17)](https://github.com/BenCodez/VotingPlugin-Control/pull/17) +- [Scope-first Control WebUI v1 (Control PR #18)](https://github.com/BenCodez/VotingPlugin-Control/pull/18) +- [Named reward-file connector capability (VotingPlugin PR #1612)](https://github.com/BenCodez/VotingPlugin/pull/1612) - [VotingPlugin deployment capability (VotingPlugin PR #1609)](https://github.com/BenCodez/VotingPlugin/pull/1609) - [VotingPlugin HTTP and deployment capabilities (PR #1594)](https://github.com/BenCodez/VotingPlugin/pull/1594) - [VotingPlugin proxy configuration management merge (PR #1596)](https://github.com/BenCodez/VotingPlugin/pull/1596) diff --git a/VotingPlugin/proxy-method-HTTP.md b/VotingPlugin/proxy-method-HTTP.md index 4f1a24f..9b6b506 100644 --- a/VotingPlugin/proxy-method-HTTP.md +++ b/VotingPlugin/proxy-method-HTTP.md @@ -2,7 +2,7 @@ title: HTTP Proxy Transport description: Connect VotingPlugin backends to one secure proxy listener without opening a port on every backend published: true -date: 2026-09-18T00:00:00.000Z +date: 2026-09-19T00:00:00.000Z tags: editor: markdown dateCreated: 2026-09-02T00:00:00.000Z @@ -10,7 +10,7 @@ dateCreated: 2026-09-02T00:00:00.000Z # HTTP Proxy Transport -> **Development-build feature:** `BungeeMethod: HTTP` is not available in the latest public VotingPlugin release, **7.1.1**. This page currently requires the unmerged [VotingPlugin PR #1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`72d5183d`](https://github.com/BenCodez/VotingPlugin/commit/72d5183de1837082dd30173bbd203e45d9189d4c) or later. Release users do not have the `HTTP` method, its configuration keys, or its proxy commands. +> **Development-build feature:** `BungeeMethod: HTTP` is not available in the latest public VotingPlugin release, **7.1.1**. This page requires the unmerged [VotingPlugin PR #1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`bc9dac63`](https://github.com/BenCodez/VotingPlugin/commit/bc9dac6303626e1757e4b5570b6fba548399fd27) or later. Release users do not have the `HTTP` method, its configuration keys, or its proxy commands. The implementation remains under review and should not be treated as release-ready. {.is-warning} The HTTP proxy method gives every backend an **outbound**, encrypted connection to one HTTPS listener on the BungeeCord or Velocity proxy. Only the proxy listener port needs to be reachable. Backend servers do not expose an HTTP transport port. @@ -148,9 +148,9 @@ To roll back, select the previous method on the proxy and every backend, restore ## Control WebUI compatibility -The current public Control release, **v0.1.9**, includes negotiated `config.proxy-method.v2` support for HTTP. The latest public VotingPlugin release, 7.1.1, does not advertise that capability and cannot use HTTP. Configure this development transport manually unless every selected node runs a compatible PR #1594 build. +The current public Control release, **v1.0.0**, includes negotiated `config.proxy-method.v2` support for HTTP. The latest public VotingPlugin release, 7.1.1, does not advertise that capability and cannot use HTTP. Configure this development transport manually unless every selected node runs a compatible PR #1594 build. -Control [PR #13](https://github.com/BenCodez/VotingPlugin-Control/pull/13) is included in v0.1.9, while VotingPlugin PR #1594 provides the still-unreleased node-side `config.proxy-method.v2` workflow for HTTP. The proxy-method workflow previews the change and then asks for browser confirmation before applying it. Verify that the proxy and every selected backend advertise v2 before using the WebUI. For production networks, wait for a compatible public VotingPlugin release. Retain console access and external backups for rollback. +Control [PR #13](https://github.com/BenCodez/VotingPlugin-Control/pull/13) is included in v1.0.0, while VotingPlugin PR #1594 provides the still-unreleased node-side `config.proxy-method.v2` workflow for HTTP. The proxy-method workflow previews the change and then asks for browser confirmation before applying it. Verify that the proxy and every selected backend advertise v2 before using the WebUI. For production networks, wait for a compatible public VotingPlugin release. Retain console access and external backups for rollback. ## Troubleshooting @@ -178,6 +178,6 @@ Control [PR #13](https://github.com/BenCodez/VotingPlugin-Control/pull/13) is in ## Source references - [VotingPlugin HTTP transport PR #1594](https://github.com/BenCodez/VotingPlugin/pull/1594) -- [Development HTTP transport guide](https://github.com/BenCodez/VotingPlugin/blob/72d5183de1837082dd30173bbd203e45d9189d4c/docs/http-transport.md) -- [Development proxy configuration](https://github.com/BenCodez/VotingPlugin/blob/72d5183de1837082dd30173bbd203e45d9189d4c/VotingPlugin/src/main/resources/bungeeconfig.yml) -- [Development backend configuration](https://github.com/BenCodez/VotingPlugin/blob/72d5183de1837082dd30173bbd203e45d9189d4c/VotingPlugin/src/main/resources/BungeeSettings.yml) +- [Development HTTP transport guide](https://github.com/BenCodez/VotingPlugin/blob/bc9dac6303626e1757e4b5570b6fba548399fd27/docs/http-transport.md) +- [Development proxy configuration](https://github.com/BenCodez/VotingPlugin/blob/bc9dac6303626e1757e4b5570b6fba548399fd27/VotingPlugin/src/main/resources/bungeeconfig.yml) +- [Development backend configuration](https://github.com/BenCodez/VotingPlugin/blob/bc9dac6303626e1757e4b5570b6fba548399fd27/VotingPlugin/src/main/resources/BungeeSettings.yml)