calagoapi-minecraft 1.0.dev2__tar.gz → 2.0.dev1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. calagoapi_minecraft-2.0.dev1/PKG-INFO +172 -0
  2. calagoapi_minecraft-2.0.dev1/README.md +148 -0
  3. {calagoapi_minecraft-1.0.dev2 → calagoapi_minecraft-2.0.dev1}/calagoapi_minecraft/__init__.py +7 -10
  4. {calagoapi_minecraft-1.0.dev2 → calagoapi_minecraft-2.0.dev1}/calagoapi_minecraft/aio.py +5 -11
  5. calagoapi_minecraft-2.0.dev1/calagoapi_minecraft/bridge.py +33 -0
  6. calagoapi_minecraft-2.0.dev1/calagoapi_minecraft/config.py +72 -0
  7. {calagoapi_minecraft-1.0.dev2 → calagoapi_minecraft-2.0.dev1}/calagoapi_minecraft/exceptions.py +4 -4
  8. {calagoapi_minecraft-1.0.dev2 → calagoapi_minecraft-2.0.dev1}/calagoapi_minecraft/extension.py +6 -10
  9. {calagoapi_minecraft-1.0.dev2 → calagoapi_minecraft-2.0.dev1}/calagoapi_minecraft/manager.py +53 -56
  10. {calagoapi_minecraft-1.0.dev2 → calagoapi_minecraft-2.0.dev1}/calagoapi_minecraft/properties.py +43 -43
  11. calagoapi_minecraft-2.0.dev1/calagoapi_minecraft/server.py +463 -0
  12. calagoapi_minecraft-2.0.dev1/calagoapi_minecraft.egg-info/PKG-INFO +172 -0
  13. {calagoapi_minecraft-1.0.dev2 → calagoapi_minecraft-2.0.dev1}/calagoapi_minecraft.egg-info/SOURCES.txt +1 -3
  14. {calagoapi_minecraft-1.0.dev2 → calagoapi_minecraft-2.0.dev1}/calagoapi_minecraft.egg-info/requires.txt +1 -1
  15. {calagoapi_minecraft-1.0.dev2 → calagoapi_minecraft-2.0.dev1}/pyproject.toml +4 -4
  16. {calagoapi_minecraft-1.0.dev2 → calagoapi_minecraft-2.0.dev1}/tests/test_minecraft_examples.py +28 -8
  17. calagoapi_minecraft-2.0.dev1/tests/test_minecraft_extension.py +164 -0
  18. {calagoapi_minecraft-1.0.dev2 → calagoapi_minecraft-2.0.dev1}/tests/test_minecraft_server.py +50 -72
  19. calagoapi_minecraft-1.0.dev2/PKG-INFO +0 -204
  20. calagoapi_minecraft-1.0.dev2/README.md +0 -180
  21. calagoapi_minecraft-1.0.dev2/calagoapi_minecraft/bridge.py +0 -86
  22. calagoapi_minecraft-1.0.dev2/calagoapi_minecraft/config.py +0 -79
  23. calagoapi_minecraft-1.0.dev2/calagoapi_minecraft/server.py +0 -631
  24. calagoapi_minecraft-1.0.dev2/calagoapi_minecraft/versions.py +0 -232
  25. calagoapi_minecraft-1.0.dev2/calagoapi_minecraft.egg-info/PKG-INFO +0 -204
  26. calagoapi_minecraft-1.0.dev2/tests/test_minecraft_extension.py +0 -187
  27. calagoapi_minecraft-1.0.dev2/tests/test_minecraft_versions.py +0 -111
  28. {calagoapi_minecraft-1.0.dev2 → calagoapi_minecraft-2.0.dev1}/calagoapi_minecraft.egg-info/dependency_links.txt +0 -0
  29. {calagoapi_minecraft-1.0.dev2 → calagoapi_minecraft-2.0.dev1}/calagoapi_minecraft.egg-info/entry_points.txt +0 -0
  30. {calagoapi_minecraft-1.0.dev2 → calagoapi_minecraft-2.0.dev1}/calagoapi_minecraft.egg-info/top_level.txt +0 -0
  31. {calagoapi_minecraft-1.0.dev2 → calagoapi_minecraft-2.0.dev1}/setup.cfg +0 -0
