calagoapi-minecraft 1.0.dev2__py3-none-any.whl → 2.0.dev1__py3-none-any.whl

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.
@@ -2,50 +2,39 @@ import json
2
2
  import threading
3
3
  import time
4
4
 
5
- from hungerbridge import BridgeClient, HungerBridgeError, ReleaseAsset, Stream, redeem_pickup
6
- from hungerbridge.protocol import MAX_HISTORY
7
- from hungerbridge.releases import find_release, parse_asset_name
5
+ from hungerbridge import BridgeClient, BridgeRelease, Credentials, HungerBridgeError, Stream, findRelease, redeemPickup
8
6
 
9
7
  from calagoapi import Server
10
8
  from calagoapi.console import Console
11
- from calagoapi.utils.convert import formatDuration
12
9
  from calagoapi.utils.exceptions import NotFoundError, WaitTimeoutError
13
10
 
14
11
  from calagoapi_minecraft import bridge as _bridge
15
12
  from calagoapi_minecraft import properties as _properties
16
- from calagoapi_minecraft.config import checkToken, settings
13
+ from calagoapi_minecraft.config import credentials as _credentials, settings
17
14
  from calagoapi_minecraft.exceptions import BridgeNotConfiguredError, MinecraftError
18
- from calagoapi_minecraft.versions import VersionManager
19
15
 
20
16
 
21
17
  # default Minecraft port, used when an address has none
22
18
  DEFAULT_PORT = 25565
23
19
 
24
20
 
25
- def _history(history) -> int:
26
- '''streamConsole(history=...) -> the bridge's ?history=N (None for none)'''
27
- if history is True:
28
- return MAX_HISTORY
29
- return int(history) if history else None
30
-
31
-
32
21
  class MinecraftServer(Server):
33
22
  '''
34
23
  A Minecraft server: everything a Server has, plus Minecraft features.
35
24
 
36
25
  Two channels are used, and every method uses exactly one of them:
37
26
 
38
- - the panel / node daemon (inherited from Server): power (start, stop, ...),
39
- resources (getRAM, getCPU, ...), files, backups, server.properties, the
40
- Version Changer (`server.versions`), sendPanelCommand() and `server.console`;
41
- - HungerBridge, the plugin/mod inside the game, through HungerBridgePy
42
- (`server.bridge`): sendCommand() with output, streamConsole(), players,
43
- TPS/MSPT, world and JVM metrics, writeLog().
27
+ - the panel / node daemon (inherited from Server): power, resources, files, backups,
28
+ server.properties, installBridge(), sendPanelCommand() and `server.console`;
29
+ - HungerBridge, the plugin/mod inside the game, through HungerBridgePy: `server.bridge`
30
+ is a `hungerbridge.BridgeClient` with the whole HungerBridge API (players, TPS, JVM
31
+ metrics, log(), ...). MinecraftServer adds sendCommand() and streamConsole() on top,
32
+ the bridge versions of Server's panel methods.
44
33
 
45
- Bridge methods need a token: `enable('minecraft', config={'bridge_token': ...})`,
46
- `bridge_token=` here, connectBridge(), or createBridgeToken(). Without one they
47
- raise BridgeNotConfiguredError. Errors from the bridge are HungerBridgePy's
48
- `hungerbridge.HungerBridgeError` subclasses.
34
+ Bridge methods need a token: `enable('minecraft', config={'bridge_token_id': ...,
35
+ 'bridge_token_secret': ...})`, the arguments here, connectBridge() or createBridgeToken().
36
+ Without one they raise BridgeNotConfiguredError. Errors from the bridge are
37
+ HungerBridgePy's `hungerbridge.HungerBridgeError` subclasses.
49
38
 
50
39
  Args:
51
40
  panel: The Panel the server lives on.
@@ -55,24 +44,22 @@ class MinecraftServer(Server):
55
44
  address: Address players use ("host" or "host:port"); overrides getAddress().
56
45
  bridge_url: HungerBridge URL, e.g. "http://10.0.0.5:1913". Defaults to the
57
46
  `bridge_url` config, then the server's address with `bridge_port`.
58
- bridge_token: "tokenId:secret" for this server; defaults to the `bridge_token` config.
47
+ bridge_token_id, bridge_token_secret: HungerBridge token for this server; default to
48
+ the config.
59
49
 
60
50
  Example:
61
- enable('minecraft', config={'bridge_token': 'bot:9f2c...'})
62
- server = panel.minecraft.getServer('abc123', bridge_url='http://10.0.0.5:1913')
63
-
64
- print(server.sendCommand('list')) # output of the command
65
- print(f'{server.getPlayerCount()} online, TPS {server.getTPS()}')
66
- print(f'container RAM {server.getRAM()} MiB, JVM heap {server.getMemoryInfo()["used"]} MiB')
51
+ server = panel.minecraft.getServer('abc123', bridge_url='http://10.0.0.5:1913',
52
+ bridge_token_id='bot', bridge_token_secret='9f2c...')
53
+ print(server.sendCommand('list')) # output of the command
54
+ print(server.bridge.getTPS('1m'), server.bridge.getPlayers())
67
55
  '''
