calagoapi 1.0.dev1__py3-none-any.whl

calagoapi/servers/manager.py

@@ -0,0 +1,167 @@
+from calagoapi.servers.generic import GenericServer
+from calagoapi.servers.minecraft import MinecraftServer
+from calagoapi.utils.model import Model, idOf
+
+
+class ServerGroup(Model):
+    '''
+    A personal folder of servers in the panel sidebar.
+
+    Example:
+        group = panel.servers.createGroup('Minigames', [lobby, bedwars])
+        group.addServer(skywars)
+    '''
+    def _api(self):
+        return self.panel.api.servers
+
+    def getName(self) -> str:
+        '''Returns the group name.'''
+        return self.data.get('name')
+
+    def getOrder(self) -> int:
+        '''Returns the group's position in the sidebar.'''
+        return self.data.get('order')
+
+    def getServerIds(self) -> list:
+        '''Returns the UUIDs of the servers in the group, in display order.'''
+        return self.data.get('server_order', [])
+
+    def getServers(self, search: str = None, page: int = None, per_page: int = None):
+        '''Returns the servers in the group as GenericServer objects.'''
+        return self._api().groupServers(self.getUUID(), search, page, per_page).map(
+            lambda data: GenericServer(self.panel, data=data)
+        )
+
+    def rename(self, name: str) -> 'ServerGroup':
+        '''Renames the group.'''
+        self._api().updateGroup(self.getUUID(), name)
+        return self._update({'name': name})
+
+    def setServers(self, servers: list) -> 'ServerGroup':
+        '''Replaces the servers in the group (objects or ids), in display order.'''
+        server_order = [idOf(s) for s in servers]
+        self._api().updateGroup(self.getUUID(), self.getName(), server_order)
+        return self._update({'server_order': server_order})
+
+    def addServer(self, server) -> 'ServerGroup':
+        '''Adds a server to the group.'''
+        return self.setServers(self.getServerIds() + [idOf(server)])
+
+    def removeServer(self, server) -> 'ServerGroup':
+        '''Removes a server from the group.'''
+        return self.setServers([s for s in self.getServerIds() if s != idOf(server)])
+
+    def delete(self) -> None:
+        '''Deletes the group (the servers are not affected).'''
+        return self._api().deleteGroup(self.getUUID())
+
+
+class ServerManager:
+    '''
+    Access to the servers the API key can see, available as `panel.servers`.
+
+    Example:
+        server = panel.servers.getServer('abc123')
+        for server in panel.servers.getServers():
+            print(server.getName(), server.getStatus())
+    '''
+    def __init__(self, panel):
+        self.panel = panel
+        self.api = panel.api.servers
+
+    def getServer(self, server_id: str, name: str = None) -> GenericServer:
+        '''
+        Returns a server.
+
+        Args:
+            server_id: Server UUID or short id.
+            name: Optional display name used in logs and repr().
+
+        Example:
+            server = panel.servers.getServer('abc123')
+        '''
+        server = GenericServer(self.panel, server_id, name)
+        server.refreshDetails()
+        if name is None:
+            server.name = server.getName()
+        return server
+
+    def getMinecraftServer(self, server_id: str, name: str = None, server_domain: str = None, server_port: int = None) -> MinecraftServer:
+        '''
+        Returns a server with the Minecraft helpers of MinecraftServer.
+
+        Example:
+            server = panel.servers.getMinecraftServer('abc123')
+            server.say('Hello')
+        '''
+        server = MinecraftServer(self.panel, server_id, name, server_domain, server_port)
+        server.refreshDetails()
+        if name is None:
+            server.name = server.getName()
+        return server
+
+    def getServers(self, search: str = None, page: int = None, per_page: int = None, all_servers: bool = False):
+        '''
+        Lists servers.
+
+        Args:
+            search: Filter by name.
+            page: Only fetch this page. By default every server is returned.
+            per_page: Page size.
+            all_servers: Admins only, include servers the user does not own or have access to.
+
+        Returns:
+            A Page (list) of GenericServer objects.
+        '''
+        return self.api.list(search, all_servers or None, page, per_page).map(
+            lambda data: GenericServer(self.panel, data=data)
+        )
+
+    def listServers(self, search: str = None):
+        '''Alias of getServers().'''
+        return self.getServers(search)
+
+    def getServerByName(self, name: str) -> GenericServer:
+        '''Returns the first server whose name matches exactly, or None.'''
+        for server in self.getServers(search=name):
+            if server.getName() == name:
+                return server
+        return None
+
+    def getEggs(self, search: str = None, page: int = None, per_page: int = None):
+        '''Returns the eggs (server types) used by the user's servers.'''
+        return self.api.eggs(search, page, per_page)
+
+    def getCommandSnippets(self, egg) -> list:
+        '''Returns the user's command snippets that apply to an egg.'''
+        return self.api.eggCommandSnippets(egg.get('uuid') if isinstance(egg, dict) else idOf(egg))
+
+    # groups
+    def getGroups(self) -> list:
+        '''Returns the user's server groups.'''
+        return [ServerGroup(self.panel, data) for data in self.api.groups()]
+
+    def getGroup(self, group_id_or_name: str) -> ServerGroup:
+        '''Returns a server group by UUID or name, or None.'''
+        for group in self.getGroups():
+            if group_id_or_name in (group.getUUID(), group.getName()):
+                return group
+        return None
+
+    def createGroup(self, name: str, servers: list = None) -> ServerGroup:
+        '''
+        Creates a server group.
+
+        Args:
+            name: Group name.
+            servers: Servers (objects or ids) to put in it.
+        '''
+        return ServerGroup(self.panel, self.api.createGroup(name, [idOf(s) for s in servers or []]))
+
+    def deleteGroup(self, group) -> None:
+        '''Deletes a server group.'''
+        return self.api.deleteGroup(idOf(group))
+
+    def orderGroups(self, groups: list) -> None:
+        '''Sets the order of the server groups.'''
+        return self.api.orderGroups([idOf(g) for g in groups])

