calagoapi 1.0.dev1__py3-none-any.whl

calagoapi/api/auth.py

@@ -0,0 +1,52 @@
+# Internal Calagopus AuthAPI (public, unauthenticated endpoints)
+class AuthAPI:
+    def __init__(self, client):
+        self.client = client
+
+    def login(self, user, password, captcha=None):
+        return self.client.post('/api/auth/login', json={'user': user, 'password': password, 'captcha': captcha})
+
+    def checkpoint(self, code, confirmation_token, method=None):
+        return self.client.post('/api/auth/login/checkpoint', json={
+            'code': code,
+            'confirmation_token': confirmation_token,
+            'method': method,
+        })['user']
+
+    def checkpointEmail(self, confirmation_token):
+        return self.client.post('/api/auth/login/checkpoint/email', json={'confirmation_token': confirmation_token})
+
+    def register(self, username, email, password, name_first=None, name_last=None, language=None, captcha=None):
+        return self.client.post('/api/auth/register', json={
+            'username': username,
+            'email': email,
+            'password': password,
+            'name_first': name_first,
+            'name_last': name_last,
+            'language': language,
+            'captcha': captcha,
+        })['user']
+
+    def verifyEmail(self, token):
+        return self.client.post('/api/auth/email/verify', json={'token': token})
+
+    def forgotPassword(self, email, captcha=None):
+        return self.client.post('/api/auth/password/forgot', json={'email': email, 'captcha': captcha})
+
+    def resetPassword(self, token, new_password):
+        return self.client.post('/api/auth/password/reset', json={'token': token, 'new_password': new_password})
+
+    def oauthProviders(self):
+        return self.client.get('/api/auth/oauth')['oauth_providers']
+
+    def oauthRedirectUrl(self, oauth_provider_id):
+        return f'{self.client.url}/api/auth/oauth/redirect/{oauth_provider_id}'
+
+    def securityKeyOptions(self, user=None, discoverable=False):
+        if discoverable:
+            return self.client.get('/api/auth/login/security-key/discoverable')
+        return self.client.get('/api/auth/login/security-key', params={'user': user})
+
+    def securityKeyLogin(self, uuid, public_key_credential, discoverable=False):
+        path = '/api/auth/login/security-key/discoverable' if discoverable else '/api/auth/login/security-key'
+        return self.client.post(path, json={'uuid': uuid, 'public_key_credential': public_key_credential})['user']

calagoapi/api/backups.py

