calagoapi 1.0.dev1__py3-none-any.whl

calagoapi/aio/__init__.py

@@ -0,0 +1,9 @@
+from .console import AsyncConsole
+from .panel import AsyncPanel, AsyncServer, AsyncWrapper
+
+__all__ = [
+    'AsyncPanel',
+    'AsyncServer',
+    'AsyncConsole',
+    'AsyncWrapper',
+]

calagoapi/aio/console.py

@@ -0,0 +1,289 @@
+import asyncio
+import inspect
+import time
+
+from websockets.asyncio.client import connect
+from websockets.exceptions import ConnectionClosed, WebSocketException
+
+from calagoapi.console.console import (
+    ConsoleEvent,
+    socketUrl,
+    sslContext,
+    encode,
+    decode,
+    logger,
+    POWER_ACTIONS,
+    TOKEN_EVENTS,
+    ERROR_EVENTS,
+)
+from calagoapi.utils.exceptions import CalagoAPIError, ConsoleError, InvalidActionError, WaitTimeoutError
+
+
+class AsyncConsole:
+    '''
+    The live console of a server for asyncio code, available as `server.console`
+    on servers from AsyncPanel.
+
+    Same methods as Console, but awaitable. Callbacks may be plain functions
+    or coroutines.
+
+    Example:
+        async with server.console as console:
+            await console.sendCommand('list')
+            async for line in console.lines():
+                print(line)
+
+        server.console.onConsoleLine(print)
+        await server.console.listen()
+        ...
+        await server.console.stop()
+
+    Args:
+        server: The (regular) GenericServer whose console to open.
+    '''
+    def __init__(self, server):
+        self.server = server
+        self.socket = None
+        self.permissions = []
+        self.handlers = {}
+        self.running = False
+        self.task = None
+
+    def __repr__(self):
+        state = 'connected' if self.isConnected() else 'closed'
+        return f'<AsyncConsole {self.server.name!r} {state}>'
+
+    async def __aenter__(self):
+        return await self.connect()
+
+    async def __aexit__(self, *exc):
+        await self.stop()
+
+    # connection
+    async def connect(self, timeout: int = 10) -> 'AsyncConsole':
+        '''
+        Opens the websocket and authenticates. Does nothing if already connected.
+
+        Raises:
+            ConsoleError: The daemon could not be reached or refused the token.
+        '''
+        if self.socket:
+            return self
+        credentials = await asyncio.to_thread(self.server.getWebsocket)
+        url = socketUrl(credentials['url'])
+        try:
+            self.socket = await connect(
+                url,
+                origin=self.server.panel.url,
+                ssl=sslContext(url, self.server.panel.client.session.verify),
+                open_timeout=timeout,
+                user_agent_header='CalagoAPI',
+            )
+        except (OSError, WebSocketException, asyncio.TimeoutError) as e:
+            raise ConsoleError(f'Could not connect to the console of {self.server.name}: {e}') from e
+        self.server.panel.consoles.add(self)
+
+        await self._send('auth', credentials['token'])
+        deadline = time.monotonic() + timeout
+        while True:
+            event = await self._receive(max(deadline - time.monotonic(), 0.01))
+            if event is None:
+                await self.close()
+                raise ConsoleError(f'The console of {self.server.name} did not confirm authentication')
+            if event.getEvent() == 'auth success':
+                self.permissions = event.getArgs()
+                return self
+            if event.getEvent() in ERROR_EVENTS:
+                await self.close()
+                raise ConsoleError(f'Console authentication failed: {event.getArg()}')
+
+    async def close(self) -> None:
+        '''Closes the websocket. Use stop() to also end a running listen().'''
+        socket, self.socket = self.socket, None
+        self.server.panel.consoles.discard(self)
+        if socket:
+            await socket.close()
+
+    def isConnected(self) -> bool:
+        '''Returns True while the websocket is open.'''
+        return self.socket is not None
+
+    def getPermissions(self) -> list:
+        '''Returns the console permissions the daemon granted.'''
+        return self.permissions
+
+    # sending
+    async def _send(self, event, *args):
+        if not self.socket:
+            raise ConsoleError('The console is not connected, call connect() first')
+        try:
+            await self.socket.send(encode(event, *args))
+        except ConnectionClosed as e:
+            self.socket = None
+            raise ConsoleError(f'The console connection was closed: {e}') from e
+
+    async def sendCommand(self, command: str) -> None:
+        '''Sends a console command over the websocket.'''
+        await self._send('send command', command)
+
+    async def setState(self, action: str) -> None:
+        '''Sends a power action: start, restart, stop or kill.'''
+        if action not in POWER_ACTIONS:
+            raise InvalidActionError(f'Invalid power action "{action}", expected one of: {", ".join(POWER_ACTIONS)}')
+        await self._send('set state', action)
+
+    async def requestLogs(self) -> None:
+        '''Asks the daemon to resend recent console lines.'''
+        await self._send('send logs')
+
+    async def requestStats(self) -> None:
+        '''Asks the daemon for resource usage now.'''
+        await self._send('send stats')
+
+    async def requestStatus(self) -> None:
+        '''Asks the daemon for the power state now.'''
+        await self._send('send status')
+
+    # receiving
+    async def _receive(self, timeout=None):
+        if not self.socket:
+            return None
+        try:
+            raw = await asyncio.wait_for(self.socket.recv(), timeout)
+        except asyncio.TimeoutError:
+            return None
+        except ConnectionClosed:
+            await self.close()
+            return None
+        return decode(raw) or ConsoleEvent('unknown')
+
+    async def _renewToken(self):
+        credentials = await asyncio.to_thread(self.server.getWebsocket)
+        await self._send('auth', credentials['token'])
+
+    async def events(self, timeout: float = None):
+        '''
+        Yields every event from the daemon until the connection closes.
+
+        Args:
+            timeout: Stop when no event arrives for this many seconds. None waits forever.
+        '''
+        while self.socket:
+            event = await self._receive(timeout)
+            if event is None:
+                return
+            if event.getEvent() in TOKEN_EVENTS:
+                await self._renewToken()
+                continue
+            yield event
+
+    async def lines(self, history: bool = True, timeout: float = None):
+        '''
+        Yields console lines as they are printed.
+
+        Example:
+            async for line in console.lines(history=False):
+                print(line)
+        '''
+        await self.connect()
+        if history:
+            await self.requestLogs()
+        async for event in self.events(timeout):
+            if event.getEvent() == 'console output':
+                yield event.getArg(0, '')
+
+    async def waitFor(self, text: str, timeout: float = 60) -> str:
+        '''
+        Waits until a console line contains `text` and returns that line.
+
+        Raises:
+            WaitTimeoutError: No matching line within `timeout` seconds.
+        '''
+        await self.connect()
+        deadline = time.monotonic() + timeout
+        while True:
+            remaining = deadline - time.monotonic()
+            event = await self._receive(remaining) if remaining > 0 else None
+            if event is None:
+                raise WaitTimeoutError(f'No console line containing {text!r} within {timeout}s')
+            if event.getEvent() in TOKEN_EVENTS:
+                await self._renewToken()
+            elif event.getEvent() == 'console output' and text in event.getArg(0, ''):
+                return event.getArg()
+
+    # callbacks
+    def on(self, event: str, callback) -> 'AsyncConsole':
+        '''Calls `callback(ConsoleEvent)` for an event while listen() runs. Use '*' for every event.'''
+        self.handlers.setdefault(event, []).append(callback)
+        return self
+
+    def onConsoleLine(self, callback) -> 'AsyncConsole':
+        '''Calls `callback(line)` for every console line.'''
+        return self.on('console output', lambda event: callback(event.getArg(0, '')))
+
+    def onStatus(self, callback) -> 'AsyncConsole':
+        '''Calls `callback(state)` when the power state changes.'''
+        return self.on('status', lambda event: callback(event.getArg()))
+
+    def onStats(self, callback) -> 'AsyncConsole':
+        '''Calls `callback(resources)` with a resource usage dict.'''
+        return self.on('stats', lambda event: callback(event.getData()))
+
+    async def _dispatch(self, event):
+        for callback in self.handlers.get(event.getEvent(), []) + self.handlers.get('*', []):
+            try:
+                result = callback(event)
+                if inspect.isawaitable(result):
+                    await result
+            except Exception:
+                logger.exception('console callback for %r failed', event.getEvent())
+
+    async def listen(self, background: bool = True, history: bool = False, reconnect: bool = True) -> 'AsyncConsole':
+        '''
+        Delivers events to the registered callbacks.
+
+        Args:
+            background: Run as an asyncio task and return immediately. False waits until stop().
+            history: Replay recent console lines first.
+            reconnect: Reconnect automatically (with backoff) if the connection drops.
+        '''
+        if self.running:
+            return self
+        await self.connect()
+        self.running = True
+        if background:
+            self.task = asyncio.create_task(self._loop(history, reconnect))
+        else:
+            await self._loop(history, reconnect)
+        return self
+
+    async def _loop(self, history, reconnect):
+        delay = 1
+        while self.running:
+            try:
+                await self.connect()
+                delay = 1
+                if history:
+                    await self.requestLogs()
+                    history = False
+                async for event in self.events():
+                    await self._dispatch(event)
+            except CalagoAPIError as e:
+                logger.warning('console of %s disconnected: %s', self.server.name, e)
+            if not self.running or not reconnect:
+                break
+            await asyncio.sleep(delay)
+            delay = min(delay * 2, 30)
+        self.running = False
+
+    async def stop(self) -> None:
+        '''Stops listen() and closes the connection.'''
+        self.running = False
+        await self.close()
+        task, self.task = self.task, None
+        if task and task is not asyncio.current_task():
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass

