calagoapi 1.0.dev1__py3-none-any.whl

calagoapi/account/models.py

@@ -0,0 +1,221 @@
+from calagoapi.utils.model import Model
+
+
+class ApiKey(Model):
+    '''
+    An API key of the current account.
+
+    The secret key is only known right after creation (`getKey()`).
+
+    Example:
+        api_key = panel.account.createApiKey('backup-bot', server_permissions=['backup.*'])
+        print(api_key.getKey())  # store it now, it is never shown again
+    '''
+    def __init__(self, panel, data: dict, key: str = None):
+        super().__init__(panel, data)
+        self.key = key
+
+    def getName(self) -> str:
+        '''Returns the key name.'''
+        return self.data.get('name')
+
+    def getKey(self) -> str:
+        '''Returns the full secret key. Only available right after creation or recreate().'''
+        return self.key
+
+    def getKeyStart(self) -> str:
+        '''Returns the first characters of the key, for identification.'''
+        return self.data.get('key_start')
+
+    def getAllowedIPs(self) -> list:
+        '''Returns the IPs allowed to use the key. Empty means all.'''
+        return self.data.get('allowed_ips', [])
+
+    def getUserPermissions(self) -> list:
+        '''Returns the account permissions of the key.'''
+        return self.data.get('user_permissions', [])
+
+    def getAdminPermissions(self) -> list:
+        '''Returns the admin permissions of the key.'''
+        return self.data.get('admin_permissions', [])
+
+    def getServerPermissions(self) -> list:
+        '''Returns the server permissions of the key.'''
+        return self.data.get('server_permissions', [])
+
+    def getLastUsed(self) -> str:
+        '''Returns when the key was last used.'''
+        return self.data.get('last_used')
+
+    def getExpires(self) -> str:
+        '''Returns when the key expires, or None.'''
+        return self.data.get('expires')
+
+    def isEnabled(self) -> bool:
+        '''Returns True if the key is enabled.'''
+        return bool(self.data.get('enabled'))
+
+    def update(self, **fields) -> 'ApiKey':
+        '''
+        Changes the key. Fields: name, enabled, allowed_ips, user_permissions,
+        admin_permissions, server_permissions, expires.
+        '''
+        allowed_ips = fields.pop('allowed_ips', self.getAllowedIPs())
+        self.panel.api.account.updateApiKey(self.getUUID(), allowed_ips, **fields)
+        return self._update({'allowed_ips': allowed_ips, **fields})
+
+    def rename(self, name: str) -> 'ApiKey':
+        '''Renames the key.'''
+        return self.update(name=name)
+
+    def enable(self) -> 'ApiKey':
+        '''Enables the key.'''
+        return self.update(enabled=True)
+
+    def disable(self) -> 'ApiKey':
+        '''Disables the key.'''
+        return self.update(enabled=False)
+
+    def recreate(self) -> str:
+        '''Generates a new secret for the key and returns it.'''
+        self.key = self.panel.api.account.recreateApiKey(self.getUUID())
+        return self.key
+
+    def duplicate(self, name: str) -> 'ApiKey':
+        '''Creates a copy with the same permissions. The copy holds its new secret.'''
+        result = self.panel.api.account.duplicateApiKey(self.getUUID(), name)
+        return ApiKey(self.panel, result['api_key'], result.get('key'))
+
+    def delete(self) -> None:
+        '''Deletes the key.'''
+        return self.panel.api.account.deleteApiKey(self.getUUID())
+
+
+class SshKey(Model):
+    '''An SSH public key used for SFTP login.'''
+    def getName(self) -> str:
+        '''Returns the key name.'''
+        return self.data.get('name')
+
+    def getFingerprint(self) -> str:
+        '''Returns the key fingerprint.'''
+        return self.data.get('fingerprint')
+
+    def rename(self, name: str) -> 'SshKey':
+        '''Renames the key.'''
+        self.panel.api.account.updateSshKey(self.getUUID(), name)
+        return self._update({'name': name})
+
+    def delete(self) -> None:
+        '''Deletes the key.'''
+        return self.panel.api.account.deleteSshKey(self.getUUID())
+
+
+class SecurityKey(Model):
+    '''A WebAuthn security key / passkey.'''
+    def getName(self) -> str:
+        '''Returns the key name.'''
+        return self.data.get('name')
+
+    def getCredentialId(self) -> str:
+        '''Returns the WebAuthn credential id.'''
+        return self.data.get('credential_id')
+
+    def getLastUsed(self) -> str:
+        '''Returns when the key was last used.'''
+        return self.data.get('last_used')
+
+    def rename(self, name: str) -> 'SecurityKey':
+        '''Renames the key.'''
+        self.panel.api.account.updateSecurityKey(self.getUUID(), name)
+        return self._update({'name': name})
+
+    def delete(self, password: str = None) -> None:
+        '''Deletes the key.'''
+        return self.panel.api.account.deleteSecurityKey(self.getUUID(), password)
+
+
+class Session(Model):
+    '''A logged-in browser session.'''
+    def __repr__(self):
+        return f'<Session {self.getIP()!r}>'
+
+    def getIP(self) -> str:
+        '''Returns the IP address.'''
+        return self.data.get('ip')
+
+    def getUserAgent(self) -> str:
+        '''Returns the browser user agent.'''
+        return self.data.get('user_agent')
+
+    def getLastUsed(self) -> str:
+        '''Returns when the session was last used.'''
+        return self.data.get('last_used')
+
+    def isCurrent(self) -> bool:
+        '''Returns True for the session making this request.'''
+        return bool(self.data.get('is_using'))
+
+    def delete(self) -> None:
+        '''Logs the session out.'''
+        return self.panel.api.account.deleteSession(self.getUUID())
+
+
+class OAuthLink(Model):
+    '''An external account (Discord, GitHub, ...) linked for login.'''
+    def __repr__(self):
+        return f'<OAuthLink {self.getIdentifier()!r}>'
+
+    def getProvider(self) -> dict:
+        '''Returns the OAuth provider.'''
+        return self.data.get('oauth_provider')
+
+    def getIdentifier(self) -> str:
+        '''Returns the external account id.'''
+        return self.data.get('identifier')
+
+    def getLastUsed(self) -> str:
+        '''Returns when the link was last used to log in.'''
+        return self.data.get('last_used')
+
+    def delete(self) -> None:
+        '''Unlinks the account.'''
+        return self.panel.api.account.deleteOauthLink(self.getUUID())
+
+
+class CommandSnippet(Model):
+    '''
+    A saved console command, shown on matching servers.
+
+    Example:
+        snippet = panel.account.createCommandSnippet('Day', 'time set day')
+    '''
+    def getName(self) -> str:
+        '''Returns the snippet name.'''
+        return self.data.get('name')
+
+    def getCommand(self) -> str:
+        '''Returns the command.'''
+        return self.data.get('command')
+
+    def getEggs(self) -> list:
+        '''Returns the eggs the snippet applies to. Empty means all.'''
+        return self.data.get('eggs', [])
+
+    def update(self, name: str = None, command: str = None, eggs: list = None) -> 'CommandSnippet':
+        '''Changes the snippet.'''
+        name = name or self.getName()
+        self.panel.api.account.updateCommandSnippet(self.getUUID(), name, command, eggs)
+        return self._update({'name': name, 'command': command, 'eggs': eggs})
+
+    def duplicate(self, name: str) -> 'CommandSnippet':
+        '''Copies the snippet.'''
+        return CommandSnippet(self.panel, self.panel.api.account.duplicateCommandSnippet(self.getUUID(), name))
+
+    def runOn(self, server) -> None:
+        '''Sends the command to a server.'''
+        return server.sendCommand(self.getCommand())
+
+    def delete(self) -> None:
+        '''Deletes the snippet.'''
+        return self.panel.api.account.deleteCommandSnippet(self.getUUID())

