EasyLibraryAgent

Current stable release: 1.0.0

EasyLibraryAgent is the external Go service used by the optional EasyLibrary Agent Bridge. It is not a Minecraft proxy and does not replace PocketMine-MP. Players still connect to PMMP normally.

The Agent provides shared network services for PMMP plugins that use EasyLibrary:

• server registry and heartbeat state
• PubSub events
• reliable delivery tracking
• KV storage, flags and locks with TTL
• RPC request/response
• safe allowlisted compute services
• local interactive console for operations
• server-style runtime directories

PocketMine-MP plugins should integrate through the EasyLibrary PHP namespaces:

imperazim\agent\api\*
imperazim\agent\constant\*
imperazim\agent\event\*

The /easyagent PMMP command is diagnostic/admin/debug tooling. Real plugin flows should use the API and listeners.

Recommended installation from a release binary

Stable releases provide ready-to-run binaries in the GitHub Releases page. The recommended production flow is to download the binary for your system instead of building from source.

Example for Linux AMD64:

mkdir -p ~/easylibrary-agent
cd ~/easylibrary-agent

# Upload or download the release binary into this folder.
# Example filename used by releases:
# easylib-agent-linux-amd64

chmod +x easylib-agent-linux-amd64
./easylib-agent-linux-amd64 --version
# Expected: EasyLibraryAgent 1.0.0
./easylib-agent-linux-amd64 --init
nano config/agent.toml
./easylib-agent-linux-amd64 --config config/agent.toml

For Windows, use the .exe binary from the release page:

.\easylib-agent-windows-amd64.exe --version
# Expected: EasyLibraryAgent 1.0.0
.\easylib-agent-windows-amd64.exe --init
.\easylib-agent-windows-amd64.exe --config config\agent.toml

Release assets should include at least:

easylib-agent-linux-amd64
easylib-agent-linux-arm64
easylib-agent-windows-amd64.exe
checksums.txt
agent.example.toml

Build from source

Build manually when developing the Agent or testing unreleased changes:

git clone https://github.com/ImperaZim/EasyLibraryAgent.git
cd EasyLibraryAgent
go test ./...
go build -o easylib-agent ./cmd/easylib-agent
./easylib-agent --version
# Expected: EasyLibraryAgent 1.0.0

Initialize directories and config:

./easylib-agent --init

Start the service:

./easylib-agent --config config/agent.toml

Stable Compatibility

EasyLibraryAgent 1.0.0 is the stable release of the external Agent service.

Use it with EasyLibraryAgentBridge 1.0.0+ or the embedded Agent Bridge shipped with EasyLibrary 2.0.0+.

Runtime directories

--init creates a server-style layout:

config/   agent.toml and config samples
plugins/  reserved for future Agent extensions; no external code is loaded yet
logs/     reserved for logs when file logging is added
data/     reserved for persistent runtime data
runtime/  reserved for process/runtime metadata

The Agent never overwrites an existing agent.toml or config/agent.toml.

Minimal production config

Edit config/agent.toml and replace the placeholder secret with a strong random value.

bind = "0.0.0.0:25508"
secret = "CHANGE_ME_REPLACE_WITH_RANDOM_SECRET"

[sync]
enabled = true
default_ttl_seconds = 30

[logging]
level = "info"
log_heartbeats = false
log_kv = false
log_connections = true
log_pubsub = false

[delivery]
expire_seconds = 0
completed_retention_seconds = 600
failed_retention_seconds = 1800
max_records = 1000

[registry]
stale_seconds = 30
offline_retention_seconds = 300

[console]
enabled = true
prompt = "> "

[compute]
enabled = true
default_timeout_seconds = 5
max_payload_bytes = 65536
max_concurrent_tasks = 4
retain_seconds = 600
allowed_methods = ["compute.ping", "compute.echo", "compute.math.basic", "compute.json.diff", "compute.region.intersects", "compute.leaderboard.sort"]

Keep the Agent port private whenever possible. Use a firewall, panel rules or a private network/VPN when running multiple servers.

Connect PocketMine-MP servers

In EasyLibrary's plugin_data/EasyLibrary/config.yml, enable the bridge explicitly:

agent:
  enabled: true
  address: "127.0.0.1:25508"
  secret: "CHANGE_ME_REPLACE_WITH_THE_SAME_AGENT_SECRET"
  server-id: "rankup-main"
  required: false