68
56
  def __init__(self, panel, server_id: str = None, name: str = None, data: dict = None, *,
69
- address: str = None, bridge_url: str = None, bridge_token: str = None):
57
+ address: str = None, bridge_url: str = None, bridge_token_id: str = None,
58
+ bridge_token_secret: str = None):
70
59
  super().__init__(panel, server_id, name, data)
71
- checkToken(bridge_token, 'bridge_token')
72
60
  self.address = address
73
- self.versions = VersionManager(self)
74
61
  self._bridge_url = bridge_url.rstrip('/') if bridge_url else None
75
- self._bridge_token = bridge_token
62
+ self._credentials = _credentials(bridge_token_id, bridge_token_secret, 'bridge_token_id/bridge_token_secret')
76
63
  self._bridge = None
77
64
  self._bridge_lock = threading.RLock()
78
65
 
@@ -103,57 +90,64 @@ class MinecraftServer(Server):
103
90
  host = address.rsplit(':', 1)[0]
104
91
  return f'http://{host}:{config["bridge_port"]}'
105
92
 
93
+ def _configuredCredentials(self):
94
+ if self._credentials is not None:
95
+ return self._credentials
96
+ config = settings()
97
+ return _credentials(config['bridge_token_id'], config['bridge_token_secret'])
98
+
106
99
  def hasBridge(self) -> bool:
107
100
  '''Returns True if a bridge client or token is configured (no request is made).'''
108
- return self._bridge is not None or bool(self._bridge_token or settings()['bridge_token'])
101
+ return self._bridge is not None or self._configuredCredentials() is not None
109
102
 
110
103
  @property
111
104
  def bridge(self) -> BridgeClient:
112
105
  '''
113
- The HungerBridgePy client of this server (`hungerbridge.BridgeClient`), created
114
- on first use. Everything HungerBridgePy offers is available here.
106
+ The HungerBridgePy client of this server (`hungerbridge.BridgeClient`), created on
107
+ first use. Everything HungerBridge offers is available here.
115
108
 
116
109
  Raises:
117
110
  BridgeNotConfiguredError: No bridge token is configured.
118
111
 
119
112
  Example:
120
- server.bridge.getTokenInfo()
121
- server.bridge.stopServer() # HungerBridge's stop; server.stop() is the panel's
113
+ server.bridge.getTPS('1m')
114
+ server.bridge.log('backup finished', level='BACKUP', logger='Backups')
122
115
  '''
123
116
  with self._bridge_lock:
124
117
  if self._bridge is None:
125
- token = self._bridge_token or settings()['bridge_token']
126
- if not token:
118
+ credentials = self._configuredCredentials()
119
+ if credentials is None:
127
120
  raise BridgeNotConfiguredError(
128
- f'{self.name} has no HungerBridge token. Use enable("minecraft", config={{"bridge_token": '
129
- f'"id:secret"}}), server.connectBridge(url, "id:secret") or server.createBridgeToken().')
130
- self._bridge = _bridge.newClient(self.getBridgeUrl(), token)
121
+ f'{self.name} has no HungerBridge token. Use enable("minecraft", config={{"bridge_token_id": ..., '
122
+ f'"bridge_token_secret": ...}}), server.connectBridge(token_id=..., token_secret=...) '
123
+ f'or server.createBridgeToken().')
124
+ self._bridge = _bridge.newClient(self.getBridgeUrl(), credentials)
131
125
  return self._bridge
