diff --git a/.wikijs/navigation.json b/.wikijs/navigation.json index 12206e7..6164ea3 100644 --- a/.wikijs/navigation.json +++ b/.wikijs/navigation.json @@ -175,6 +175,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/Control-WebUI.md b/VotingPlugin/Control-WebUI.md index dd4faff..4ede832 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-14T00:00:00.000Z +date: 2026-09-20T00:00:00.000Z tags: editor: markdown dateCreated: 2026-08-31T00:00:00.000Z @@ -10,27 +10,31 @@ 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 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. -## Active development after Control v0.1.7 +## Control v1.0.0 compatibility boundary -> **Not available in Control v0.1.7:** Automatic selected-server loading, negotiated HTTP proxy-method switching, the private VotingPlugin artifact store, and VotingPlugin JAR staging are proposed by stacked Control PRs [#13](https://github.com/BenCodez/VotingPlugin-Control/pull/13), [#14](https://github.com/BenCodez/VotingPlugin-Control/pull/14), and [#15](https://github.com/BenCodez/VotingPlugin-Control/pull/15). Their node-side capabilities require VotingPlugin PR [#1594](https://github.com/BenCodez/VotingPlugin/pull/1594) at commit [`2e49dd66`](https://github.com/BenCodez/VotingPlugin/commit/2e49dd66699aefe24a572416053c9954e6e864e4) or later. All four PRs remain open and unreleased; do not rely on these workflows until compatible public releases exist. +> **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. Verified JAR staging requires merged commit [`e89e60bd`](https://github.com/BenCodez/VotingPlugin/commit/e89e60bd064f96c90499b6b5cabfe1ea2ae143e9) or later. HTTP and its negotiated `config.proxy-method.v2` workflow require merged development commit [`46088736`](https://github.com/BenCodez/VotingPlugin/commit/460887368d2a980b79bb8cebd518d5a5bd3f5913) or later. These changes are merged into development but have not shipped in a public VotingPlugin release. Installing Control v1.0.0 alone does not add them 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 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`. +- 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. -These workflows still require their open review findings to be resolved. Continue using manual VotingPlugin updates and manual HTTP configuration in the meantime. +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 @@ -183,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 | @@ -206,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. @@ -219,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. @@ -238,15 +266,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 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 -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 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 development build containing merged commit `e89e60bd` or later 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 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 @@ -254,6 +282,7 @@ Every configuration write uses the same sequence: 1. **Read** the current redacted configuration and revision. 2. **Preview** the exact proposed change independently on every selected target. + At this point nothing has been saved. Ctrl/Command+S in the full YAML editor also performs this preview step only. 3. Review all target changes and failures. 4. Confirm the one-time approval generated for that successful preview. 5. **Apply** using the exact revisions from preview. @@ -315,7 +344,8 @@ 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. | +| No connected node is eligible for a VotingPlugin deployment | VotingPlugin 7.1.1 lacks `plugin.deploy.v1`. Manually install a development build containing merged commit `e89e60bd` or later 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 @@ -345,10 +375,15 @@ 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 proposal (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 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) - [Development backend `Config.yml`](https://github.com/BenCodez/VotingPlugin/blob/master/VotingPlugin/src/main/resources/Config.yml) diff --git a/VotingPlugin/Proxy-Setups.md b/VotingPlugin/Proxy-Setups.md index f88cc86..87bdec3 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](/VotingPlugin/Proxy-method-PLUGINMESSAGING) | Uses the proxy plugin-message channel; this is the 7.1.1 release default. | +| [HTTP](/VotingPlugin/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](/VotingPlugin/proxy-method-REDIS) | Uses a private Redis service for cross-server messages. | | [MQTT](/VotingPlugin/proxy-method-MQTT) | Uses an MQTT broker for cross-server messages. | | [SOCKETS](/VotingPlugin/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..0169575 --- /dev/null +++ b/VotingPlugin/proxy-method-HTTP.md @@ -0,0 +1,183 @@ +--- +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-20T00: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**. [VotingPlugin PR #1594](https://github.com/BenCodez/VotingPlugin/pull/1594) is merged into development at commit [`46088736`](https://github.com/BenCodez/VotingPlugin/commit/460887368d2a980b79bb8cebd518d5a5bd3f5913), but it has not shipped in a public release. Release users do not have the `HTTP` method, its configuration keys, or its proxy commands. Use a build containing `46088736` or later only for development testing; production networks should wait for a compatible public VotingPlugin release. +{.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. Put at least one player online on each backend, then run the proxy status command and confirm every expected backend responds. The status command skips empty backends. +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. +- An HTTP Vote Party threshold commit journals backend reward deliveries, the proxy broadcast, and ordered proxy commands together. Pending proxy effects resume after restart, but those local effects are at-least-once: a crash after execution and before progress is saved can repeat one. A Velocity command that does not complete within 60 seconds moves to `VoteParty.QuarantinedProxyEffects` for manual review instead of blocking later work. +- 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 + +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 development build containing merged commit `46088736` or later. + +Control [PR #13](https://github.com/BenCodez/VotingPlugin-Control/pull/13) is included in v1.0.0, while the merged-but-unreleased VotingPlugin commit `46088736` provides the 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 + +| 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](/VotingPlugin/Proxy-Setups) +- [Dedicated Voting Proxy](/VotingPlugin/Dedicated-Voting-Proxy) +- [PLUGINMESSAGING](/VotingPlugin/Proxy-method-PLUGINMESSAGING) +- [Redis](/VotingPlugin/proxy-method-REDIS) +- [Votifier Troubleshooting](/VotingPlugin/Votifier-Troubleshooting) +- [Online and Offline Mode](/VotingPlugin/Online-Offline-Mode) + +## Source references + +- [VotingPlugin HTTP transport PR #1594](https://github.com/BenCodez/VotingPlugin/pull/1594) +- [Merged HTTP transport guide](https://github.com/BenCodez/VotingPlugin/blob/460887368d2a980b79bb8cebd518d5a5bd3f5913/docs/http-transport.md) +- [Merged proxy configuration](https://github.com/BenCodez/VotingPlugin/blob/460887368d2a980b79bb8cebd518d5a5bd3f5913/VotingPlugin/src/main/resources/bungeeconfig.yml) +- [Merged backend configuration](https://github.com/BenCodez/VotingPlugin/blob/460887368d2a980b79bb8cebd518d5a5bd3f5913/VotingPlugin/src/main/resources/BungeeSettings.yml) diff --git a/sidebar.md b/sidebar.md index b24de1c..456414a 100644 --- a/sidebar.md +++ b/sidebar.md @@ -32,6 +32,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)