calagoapi/servers/minecraft.py

@@ -0,0 +1,207 @@
+import json
+
+from calagoapi.servers.generic import GenericServer
+from calagoapi.utils.model import idOf
+from calagoapi.utils.exceptions import NotFoundError
+
+
+class MinecraftServer(GenericServer):
+    '''
+    A Minecraft server.
+
+    Adds Minecraft helpers on top of GenericServer: console shortcuts,
+    server.properties editing, EULA handling and the Calagopus Minecraft
+    Version Changer (install any Paper, Purpur, Fabric, Forge, ... build).
+
+    Args:
+        panel: The Panel the server lives on.
+        server_id: Server UUID (or short id).
+        name: Optional display name.
+        server_domain: Optional address players use, overrides getAddress().
+        server_port: Optional port players use.
+        data: Optional server data, if already fetched.
+
+    Example:
+        server = panel.servers.getMinecraftServer('abc123')
+        server.say('Restarting in 5 minutes!')
+        server.setProperty('max-players', 50)
+
+        build = server.getBuilds('PAPER', '1.21.1')[0]
+        server.installVersion(build)
+    '''
+    def __init__(self, panel, server_id: str = None, name: str = None, server_domain: str = None,
+                 server_port: int = None, data: dict = None):
+        super().__init__(panel, server_id, name, data)
+
+        # Minecraft-specific fields
+        self.server_domain = server_domain
+        self.server_port = server_port
+
+    def getAddress(self) -> str:
+        '''Returns server_domain:server_port if set, otherwise the primary allocation address.'''
+        if self.server_domain:
+            return f'{self.server_domain}:{self.server_port or 25565}'
+        return super().getAddress()
+
+
+    # console helpers
+    def say(self, message: str) -> None:
+        '''Broadcasts a chat message as the server.'''
+        return self.sendCommand(f'say {message}')
+
+    def broadcast(self, message: str) -> None:
+        '''Alias of say().'''
+        return self.say(message)
+
+    def tellraw(self, target: str, component) -> None:
+        '''
+        Sends a JSON text component.
+
+        Example:
+            server.tellraw('@a', {'text': 'Hello', 'color': 'gold'})
+        '''
+        if not isinstance(component, str):
+            component = json.dumps(component)
+        return self.sendCommand(f'tellraw {target} {component}')
+
+    def kick(self, player: str, reason: str = None) -> None:
+        '''Kicks a player.'''
+        return self.sendCommand(f'kick {player} {reason}' if reason else f'kick {player}')
+
+    def ban(self, player: str, reason: str = None) -> None:
+        '''Bans a player.'''
+        return self.sendCommand(f'ban {player} {reason}' if reason else f'ban {player}')
+
+    def pardon(self, player: str) -> None:
+        '''Unbans a player.'''
+        return self.sendCommand(f'pardon {player}')
+
+    def op(self, player: str) -> None:
+        '''Gives a player operator status.'''
+        return self.sendCommand(f'op {player}')
+
+    def deop(self, player: str) -> None:
+        '''Removes operator status from a player.'''
+        return self.sendCommand(f'deop {player}')
+
+    def whitelistAdd(self, player: str) -> None:
+        '''Adds a player to the whitelist.'''
+        return self.sendCommand(f'whitelist add {player}')
+
+    def whitelistRemove(self, player: str) -> None:
+        '''Removes a player from the whitelist.'''
+        return self.sendCommand(f'whitelist remove {player}')
+
+    def saveAll(self) -> None:
+        '''Saves every world.'''
+        return self.sendCommand('save-all')
+
+
+    # server.properties
+    def getProperties(self) -> dict:
+        '''
+        Reads server.properties.
+
+        Returns:
+            dict of property name -> string value.
+
+        Example:
+            server.getProperties()['max-players']
+        '''
+        properties = {}
+        for line in self.files.readFile('/server.properties').splitlines():
+            line = line.strip()
+            if not line or line.startswith('#') or '=' not in line:
+                continue
+            key, value = line.split('=', 1)
+            properties[key.strip()] = value.strip()
+        return properties
+
+    def getProperty(self, key: str, default=None) -> str:
+        '''Returns one server.properties value.'''
+        return self.getProperties().get(key, default)
+
+    def setProperty(self, key: str, value) -> None:
+        '''Changes one server.properties value. Takes effect after a restart.'''
+        return self.setProperties({key: value})
+
+    def setProperties(self, values: dict) -> None:
+        '''
+        Changes several server.properties values, keeping comments and order.
+
+        Example:
+            server.setProperties({'motd': 'Welcome!', 'max-players': 100})
+        '''
+        values = {k: _propertyValue(v) for k, v in values.items()}
+        lines = []
+        for line in self.files.readFile('/server.properties').splitlines():
+            key = line.split('=', 1)[0].strip()
+            if '=' in line and not line.lstrip().startswith('#') and key in values:
+                line = f'{key}={values.pop(key)}'
+            lines.append(line)
+        lines.extend(f'{k}={v}' for k, v in values.items())
+        return self.files.writeFile('/server.properties', '\n'.join(lines) + '\n')
+
+    def getMOTD(self) -> str:
+        '''Returns the message of the day from server.properties.'''
+        return self.getProperty('motd')
+
+    def setMOTD(self, motd: str) -> None:
+        '''Sets the message of the day.'''
+        return self.setProperty('motd', motd)
+
+    def acceptEula(self) -> None:
+        '''Writes eula=true to eula.txt.'''
+        return self.files.writeFile('/eula.txt', 'eula=true\n')
+
+    def isEulaAccepted(self) -> bool:
+        '''Returns True if eula.txt contains eula=true.'''
+        try:
+            return 'eula=true' in self.files.readFile('/eula.txt').replace(' ', '').lower()
+        except NotFoundError:
+            return False
+
+
+    # version changer
+    def getInstalledVersion(self) -> dict:
+        '''Returns the installed build (type, version, build), or None if unknown.'''
+        return self.panel.api.versions.installed(self.server_id)
+
+    def getVersionTypes(self) -> dict:
+        '''Returns the available server types (PAPER, PURPUR, FABRIC, VANILLA, ...).'''
+        return self.panel.api.versions.types(self.server_id)
+
+    def getVersions(self, type: str, search: str = None, page: int = None, per_page: int = None):
+        '''
+        Returns the Minecraft versions available for a server type.
+
+        Example:
+            server.getVersions('PAPER', page=1, per_page=10)
+        '''
+        return self.panel.api.versions.versions(self.server_id, type, search, page, per_page)
+
+    def getBuilds(self, type: str, version: str, search: str = None, page: int = None, per_page: int = None):
+        '''Returns the builds of a version, newest first.'''
+        return self.panel.api.versions.builds(self.server_id, type, version, search, page, per_page)
+
+    def installVersion(self, build, truncate_directory: bool = False, accept_eula: bool = True) -> None:
+        '''
+        Installs a server build.
+
+        Args:
+            build: Build dict from getBuilds() or build UUID.
+            truncate_directory: Delete every file first.
+            accept_eula: Accept the Minecraft EULA.
+
+        Example:
+            latest = server.getBuilds('PAPER', '1.21.1', page=1, per_page=1)[0]
+            server.installVersion(latest)
+        '''
+        build_id = build.get('uuid') if isinstance(build, dict) else idOf(build)
+        return self.panel.api.versions.install(self.server_id, build_id, truncate_directory, accept_eula)
+
+
+def _propertyValue(value):
+    if isinstance(value, bool):
+        return 'true' if value else 'false'
+    return str(value)