132
126
 
133
- def connectBridge(self, url: str = None, token: str = None, **options) -> BridgeClient:
127
+ def connectBridge(self, url: str = None, *, token_id: str = None, token_secret: str = None, **options) -> BridgeClient:
134
128
  '''
135
129
  Sets the bridge URL and/or token for this server and returns the new client.
136
130
 
137
131
  Args:
138
132
  url: HungerBridge URL; keeps the current one when None.
139
- token: "tokenId:secret"; keeps the current one when None.
140
- **options: BridgeClient options, e.g. timeout=(5, 30), static_delay=0.2.
133
+ token_id, token_secret: A new token (both, or neither to keep the current one).
134
+ **options: BridgeClient options, e.g. timeout=(5, 30), min_interval=0.2.
141
135
 
142
136
  Example:
143
- server.connectBridge('http://10.0.0.5:1913', 'bot:9f2c...')
137
+ server.connectBridge('http://10.0.0.5:1913', token_id='bot', token_secret='9f2c...')
144
138
  '''
145
- checkToken(token, 'token')
139
+ new = _credentials(token_id, token_secret, 'token_id/token_secret')
146
140
  with self._bridge_lock:
147
141
  if url:
148
142
  self._bridge_url = url.rstrip('/')
149
- if token:
150
- self._bridge_token = token
143
+ if new is not None:
144
+ self._credentials = new
151
145
  self.closeBridge()
152
146
  if options:
153
- token = self._bridge_token or settings()['bridge_token']
154
- if not token:
155
- raise BridgeNotConfiguredError(f'{self.name} has no HungerBridge token; pass token=')
156
- self._bridge = _bridge.newClient(self.getBridgeUrl(), token, **options)
147
+ credentials = self._configuredCredentials()
148
+ if credentials is None:
149
+ raise BridgeNotConfiguredError(f'{self.name} has no HungerBridge token; pass token_id and token_secret')
150
+ self._bridge = _bridge.newClient(self.getBridgeUrl(), credentials, **options)
157
151
  return self.bridge
158
152
 
159
153
  def setBridge(self, client: BridgeClient) -> 'MinecraftServer':
@@ -169,7 +163,7 @@ class MinecraftServer(Server):
169
163
  with self._bridge_lock:
170
164
  client, self._bridge = self._bridge, None
171
165
  if client is not None:
172
- _bridge.closeClient(client)
166
+ client.close()
173
167
 
174
168
  def isBridgeReachable(self) -> bool:
175
169
  '''Returns True if HungerBridge answers an authenticated ping.'''
@@ -204,17 +198,18 @@ class MinecraftServer(Server):
204
198
  `hb token create` (resolved against getBridgeUrl()).
205
199
  '''
206
200
  url = pickup_url if pickup_url.startswith(('http://', 'https://')) else f'{self.getBridgeUrl()}{pickup_url}'
207
- token_id, secret = redeem_pickup(url)
208
- return self.connectBridge(token=f'{token_id}:{secret}')
201
+ token = redeemPickup(url)
202
+ return self.connectBridge(token_id=token.token_id, token_secret=token.token_secret)
209
203
 
210
204
  def createBridgeToken(self, token_id: str = 'calagoapi', policy: str = 'admin', expiry: int = None,
211
- timeout: float = 30, url: str = None) -> str:
205
+ timeout: float = 30, url: str = None) -> Credentials:
212
206
  '''
213
207
  Creates a HungerBridge token through the server console and connects the bridge with it.
214
208
 
215
209
  Runs `hb token create <token_id> <policy> [expiry]` over the daemon console (the
216
210
  command is console-only), reads the pickup URL it prints, redeems it, and returns