@@ -0,0 +1,99 @@
+# Internal Calagopus BackupsAPI
+class BackupsAPI:
+    def __init__(self, client):
+        self.client = client
+
+    def _path(self, server_id, suffix=''):
+        return f'/api/client/servers/{server_id}/backups{suffix}'
+
+    # backups
+    def list(self, server_id, search=None, ungrouped=None, kind=None, database_instance_uuid=None, database_type=None, page=None, per_page=None):
+        return self.client.list(self._path(server_id), 'backups', {
+            'search': search,
+            'ungrouped': ungrouped,
+            'kind': kind,
+            'database_instance_uuid': database_instance_uuid,
+            'database_type': database_type,
+        }, page, per_page)
+
+    def system(self, server_id, search=None, page=None, per_page=None):
+        return self.client.list(self._path(server_id, '/system'), 'backups', {'search': search}, page, per_page)
+
+    def get(self, server_id, backup_id):
+        return self.client.get(self._path(server_id, f'/{backup_id}'))['backup']
+
+    def create(self, server_id, name=None, ignored_files=None, backup_group_uuid=None, database_instance_uuid=None):
+        return self.client.post(self._path(server_id), json={
+            'name': name,
+            'ignored_files': ignored_files or [],
+            'backup_group_uuid': backup_group_uuid,
+            'database_instance_uuid': database_instance_uuid,
+        })['backup']
+
+    def update(self, server_id, backup_id, name=None, backup_group_uuid=None, locked=None):
+        return self.client.patch(self._path(server_id, f'/{backup_id}'), json={
+            'name': name,
+            'backup_group_uuid': backup_group_uuid,
+            'locked': locked,
+        })
+
+    def delete(self, server_id, backup_id):
+        return self.client.delete(self._path(server_id, f'/{backup_id}'))
+
+    def deleteMany(self, server_id, backup_ids):
+        return self.client.delete(self._path(server_id), json={'selector': {'type': 'uuids', 'uuids': backup_ids}})
+
+    def updateMany(self, server_id, backup_ids, backup_group_uuid=None, locked=None):
+        return self.client.patch(self._path(server_id), json={
+            'selector': {'type': 'uuids', 'uuids': backup_ids},
+            'backup_group_uuid': backup_group_uuid,
+            'locked': locked,
+        })
+
+    def downloadUrl(self, server_id, backup_id, archive_format=None):
+        return self.client.get(
+            self._path(server_id, f'/{backup_id}/download'),
+            params={'archive_format': archive_format}
+        )['url']
+
+    def query(self, server_id, backup_id):
+        return self.client.get(self._path(server_id, f'/{backup_id}/query'))
+
+    def export(self, server_id, backup_id, path, archive_format=None, foreground=None):
+        return self.client.post(self._path(server_id, f'/{backup_id}/export'), json={
+            'path': path,
+            'archive_format': archive_format,
+            'foreground': foreground,
+        })
+
+    def restore(self, server_id, backup_id, truncate_directory=None, restore_startup=None, database_instance_uuid=None):
+        return self.client.post(self._path(server_id, f'/{backup_id}/restore'), json={
+            'truncate_directory': truncate_directory,
+            'restore_startup': restore_startup,
+            'database_instance_uuid': database_instance_uuid,
+        })
+
+    def unlock(self, server_id):
+        return self.client.post(self._path(server_id, '/unlock'))
+
+    def usage(self, server_id):
+        return self.client.get(self._path(server_id, '/usage'))['usage']
+
+    # backup groups
+    def groups(self, server_id):
+        return self.client.get(self._path(server_id, '/groups'))['backup_groups']
+
+    def groupBackups(self, server_id, group_id, search=None, page=None, per_page=None):
+        return self.client.list(self._path(server_id, f'/groups/{group_id}'), 'backups', {'search': search}, page, per_page)
+
+    def createGroup(self, server_id, name, retention=None):
+        return self.client.post(self._path(server_id, '/groups'), json={'name': name, 'retention': retention})['backup_group']
+
+    def updateGroup(self, server_id, group_id, name=None, retention=None):
+        return self.client.patch(self._path(server_id, f'/groups/{group_id}'), json={'name': name, 'retention': retention})
+
+    def deleteGroup(self, server_id, group_id, lock_backups=None):
+        return self.client.delete(self._path(server_id, f'/groups/{group_id}'), json={'lock_backups': lock_backups})
+
+    def orderGroups(self, server_id, group_order):
+        return self.client.put(self._path(server_id, '/groups/order'), json={'backup_group_order': group_order})

calagoapi/api/client.py

