Proxy Network Integration

This page documents the proxy-backed features of EzEconomy: distributed locking, proxy-side caching, and cross-server payment notifications via plugin messaging between servers and a proxy.

Summary

  • EzEconomy supports both Velocity and BungeeCord/Waterfall proxies for cross-server communication.
  • Velocity: deploy ezeconomy-velocity.jar on the proxy for payment notifications and player list broadcasting. See Velocity integration.
  • BungeeCord: deploy ezeconomy-bungeecord-proxy.jar on the proxy for locking, caching, and payment notifications. Use locking-strategy: BUNGEECORD and/or caching-strategy: BUNGEECORD in config.yml.
  • Redis: use RedisMessagingTransport from ezeconomy-redis for proxy-independent cross-server messaging. See Cross-server messaging.

Why use the proxy-backed model

  • Centralizes lock and cache state on the proxy, reducing cross-server coordination complexity from servers’ perspectives.
  • Useful when you prefer the proxy to act as the canonical short-term store (e.g., small networks without Redis).

Server configuration (core plugin)

  • In config.yml on each backend server set:
locking-strategy: BUNGEECORD
caching-strategy: BUNGEECORD
  • Ensure you have the ezeconomy-bungeecord extension installed on the server (if required) or that the server classpath can provide the lock/cache provider implementations.
  • Edit bungeecord.yml in the server plugin data folder to match the proxy settings (example below).

bungeecord.yml (server-side) example 

enabled: true
channel: ezeconomy:locks
ttl-ms: 60000          # default TTL for lock requests
retry-ms: 150          # retry interval when awaiting responses
max-attempts: 5        # how many times to retry acquiring a lock
fallback-to-local: true
shared-secret: "your-secret"   # optional: must match proxy config

Proxy configuration (proxy component)

  • Deploy ezeconomy-bungeecord-proxy on your Bungee/Waterfall proxy and place a bungeecord.yml in the proxy plugin data folder. Important keys:
enabled: true
channel: ezeconomy:locks
shared-secret: "your-secret"   # must match servers when set
cleanup-interval-ms: 5000       # how often the proxy evicts expired locks/cached entries

# Optional: proxy storage/redis config for cache backing
proxy:
  enabled: true
  type: redis
  redis:
    host: 127.0.0.1
    port: 6379
    password: ''
    database: 0

# Optional lightweight cache tuning
cache:
  enabled: true
  ttl-seconds: 300

How it works

  • Servers send plugin messaging packets to the proxy on the configured channel.
  • Supported packet actions:
    • ACQUIRE / ACQUIRE_RESPONSE — lock management (returns a token on success)
    • RELEASE — release a lock
    • CACHE_GET / CACHE_GET_RESPONSE — fetch a cached value and its expiry
    • CACHE_SET — set a cached value with TTL on the proxy
  • Messages include an optional shared-secret for basic authentication between servers and the proxy.

Behavior and safety notes

  • If fallback-to-local is true on servers, the plugin will fall back to in-JVM locking/caching when the proxy is unavailable. This prevents startup or runtime failures when the proxy is down but may reduce cross-server consistency.
  • The proxy evicts expired locks and cache entries based on cleanup-interval-ms.
  • Plugin messaging requires at least one online player to send messages from a server to the proxy; the transport implementation chooses an arbitrary online player to send messages. Ensure servers have at least one dummy or real online player for critical operations, or prefer Redis for fully headless reliability.

Troubleshooting

  • Mismatch in shared-secret will result in silently ignored messages — check proxy and server logs for authentication failures.
  • If messages appear to time out, verify channel matches on servers and proxy and that the proxy plugin is enabled and connected.
  • Use fallback-to-local: true during testing to avoid hard failures while verifying configuration.

See also