calagoapi/aio/panel.py

@@ -0,0 +1,176 @@
+import asyncio
+import functools
+import inspect
+
+from calagoapi.panel import Panel
+from calagoapi.console import Console
+from calagoapi.servers.generic import GenericServer
+from calagoapi.utils.model import Page
+from calagoapi.aio.console import AsyncConsole
+
+
+def wrap(value):
+    '''Wraps CalagoAPI objects returned by a call so their methods are awaitable too'''
+    if isinstance(value, Page):
+        return value.map(wrap)
+    if isinstance(value, list):
+        return [wrap(v) for v in value]
+    if isinstance(value, GenericServer):
+        return AsyncServer(value)
+    if isinstance(value, Console):
+        return AsyncConsole(value.server)
+    if type(value).__module__.startswith('calagoapi.') and not isinstance(value, BaseException):
+        return AsyncWrapper(value)
+    return value
+
+
+def unwrap(value):
+    '''Turns wrapped objects passed as arguments back into the regular objects'''
+    if isinstance(value, AsyncWrapper):
+        return value.target
+    if isinstance(value, list):
+        return [unwrap(v) for v in value]
+    if isinstance(value, tuple):
+        return tuple(unwrap(v) for v in value)
+    if isinstance(value, dict):
+        return {unwrap(k): unwrap(v) for k, v in value.items()}
+    return value
+
+
+class AsyncWrapper:
+    '''
+    The async version of any CalagoAPI object.
+
+    Every method of the wrapped object becomes a coroutine with the same name,
+    arguments and docstring. Calls run in a worker thread, so many can run at
+    once with asyncio.gather(). Plain attributes (like `server.name`) are read
+    directly. Objects returned by a method are wrapped as well.
+
+    Example:
+        backups = await server.backups.getBackups()
+        await backups[0].lock()
+        print(await backups[0].getName())    # getters are awaitable too
+        print(backups[0].data['name'])       # plain attributes are not
+    '''
+    def __init__(self, target):
+        object.__setattr__(self, 'target', target)
+
+    def __getattr__(self, name):
+        value = getattr(self.target, name)
+        if not inspect.ismethod(value):
+            return wrap(value)
+
+        @functools.wraps(value)
+        async def method(*args, **kwargs):
+            args = [unwrap(a) for a in args]
+            kwargs = {k: unwrap(v) for k, v in kwargs.items()}
+            return wrap(await asyncio.to_thread(value, *args, **kwargs))
+
+        return method
+
+    def __setattr__(self, name, value):
+        setattr(self.target, name, value)
+
+    def __getitem__(self, key):
+        return self.target[key]
+
+    def __contains__(self, key):
+        return key in self.target
+
+    def __eq__(self, other):
+        return self.target == unwrap(other)
+
+    def __hash__(self):
+        return hash(self.target)
+
+    def __repr__(self):
+        return f'<async {self.target!r}>'
+
+    def __str__(self):
+        return str(self.target)
+
+    def __dir__(self):
+        return sorted(set(dir(self.target)) | set(super().__dir__()))
+
+
+class AsyncServer(AsyncWrapper):
+    '''
+    The async version of GenericServer / MinecraftServer.
+
+    Every server method is awaitable, and `server.console` is an AsyncConsole.
+
+    Example:
+        server = await panel.servers.getServer('abc123')
+        await server.restart()
+        async for line in server.streamConsole():
+            print(line)
+    '''
+    def __init__(self, server):
+        super().__init__(server)
+        object.__setattr__(self, 'console', AsyncConsole(server))
+
+    async def streamConsole(self, history: bool = True, timeout: float = None):
+        '''
+        Yields console lines live, as they are printed.
+
+        Example:
+            async for line in server.streamConsole(history=False):
+                print(line)
+        '''
+        async with AsyncConsole(self.target) as console:
+            async for line in console.lines(history, timeout):
+                yield line
+
+    async def onConsoleLine(self, callback, history: bool = False) -> AsyncConsole:
+        '''
+        Calls `callback(line)` for every console line in a background task.
+        The callback may be a plain function or a coroutine.
+
+        Example:
+            await server.onConsoleLine(print)
+        '''
+        self.console.onConsoleLine(callback)
+        return await self.console.listen(history=history)
+
+
+class AsyncPanel(AsyncWrapper):
+    '''
+    The async version of Panel, for asyncio applications such as Discord bots.
+
+    Takes the same arguments as Panel. Every method of every object is
+    awaitable and keeps its name, so the documentation of the regular API
+    applies unchanged, just add `await`.
+
+    Requests run in worker threads on top of the regular client, so slow
+    calls never block the event loop and independent calls run concurrently.
+    The live console uses a native asyncio websocket.
+
+    Example:
+        import asyncio
+        from calagoapi import AsyncPanel
+
+        async def main():
+            async with AsyncPanel(url='https://panel.example.com', api_key='...') as panel:
+                servers = await panel.servers.getServers()
+                statuses = await asyncio.gather(*(server.getStatus() for server in servers))
+                for server, status in zip(servers, statuses):
+                    print(server.name, status)
+
+        asyncio.run(main())
+    '''
+    def __init__(self, url: str, api_key: str, name: str = None, timeout: int = 10, verify: bool = True,
+                 max_retries: int = 3):
+        super().__init__(Panel(url, api_key, name, timeout, verify, max_retries))
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *exc):
+        await self.close()
+
+    async def close(self) -> None:
+        '''Closes open consoles and the pooled HTTP connections.'''
+        for console in list(self.target.consoles):
+            if inspect.iscoroutinefunction(console.close):
+                await console.close()
+        await asyncio.to_thread(self.target.close)