217
- the token so you can store it (e.g. as the `bridge_token` config).
211
+ the token so you can store it (e.g. as the `bridge_token_id`/`bridge_token_secret`
212
+ config).
218
213
 
219
214
  Args:
220
215
  token_id: Id of the new token.
@@ -224,14 +219,14 @@ class MinecraftServer(Server):
224
219
  url: Bridge URL to use for this server (see getBridgeUrl()).
225
220
 
226
221
  Returns:
227
- The token, "tokenId:secret".
222
+ hungerbridge.Credentials (token_id, token_secret).
228
223
 
229
224
  Raises:
230
225
  MinecraftError: No pickup URL appeared (bridge not installed, unknown policy, ...).
231
226
 
232
227
  Example:
233
228
  token = server.createBridgeToken(url='http://10.0.0.5:1913')
234
- save_somewhere(token)
229
+ save_somewhere(token.token_id, token.token_secret)
235
230
  '''
236
231
  if url:
237
232
  self._bridge_url = url.rstrip('/')
@@ -251,51 +246,28 @@ class MinecraftServer(Server):
251
246
  f'No HungerBridge pickup URL appeared on the console of {self.name} within {timeout}s after '
252
247
  f'"{command}". Is HungerBridge installed and does policy {policy!r} exist?')
253
248
  pickup = _bridge.findPickup(line)
254
- client = self.redeemBridgePickup(pickup)
255
- return f'{client.credentials.token_id}:{client.credentials.secret}'
256
-
257
- def getBridgeInfo(self) -> dict:
258
- '''Returns platform, minecraft_version, bridge_version, port and protocol_version.'''
259
- return self.bridge.getServerMeta()
260
-
261
- def getBridgeTokenInfo(self) -> dict:
262
- '''Returns the token's token_id, policy_id, permissions and expiry.'''
263
- return self.bridge.getTokenInfo()
264
-
265
- def getPlatform(self) -> str:
266
- '''Returns 'paper', 'folia' or 'fabric' (as reported by HungerBridge).'''
267
- return self.bridge.getPlatform()
268
-
269
- def getMinecraftVersion(self) -> str:
270
- '''Returns the running Minecraft version, e.g. '1.21.11' (as reported by HungerBridge).'''
271
- return self.bridge.getMinecraftVersion()
249
+ return self.redeemBridgePickup(pickup).credentials
272
250
 
273
251
 
274
252
  # commands and console (HungerBridge)
275
- def sendCommand(self, command: str, *, silent: bool = False, showConsole: bool = False):
253
+ def sendCommand(self, command: str, *, show_console: bool = False) -> str:
276
254
  '''
277
- Runs a console command through HungerBridge and returns its output.
255
+ Runs a console command through HungerBridge and returns its output
256
+ (HungerBridgePy runCommand()).
278
257
 
279
- The command runs as the console on the server thread (Folia: the global region);
280
- HungerBridge waits up to 5 seconds for it. Uses HungerBridgePy's runCommand().
281
-
282
- Args:
283
- command: The command, without a leading slash.
284
- silent: Do not capture output (returns None).
285
- showConsole: Also print the command and its output to the server console.
286
-
287
- Returns:
288
- The captured output lines joined with newlines, or None when silent.
258
+ The command runs with console permissions on the server thread (Folia: the global
259
+ region). Its output is captured directly and is not printed to the server console
260
+ unless show_console is True.
289
261
 
290
262
  Example:
291
263
  print(server.sendCommand('list'))
292
- server.sendCommand('save-all', silent=True)
264
+ server.sendCommand('save-all', show_console=True)
293
265
  '''
294
- return self.bridge.runCommand(command, showConsole=showConsole, silent=silent)
266
+ return self.bridge.runCommand(command, show_console=show_console)
295
267
 
296
- def sendCommands(self, commands: list, *, silent: bool = False, showConsole: bool = False) -> list:
268
+ def sendCommands(self, commands: list, *, show_console: bool = False) -> list:
297
269
  '''Runs several commands in order. Returns their outputs.'''