calagoapi/tunnels/__init__.py

@@ -0,0 +1,5 @@
+from .tunnel import TunnelManager
+
+__all__ = [
+    'TunnelManager',
+]

calagoapi/tunnels/tunnel.py

@@ -0,0 +1,112 @@
+from calagoapi.utils.model import idOf
+
+
+class TunnelManager:
+    '''
+    The server's network tunnel, available as `server.tunnel`.
+
+    A tunnel exposes server ports through the node's tunnel without opening
+    them publicly, and lets servers reach each other privately.
+
+    Example:
+        if server.tunnel.isSupported() and not server.tunnel.exists():
+            server.tunnel.createTunnel('survival')
+        server.tunnel.setPorts([25565])
+        server.tunnel.connect(proxy_server)
+        print(server.tunnel.getAddress())
+    '''
+    def __init__(self, server):
+        self.server = server
+        self.api = server.panel.api.network
+
+    @property
+    def server_id(self):
+        return self.server.server_id
+
+    def getInfo(self) -> dict:
+        '''
+        Returns the full tunnel state.
+
+        Returns:
+            dict with supported, tunnel, ports, allocation_ports, outgoing and incoming.
+        '''
+        return self.api.tunnel(self.server_id)
+
+    def getTunnel(self) -> dict:
+        '''Returns the tunnel (name, alias, address), or None if none exists.'''
+        return self.getInfo().get('tunnel')
+
+    def isSupported(self) -> bool:
+        '''Returns True if the server's node supports tunnels.'''
+        return bool(self.getInfo().get('supported'))
+
+    def exists(self) -> bool:
+        '''Returns True if the server has a tunnel.'''
+        return self.getTunnel() is not None
+
+    def getName(self) -> str:
+        '''Returns the tunnel name.'''
+        return (self.getTunnel() or {}).get('name')
+
+    def getAlias(self) -> str:
+        '''Returns the tunnel alias (the hostname other servers use).'''
+        return (self.getTunnel() or {}).get('alias')
+
+    def getAddress(self) -> str:
+        '''Returns the public tunnel address, if any.'''
+        return (self.getTunnel() or {}).get('address')
+
+    def getPorts(self) -> list:
+        '''Returns the ports exposed through the tunnel.'''
+        return self.getInfo().get('ports', [])
+
+    def getOutgoing(self) -> list:
+        '''Returns the servers this server can reach through the tunnel.'''
+        return self.getInfo().get('outgoing', [])
+
+    def getIncoming(self) -> list:
+        '''Returns the servers that can reach this server through the tunnel.'''
+        return self.getInfo().get('incoming', [])
+
+    def createTunnel(self, name: str = None) -> dict:
+        '''Creates the tunnel. Returns the tunnel info.'''
+        return self.api.createTunnel(self.server_id, name)
+
+    def rename(self, name: str) -> dict:
+        '''Renames the tunnel.'''
+        return self.api.renameTunnel(self.server_id, name)
+
+    def deleteTunnel(self) -> None:
+        '''Deletes the tunnel.'''
+        return self.api.deleteTunnel(self.server_id)
+
+    def setPorts(self, ports: list) -> None:
+        '''
+        Sets the exposed ports.
+
+        Args:
+            ports: List of port numbers (tcp + udp), or {'port': 25565, 'protocols': ['tcp']} dicts.
+
+        Example:
+            server.tunnel.setPorts([25565, {'port': 19132, 'protocols': ['udp']}])
+        '''
+        ports = [p if isinstance(p, dict) else {'port': p, 'protocols': ['tcp', 'udp']} for p in ports]
+        return self.api.setTunnelPorts(self.server_id, ports)
+
+    def getConnectableServers(self, search: str = None, page: int = None, per_page: int = None):
+        '''Returns servers this tunnel can connect to.'''
+        return self.api.tunnelConnectable(self.server_id, search, None, page, per_page)
+
+    def connect(self, server) -> None:
+        '''Lets this server reach another server (object or id) through the tunnel.'''
+        return self.api.connectTunnel(self.server_id, idOf(server))
+
+    def disconnect(self, server, incoming: bool = False) -> None:
+        '''
+        Removes a tunnel connection.
+
+        Args:
+            server: The connected server (object or id).
+            incoming: Remove the connection that reaches this server instead of the outgoing one.
+        '''
+        return self.api.disconnectTunnel(self.server_id, idOf(server), incoming or None)