Use a unique server-id for every PMMP server connected to the same Agent.

Recommended production command surface:

agent:
  commands:
    enabled: true
    advanced: false
    debug: false

With this setup, /easyagent remains available for status/report diagnostics, while real network activity is performed by plugins through EasyLibrary APIs.

Use From Other Systems

External tools can talk to EasyLibraryAgent directly over TCP JSON-line requests. This is useful for Discord bots, panels, Java plugins, monitoring scripts and deployment automation.

Minimal request:

{"type":"ping","request_id":"tool-1","token":"CHANGE_ME","server_id":"external-tool","payload":{}}

Common external bridge uses:

• read server registry with servers.registry
• publish network messages with pubsub.publish
• set temporary flags with network.flag.set
• run allowlisted compute tasks with compute.run
• build custom responders with pubsub.poll, delivery.ack, delivery.result and rpc.response

See docs/BRIDGES.md for Discord.js, Java plugin and generic bridge examples.

Interactive console

When the Agent runs in a terminal, screen or tmux session, it accepts commands from stdin:

help
status
health
version
dirs
servers
servers info <serverId>
registry
delivery status
delivery recent [limit]
rpc summary
rpc recent [limit]
kv namespaces [limit]
flags [limit]
pubsub status
pubsub channels
pubsub recent [limit]
compute methods
compute recent [limit]
clear
exit
stop

Example:

EasyLibrary Agent 1.0.0 listening on 0.0.0.0:25508
Agent console ready. Type 'help' for commands.
> servers
> compute methods
> stop

The interactive console is local-only. It is not a remote admin API.

Compute services

Compute services let the Agent act as a small safe coprocessor for tasks that are expensive, global, batch-oriented or asynchronous.

Use compute for:

• region intersection checks
• leaderboard sorting
• JSON diff reports
• simple math batches
• future plugin-specific validation jobs

Do not use compute for:

• tiny same-tick calculations
• permission checks
• formatting a single string
• arbitrary code execution
• direct world mutation

The PHP side only exposes official constants such as AgentComputeMethods::REGION_INTERSECTS, and the Go side validates compute.allowed_methods.

See docs/COMPUTE.md.

Running with systemd

A simple Linux service can run the release binary:

[Unit]
Description=EasyLibraryAgent
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/easylibrary-agent
ExecStart=/opt/easylibrary-agent/easylib-agent-linux-amd64 --config /opt/easylibrary-agent/config/agent.toml
Restart=on-failure
RestartSec=5s
User=easylib
Group=easylib

[Install]
WantedBy=multi-user.target

See docs/SYSTEMD.md for a complete setup.

Documentation

• docs/INSTALL.md - release binary install and source build.
• docs/CONFIG.md - config reference and production examples.
• docs/BRIDGES.md - Discord.js, Java plugin and generic TCP bridge examples.
• docs/CONSOLE.md - interactive console commands.
• docs/DIRECTORIES.md - runtime directory layout.
• docs/OPERATIONS.md - operation notes and common commands.
• docs/SYSTEMD.md - Linux service setup.
• docs/COMPUTE.md - allowlisted coprocessor services.
• docs/SECURITY.md - secret, firewall and safe method rules.
• docs/TROUBLESHOOTING.md - common failures and fixes.
• docs/PROTOCOL.md - JSON-line protocol overview.
• docs/RELEASE_CHECKLIST.md - release validation checklist.

Troubleshooting quick checks

./easylib-agent --version
./easylib-agent --dirs
./easylib-agent --config config/agent.toml

Inside PMMP:

/easyagent status
/easyagent report
/easyagent report readiness

Common issues:

• secret mismatch: PMMP can connect but requests fail or are rejected.
• wrong address: PMMP cannot reach the Agent port.
• firewall/panel blocks the port: remote servers cannot connect.
• stale PubSub cursor after Agent restart: supported clients recover automatically with cursor reset metadata.
• agent.enabled=false: no Agent runtime or /easyagent command is loaded by EasyLibrary.

Security notes

• Use a strong random secret.
• Do not publish the secret in examples, screenshots, logs or support messages.
• Bind to a private interface when possible.
• Restrict the port with firewall rules.
• Keep compute and RPC methods allowlisted.
• Keep command dispatch protected by allowlist/blocklist settings.
• Treat /easyagent commands as diagnostics/admin/debug tools, not gameplay APIs.

License

EasyLibraryAgent is licensed under the MIT License.