298
- return [self.sendCommand(command, silent=silent, showConsole=showConsole) for command in commands]
270
+ return [self.sendCommand(command, show_console=show_console) for command in commands]
299
271
 
300
272
  def sendPanelCommand(self, command: str) -> None:
301
273
  '''
@@ -306,19 +278,19 @@ class MinecraftServer(Server):
306
278
  '''
307
279
  return Server.sendCommand(self, command)
308
280
 
309
- def streamConsole(self, history: int = 0, timeout: float = None, *, reconnect: bool = None, sanitize: bool = True):
281
+ def streamConsole(self, history: int = 0, timeout: float = None, *, reconnect: bool = None):
310
282
  '''
311
- Yields console log lines live, from HungerBridge's log stream (HungerBridgePy streamLogs()).
283
+ Yields console lines live from HungerBridge's log stream, e.g.
284
+ "[12:00:05] [Server thread/INFO]: Steve joined the game".
285
+
286
+ Lines are plain text in HungerBridge's format on every loader. For the structured
287
+ events (level, thread, logger, message) use server.bridge.streamLogs().
312
288
 
313
289
  Args:
314
- history: Replay this many recent lines first (at most 200; True means 200).
290
+ history: Replay this many recent lines first (True: everything the bridge keeps).
315
291
  timeout: Stop when nothing is logged for this many seconds. None streams forever.
316
- reconnect: Reconnect (and replay only missed lines) when the stream drops.
292
+ reconnect: Reconnect (replaying exactly what was missed) when the stream drops.
317
293
  None uses the `stream_reconnect` config (default True).
318
- sanitize: Strip colours and unescape line breaks.
319
-
320
- Lines look like "[12:00:05 INFO]: Steve joined the game". Permanent errors (bad
321
- token, missing permission) are raised as HungerBridgeError subclasses.
322
294
 
323
295
  Example:
324
296
  for line in server.streamConsole(history=20):
@@ -327,11 +299,12 @@ class MinecraftServer(Server):
327
299
  '''
328
300
  if reconnect is None:
329
301
  reconnect = settings()['stream_reconnect']
330
- return self.bridge.streamLogs(_history(history), timeout=timeout, reconnect=reconnect, sanitize=sanitize)
302
+ events = self.bridge.streamLogs(history or None, timeout=timeout, reconnect=reconnect)
303
+ return (event.line for event in events)
331
304
 
332
- def onConsoleLine(self, callback, history: int = 0, *, reconnect: bool = None, sanitize: bool = True) -> Stream:
305
+ def onConsoleLine(self, callback, history: int = 0, *, reconnect: bool = None) -> Stream:
333
306
  '''
334
- Calls `callback(line)` for every console log line, in a background thread.
307
+ Calls `callback(line)` for every console line, in a background thread.
335
308
 
336
309
  Returns the HungerBridgePy Stream; call `.disconnect()` on it to stop.
337
310
 
@@ -342,43 +315,17 @@ class MinecraftServer(Server):
342
315
  '''
343
316
  if reconnect is None:
344
317
  reconnect = settings()['stream_reconnect']
318
+ stream = self.bridge.openStream(on_event=lambda event: callback(event.line),
319
+ on_history=lambda events: [callback(event.line) for event in events])
320
+ return stream.connect(history or None, reconnect=reconnect)
345
321
 
346
- def deliver(line):
347
- callback(Stream.sanitize(line) if sanitize else line)
348
-
349
- def deliverHistory(lines):
350
- for line in lines:
351
- deliver(line)
352
-
353
- stream = self.bridge.openStream(history_handler=deliverHistory, new_log_handler=deliver)
354
- stream.connect(history=_history(history), reconnect=reconnect)
355
- return stream
356
322
 
357
- def writeLog(self, message: str, level: str = 'info', thread: str = None) -> dict:
358
- '''
359
- Writes a line to the server log (any level name, e.g. 'INFO', 'WARN' or a custom 'BOT').
360
-
361
- Example:
362
- server.writeLog('backup finished', level='BOT', thread='calagoapi')
363
- '''
364
- return self.bridge.log(message, level=level, thread=thread)
365
-
366
-
367
- # chat and players (commands through HungerBridge)
368
- def say(self, message: str):
323
+ # chat and moderation (commands through HungerBridge)
324
+ def say(self, message: str) -> str:
369
325
  '''Broadcasts a chat message as the server.'''