calagoapi/users/__init__.py

@@ -0,0 +1,11 @@
+from .activity import Activity
+from .subuser import Subuser, SubuserManager
+from .user import User, UserManager
+
+__all__ = [
+    'Activity',
+    'Subuser',
+    'SubuserManager',
+    'User',
+    'UserManager',
+]

calagoapi/users/activity.py

@@ -0,0 +1,45 @@
+from calagoapi.utils.model import Model
+
+
+class Activity(Model):
+    '''
+    One entry of an activity log (server, account or panel-wide).
+
+    Example:
+        for entry in server.getActivity(page=1, per_page=10):
+            print(entry.getCreated(), entry.getUsername(), entry.getEvent())
+    '''
+    def __repr__(self):
+        return f'<Activity {self.getEvent()!r} by {self.getUsername()!r}>'
+
+    def getEvent(self) -> str:
+        '''Returns the event name, e.g. "server:power.start".'''
+        return self.data.get('event')
+
+    def getUser(self) -> dict:
+        '''Returns the user who caused the event, or None for system events.'''
+        return self.data.get('user')
+
+    def getUsername(self) -> str:
+        '''Returns the username who caused the event, or None.'''
+        return (self.data.get('user') or {}).get('username')
+
+    def getImpersonator(self) -> dict:
+        '''Returns the admin who acted on behalf of the user, if any.'''
+        return self.data.get('impersonator')
+
+    def getIP(self) -> str:
+        '''Returns the IP address the event came from.'''
+        return self.data.get('ip')
+
+    def getData(self) -> dict:
+        '''Returns event specific details.'''
+        return self.data.get('data')
+
+    def isApi(self) -> bool:
+        '''Returns True if the event was caused through the API.'''
+        return bool(self.data.get('is_api'))
+
+    def isSchedule(self) -> bool:
+        '''Returns True if the event was caused by a schedule.'''
+        return bool(self.data.get('is_schedule'))

