enderpearl 1.0.1

Async proxy for Minecraft and HTTP traffic with automated server wake-up.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

# enderpearl

[![Crates.io](https://img.shields.io/crates/v/enderpearl?style=flat-square)](https://crates.io/crates/enderpearl)
[![CI](https://img.shields.io/github/actions/workflow/status/SirCesarium/enderpearl/ci.yml?branch=main&style=flat-square)](https://github.com/SirCesarium/enderpearl/actions)
[![License](https://img.shields.io/github/license/SirCesarium/enderpearl?style=flat-square)]()

Async reverse proxy for Minecraft Java and HTTP traffic with automated server lifecycle.

Enderpearl shuts down the backend when idle and wakes it on ping or join.

## Install

```bash
cargo install enderpearl
```

Or download a prebuilt binary from [GitHub Releases](https://github.com/SirCesarium/enderpearl/releases) — `.deb`, `.rpm`, `.msi` included.

Docker:

```bash
docker pull ghcr.io/sircesarium/enderpearl
```

## Quick start

```bash
enderpearl init              # interactive config wizard
enderpearl                   # start proxy (reads enderpearl.toml)
```

## Configuration

```toml
[server]
bind = "0.0.0.0"
port = 25565

[upstream.minecraft_java]
forward_to = "127.0.0.1:25566"
wake_command = "docker start mc-server"

# Optional:
shutdown_cmd = "docker stop mc-server"
startup_on = "ping"                # join | ping | always
offline_motd = "{...}"             # fake MOTD JSON
offline_message = "{...}"          # fake disconnect JSON
startup_webhook = "https://..."    # POST on wake
shutdown_webhook = "https://..."   # POST on shutdown

[upstream.web]
forward_to = "127.0.0.1:8080"
```

When a client connects, enderpearl checks if the backend is reachable. If online, traffic is proxied straight through. If offline, `JavaProxy` intercepts the Minecraft handshake, responds with a fake MOTD (or disconnect), and runs `wake_command` to start the server. An inactivity monitor polls the backend and runs `shutdown_cmd` after the configured idle timeout.

## CLI

| Command | What |
|---------|------|
| `run` (default) | Start the proxy |
| `init` | Interactive config wizard |

| Flag | What |
|------|------|
| `-c`, `--config` | Config path (default: `enderpearl.toml`) |

## Library usage

Embed enderpearl's proxy engine in your own Rust application:

```bash
cargo add enderpearl --no-default-features --features java
```

```rust
let config = EnderConfig {
    bind: "0.0.0.0".into(),
    port: 25565,
    upstreams: vec![EnderRoute::new(
        ProtocolKind::Java.instantiate(false).unwrap(),
        vec!["127.0.0.1:25566".into()],
    )],
    ..Default::default()
};

let router = EnderRouter::new(&config, &HashMap::new())?;
router.serve("0.0.0.0:25565".parse()?).await?;
```

Custom lifecycle handler — implement `LifecycleHandler` for your own startup/shutdown logic:

```rust
impl LifecycleHandler for MyHandler {
    fn on_startup(&self) -> AsyncResultFuture {
        Box::pin(async { /* docker start, systemctl, etc */ })
    }
    fn on_shutdown(&self) -> AsyncResultFuture {
        Box::pin(async { /* docker stop, etc */ })
    }
}
```

Custom protocols — define new protocol handlers with `ServerProxy`:

```rust
struct BedrockProxy { /* ... */ }

impl ServerProxy for BedrockProxy {
    fn serve(self: Arc<Self>) -> Pin<Box<dyn Future<Output = Result<u16>> + Send>> {
        Box::pin(async move {
            let listener = TcpListener::bind("127.0.0.1:0").await?;
            let port = listener.local_addr()?.port();
            // accept loop with custom MOTD, wake, etc
            Ok(port)
        })
    }
}
```

Then add it to the config:

```rust
let mut route = EnderRoute::new(Arc::new(MyProtocol), vec!["127.0.0.1:12345".into()]);
route.proxy = Some(Arc::new(BedrockProxy { .. }));
```

The route is redirected to the proxy's local port — refractium handles traffic detection and forwarding.

## Feature flags

| Feature | What |
|---------|------|
| `cli` | CLI parsing (`enderpearl init`, `--config`) + TOML parsing |
| `java` | Minecraft Java protocol detection and `JavaProxy` |
| `web` | HTTP protocol detection |
| `pretty-cli` | Colored output, banners, spinners |
| `logging` | Structured tracing to stderr |

```bash
# Headless server, no colors needed:
cargo install enderpearl --no-default-features --features cli,java,web,logging
```

> [!NOTE]
> Maintenance mode. Bug fixes and dep updates only.

## License

MIT