370
326
  return self.sendCommand(f'say {message}')
371
327
 
372
- def broadcast(self, message: str, prefix: str = None):
373
- '''
374
- Shows a message to every player with tellraw (HungerBridgePy broadcast()).
375
-
376
- Example:
377
- server.broadcast('Event starts now', prefix='[Event] ')
378
- '''
379
- return self.bridge.broadcast(message, prefix)
380
-
381
- def tellraw(self, target: str, component):
328
+ def tellraw(self, target: str, component) -> str:
382
329
  '''
383
330
  Sends a JSON text component.
384
331
 
@@ -389,195 +336,80 @@ class MinecraftServer(Server):
389
336
  component = json.dumps(component, ensure_ascii=False)
390
337
  return self.sendCommand(f'tellraw {target} {component}')
391
338
 
392
- def kick(self, player: str, reason: str = None):
339
+ def kick(self, player: str, reason: str = None) -> str:
393
340
  '''Kicks a player.'''
394
341
  return self.sendCommand(f'kick {player} {reason}' if reason else f'kick {player}')
395
342
 
396
- def ban(self, player: str, reason: str = None):
343
+ def ban(self, player: str, reason: str = None) -> str:
397
344
  '''Bans a player.'''
398
345
  return self.sendCommand(f'ban {player} {reason}' if reason else f'ban {player}')
399
346
 
400
- def pardon(self, player: str):
347
+ def pardon(self, player: str) -> str:
401
348
  '''Unbans a player.'''
402
349
  return self.sendCommand(f'pardon {player}')
403
350
 
404
- def op(self, player: str):
351
+ def op(self, player: str) -> str:
405
352
  '''Gives a player operator status.'''
406
353
  return self.sendCommand(f'op {player}')
407
354
 
408
- def deop(self, player: str):
355
+ def deop(self, player: str) -> str:
409
356
  '''Removes operator status from a player.'''
410
357
  return self.sendCommand(f'deop {player}')
411
358
 
412
- def whitelistAdd(self, player: str):
359
+ def whitelistAdd(self, player: str) -> str:
413
360
  '''Adds a player to the whitelist.'''
414
361
  return self.sendCommand(f'whitelist add {player}')
415
362
 
416
- def whitelistRemove(self, player: str):
363
+ def whitelistRemove(self, player: str) -> str:
417
364
  '''Removes a player from the whitelist.'''
418
365
  return self.sendCommand(f'whitelist remove {player}')
419
366
 
420
- def saveAll(self):
367
+ def saveAll(self) -> str:
421
368
  '''Saves every world.'''
422
369
  return self.sendCommand('save-all')
423
370
 
424
- def getPlayers(self) -> list:
425
- '''Returns the names of the online players (capped by HungerBridge's players.max-list).'''
426
- return self.bridge.getPlayers('list') or []
427
-
428
- def getPlayerCount(self) -> int:
429
- '''Returns how many players are online.'''
430
- return self.bridge.getPlayers('count')
431
-
432
- def getMaxPlayers(self) -> int:
433
- '''Returns the number of player slots.'''
434
- return self.bridge.getMaxPlayers()
435
-
436
-
437
- # game performance and world (HungerBridge)
438
- def getTPS(self, mode: str = 'current') -> float:
439
- '''
440
- Returns ticks per second: mode 'current', '1m', '5m' or '15m' (-1 if unavailable).
441
-
442
- Example:
443
- if server.getTPS('1m') < 18:
444
- print('lagging')
445
- '''
446
- return self.bridge.getTPS(mode)
447
-
448
- def getMSPT(self) -> float:
449
- '''Returns milliseconds per tick.'''
450
- return self.bridge.getMSPT()
451
-
452
- def getPerformance(self) -> dict:
453
- '''
454
- Returns one snapshot for dashboards (three bridge calls):
455
- {'tps': {'current', '1m', '5m', '15m'}, 'mspt', 'players', 'max_players'}.
456
- '''
457
- players = self.bridge.getPlayerStats()
458
- return {
459
- 'tps': self.bridge.getTPSStats(),
460
- 'mspt': self.bridge.getMSPT(),
461
- 'players': players['count'],
462
- 'max_players': players['max'],
463
- }
464
-
465
- def getWorldTime(self) -> int:
466
- '''Returns the overworld time of day in ticks (0-23999).'''
467
- return self.bridge.getWorldTime()
468
-
469
- def getWorldTimeInfo(self) -> dict:
470
- '''Returns time (tick of day), full_time, day and server_time.'''
471
- return self.bridge.getWorldTimeInfo()
472
-
473
- def getWeather(self) -> str:
474
- '''Returns 'clear', 'rain' or 'thunder'.'''
475
- return self.bridge.getWorldWeather()
476
-
477
- def getLoadedChunks(self) -> dict:
478
- '''Returns loaded chunks: total, world, world_nether, world_the_end.'''
479
- return self.bridge.getLoadedChunks()
480
-
481
- def getLoadedEntities(self) -> dict:
482
- '''Returns loaded entities: total, world, world_nether, world_the_end.'''
483
- return self.bridge.getLoadedEntities()
484
-
485
-
486
- # JVM information (HungerBridge) - additional to getRAM()/getCPU()/getUptime() (panel)
487
- def getMemoryInfo(self, unit: str = 'mib') -> dict:
488
- '''
489
- Returns JVM memory: heap_*, nonheap_*, jvm_*, process_* and the summary keys used,
490
- total (committed heap), free and max, in `unit` ('b', 'kib', 'mib', 'gib', 'mb', ...).
491
-
492
- getRAM() stays the container's memory as the panel reports it.
493
- '''
494
- return self.bridge.getMemoryStats(unit)
495
-
496
- def getProcessInfo(self, unit: str = 'mib') -> dict:
497
- '''Returns the server process: process_used, process_virtual (in `unit`) and uptime_ms.'''
498
- info = self.bridge.getProcessMemory(unit)
499
- info['uptime_ms'] = self.bridge.getUptime()
500
- return info
501
371
 
502
- def getProcessorInfo(self) -> dict:
372
+ # installing HungerBridge (Modrinth through HungerBridgePy + panel files)
373
+ def installBridge(self, minecraft_version: str, loader: str, *, version: str = None,
374
+ replace: bool = True) -> BridgeRelease:
503
375
  '''
504
- Returns load (the JVM process's CPU load, 0-1) and processors (available cores).
376
+ Downloads the HungerBridge jar for a Minecraft version and loader from Modrinth into
377
+ /plugins (paper, purpur, folia) or /mods (fabric). Restart the server afterwards.
505
378
 
506
- getCPU() stays the container's CPU usage as the panel reports it.
507
- '''
508
- return self.bridge.getCPUStats()
509
-
510
- def getThreadInfo(self) -> dict:
511
- '''Returns JVM thread counts: current, peak, daemon.'''
512
- return self.bridge.getThreadStats()
513
-
514
- def getGarbageCollectorInfo(self) -> dict:
515
- '''Returns gc_type, gc_count, gc_time_ms, last_gc_pause_ms and avg_gc_pause_ms.'''
516
- return self.bridge.getGCStats()
517
-
518
- def getNetworkInfo(self) -> dict:
519
- '''Returns bytes_in_per_sec, bytes_out_per_sec, total_bytes_in and total_bytes_out (host, Linux only).'''
520
- return self.bridge.getNetworkStats()
521
-
522
- def getJVMUptime(self, formatted: bool = False):
523
- '''Returns how long the JVM runs, in milliseconds, or like "3h 12m" with formatted=True.'''
524
- uptime = self.bridge.getUptime()
525
- return formatDuration(uptime) if formatted and uptime is not None else uptime
526
-
527
-
528
- # installing HungerBridge (panel files + HungerBridgePy release lookup)
529
- def findBridgeRelease(self, minecraft_version: str, loader: str, release: str = None) -> ReleaseAsset:
530
- '''
531
- Finds the HungerBridge jar for a Minecraft version and loader (HungerBridgePy find_release()).
379
+ Nothing is detected: pass what the server runs. The release is chosen from Modrinth's
380
+ version metadata (loaders, game versions) by HungerBridgePy's findRelease().
532
381
 
533
382
  Args:
534
- minecraft_version: e.g. '1.21.11', or 'latest'.
535
- loader: 'paper' or 'fabric' (server types such as 'PURPUR' work too).
536
- release: Release tag; None uses the `release` config ('latest').
537
- '''
538
- config = settings()
539
- return find_release(minecraft_version, loader, release or config['release'],
540
- repository=config['repository'], api_url=config['github_api'])
541
-
542
- def installBridge(self, minecraft_version: str = None, loader: str = None, release: str = None,
543
- replace: bool = True) -> ReleaseAsset:
544
- '''
545
- Downloads the matching HungerBridge jar into /plugins (Paper, Purpur, Folia) or
546
- /mods (Fabric). Restart the server afterwards.
547
-
548
- The loader and Minecraft version are detected unless given: from the Version
549
- Changer, a running bridge, or the egg name and startup variables.
550
-
551
- Args:
552
- minecraft_version: e.g. '1.21.11', or 'latest'.
553
- loader: 'paper' or 'fabric'.
554
- release: HungerBridge release tag; None uses the `release` config.
555
- replace: Delete other HungerBridge jars in that directory first.
383
+ minecraft_version: e.g. '1.21.11' or '26.3'.
384
+ loader: 'paper', 'purpur', 'folia' or 'fabric'.
385
+ version: A HungerBridge version number to pin (e.g. '5-alpha.1'); None: the newest
386
+ compatible release.
387
+ replace: Delete other HungerBridge*.jar files in that directory first.
556
388
 
557
389
  Returns:
558
- The installed hungerbridge.ReleaseAsset (name, url, loader, minecraft_version, release).
390
+ The installed hungerbridge.BridgeRelease (version_number, filename, url, sha512, ...).
391
+
392
+ Raises:
393
+ ValueError: A missing argument, or a loader/version HungerBridge is not published for.
394
+ hungerbridge.HungerBridgeNotFound: No compatible release exists.
559
395
 
560
396
  Example:
561
- server.installBridge()
397
+ server.installBridge(minecraft_version='1.21.11', loader='paper')
562
398
  server.restart()
563
399
  server.waitForBridge()
564
400
  '''
565
- loader, minecraft_version = _bridge.detectPlatform(self, loader, minecraft_version)
566
- if loader is None or minecraft_version is None:
567
- raise MinecraftError(
568
- f'Cannot tell which HungerBridge jar {self.name} needs (loader={loader!r}, '
569
- f'minecraft_version={minecraft_version!r}). Pass them, e.g. installBridge("1.21.11", "paper").')
570
- asset = self.findBridgeRelease(minecraft_version, loader, release)
401
+ release = findRelease(minecraft_version=minecraft_version, loader=loader, version=version)
571
402
  if replace:
572
403
  try:
573
- old = [f.getName() for f in self.files.listFiles(asset.directory)
574
- if f.getName() != asset.name and parse_asset_name(f.getName())]
404
+ old = [f.getName() for f in self.files.listFiles(release.directory)
405
+ if f.getName() != release.filename and f.getName().lower().startswith('hungerbridge')
406
+ and f.getName().lower().endswith('.jar')]
575
407
  except NotFoundError:
576
408
  old = []
577
409
  if old:
578
- self.files.deleteFiles(asset.directory, old)
579
- self.files.pullFile(asset.url, asset.directory, name=asset.name)
580
- return asset
410
+ self.files.deleteFiles(release.directory, old)
411
+ self.files.pullFile(release.url, release.directory, name=release.filename)
412
+ return release
581
413
 
582
414
 
583
415
  # server.properties and EULA (panel files)