@@ -0,0 +1,198 @@
+import time
+from urllib.parse import quote
+
+import requests
+
+from calagoapi.utils.model import Page
+from calagoapi.utils.exceptions import (
+    CalagoAPIError,
+    BadRequestError,
+    AuthenticationError,
+    PermissionDeniedError,
+    NotFoundError,
+    ConflictError,
+    RateLimitError,
+    ServerError,
+    PanelConnectionError,
+)
+
+
+RETRY_STATUSES = (502, 503, 504)
+
+ERRORS = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    429: RateLimitError,
+}
+
+
+def segment(value):
+    '''Encodes a free-text value (file name, identifier, ...) for use as one URL path segment'''
+    return quote(str(value), safe='')
+
+
+def clean(values):
+    '''Drops None values so optional parameters are never sent'''
+    if values is None:
+        return None
+    return {k: v for k, v in values.items() if v is not None}
+
+
+class Client:
+    '''
+    Internal HTTP client for Calagopus.
+
+    Every request made by CalagoAPI goes through this class. It handles
+    authentication, JSON encoding, error handling, retries and pagination.
+    You normally never need it directly, use `Panel` instead.
+
+    Retries: rate limited requests (429) are retried after the panel's
+    Retry-After delay. GET requests are also retried on connection errors
+    and on 502, 503 and 504. Other requests are never retried, so a power
+    action or backup is never sent twice.
+    '''
+    def __init__(self, url: str, api_key: str, timeout: int = 10, verify: bool = True, user_agent: str = None,
+                 max_retries: int = 3, max_retry_wait: int = 60):
+        self.url = url.rstrip('/')
+        self.api_key = api_key
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.max_retry_wait = max_retry_wait
+
+        self.session = requests.Session()
+        self.session.verify = verify
+        self.session.headers.update(self.headers)
+        if user_agent:
+            self.session.headers['User-Agent'] = user_agent
+
+    @property
+    def headers(self):
+        return {
+            'Authorization': f'Bearer {self.api_key}',
+            'Accept': 'application/json',
+        }
+
+    # http core
+    def request(self, method, path, params=None, json=None, data=None, headers=None, raw=False, timeout=None, stream=False):
+        # optional body fields left as None are omitted, the panel then keeps its default
+        if isinstance(json, dict):
+            json = clean(json)
+
+        attempt = 0
+        while True:
+            try:
+                r = self.session.request(
+                    method,
+                    f'{self.url}{path}',
+                    params=clean(params),
+                    json=json,
+                    data=data,
+                    headers=headers,
+                    timeout=timeout or self.timeout,
+                    stream=stream,
+                )
+            except requests.RequestException as e:
+                if method == 'GET' and attempt < self.max_retries:
+                    attempt += 1
+                    time.sleep(self.retryDelay(attempt))
+                    continue
+                raise PanelConnectionError(f'Could not reach {self.url}: {e}') from e
+
+            retryable = r.status_code == 429 or (method == 'GET' and r.status_code in RETRY_STATUSES)
+            if retryable and attempt < self.max_retries:
+                attempt += 1
+                time.sleep(self.retryDelay(attempt, r.headers.get('Retry-After')))
+                continue
+            break
+
+        if r.status_code >= 400:
+            self.raiseError(r)
+        if raw:
+            return r
+        return self.parse(r)
+
+    def retryDelay(self, attempt, retry_after=None):
+        '''Seconds to wait before a retry: the panel's Retry-After, or 0.5s, 1s, 2s, ...'''
+        try:
+            delay = float(retry_after)
+        except (TypeError, ValueError):
+            delay = 0.5 * 2 ** (attempt - 1)
+        return min(max(delay, 0), self.max_retry_wait)
+
+    def close(self):
+        '''Closes the pooled HTTP connections.'''
+        self.session.close()
+
+    def get(self, path, params=None, **kwargs):
+        return self.request('GET', path, params=params, **kwargs)
+    def post(self, path, json=None, params=None, **kwargs):
+        return self.request('POST', path, params=params, json=json, **kwargs)
+    def put(self, path, json=None, params=None, **kwargs):
+        return self.request('PUT', path, params=params, json=json, **kwargs)
+    def patch(self, path, json=None, params=None, **kwargs):
+        return self.request('PATCH', path, params=params, json=json, **kwargs)
+    def delete(self, path, json=None, params=None, **kwargs):
+        return self.request('DELETE', path, params=params, json=json, **kwargs)
+
+    # plain-text bodies (file writes, database imports)
+    def postText(self, path, content, params=None, content_type='text/plain'):
+        if isinstance(content, str):
+            content = content.encode('utf-8')
+        return self.request('POST', path, params=params, data=content, headers={'Content-Type': content_type})
+
+    # responses
+    @staticmethod
+    def parse(r):
+        if not r.content:
+            return None
+        if 'json' in r.headers.get('Content-Type', ''):
+            return r.json()
+        return r.text
+
+    @staticmethod
+    def raiseError(r):
+        errors = []
+        try:
+            body = r.json()
+            if isinstance(body, dict):
+                errors = body.get('errors') or []
+        except ValueError:
+            pass
+
+        message = '; '.join(str(e) for e in errors) or r.text.strip() or r.reason
+        message = f'{r.status_code} {r.request.method} {r.request.path_url}: {message}'
+
+        if r.status_code == 429:
+            retry_after = r.headers.get('Retry-After')
+            raise RateLimitError(message, r.status_code, errors, r, float(retry_after) if retry_after else None)
+        if r.status_code >= 500:
+            raise ServerError(message, r.status_code, errors, r)
+        raise ERRORS.get(r.status_code, CalagoAPIError)(message, r.status_code, errors, r)
+
+    # pagination
+    def list(self, path, key, params=None, page=None, per_page=None) -> Page:
+        '''
+        Fetches a paginated listing.
+
+        When `page` is given only that page is returned, otherwise every page is
+        fetched and combined into one Page.
+        '''
+        params = dict(params or {})
+
+        if page is not None:
+            params.update(page=page, per_page=per_page or 50)
+            result = self.get(path, params=params)[key]
+            return Page(result['data'], result['total'], result['page'], result['per_page'])
+
+        items = []
+        current = 1
+        while True:
+            params.update(page=current, per_page=per_page or 100)
+            result = self.get(path, params=params)[key]
+            items.extend(result['data'])
+            if not result['data'] or len(items) >= result['total']:
+                return Page(items, result['total'], 1, len(items))
+            current += 1