calagoapi/admin/__init__.py

@@ -0,0 +1,48 @@
+from calagoapi.utils.resource import AdminResource, AdminManager
+from .resources import (
+    Location,
+    Nest,
+    Egg,
+    EggVariable,
+    Mount,
+    Device,
+    Role,
+    Announcement,
+    OAuthProvider,
+    DatabaseHost,
+    DatabaseAgentHost,
+    DatabaseAgentTemplate,
+    BackupConfiguration,
+    BackupPolicy,
+    EggRepository,
+    EggConfiguration,
+    SubdomainDomain,
+)
+from .admin import Admin, SystemManager, EmailManager, ExtensionManager, AssetManager
+
+__all__ = [
+    'Admin',
+    'AdminResource',
+    'AdminManager',
+    'SystemManager',
+    'EmailManager',
+    'ExtensionManager',
+    'AssetManager',
+    'Location',
+    'Nest',
+    'Egg',
+    'EggVariable',
+    'Mount',
+    'Device',
+    'Role',
+    'Announcement',
+    'OAuthProvider',
+    'DatabaseHost',
+    'DatabaseAgentHost',
+    'DatabaseAgentTemplate',
+    'BackupConfiguration',
+    'BackupPolicy',
+    'EggRepository',
+    'EggConfiguration',
+    'SubdomainDomain',
+]