calagoapi/users/subuser.py

@@ -0,0 +1,127 @@
+from calagoapi.utils.model import Model, idOf
+
+
+class Subuser(Model):
+    '''
+    A user who has been given access to a server.
+
+    Args:
+        server: The server.
+        data: Raw subuser data from Calagopus.
+
+    Example:
+        subuser = server.users.addSubuser('friend@example.com', ['control.console', 'control.start'])
+        subuser.addPermissions(['file.read'])
+        print(subuser.getUsername(), subuser.getPermissions())
+    '''
+    def __init__(self, server, data: dict):
+        super().__init__(server.panel, data)
+        self.server = server
+
+    def __repr__(self):
+        return f'<Subuser {self.getUsername()!r}>'
+
+    def getUUID(self) -> str:
+        '''Returns the user's UUID.'''
+        return (self.data.get('user') or {}).get('uuid')
+
+    def getUser(self) -> dict:
+        '''Returns the raw user info (uuid, username, avatar, totp_enabled).'''
+        return self.data.get('user', {})
+
+    def getUsername(self) -> str:
+        '''Returns the username.'''
+        return self.getUser().get('username')
+
+    def getAvatar(self) -> str:
+        '''Returns the avatar URL, if any.'''
+        return self.getUser().get('avatar')
+
+    def getPermissions(self) -> list:
+        '''Returns the granted permissions, e.g. ["control.console", "file.read"].'''
+        return self.data.get('permissions', [])
+
+    def getIgnoredFiles(self) -> list:
+        '''Returns the file patterns hidden from this user.'''
+        return self.data.get('ignored_files', [])
+
+    def hasPermission(self, permission: str) -> bool:
+        '''Returns True if the subuser has the permission.'''
+        return permission in self.getPermissions()
+
+    def hasTwoFactor(self) -> bool:
+        '''Returns True if the user has two-factor authentication enabled.'''
+        return bool(self.getUser().get('totp_enabled'))
+
+    def setPermissions(self, permissions: list) -> 'Subuser':
+        '''Replaces the subuser's permissions.'''
+        self.panel.api.users.update(self.server.server_id, self.getUUID(), permissions=permissions)
+        return self._update({'permissions': list(permissions)})
+
+    def addPermissions(self, permissions: list) -> 'Subuser':
+        '''Grants additional permissions.'''
+        current = self.getPermissions()
+        return self.setPermissions(current + [p for p in permissions if p not in current])
+
+    def removePermissions(self, permissions: list) -> 'Subuser':
+        '''Revokes permissions.'''
+        return self.setPermissions([p for p in self.getPermissions() if p not in permissions])
+
+    def setIgnoredFiles(self, ignored_files: list) -> 'Subuser':
+        '''Sets file patterns the subuser cannot see.'''
+        self.panel.api.users.update(self.server.server_id, self.getUUID(), ignored_files=ignored_files)
+        return self._update({'ignored_files': list(ignored_files)})
+
+    def delete(self) -> None:
+        '''Removes the subuser from the server.'''
+        return self.panel.api.users.delete(self.server.server_id, self.getUUID())
+
+
+class SubuserManager:
+    '''
+    Subuser management for one server, available as `server.users`.
+
+    Use `panel.account.getPermissions()` to list every permission that exists.
+
+    Example:
+        server.users.addSubuser('friend@example.com', ['control.console'])
+        for subuser in server.users.getSubusers():
+            print(subuser.getUsername())
+    '''
+    def __init__(self, server):
+        self.server = server
+        self.api = server.panel.api.users
+
+    def getSubusers(self, search: str = None, page: int = None, per_page: int = None):
+        '''Lists the server's subusers as a Page of Subuser objects.'''
+        return self.api.list(self.server.server_id, search, page, per_page).map(lambda data: Subuser(self.server, data))
+
+    def getSubuser(self, uuid_or_username: str) -> Subuser:
+        '''Returns a subuser by user UUID or username, or None.'''
+        for subuser in self.getSubusers():
+            if uuid_or_username in (subuser.getUUID(), subuser.getUsername()):
+                return subuser
+        return None
+
+    def addSubuser(self, email: str, permissions: list, ignored_files: list = None) -> Subuser:
+        '''
+        Invites a user to the server.
+
+        Args:
+            email: Email of the user. An account is created if needed.
+            permissions: Permissions to grant.
+            ignored_files: File patterns to hide from the user.
+        '''
+        return Subuser(self.server, self.api.create(self.server.server_id, email, permissions, ignored_files))
+
+    def createSubuser(self, email: str, permissions: list, ignored_files: list = None) -> Subuser:
+        '''Alias of addSubuser().'''
+        return self.addSubuser(email, permissions, ignored_files)
+
+    def updateSubuser(self, subuser, permissions: list = None, ignored_files: list = None) -> None:
+        '''Changes a subuser's permissions and/or ignored files.'''
+        return self.api.update(self.server.server_id, idOf(subuser), permissions, ignored_files)
+
+    def deleteSubuser(self, subuser) -> None:
+        '''Removes a subuser from the server.'''
+        return self.api.delete(self.server.server_id, idOf(subuser))