calagoapi/api/databases.py

@@ -0,0 +1,217 @@
+# Internal Calagopus DatabasesAPI
+class DatabasesAPI:
+    def __init__(self, client):
+        self.client = client
+
+    def _path(self, server_id, suffix=''):
+        return f'/api/client/servers/{server_id}/databases{suffix}'
+
+    def _instance(self, server_id, instance_id, suffix=''):
+        return self._path(server_id, f'/instances/{instance_id}{suffix}')
+
+    # hosted databases
+    def list(self, server_id, search=None, include_password=None, page=None, per_page=None):
+        return self.client.list(self._path(server_id), 'databases', {
+            'search': search,
+            'include_password': include_password,
+        }, page, per_page)
+
+    def get(self, server_id, database_id, include_password=None):
+        return self.client.get(
+            self._path(server_id, f'/{database_id}'),
+            params={'include_password': include_password}
+        )['database']
+
+    def create(self, server_id, database_host_uuid, name):
+        return self.client.post(self._path(server_id), json={
+            'database_host_uuid': database_host_uuid,
+            'name': name,
+        })['database']
+
+    def update(self, server_id, database_id, locked=None):
+        return self.client.patch(self._path(server_id, f'/{database_id}'), json={'locked': locked})
+
+    def delete(self, server_id, database_id):
+        return self.client.delete(self._path(server_id, f'/{database_id}'))
+
+    def rotatePassword(self, server_id, database_id):
+        return self.client.post(self._path(server_id, f'/{database_id}/rotate-password'))['password']
+
+    def recreate(self, server_id, database_id):
+        return self.client.post(self._path(server_id, f'/{database_id}/recreate'))
+
+    def size(self, server_id, database_id):
+        return self.client.get(self._path(server_id, f'/{database_id}/size'))['size']
+
+    def hosts(self, server_id):
+        return self.client.get(self._path(server_id, '/hosts'))['database_hosts']
+
+    # database explorer, `base` is the database path from databasePath() / instanceDatabasePath()
+    def databasePath(self, server_id, database_id):
+        return self._path(server_id, f'/{database_id}')
+
+    def instanceDatabasePath(self, server_id, instance_id, database_id):
+        return self._instance(server_id, instance_id, f'/databases/{database_id}')
+
+    def schema(self, base):
+        return self.client.get(f'{base}/explorer/schema')
+
+    def tableTypes(self, base):
+        return self.client.get(f'{base}/explorer/tables/types')['types']
+
+    def query(self, base, query, rows=None, read_only=None):
+        return self.client.post(f'{base}/explorer/query', json={
+            'query': query,
+            'rows': rows,
+            'read_only': read_only,
+        })['results']
+
+    def rows(self, base, table, schema=None, order_by=None, descending=None, limit=None, offset=None, filters=None):
+        return self.client.post(f'{base}/explorer/rows', json={
+            'table': table,
+            'schema': schema,
+            'order_by': order_by,
+            'descending': descending,
+            'limit': limit,
+            'offset': offset,
+            'filters': filters,
+        })['result']
+
+    def insertRows(self, base, table, rows, schema=None):
+        return self.client.post(f'{base}/explorer/rows/insert', json={'table': table, 'rows': rows, 'schema': schema})['affected']
+
+    def updateRows(self, base, table, rows, schema=None):
+        return self.client.post(f'{base}/explorer/rows/update', json={'table': table, 'rows': rows, 'schema': schema})['affected']
+
+    def deleteRows(self, base, table, rows, schema=None):
+        return self.client.post(f'{base}/explorer/rows/delete', json={'table': table, 'rows': rows, 'schema': schema})['affected']
+
+    def createTable(self, base, table, columns, schema=None):
+        return self.client.post(f'{base}/explorer/tables', json={'table': table, 'columns': columns, 'schema': schema})
+
+    def renameTable(self, base, table, name, schema=None):
+        return self.client.post(f'{base}/explorer/tables/rename', json={'table': table, 'name': name, 'schema': schema})
+
+    def deleteTable(self, base, table, schema=None):
+        return self.client.post(f'{base}/explorer/tables/delete', json={'table': table, 'schema': schema})
+
+    def addColumn(self, base, table, column, schema=None):
+        return self.client.post(f'{base}/explorer/tables/columns', json={'table': table, 'column': column, 'schema': schema})
+
+    def renameColumn(self, base, table, column, name, schema=None):
+        return self.client.post(f'{base}/explorer/tables/columns/rename', json={
+            'table': table,
+            'column': column,
+            'name': name,
+            'schema': schema,
+        })
+
+    def deleteColumn(self, base, table, column, schema=None):
+        return self.client.post(f'{base}/explorer/tables/columns/delete', json={'table': table, 'column': column, 'schema': schema})
+
+    # database instances
+    def instances(self, server_id, search=None, page=None, per_page=None):
+        return self.client.list(self._path(server_id, '/instances'), 'instances', {'search': search}, page, per_page)
+
+    def instance(self, server_id, instance_id):
+        return self.client.get(self._instance(server_id, instance_id))
+
+    def templates(self, server_id):
+        return self.client.get(self._path(server_id, '/instances/templates'))['templates']
+
+    def createInstance(self, server_id, template_uuid, name, image=None):
+        return self.client.post(self._path(server_id, '/instances'), json={
+            'template_uuid': template_uuid,
+            'name': name,
+            'image': image,
+        })['instance']
+
+    def updateInstance(self, server_id, instance_id, name=None, locked=None):
+        return self.client.patch(self._instance(server_id, instance_id), json={'name': name, 'locked': locked})
+
+    def deleteInstance(self, server_id, instance_id, force=None):
+        return self.client.delete(self._instance(server_id, instance_id), params={'force': force})
+
+    def instancePower(self, server_id, instance_id, action):
+        return self.client.post(self._instance(server_id, instance_id, '/power'), json={'action': action})
+
+    def instanceResources(self, server_id, instance_id):
+        return self.client.get(self._instance(server_id, instance_id, '/resources'))['resources']
+
+    def instanceLogs(self, server_id, instance_id, lines=None):
+        return self.client.get(self._instance(server_id, instance_id, '/logs'), params={'lines': lines})
+
+    def upgradeInstance(self, server_id, instance_id):
+        return self.client.post(self._instance(server_id, instance_id, '/update'))['instance']
+
+    def exportInstance(self, server_id, instance_id):
+        return self.client.get(self._instance(server_id, instance_id, '/export'))
+
+    def importInstance(self, server_id, instance_id, content, wipe=None):
+        return self.client.postText(
+            self._instance(server_id, instance_id, '/import'), content,
+            params={'wipe': wipe}, content_type='application/octet-stream'
+        )
+
+    def cancelInstanceOperation(self, server_id, instance_id, operation_id):
+        return self.client.delete(self._instance(server_id, instance_id, f'/operations/{operation_id}'))
+
+    # databases inside an instance
+    def instanceDatabases(self, server_id, instance_id):
+        return self.client.get(self._instance(server_id, instance_id, '/databases'))['databases']
+
+    def createInstanceDatabase(self, server_id, instance_id, name):
+        return self.client.post(self._instance(server_id, instance_id, '/databases'), json={'name': name})['database']
+
+    def deleteInstanceDatabase(self, server_id, instance_id, database_id):
+        return self.client.delete(self.instanceDatabasePath(server_id, instance_id, database_id))
+
+    def recreateInstanceDatabase(self, server_id, instance_id, database_id):
+        return self.client.post(f'{self.instanceDatabasePath(server_id, instance_id, database_id)}/recreate')
+
+    def instanceDatabaseSize(self, server_id, instance_id, database_id):
+        return self.client.get(f'{self.instanceDatabasePath(server_id, instance_id, database_id)}/size')['size']
+
+    def exportInstanceDatabase(self, server_id, instance_id, database_id):
+        return self.client.get(f'{self.instanceDatabasePath(server_id, instance_id, database_id)}/export')
+
+    def importInstanceDatabase(self, server_id, instance_id, database_id, content, source_db=None, wipe=None):
+        return self.client.postText(
+            f'{self.instanceDatabasePath(server_id, instance_id, database_id)}/import', content,
+            params={'source_db': source_db, 'wipe': wipe}, content_type='application/octet-stream'
+        )
+
+    def importInstanceDatabaseRemote(self, server_id, instance_id, database_id, url, source_db=None, wipe=None):
+        return self.client.post(f'{self.instanceDatabasePath(server_id, instance_id, database_id)}/import/remote', json={
+            'url': url,
+            'source_db': source_db,
+            'wipe': wipe,
+        })['operation']
+
+    # instance users
+    def instanceUsers(self, server_id, instance_id):
+        return self.client.get(self._instance(server_id, instance_id, '/users'))['users']
+
+    def createInstanceUser(self, server_id, instance_id, username, databases=None):
+        return self.client.post(self._instance(server_id, instance_id, '/users'), json={
+            'username': username,
+            'databases': databases,
+        })['user']
+
+    def deleteInstanceUser(self, server_id, instance_id, user_id):
+        return self.client.delete(self._instance(server_id, instance_id, f'/users/{user_id}'))
+
+    def rotateInstanceUserPassword(self, server_id, instance_id, user_id):
+        return self.client.post(self._instance(server_id, instance_id, f'/users/{user_id}/rotate-password'))['password']
+
+    def setInstanceUserDatabases(self, server_id, instance_id, user_id, databases):
+        return self.client.put(
+            self._instance(server_id, instance_id, f'/users/{user_id}/databases'),
+            json={'databases': databases}
+        )['databases']
+
+    def setInstanceUserPermission(self, server_id, instance_id, user_id, database_id, permission):
+        return self.client.put(
+            self._instance(server_id, instance_id, f'/users/{user_id}/databases/{database_id}'),
+            json={'permission': permission}
+        )['database']