calagoapi/admin/admin.py

@@ -0,0 +1,341 @@
+import os
+
+from calagoapi.admin.managers import (
+    LocationManager,
+    NestManager,
+    MountManager,
+    DeviceManager,
+    RoleManager,
+    AnnouncementManager,
+    OAuthProviderManager,
+    DatabaseHostManager,
+    DatabaseAgentHostManager,
+    DatabaseAgentTemplateManager,
+    BackupConfigurationManager,
+    BackupPolicyManager,
+    EggRepositoryManager,
+    EggConfigurationManager,
+    SubdomainDomainManager,
+)
+from calagoapi.nodes import NodeManager
+from calagoapi.servers.admin import AdminServerManager
+from calagoapi.users import UserManager, Activity
+from calagoapi.utils.model import idOf
+
+
+class SystemManager:
+    '''
+    Panel health, updates and diagnostics, available as `panel.admin.system`.
+
+    Example:
+        overview = panel.admin.system.getOverview()
+        print(overview['version'])
+        if panel.admin.system.getUpdates():
+            print('An update is available')
+    '''
+    def __init__(self, panel):
+        self.panel = panel
+        self.api = panel.api.admin
+
+    def getOverview(self) -> dict:
+        '''Returns panel version, CPU, memory, cache and database information.'''
+        return self.api.system('overview')
+
+    def getHealth(self) -> dict:
+        '''Returns time sync and pending migration information.'''
+        return self.api.system('health/general')
+
+    def getNodeHealth(self, page: int = None, per_page: int = None) -> dict:
+        '''Returns nodes whose clock is out of sync or that cannot be reached.'''
+        return self.api.system('health/nodes', params={'page': page, 'per_page': per_page})
+
+    def getTelemetry(self) -> dict:
+        '''Returns the anonymous telemetry the panel would send.'''
+        return self.api.system('telemetry')['telemetry']
+
+    def getUpdates(self) -> dict:
+        '''Returns available panel update information.'''
+        return self.api.system('updates')['update_information']
+
+    def recheckUpdates(self) -> dict:
+        '''Checks for updates now.'''
+        return self.api.system('updates/recheck', 'POST')['update_information']
+
+    def getUpdateHistory(self) -> dict:
+        '''Returns the panel version history.'''
+        return self.api.system('updates/history')['version_history']
+
+    def getOutdatedNodes(self, page: int = None, per_page: int = None) -> dict:
+        '''Returns nodes running an outdated daemon.'''
+        return self.api.system('updates/nodes', params={'page': page, 'per_page': per_page})
+
+    def getOutdatedDatabaseAgentHosts(self, page: int = None, per_page: int = None) -> dict:
+        '''Returns database agent hosts running an outdated agent.'''
+        return self.api.system('updates/database-agent-hosts', params={'page': page, 'per_page': per_page})
+
+    def isDebugEnabled(self) -> bool:
+        '''Returns True if debug logging is enabled.'''
+        return bool(self.api.system('debug').get('enabled'))
+
+    def setDebug(self, enabled: bool) -> None:
+        '''Turns debug logging on or off.'''
+        return self.api.system('debug', 'POST', json={'enabled': enabled})
+
+
+class EmailManager:
+    '''
+    Email templates and variables, available as `panel.admin.email`.
+
+    Example:
+        panel.admin.email.sendTestEmail('me@example.com')
+        panel.admin.email.updateTemplate('password_reset', subject='Reset your password')
+    '''
+    def __init__(self, panel):
+        self.panel = panel
+        self.api = panel.api.admin
+
+    def sendTestEmail(self, email: str) -> None:
+        '''Sends a test email using the current mail settings.'''
+        return self.api.sendTestEmail(email)
+
+    def getTemplates(self) -> list:
+        '''Returns every email template.'''
+        return self.api.emailTemplates()
+
+    def getTemplate(self, identifier: str) -> dict:
+        '''Returns one email template.'''
+        return self.api.emailTemplate(identifier)
+
+    def updateTemplate(self, identifier: str, subject: str = None, content: str = None, enabled: bool = None) -> None:
+        '''Changes an email template.'''
+        return self.api.updateEmailTemplate(identifier, subject, content, enabled)
+
+    def getTemplateVariables(self, identifier: str) -> list:
+        '''Returns variables defined for one template.'''
+        return self.api.emailVariables(identifier)
+
+    def createTemplateVariable(self, identifier: str, name: str, value: str, value_translations: dict = None) -> None:
+        '''Defines a variable for one template.'''
+        return self.api.createEmailVariable(name, value, value_translations, identifier)
+
+    def updateTemplateVariable(self, identifier: str, name: str, value: str = None, value_translations: dict = None) -> None:
+        '''Changes a template variable.'''
+        return self.api.updateEmailVariable(name, value, value_translations, identifier)
+
+    def deleteTemplateVariable(self, identifier: str, name: str) -> None:
+        '''Deletes a template variable.'''
+        return self.api.deleteEmailVariable(name, identifier)
+
+    def getVariables(self) -> list:
+        '''Returns global email variables.'''
+        return self.api.emailVariables()
+
+    def createVariable(self, name: str, value: str, value_translations: dict = None) -> None:
+        '''Defines a global email variable.'''
+        return self.api.createEmailVariable(name, value, value_translations)
+
+    def updateVariable(self, name: str, value: str = None, value_translations: dict = None) -> None:
+        '''Changes a global email variable.'''
+        return self.api.updateEmailVariable(name, value, value_translations)
+
+    def deleteVariable(self, name: str) -> None:
+        '''Deletes a global email variable.'''
+        return self.api.deleteEmailVariable(name)
+
+
+class ExtensionManager:
+    '''
+    Panel extensions, available as `panel.admin.extensions`.
+
+    Example:
+        for extension in panel.admin.extensions.getExtensions():
+            print(extension['identifier'])
+        panel.admin.extensions.disable('dev.0x7d8.subdomainmanager')
+        panel.admin.extensions.restart()
+    '''
+    VERSION_CHANGER = 'dev.0x7d8.minecraftversionchanger'
+
+    def __init__(self, panel):
+        self.panel = panel
+        self.api = panel.api.admin
+
+    def getInfo(self) -> dict:
+        '''Returns installed, disabled and pending extensions.'''
+        return self.api.extensions()
+
+    def getExtensions(self) -> list:
+        '''Returns installed extensions.'''
+        return self.getInfo().get('extensions', [])
+
+    def setEnabled(self, extension: str, enabled: bool) -> bool:
+        '''Enables or disables an extension. Returns True if a restart is needed.'''
+        return self.api.setExtensionEnabled(extension, enabled)
+
+    def enable(self, extension: str) -> bool:
+        '''Enables an extension.'''
+        return self.setEnabled(extension, True)
+
+    def disable(self, extension: str) -> bool:
+        '''Disables an extension.'''
+        return self.setEnabled(extension, False)
+
+    def getStatus(self) -> dict:
+        '''Returns build status, running version and pending changes.'''
+        return self.api.manageExtensions('status')
+
+    def install(self, file, accept_license: bool = False) -> dict:
+        '''
+        Uploads and installs an extension package.
+
+        Args:
+            file: Local path or bytes of the extension archive.
+            accept_license: Accept the extension's license.
+        '''
+        if isinstance(file, (str, os.PathLike)):
+            with open(file, 'rb') as f:
+                file = f.read()
+        return self.api.manageExtensions('add', 'PUT', params={'accept_license': accept_license}, data=file,
+                                         headers={'Content-Type': 'application/octet-stream'})
+
+    def remove(self, extension: str, remove_migrations: bool = False) -> None:
+        '''Uninstalls an extension.'''
+        return self.api.removeExtension(extension, remove_migrations)
+
+    def rebuild(self, force: bool = False) -> str:
+        '''Rebuilds the panel with the current extensions. Returns the build id.'''
+        return self.api.manageExtensions('rebuild', 'POST', params={'force': force})['build_id']
+
+    def cancelRebuild(self, build_id: str = None) -> str:
+        '''Cancels a running rebuild.'''
+        return self.api.manageExtensions('rebuild/cancel', 'POST', params={'build_id': build_id})['build_id']
+
+    def getBuildLogs(self, build_id: str = None, from_offset: int = None) -> dict:
+        '''Returns build output (offset, data, eof).'''
+        return self.api.manageExtensions('logs', params={'build_id': build_id, 'from_offset': from_offset})
+
+    def restart(self) -> None:
+        '''Restarts the panel to apply extension changes.'''
+        return self.api.manageExtensions('restart', 'POST')
+
+    # Minecraft Version Changer
+    def getVersionChangerSettings(self) -> dict:
+        '''Returns the Minecraft Version Changer settings.'''
+        return self.api.extension(self.VERSION_CHANGER, 'settings')['settings']
+
+    def updateVersionChangerSettings(self, **settings) -> None:
+        '''Changes Minecraft Version Changer settings (mcjars_url, mcjars_api_key, type_egg_assignments, ...).'''
+        return self.api.extension(self.VERSION_CHANGER, 'settings', 'PUT', json=settings)
+
+    def getVersionChangerStatistics(self) -> dict:
+        '''Returns install statistics by server type and version.'''
+        return self.api.extension(self.VERSION_CHANGER, 'statistics/total')
+
+    def getVersionChangerDefaultOrder(self) -> list:
+        '''Returns the default order of server types in the version picker.'''
+        return self.api.extension(self.VERSION_CHANGER, 'default-order')['mcjars_type_order']
+
+
+class AssetManager:
+    '''
+    Panel assets (logos, images), available as `panel.admin.assets`.
+
+    Example:
+        panel.admin.assets.upload('logo.png', directory='branding')
+    '''
+    def __init__(self, panel):
+        self.panel = panel
+        self.api = panel.api.admin
+
+    def getAssets(self, directory: str = None, page: int = None, per_page: int = None):
+        '''Lists assets.'''
+        return self.api.assets(directory, page, per_page)
+
+    def upload(self, file, directory: str = None, content_type: str = 'application/octet-stream') -> list:
+        '''Uploads an asset from a local path or bytes.'''
+        if isinstance(file, (str, os.PathLike)):
+            with open(file, 'rb') as f:
+                file = f.read()
+        return self.api.uploadAsset(file, directory, content_type)
+
+    def search(self, query: str, directory: str = None, per_page: int = None) -> list:
+        '''Searches assets by name.'''
+        return self.api.searchAssets(query, directory, per_page)
+
+    def delete(self, names: list) -> int:
+        '''Deletes assets by name. Returns how many were deleted.'''
+        return self.api.deleteAssets(names)
+
+
+class Admin:
+    '''
+    Panel administration, available as `panel.admin`. Requires an API key with admin permissions.
+
+    Managers:
+        users, servers, nodes, locations, nests, mounts, devices, roles,
+        announcements, oauth, database_hosts, database_agent_hosts,
+        database_templates, backup_configurations, backup_policies,
+        egg_repositories, egg_configurations, subdomain_domains,
+        system, email, extensions, assets
+
+    Example:
+        for node in panel.admin.nodes.getNodes():
+            print(node.getName(), node.isInMaintenance())
+
+        user = panel.admin.users.createUser('steve', 'steve@example.com')
+        panel.admin.servers.deployServer('Steve SMP', user, paper_egg, locations=[eu])
+    '''
+    def __init__(self, panel):
+        self.panel = panel
+        self.api = panel.api.admin
+
+        self.users = UserManager(panel)
+        self.servers = AdminServerManager(panel)
+        self.nodes = NodeManager(panel)
+        self.locations = LocationManager(panel)
+        self.nests = NestManager(panel)
+        self.mounts = MountManager(panel)
+        self.devices = DeviceManager(panel)
+        self.roles = RoleManager(panel)
+        self.announcements = AnnouncementManager(panel)
+        self.oauth = OAuthProviderManager(panel)
+        self.database_hosts = DatabaseHostManager(panel)
+        self.database_agent_hosts = DatabaseAgentHostManager(panel)
+        self.database_templates = DatabaseAgentTemplateManager(panel)
+        self.backup_configurations = BackupConfigurationManager(panel)
+        self.backup_policies = BackupPolicyManager(panel)
+        self.egg_repositories = EggRepositoryManager(panel)
+        self.egg_configurations = EggConfigurationManager(panel)
+        self.subdomain_domains = SubdomainDomainManager(panel)
+
+        self.system = SystemManager(panel)
+        self.email = EmailManager(panel)
+        self.extensions = ExtensionManager(panel)
+        self.assets = AssetManager(panel)
+
+    def getSettings(self) -> dict:
+        '''Returns the panel settings.'''
+        return self.api.settings()
+
+    def updateSettings(self, **sections) -> None:
+        '''
+        Changes panel settings. Pass whole sections, e.g. app, server, user,
+        activity, ratelimits, webauthn, mail_mode, captcha_provider.
+
+        Example:
+            settings = panel.admin.getSettings()
+            settings['app']['name'] = 'My Hosting'
+            panel.admin.updateSettings(app=settings['app'])
+        '''
+        return self.api.updateSettings(**sections)
+
+    def getActivity(self, search: str = None, user=None, page: int = 1, per_page: int = 50):
+        '''Returns the panel-wide admin activity log.'''
+        return self.api.activity(idOf(user), search, page, per_page).map(lambda data: Activity(self.panel, data))
+
+    def getStats(self) -> dict:
+        '''Returns panel statistics (users, servers, nodes, ...).'''
+        return self.api.generalStats()
+
+    def getBackupStats(self) -> dict:
+        '''Returns backup statistics for today, this week, this month and all time.'''
+        return self.api.backupStats()