calagoapi/api/__init__.py

@@ -0,0 +1,63 @@
+from .client import Client
+from .servers import ServersAPI
+from .files import FilesAPI
+from .backups import BackupsAPI
+from .databases import DatabasesAPI
+from .schedules import SchedulesAPI
+from .network import NetworkAPI
+from .users import UsersAPI
+from .attachments import AttachmentsAPI
+from .versions import VersionsAPI
+from .account import AccountAPI
+from .auth import AuthAPI
+from .public import PublicAPI
+from .admin import AdminAPI, ResourceAPI
+
+
+class API:
+    '''
+    Bundle of every internal API module, available as `panel.api`.
+
+    These modules are the only place CalagoAPI talks HTTP. You normally
+    never need them, but they are handy for calls the high-level objects
+    do not wrap yet.
+
+    Example:
+        panel.api.servers.resources(server_id)
+        panel.api.client.get('/api/client/permissions')
+    '''
+    def __init__(self, client: Client):
+        self.client = client
+        self.servers = ServersAPI(client)
+        self.files = FilesAPI(client)
+        self.backups = BackupsAPI(client)
+        self.databases = DatabasesAPI(client)
+        self.schedules = SchedulesAPI(client)
+        self.network = NetworkAPI(client)
+        self.users = UsersAPI(client)
+        self.attachments = AttachmentsAPI(client)
+        self.versions = VersionsAPI(client)
+        self.account = AccountAPI(client)
+        self.auth = AuthAPI(client)
+        self.public = PublicAPI(client)
+        self.admin = AdminAPI(client)
+
+
+__all__ = [
+    'API',
+    'Client',
+    'ServersAPI',
+    'FilesAPI',
+    'BackupsAPI',
+    'DatabasesAPI',
+    'SchedulesAPI',
+    'NetworkAPI',
+    'UsersAPI',
+    'AttachmentsAPI',
+    'VersionsAPI',
+    'AccountAPI',
+    'AuthAPI',
+    'PublicAPI',
+    'AdminAPI',
+    'ResourceAPI',
+]