@@ -0,0 +1,172 @@
1
+ Metadata-Version: 2.4
2
+ Name: calagoapi-minecraft
3
+ Version: 2.0.dev1
4
+ Summary: Minecraft servers for CalagoAPI: commands with output, console streaming, players and metrics through HungerBridge, bridge installs from Modrinth, server.properties.
5
+ Author: iFamished
6
+ License: GPL-3.0
7
+ Project-URL: Homepage, https://github.com/HungerNet/CalagoAPI
8
+ Project-URL: Documentation, https://github.com/HungerNet/CalagoAPI/tree/main/docs/tutorials/minecraft
9
+ Project-URL: Source, https://github.com/HungerNet/CalagoAPI/tree/main/src/extensions/calagoapi-minecraft
10
+ Project-URL: HungerBridge, https://modrinth.com/project/hungerbridge
11
+ Project-URL: HungerBridgePy, https://github.com/HungerNet/HungerBridgePy
12
+ Keywords: calagopus,calagoapi,minecraft,hungerbridge,paper,fabric,extension
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Development Status :: 4 - Beta
17
+ Classifier: Intended Audience :: Developers
18
+ Classifier: Topic :: Games/Entertainment
19
+ Requires-Python: >=3.9
20
+ Description-Content-Type: text/markdown
21
+ Requires-Dist: calagoapi>=2.0.dev1
22
+ Requires-Dist: hungerbridge>=2.0.dev1
23
+ Requires-Dist: requests
24
+
25
+ # calagoapi-minecraft
26
+
27
+ Minecraft servers for [CalagoAPI](https://github.com/HungerNet/CalagoAPI), the Calagopus
28
+ panel SDK. `MinecraftServer` is a `calagoapi.Server` with Minecraft features:
29
+
30
+ - **commands with output** and **live console streaming** through
31
+ [HungerBridge](https://modrinth.com/project/hungerbridge), the plugin/mod inside the game,
32
+ using [HungerBridgePy](https://github.com/HungerNet/HungerBridgePy) (`server.bridge`);
33
+ - installing HungerBridge from Modrinth and creating its tokens through the panel;
34
+ - `server.properties`, EULA, chat and moderation helpers.
35
+
36
+ Version 2 needs HungerBridge 5 and HungerBridgePy 2 (protocol v2). Upgrading from 1.x:
37
+ [docs/migrating-minecraft-2.0.md](../../../docs/migrating-minecraft-2.0.md).
38
+
39
+ ```bash
40
+ pip install calagoapi calagoapi-minecraft # also installs hungerbridge (HungerBridgePy)
41
+ ```
42
+
43
+ ```python
44
+ from calagoapi import Panel
45
+ from calagoapi.extensions import enable
46
+
47
+ enable('minecraft', config={'bridge_token_id': 'calagoapi', 'bridge_token_secret': '9f2c...'})
48
+
49
+ with Panel(url='https://panel.example.com', api_key='c7sp_...') as panel:
50
+ server = panel.minecraft.getServer('abc123', bridge_url='http://10.0.0.5:1913')
51
+
52
+ print(server.sendCommand('list')) # the command's output (not printed on the console)
53
+ for line in server.streamConsole(history=10, timeout=30):
54
+ print(line)
55
+ print(f'{server.bridge.getPlayerCount()} online, TPS {server.bridge.getTPS("1m")}')
56
+ print(f'container {server.getRAM()} MiB, heap {server.bridge.getMemoryStats()["heap_used"]:.0f} MiB')
57
+ ```
58
+
59
+ Learn it step by step in the [Minecraft tutorials](../../../docs/tutorials/README.md#track-3-minecraft);
60
+ runnable code is in [examples/minecraft/](../../../examples/minecraft/README.md).
61
+
62
+ ## Two channels
63
+
64
+ | Channel | Used by |
65
+ | --- | --- |
66
+ | **Panel / daemon** (CalagoAPI) | everything inherited from `Server`: `start()`, `stop()`, `restart()`, `getRAM()`, `getCPU()`, `getStatus()`, files, backups, ...; plus `server.properties`, EULA, `installBridge()`, `createBridgeToken()`, `sendPanelCommand()`, `server.console` |
67
+ | **HungerBridge** (HungerBridgePy) | `sendCommand()`, `sendCommands()`, `streamConsole()`, `onConsoleLine()`, the chat and moderation helpers, and everything on `server.bridge` |
68
+
69
+ `server.bridge` is a `hungerbridge.BridgeClient`: players, TPS/MSPT, world, JVM metrics,
70
+ `log()`, `streamLogs()`, `broadcast()`, ... are used with HungerBridgePy's own names (see its
71
+ [API table](https://github.com/HungerNet/HungerBridgePy#api)); CalagoAPI does not add aliases.
72
+ `MinecraftServer` itself only adds what combines the panel with the bridge, or what replaces
73
+ a `Server` method with its bridge version.
74
+
75
+ Nothing falls back silently. Bridge methods without a token raise
76
+ `BridgeNotConfiguredError`; HungerBridge errors are raised as HungerBridgePy's
77
+ `hungerbridge.HungerBridgeError` subclasses (`HungerBridgeAuthError` with `.reason`,
78
+ `HungerBridgeForbidden`, `HungerBridgeNotFound`, `HungerBridgeRateLimit`,
79
+ `HungerBridgeConnectionError`, `HungerBridgeProtocolError`).
80
+
81
+ ## Getting a server
82
+
83
+ ```python
84
+ server = panel.minecraft.getServer('abc123') # after enable('minecraft')
85
+ server = panel.minecraft.getServer('abc123', address='play.example.com', bridge_url=...,
86
+ bridge_token_id=..., bridge_token_secret=...)
87
+ server = panel.minecraft.fromServer(panel.servers.getServerByName('Survival'))
88
+ servers = panel.minecraft.getServers() # every visible server, as MinecraftServer
89
+
90
+ from calagoapi_minecraft import MinecraftServer # works without enable() too
91
+ server = MinecraftServer(panel, 'abc123', bridge_token_id='calagoapi', bridge_token_secret='9f2c...')
92
+ ```
93
+
94
+ The token id and secret are always separate values: give both or neither
95
+ (`ConfigurationError` otherwise, also for a secret that is not 64 hex characters).
96
+
97
+ ## Connecting HungerBridge
98
+
99
+ | Method | Description |
100
+ | --- | --- |
101
+ | `installBridge(minecraft_version, loader, *, version=None, replace=True)` | download the HungerBridge jar for that Minecraft version and loader (`paper`, `purpur`, `folia`, `fabric`) from Modrinth into `/plugins` or `/mods`; both arguments required, nothing is detected; returns a `hungerbridge.BridgeRelease` |
102
+ | `createBridgeToken(token_id='calagoapi', policy='admin', expiry=None, timeout=30, url=None)` | run `hb token create` on the console, redeem the pickup, connect; returns `hungerbridge.Credentials` |
103
+ | `redeemBridgePickup(pickup_url)` | redeem a pickup URL (or its `/pickup/...` part) and connect |
104
+ | `connectBridge(url=None, *, token_id=None, token_secret=None, **options)` | set URL/token (and `BridgeClient` options such as `timeout`) for this server |
105
+ | `setBridge(client)`, `closeBridge()` | use your own `BridgeClient`; close connections |
106
+ | `bridge` | the `hungerbridge.BridgeClient` |
107
+ | `getBridgeUrl()`, `hasBridge()`, `isBridgeReachable()`, `waitForBridge(timeout=120)` | |
108
+
109
+ The bridge URL is `bridge_url`, else the `bridge_url` config, else the server's address
110
+ with `bridge_port` (1913). HungerBridge binds `127.0.0.1` by default. Set its
111
+ `bind-address` and `security.yaml` `ips` so your code can reach it.
112
+
113
+ ## Commands and console
114
+
115
+ | Method | Description |
116
+ | --- | --- |
117
+ | `sendCommand(command, *, show_console=False)` | HungerBridgePy `runCommand()`: returns the output text; it reaches the server console only with `show_console=True` |
118
+ | `sendCommands(commands, *, show_console=False)` | list of outputs |
119
+ | `sendPanelCommand(command)` | through the panel (`Server.sendCommand`), no output |
120
+ | `streamConsole(history=0, timeout=None, *, reconnect=None)` | yields plain console lines `[HH:mm:ss] [thread/LEVEL]: [logger] message`; `history=True` = everything HungerBridge keeps (1000) |
121
+ | `onConsoleLine(callback, history=0, *, reconnect=None)` | background callbacks; returns the `hungerbridge.Stream` (`.disconnect()`) |
122
+ | `say`, `tellraw`, `kick`, `ban`, `pardon`, `op`, `deop`, `whitelistAdd`, `whitelistRemove`, `saveAll` | chat and moderation (return the command output) |
123
+
124
+ For structured events (`level`, `thread`, `logger`, `message`) use
125
+ `server.bridge.streamLogs()`; to write your own log lines, `server.bridge.log(message,
126
+ level, thread, logger, normalize)`.
127
+
128
+ ## server.properties and EULA
129
+
130
+ `getProperties()`, `getProperty(key, default=None)`, `setProperty(key, value)`,
131
+ `setProperties(values)` (comments and order are kept; booleans become `true`/`false`),
132
+ `getMOTD()`, `setMOTD(motd)`, `acceptEula()`, `isEulaAccepted()`.
133
+
134
+ ## Configuration
135
+
136
+ `enable('minecraft', config={...})`, all optional:
137
+
138
+ | Key | Default | Meaning |
139
+ | --- | --- | --- |
140
+ | `bridge_url` | `None` | HungerBridge URL for every server; `None` uses the server's address + `bridge_port` |
141
+ | `bridge_port` | `1913` | |
142
+ | `bridge_token_id`, `bridge_token_secret` | `None` | token for every server (the secret is masked in diagnostics) |
143
+ | `bridge_timeout` | `None` | seconds or `(connect, read)`; `None` = HungerBridgePy's `(5, 30)` |
144
+ | `bridge_max_retries` | `2` | retries after HTTP 429 |
145
+ | `stream_reconnect` | `True` | default `reconnect` of `streamConsole()` / `onConsoleLine()` |
146
+
147
+ Without `enable()`, `MinecraftServer` uses these defaults (`calagoapi_minecraft.settings()`).
148
+
149
+ ## Async
150
+
151
+ ```python
152
+ async with AsyncPanel(url=..., api_key=...) as panel:
153
+ server = await panel.minecraft.getServer('abc123')
154
+ print(await server.sendCommand('list'), await server.bridge.getTPS())
155
+ async for line in server.streamConsole(history=10):
156
+ print(line)
157
+ ```
158
+
159
+ `AsyncMinecraftServer` runs HungerBridgePy in worker threads (one per open stream);
160
+ `onConsoleLine()` accepts coroutine callbacks.
161
+
162
+ ## Package layout
163
+
164
+ | Module | Responsibility |
165
+ | --- | --- |
166
+ | `server.py` | `MinecraftServer` |
167
+ | `bridge.py` | client creation, pickup line parsing |
168
+ | `properties.py` | `server.properties` text handling |
169
+ | `manager.py` | `MinecraftManager` (`panel.minecraft`) |
170
+ | `extension.py`, `config.py` | `MinecraftExtension`, defaults, validation, `settings()` |
171
+ | `aio.py` | `AsyncMinecraftServer`, async type registrations |
172
+ | `exceptions.py` | `MinecraftError`, `BridgeNotConfiguredError` |
@@ -0,0 +1,148 @@
1
+ # calagoapi-minecraft
2
+
3
+ Minecraft servers for [CalagoAPI](https://github.com/HungerNet/CalagoAPI), the Calagopus
4
+ panel SDK. `MinecraftServer` is a `calagoapi.Server` with Minecraft features:
5
+
6
+ - **commands with output** and **live console streaming** through
7
+ [HungerBridge](https://modrinth.com/project/hungerbridge), the plugin/mod inside the game,
8
+ using [HungerBridgePy](https://github.com/HungerNet/HungerBridgePy) (`server.bridge`);
9
+ - installing HungerBridge from Modrinth and creating its tokens through the panel;
10
+ - `server.properties`, EULA, chat and moderation helpers.
11
+
12
+ Version 2 needs HungerBridge 5 and HungerBridgePy 2 (protocol v2). Upgrading from 1.x:
13
+ [docs/migrating-minecraft-2.0.md](../../../docs/migrating-minecraft-2.0.md).
14
+
15
+ ```bash
16
+ pip install calagoapi calagoapi-minecraft # also installs hungerbridge (HungerBridgePy)
17
+ ```
18
+
19
+ ```python
20
+ from calagoapi import Panel
21
+ from calagoapi.extensions import enable
22
+
23
+ enable('minecraft', config={'bridge_token_id': 'calagoapi', 'bridge_token_secret': '9f2c...'})
24
+
25
+ with Panel(url='https://panel.example.com', api_key='c7sp_...') as panel:
26
+ server = panel.minecraft.getServer('abc123', bridge_url='http://10.0.0.5:1913')
27
+
28
+ print(server.sendCommand('list')) # the command's output (not printed on the console)
29
+ for line in server.streamConsole(history=10, timeout=30):
30
+ print(line)
31
+ print(f'{server.bridge.getPlayerCount()} online, TPS {server.bridge.getTPS("1m")}')
32
+ print(f'container {server.getRAM()} MiB, heap {server.bridge.getMemoryStats()["heap_used"]:.0f} MiB')
33
+ ```
34
+
35
+ Learn it step by step in the [Minecraft tutorials](../../../docs/tutorials/README.md#track-3-minecraft);
36
+ runnable code is in [examples/minecraft/](../../../examples/minecraft/README.md).
37
+
38
+ ## Two channels
39
+
40
+ | Channel | Used by |
41
+ | --- | --- |
42
+ | **Panel / daemon** (CalagoAPI) | everything inherited from `Server`: `start()`, `stop()`, `restart()`, `getRAM()`, `getCPU()`, `getStatus()`, files, backups, ...; plus `server.properties`, EULA, `installBridge()`, `createBridgeToken()`, `sendPanelCommand()`, `server.console` |
43
+ | **HungerBridge** (HungerBridgePy) | `sendCommand()`, `sendCommands()`, `streamConsole()`, `onConsoleLine()`, the chat and moderation helpers, and everything on `server.bridge` |
44
+
45
+ `server.bridge` is a `hungerbridge.BridgeClient`: players, TPS/MSPT, world, JVM metrics,
46
+ `log()`, `streamLogs()`, `broadcast()`, ... are used with HungerBridgePy's own names (see its
47
+ [API table](https://github.com/HungerNet/HungerBridgePy#api)); CalagoAPI does not add aliases.
48
+ `MinecraftServer` itself only adds what combines the panel with the bridge, or what replaces
49
+ a `Server` method with its bridge version.
50
+
51
+ Nothing falls back silently. Bridge methods without a token raise
52
+ `BridgeNotConfiguredError`; HungerBridge errors are raised as HungerBridgePy's
53
+ `hungerbridge.HungerBridgeError` subclasses (`HungerBridgeAuthError` with `.reason`,
54
+ `HungerBridgeForbidden`, `HungerBridgeNotFound`, `HungerBridgeRateLimit`,
55
+ `HungerBridgeConnectionError`, `HungerBridgeProtocolError`).
56
+
57
+ ## Getting a server
58
+
59
+ ```python
60
+ server = panel.minecraft.getServer('abc123') # after enable('minecraft')
61
+ server = panel.minecraft.getServer('abc123', address='play.example.com', bridge_url=...,
62
+ bridge_token_id=..., bridge_token_secret=...)
63
+ server = panel.minecraft.fromServer(panel.servers.getServerByName('Survival'))
64
+ servers = panel.minecraft.getServers() # every visible server, as MinecraftServer
65
+
66
+ from calagoapi_minecraft import MinecraftServer # works without enable() too
67
+ server = MinecraftServer(panel, 'abc123', bridge_token_id='calagoapi', bridge_token_secret='9f2c...')
68
+ ```
69
+
70
+ The token id and secret are always separate values: give both or neither
71
+ (`ConfigurationError` otherwise, also for a secret that is not 64 hex characters).
72
+
73
+ ## Connecting HungerBridge
74
+
75
+ | Method | Description |
76
+ | --- | --- |
77
+ | `installBridge(minecraft_version, loader, *, version=None, replace=True)` | download the HungerBridge jar for that Minecraft version and loader (`paper`, `purpur`, `folia`, `fabric`) from Modrinth into `/plugins` or `/mods`; both arguments required, nothing is detected; returns a `hungerbridge.BridgeRelease` |
78
+ | `createBridgeToken(token_id='calagoapi', policy='admin', expiry=None, timeout=30, url=None)` | run `hb token create` on the console, redeem the pickup, connect; returns `hungerbridge.Credentials` |
79
+ | `redeemBridgePickup(pickup_url)` | redeem a pickup URL (or its `/pickup/...` part) and connect |
80
+ | `connectBridge(url=None, *, token_id=None, token_secret=None, **options)` | set URL/token (and `BridgeClient` options such as `timeout`) for this server |
81
+ | `setBridge(client)`, `closeBridge()` | use your own `BridgeClient`; close connections |
82
+ | `bridge` | the `hungerbridge.BridgeClient` |
83
+ | `getBridgeUrl()`, `hasBridge()`, `isBridgeReachable()`, `waitForBridge(timeout=120)` | |
84
+
85
+ The bridge URL is `bridge_url`, else the `bridge_url` config, else the server's address
86
+ with `bridge_port` (1913). HungerBridge binds `127.0.0.1` by default. Set its
87
+ `bind-address` and `security.yaml` `ips` so your code can reach it.
88
+
89
+ ## Commands and console
90
+
91
+ | Method | Description |
92
+ | --- | --- |
93
+ | `sendCommand(command, *, show_console=False)` | HungerBridgePy `runCommand()`: returns the output text; it reaches the server console only with `show_console=True` |
94
+ | `sendCommands(commands, *, show_console=False)` | list of outputs |
95
+ | `sendPanelCommand(command)` | through the panel (`Server.sendCommand`), no output |
96
+ | `streamConsole(history=0, timeout=None, *, reconnect=None)` | yields plain console lines `[HH:mm:ss] [thread/LEVEL]: [logger] message`; `history=True` = everything HungerBridge keeps (1000) |
97
+ | `onConsoleLine(callback, history=0, *, reconnect=None)` | background callbacks; returns the `hungerbridge.Stream` (`.disconnect()`) |
98
+ | `say`, `tellraw`, `kick`, `ban`, `pardon`, `op`, `deop`, `whitelistAdd`, `whitelistRemove`, `saveAll` | chat and moderation (return the command output) |
99
+
100
+ For structured events (`level`, `thread`, `logger`, `message`) use
101
+ `server.bridge.streamLogs()`; to write your own log lines, `server.bridge.log(message,
102
+ level, thread, logger, normalize)`.
103
+
104
+ ## server.properties and EULA
105
+
106
+ `getProperties()`, `getProperty(key, default=None)`, `setProperty(key, value)`,
107
+ `setProperties(values)` (comments and order are kept; booleans become `true`/`false`),
108
+ `getMOTD()`, `setMOTD(motd)`, `acceptEula()`, `isEulaAccepted()`.
109
+
110
+ ## Configuration
111
+
112
+ `enable('minecraft', config={...})`, all optional:
113
+
114
+ | Key | Default | Meaning |
115
+ | --- | --- | --- |
116
+ | `bridge_url` | `None` | HungerBridge URL for every server; `None` uses the server's address + `bridge_port` |
117
+ | `bridge_port` | `1913` | |
118
+ | `bridge_token_id`, `bridge_token_secret` | `None` | token for every server (the secret is masked in diagnostics) |
119
+ | `bridge_timeout` | `None` | seconds or `(connect, read)`; `None` = HungerBridgePy's `(5, 30)` |
120
+ | `bridge_max_retries` | `2` | retries after HTTP 429 |
121
+ | `stream_reconnect` | `True` | default `reconnect` of `streamConsole()` / `onConsoleLine()` |
122
+
123
+ Without `enable()`, `MinecraftServer` uses these defaults (`calagoapi_minecraft.settings()`).
124
+
125
+ ## Async
126
+
127
+ ```python
128
+ async with AsyncPanel(url=..., api_key=...) as panel:
129
+ server = await panel.minecraft.getServer('abc123')
130
+ print(await server.sendCommand('list'), await server.bridge.getTPS())
131
+ async for line in server.streamConsole(history=10):
132
+ print(line)
133
+ ```
134
+
135
+ `AsyncMinecraftServer` runs HungerBridgePy in worker threads (one per open stream);
136
+ `onConsoleLine()` accepts coroutine callbacks.
137
+
138
+ ## Package layout
139
+
140
+ | Module | Responsibility |
141
+ | --- | --- |
142
+ | `server.py` | `MinecraftServer` |
143
+ | `bridge.py` | client creation, pickup line parsing |
144
+ | `properties.py` | `server.properties` text handling |
145
+ | `manager.py` | `MinecraftManager` (`panel.minecraft`) |
146
+ | `extension.py`, `config.py` | `MinecraftExtension`, defaults, validation, `settings()` |
147
+ | `aio.py` | `AsyncMinecraftServer`, async type registrations |
148
+ | `exceptions.py` | `MinecraftError`, `BridgeNotConfiguredError` |
@@ -2,22 +2,24 @@
2
2
  calagoapi-minecraft: Minecraft servers for CalagoAPI.
3
3
 
4
4
  `MinecraftServer` is a `calagoapi.Server` with Minecraft features. Commands with
5
- output, console streaming, players and game/JVM metrics go through HungerBridge (the
6
- plugin/mod inside the game) using HungerBridgePy; power, resources and files stay on
7
- the panel.
5
+ output, console streaming and everything else inside the game go through HungerBridge
6
+ (the plugin/mod) using HungerBridgePy (`server.bridge`); power, resources and files stay
7
+ on the panel.
8
8
 
9
9
  from calagoapi import Panel
10
10
  from calagoapi.extensions import enable
11
11
 
12
- enable('minecraft', config={'bridge_token': 'bot:9f2c...'})
12
+ enable('minecraft', config={'bridge_token_id': 'bot', 'bridge_token_secret': '9f2c...'})
13
13
  panel = Panel(url='https://panel.example.com', api_key='...')
14
14
 
15
15
  server = panel.minecraft.getServer('abc123', bridge_url='http://10.0.0.5:1913')
16
16
  print(server.sendCommand('list'))
17
+ print(server.bridge.getTPS('1m'))
17
18
  for line in server.streamConsole(history=10, timeout=30):
18
19
  print(line)
19
20
 
20
- MinecraftServer also works without enable(): MinecraftServer(panel, 'abc123', bridge_token=...).
21
+ MinecraftServer also works without enable():
22
+ MinecraftServer(panel, 'abc123', bridge_token_id=..., bridge_token_secret=...).
21
23
  '''
22
24
  from importlib.metadata import version as _pkg_version, PackageNotFoundError
23
25
 
@@ -28,7 +30,6 @@ except PackageNotFoundError:
28
30
 
29
31
  from .exceptions import BridgeNotConfiguredError, MinecraftError # noqa: E402
30
32
  from .config import DEFAULT_CONFIG, settings # noqa: E402
31
- from .versions import PANEL_EXTENSION, VersionChangerAdmin, VersionChangerAPI, VersionManager # noqa: E402
32
33
  from .server import DEFAULT_PORT, MinecraftServer # noqa: E402
33
34
  from .manager import MinecraftManager # noqa: E402
34
35
  from .extension import MinecraftExtension # noqa: E402
@@ -40,13 +41,9 @@ __all__ = [
40
41
  'MinecraftManager',
41
42
  'MinecraftExtension',
42
43
  'AsyncMinecraftServer',
43
- 'VersionManager',
44
- 'VersionChangerAdmin',
45
- 'VersionChangerAPI',
46
44
  'MinecraftError',
47
45
  'BridgeNotConfiguredError',
48
46
  'DEFAULT_CONFIG',
49
47
  'DEFAULT_PORT',
50
- 'PANEL_EXTENSION',
51
48
  'settings',
52
49
  ]
@@ -3,7 +3,7 @@ AsyncPanel support: registers how calagoapi-minecraft objects are wrapped.
3
3
 
4
4
  async with AsyncPanel(url=..., api_key=...) as panel:
5
5
  server = await panel.minecraft.getServer('abc123')
6
- print(await server.getTPS())
6
+ print(await server.bridge.getTPS())
7
7
  async for line in server.streamConsole(history=10):
8
8
  print(line)
9
9
 
@@ -18,7 +18,6 @@ from hungerbridge import BridgeClient, Stream
18
18
  from calagoapi.aio import AsyncServer, AsyncWrapper, iterateInThread, registerAsyncType, wrap
19
19
 
20
20
  from calagoapi_minecraft.server import MinecraftServer
21
- from calagoapi_minecraft.versions import VersionChangerAdmin, VersionManager
22
21
 
23
22
 
24
23
  class AsyncMinecraftServer(AsyncServer):
@@ -26,8 +25,7 @@ class AsyncMinecraftServer(AsyncServer):
26
25
  The async version of MinecraftServer. Every method is awaitable;
27
26
  streamConsole() is an async generator over HungerBridge's log stream.
28
27
  '''
29
- async def streamConsole(self, history: int = 0, timeout: float = None, *, reconnect: bool = None,
30
- sanitize: bool = True):
28
+ async def streamConsole(self, history: int = 0, timeout: float = None, *, reconnect: bool = None):
31
29
  '''
32
30
  Yields HungerBridge console lines (see MinecraftServer.streamConsole()).
33
31
 
@@ -35,12 +33,11 @@ class AsyncMinecraftServer(AsyncServer):
35
33
  async for line in server.streamConsole(history=20):
36
34
  print(line)
37
35
  '''
38
- lines = await asyncio.to_thread(self.target.streamConsole, history, timeout, reconnect=reconnect,
39
- sanitize=sanitize)
36
+ lines = await asyncio.to_thread(self.target.streamConsole, history, timeout, reconnect=reconnect)
40
37
  async for line in iterateInThread(lines):
41
38
  yield line
42
39
 
43
- async def onConsoleLine(self, callback, history: int = 0, *, reconnect: bool = None, sanitize: bool = True):
40
+ async def onConsoleLine(self, callback, history: int = 0, *, reconnect: bool = None):
44
41
  '''
45
42
  Calls `callback(line)` for every console line; the callback may be a coroutine
46
43
  function, it then runs on this event loop. Returns the stream (`await stream.disconnect()`).
@@ -52,13 +49,10 @@ class AsyncMinecraftServer(AsyncServer):
52
49
  if inspect.isawaitable(result):
53
50
  asyncio.run_coroutine_threadsafe(result, loop)
54
51
 
55
- stream = await asyncio.to_thread(self.target.onConsoleLine, deliver, history, reconnect=reconnect,
56
- sanitize=sanitize)
52
+ stream = await asyncio.to_thread(self.target.onConsoleLine, deliver, history, reconnect=reconnect)
57
53
  return wrap(stream)
58
54
 
59
55
 
60
56
  registerAsyncType(MinecraftServer, AsyncMinecraftServer)
61
- registerAsyncType(VersionManager, AsyncWrapper)
62
- registerAsyncType(VersionChangerAdmin, AsyncWrapper)
63
57
  registerAsyncType(BridgeClient, AsyncWrapper)
64
58
  registerAsyncType(Stream, AsyncWrapper)
@@ -0,0 +1,33 @@
1
+ '''
2
+ Helpers that connect a MinecraftServer to its HungerBridge: client creation and the
3
+ console pickup line.
4
+
5
+ The HungerBridge protocol itself (signing, endpoints, streaming, releases) lives in
6
+ HungerBridgePy (`hungerbridge`); nothing here talks HTTP to the bridge directly.
7
+ '''
8
+ import re
9
+
10
+ from hungerbridge import BridgeClient, Credentials
11
+
12
+ from calagoapi_minecraft.config import settings
13
+
14
+
15
+ # The "Pickup URL" line printed by "hb token create" / "hb token rotate"
16
+ PICKUP_PATTERN = re.compile(r'(/pickup/[0-9A-Za-z-]+\?passkey=[0-9a-fA-F]+)')
17
+ ANSI_PATTERN = re.compile(r'\x1b\[[0-9;?]*[ -/]*[@-~]')
18
+
19
+
20
+ def newClient(url: str, credentials: Credentials, **options) -> BridgeClient:
21
+ '''Creates a HungerBridgePy client with the configured timeout and retries; options win.'''
22
+ config = settings()
23
+ kwargs = {'max_retries': config['bridge_max_retries']}
24
+ if config['bridge_timeout'] is not None:
25
+ kwargs['timeout'] = config['bridge_timeout']
26
+ kwargs.update(options)
27
+ return BridgeClient(url, token_id=credentials.token_id, token_secret=credentials.token_secret, **kwargs)
28
+
29
+
30
+ def findPickup(line: str):
31
+ '''Returns "/pickup/<id>?passkey=<hex>" from a console line, or None.'''
32
+ match = PICKUP_PATTERN.search(ANSI_PATTERN.sub('', line or ''))
33
+ return match.group(1) if match else None
@@ -0,0 +1,72 @@
1
+ '''
2
+ Configuration of calagoapi-minecraft.
3
+
4
+ `enable('minecraft', config={...})` sets process-wide defaults. Without enable(),
5
+ MinecraftServer uses DEFAULT_CONFIG. Per-server values (constructor arguments,
6
+ connectBridge()) always win.
7
+ '''
8
+ from types import MappingProxyType
9
+
10
+ from calagoapi.extensions import ConfigurationError, ExtensionNotEnabledError
11
+ from hungerbridge import Credentials
12
+
13
+
14
+ DEFAULT_CONFIG = {
15
+ 'bridge_url': None, # None: the server's address with bridge_port
16
+ 'bridge_port': 1913,
17
+ 'bridge_token_id': None, # token for every server; per server: connectBridge()
18
+ 'bridge_token_secret': None, # its 64 hex character secret (masked in diagnostics)
19
+ 'bridge_timeout': None, # seconds or (connect, read); None: HungerBridgePy's default (5, 30)
20
+ 'bridge_max_retries': 2, # retries after HTTP 429, inside HungerBridgePy
21
+ 'stream_reconnect': True, # default for streamConsole() and onConsoleLine()
22
+ }
23
+
24
+
25
+ def settings():
26
+ '''
27
+ Returns the effective configuration (read-only): the enabled extension's config,
28
+ or DEFAULT_CONFIG when enable('minecraft') was not called.
29
+
30
+ Example:
31
+ from calagoapi_minecraft import settings
32
+ print(settings()['bridge_port'])
33
+ '''
34
+ from calagoapi_minecraft.extension import MinecraftExtension
35
+
36
+ try:
37
+ return MinecraftExtension.get().config
38
+ except ExtensionNotEnabledError:
39
+ return MappingProxyType(dict(DEFAULT_CONFIG))
40
+
41
+
42
+ def credentials(token_id, token_secret, where: str = 'bridge_token_id/bridge_token_secret'):
43
+ '''
44
+ Returns hungerbridge.Credentials for the pair, or None when both are None.
45
+
46
+ Raises:
47
+ ConfigurationError: only one of them is given, or HungerBridgePy rejects them
48
+ (empty id, secret that is not 64 hex characters). The secret is never echoed.
49
+ '''
50
+ if token_id is None and token_secret is None:
51
+ return None
52
+ if token_id is None or token_secret is None:
53
+ raise ConfigurationError(f'minecraft: {where}: give both the token id and the token secret')
54
+ try:
55
+ return Credentials(token_id=token_id, token_secret=token_secret)
56
+ except ValueError as error:
57
+ raise ConfigurationError(f'minecraft: {where}: {error}') from None
58
+
59
+
60
+ def validate(config: dict) -> dict:
61
+ credentials(config['bridge_token_id'], config['bridge_token_secret'])
62
+ port = config['bridge_port']
63
+ if isinstance(port, bool) or not isinstance(port, int) or not 0 < port < 65536:
64
+ raise ConfigurationError(f'minecraft: bridge_port must be 1-65535, got {port!r}')
65
+ if config['bridge_url'] is not None and not str(config['bridge_url']).startswith(('http://', 'https://')):
66
+ raise ConfigurationError(f'minecraft: bridge_url must start with http:// or https://, got {config["bridge_url"]!r}')
67
+ if not isinstance(config['stream_reconnect'], bool):
68
+ raise ConfigurationError('minecraft: stream_reconnect must be True or False')
69
+ retries = config['bridge_max_retries']
70
+ if isinstance(retries, bool) or not isinstance(retries, int) or retries < 0:
71
+ raise ConfigurationError('minecraft: bridge_max_retries must be 0 or more')
72
+ return config
@@ -3,7 +3,7 @@ from calagoapi.utils.exceptions import CalagoAPIError
3
3
 
4
4
  class MinecraftError(CalagoAPIError):
5
5
  '''
6
- A Minecraft feature could not be used, e.g. the bridge jar for a version does not exist.
6
+ A Minecraft feature could not be used, e.g. no pickup URL appeared on the console.
7
7
 
8
8
  Errors returned by HungerBridge itself are raised unchanged as
9
9
  `hungerbridge.HungerBridgeError` subclasses (HungerBridgeAuthError, ...), and panel
@@ -17,7 +17,7 @@ class BridgeNotConfiguredError(MinecraftError):
17
17
 
18
18
  Fix it with one of:
19
19
 
20
- enable('minecraft', config={'bridge_token': 'id:secret'}) # every server
21
- server.connectBridge(url, 'id:secret') # one server
22
- server.createBridgeToken() # create one through the console
20
+ enable('minecraft', config={'bridge_token_id': 'bot', 'bridge_token_secret': '...'}) # every server
21
+ server.connectBridge(url, token_id='bot', token_secret='...') # one server
22
+ server.createBridgeToken() # create one through the console
23
23
  '''
@@ -3,7 +3,7 @@ The `minecraft` CalagoAPI extension.
3
3
 
4
4
  from calagoapi.extensions import enable
5
5
 
6
- enable('minecraft', config={'bridge_token': 'bot:9f2c...'})
6
+ enable('minecraft', config={'bridge_token_id': 'bot', 'bridge_token_secret': '9f2c...'})
7
7
  server = panel.minecraft.getServer('abc123')
8
8
 
9
9
  enable() adds `panel.minecraft` (MinecraftManager) and sets process-wide defaults for
@@ -18,34 +18,30 @@ from calagoapi_minecraft.manager import MinecraftManager
18
18
 
19
19
  class MinecraftExtension(Extension):
20
20
  '''
21
- Minecraft for CalagoAPI: MinecraftServer, the Version Changer and HungerBridge
22
- (through HungerBridgePy).
21
+ Minecraft for CalagoAPI: MinecraftServer and HungerBridge (through HungerBridgePy).
23
22
 
24
23
  Config (all optional):
25
24
  bridge_url: HungerBridge URL for every server. None uses each server's address
26
25
  with bridge_port.
27
26
  bridge_port: HungerBridge port, default 1913.
28
- bridge_token: "tokenId:secret" for every server (per server: connectBridge()).
27
+ bridge_token_id, bridge_token_secret: Token for every server (per server:
28
+ connectBridge()). Give both or neither; the secret is masked in diagnostics.
29
29
  bridge_timeout: Seconds or (connect, read); None uses HungerBridgePy's (5, 30).
30
30
  bridge_max_retries: Retries after HTTP 429, default 2.
31
31
  stream_reconnect: Default reconnect for streamConsole()/onConsoleLine(), default True.
32
- auto_backup: Back up before server.versions.install(), default False.
33
- backup_name, backup_timeout: That backup's name and how long to wait for it.
34
- release: HungerBridge release used by installBridge(), default 'latest'.
35
- repository, github_api: Where HungerBridge releases are published.
36
32
  '''
37
33
  extension_id = 'minecraft'
38
34
  metadata = ExtensionMetadata(
39
35
  author='iFamished',
40
36
  version=__version__,
41
37
  schema=1,
42
- description='Minecraft servers for CalagoAPI: HungerBridge, Version Changer, server.properties',
38
+ description='Minecraft servers for CalagoAPI: HungerBridge, server.properties, bridge installs from Modrinth',
43
39
  package='calagoapi-minecraft',
44
40
  homepage='https://github.com/HungerNet/CalagoAPI/tree/main/src/extensions/calagoapi-minecraft',
45
41
  )
46
42
  default_mode = 'direct'
47
43
  default_config = DEFAULT_CONFIG
48
- secret_config = ('bridge_token',)
44
+ secret_config = ('bridge_token_secret',)
49
45
  members = [MinecraftManager]
50
46
 
51
47
  def validateConfig(self, config):