meerschaum 2.2.7__py3-none-any.whl → 2.3.0.dev3__py3-none-any.whl

meerschaum/api/routes/_actions.py

@@ -7,65 +7,143 @@ Execute Meerschaum Actions via the API
 """
 
 from __future__ import annotations
-from meerschaum.utils.typing import SuccessTuple, Union
+import asyncio
+import traceback
+import shlex
+from functools import partial
+from datetime import datetime, timezone
 
+from fastapi import WebSocket, WebSocketDisconnect
+
+from meerschaum.utils.misc import generate_password
+from meerschaum.utils.jobs import Job
+from meerschaum.utils.warnings import warn
+from meerschaum.utils.typing import SuccessTuple, Union, List, Dict
 from meerschaum.api import (
     fastapi, app, endpoints, get_api_connector, debug, manager, private, no_auth
 )
 from meerschaum.actions import actions
 import meerschaum.core
+from meerschaum.config import get_config
+from meerschaum._internal.arguments._parse_arguments import parse_dict_to_sysargs, parse_arguments
+
 actions_endpoint = endpoints['actions']
 
+def is_user_allowed_to_execute(user) -> SuccessTuple:
+    if user is None:
+        return False, "Could not load user."
+
+    if user.type == 'admin':
+        return True, "Success"
+
+    allow_non_admin = get_config(
+        'system', 'api', 'permissions', 'actions', 'non_admin', patch=True
+    )
+    if not allow_non_admin:
+        return False, (
+            "The administrator for this server has not allowed users to perform actions.\n\n"
+            + "Please contact the system administrator, or if you are running this server, "
+            + "open the configuration file with `edit config system` "
+            + "and search for 'permissions'. "
+            + "\nUnder the keys 'api:permissions:actions', "
+            + "you can allow non-admin users to perform actions."
+        )
+
+    return True, "Success"
+
+
 @app.get(actions_endpoint, tags=['Actions'])
 def get_actions(
-        curr_user = (
-            fastapi.Depends(manager) if private else None
-        ),
-    ) -> list:
+    curr_user = (
+        fastapi.Depends(manager) if private else None
+    ),
+) -> List[str]:
+    """
+    Return a list of the available actions.
+    """
     return list(actions)
 
-@app.post(actions_endpoint + "/{action}", tags=['Actions'])
-def do_action(
-        action: str,
-        keywords: dict = fastapi.Body(...),
-        curr_user = (
-            fastapi.Depends(manager) if not no_auth else None
-        ),
-    ) -> SuccessTuple:
+
+async def notify_client(client, content: str):
+    """
+    Send a line of text to a client.
     """
-    Perform a Meerschaum action (if permissions allow it).
+    try:
+        await client.send_text(content)
+    except WebSocketDisconnect:
+        pass
 
-    Parameters
-    ----------
-    action: str :
-        The action to perform.
-        
-    keywords: dict :
-        The keywords dictionary to pass to the action.
+_temp_jobs = {}
+@app.websocket(actions_endpoint + '/ws')
+async def do_action_websocket(websocket: WebSocket):
+    """
+    Execute an action and stream the output to the client.
+    """
+    await websocket.accept()
 
-    Returns
-    -------
-    A `SuccessTuple` of success, message.
+    stop_event = asyncio.Event()
 
-    """
-    if curr_user is not None and curr_user.type != 'admin':
-        from meerschaum.config import get_config
-        allow_non_admin = get_config(
-            'system', 'api', 'permissions', 'actions', 'non_admin', patch=True
-        )
-        if not allow_non_admin:
-            return False, (
-                "The administrator for this server has not allowed users to perform actions.\n\n"
-                + "Please contact the system administrator, or if you are running this server, "
-                + "open the configuration file with `edit config system` "
-                + "and search for 'permissions'. "
-                + "\nUnder the keys 'api:permissions:actions', "
-                + "you can allow non-admin users to perform actions."
+    async def monitor_logs(job):
+        success, msg = job.start()
+        await job.monitor_logs_async(
+            partial(notify_client, websocket),
+            stop_event=stop_event,
+            stop_on_exit=True,
         )
 
-    if action not in actions:
-        return False, f"Invalid action '{action}'."
-    keywords['mrsm_instance'] = keywords.get('mrsm_instance', str(get_api_connector()))
-    _debug = keywords.get('debug', debug)
-    keywords.pop('debug', None)
-    return actions[action](debug=_debug, **keywords)
+    job = None
+    try:
+        token = await websocket.receive_text()
+        user = await manager.get_current_user(token) if not no_auth else None
+        if user is None and not no_auth:
+            raise fastapi.HTTPException(
+                status_code=401,
+                detail="Invalid credentials.",
+            )
+
+        auth_success, auth_msg = is_user_allowed_to_execute(user)
+        auth_payload = {
+            'is_authenticated': auth_success,
+            'timestamp': datetime.now(timezone.utc).isoformat(),
+        }
+        await websocket.send_json(auth_payload)
+        if not auth_success:
+            await websocket.close()
+
+        sysargs = await websocket.receive_json()
+        kwargs = parse_arguments(sysargs)
+        _ = kwargs.pop('executor_keys', None)
+        _ = kwargs.pop('shell', None)
+        sysargs = parse_dict_to_sysargs(kwargs)
+
+        job_name = '.' + generate_password(12)
+        job = Job(
+            job_name,
+            sysargs,
+            _properties={
+                'logs': {
+                    'write_timestamps': False,
+                },
+            },
+        )
+        _temp_jobs[job_name] = job
+        monitor_task = asyncio.create_task(monitor_logs(job))
+        await monitor_task
+        try:
+            await websocket.close()
+        except RuntimeError:
+            pass
+    except fastapi.HTTPException:
+        await websocket.send_text("Invalid credentials.")
+        await websocket.close()
+    except WebSocketDisconnect:
+        pass
+    except asyncio.CancelledError:
+        pass
+    except Exception:
+        warn(f"Error in logs websocket:\n{traceback.format_exc()}")
+    finally:
+        if job is not None:
+            job.delete()
+        _ = _temp_jobs.pop(job_name, None)
+        stop_event.set()

meerschaum/api/routes/_jobs.py

@@ -0,0 +1,371 @@
+#! /usr/bin/env python3
+# -*- coding: utf-8 -*-
+# vim:fenc=utf-8
+
+"""
+Manage jobs via the Meerschaum API.
+"""
+
+from __future__ import annotations
+
+import os
+import select
+import asyncio
+import traceback
+from datetime import datetime
+from collections import defaultdict
+from functools import partial
+
+from fastapi import WebSocket, WebSocketDisconnect
+
+from meerschaum.utils.typing import Dict, Any, SuccessTuple, List, Optional, Union
+from meerschaum.utils.jobs import get_jobs as _get_jobs, Job, StopMonitoringLogs
+from meerschaum.utils.warnings import warn
+
+from meerschaum.api import (
+    fastapi,
+    app,
+    endpoints,
+    manager,
+    debug,
+    no_auth,
+    private,
+)
+from meerschaum.config.static import STATIC_CONFIG
+
+JOBS_STDIN_MESSAGE: str = STATIC_CONFIG['api']['jobs']['stdin_message']
+JOBS_STOP_MESSAGE: str = STATIC_CONFIG['api']['jobs']['stop_message']
+
+
+@app.get(endpoints['jobs'], tags=['Jobs'])
+def get_jobs(
+    curr_user=(
+        fastapi.Depends(manager) if not no_auth else None
+    ),
+) -> Dict[str, Dict[str, Any]]:
+    """
+    Return metadata about the current jobs.
+    """
+    jobs = _get_jobs()
+    return {
+        name: {
+            'sysargs': job.sysargs,
+            'result': job.result,
+            'daemon': {
+                'status': job.daemon.status,
+                'pid': job.daemon.pid,
+                'properties': job.daemon.properties,
+            },
+        }
+        for name, job in jobs.items()
+    }
+
+
+@app.get(endpoints['jobs'] + '/{name}', tags=['Jobs'])
+def get_job(
+    name: str,
+    curr_user=(
+        fastapi.Depends(manager) if not no_auth else None
+    ),
+) -> Dict[str, Any]:
+    """
+    Return metadata for a single job.
+    """
+    job = Job(name)
+    if not job.exists():
+        raise fastapi.HTTPException(
+            status_code=404,
+            detail=f"{job} doesn't exist."
+        )
+
+    return {
+        'sysargs': job.sysargs,
+        'result': job.result,
+        'daemon': {
+            'status': job.daemon.status,
+            'pid': job.daemon.pid,
+            'properties': job.daemon.properties,
+        },
+    }
+
+
+@app.post(endpoints['jobs'] + '/{name}', tags=['Jobs'])
+def create_job(
+    name: str,
+    sysargs: List[str],
+    curr_user=(
+        fastapi.Depends(manager) if not no_auth else None
+    ),
+) -> SuccessTuple:
+    """
+    Create and start a new job.
+    """
+    job = Job(name, sysargs)
+    if job.exists():
+        raise fastapi.HTTPException(
+            status_code=409,
+            detail=f"{job} already exists."
+        )
+
+    return job.start()
+
+
+@app.delete(endpoints['jobs'] + '/{name}', tags=['Jobs'])
+def delete_job(
+    name: str,
+    curr_user=(
+        fastapi.Depends(manager) if not no_auth else None
+    ),
+) -> SuccessTuple:
+    """
+    Delete a job.
+    """
+    job = Job(name)
+    return job.delete()
+
+
+@app.get(endpoints['jobs'] + '/{name}/exists', tags=['Jobs'])
+def get_job_exists(
+    name: str,
+    curr_user=(
+        fastapi.Depends(manager) if not no_auth else None
+    ),
+) -> bool:
+    """
+    Return whether a job exists.
+    """
+    job = Job(name)
+    return job.exists()
+
+
+@app.get(endpoints['logs'] + '/{name}', tags=['Jobs'])
+def get_logs(
+    name: str,
+    curr_user=(
+        fastapi.Depends(manager) if not no_auth else None
+    ),
+) -> Union[str, None]:
+    """
+    Return a job's log text.
+    To stream log text, connect to the WebSocket endpoint `/logs/{name}/ws`.
+    """
+    job = Job(name)
+    if not job.exists():
+        raise fastapi.HTTPException(
+            status_code=404,
+            detail=f"{job} does not exist.",
+        )
+
+    return job.get_logs()
+
+
+@app.post(endpoints['jobs'] + '/{name}/start', tags=['Jobs'])
+def start_job(
+    name: str,
+    curr_user=(
+        fastapi.Depends(manager) if not no_auth else None
+    ),
+) -> SuccessTuple:
+    """
+    Start a job if stopped.
+    """
+    job = Job(name)
+    if not job.exists():
+        raise fastapi.HTTPException(
+            status_code=404,
+            detail=f"{job} does not exist."
+        )
+    return job.start()
+
+
+@app.post(endpoints['jobs'] + '/{name}/stop', tags=['Jobs'])
+def stop_job(
+    name: str,
+    curr_user=(
+        fastapi.Depends(manager) if not no_auth else None
+    ),
+) -> SuccessTuple:
+    """
+    Stop a job if running.
+    """
+    job = Job(name)
+    if not job.exists():
+        raise fastapi.HTTPException(
+            status_code=404,
+            detail=f"{job} does not exist."
+        )
+    return job.stop()
+
+
+@app.post(endpoints['jobs'] + '/{name}/pause', tags=['Jobs'])
+def pause_job(
+    name: str,
+    curr_user=(
+        fastapi.Depends(manager) if not no_auth else None
+    ),
+) -> SuccessTuple:
+    """
+    Pause a job if running.
+    """
+    job = Job(name)
+    if not job.exists():
+        raise fastapi.HTTPException(
+            status_code=404,
+            detail=f"{job} does not exist."
+        )
+    return job.pause()
+
+
+@app.get(endpoints['jobs'] + '/{name}/stop_time', tags=['Jobs'])
+def get_stop_time(
+    name: str,
+    curr_user=(
+        fastapi.Depends(manager) if not no_auth else None
+    ),
+) -> Union[datetime, None]:
+    """
+    Get the timestamp when the job was manually stopped.
+    """
+    job = Job(name)
+    return job.stop_time
+
+
+@app.get(endpoints['jobs'] + '/{name}/is_blocking_on_stdin', tags=['Jobs'])
+def get_is_blocking_on_stdin(
+    name: str,
+    curr_user=(
+        fastapi.Depends(manager) if not no_auth else None
+    ),
+) -> bool:
+    """
+    Return whether a job is blocking on stdin.
+    """
+    job = Job(name)
+    return job.is_blocking_on_stdin()
+
+
+_job_clients = defaultdict(lambda: [])
+_job_stop_events = defaultdict(lambda: asyncio.Event())
+async def notify_clients(name: str, websocket: WebSocket, content: str):
+    """
+    Write the given content to all connected clients.
+    """
+    async def _notify_client(client):
+        try:
+            await client.send_text(content)
+        except WebSocketDisconnect:
+            if client in _job_clients[name]:
+                _job_clients[name].remove(client)
+        except Exception:
+            pass
+
+    await _notify_client(websocket)
+
+
+async def get_input_from_clients(name: str, websocket: WebSocket) -> str:
+    """
+    When a job is blocking on input, return input from the first client which provides it.
+    """
+    if not _job_clients[name]:
+        return ''
+
+    async def _read_client(client):
+        try:
+            await client.send_text(JOBS_STDIN_MESSAGE)
+            data = await client.receive_text()
+        except WebSocketDisconnect:
+            if client in _job_clients[name]:
+                _job_clients[name].remove(client)
+        except Exception:
+            pass
+        return data
+
+    read_tasks = [
+        asyncio.create_task(_read_client(client))
+        for client in _job_clients[name]
+    ]
+    done, pending = await asyncio.wait(read_tasks, return_when=asyncio.FIRST_COMPLETED)
+    for task in pending:
+        task.cancel()
+    for task in done:
+        return task.result()
+
+
+async def send_stop_message(name: str, client: WebSocket, result: SuccessTuple):
+    """
+    Send a stop message to clients when the job stops.
+    """
+    try:
+        await client.send_text(JOBS_STOP_MESSAGE)
+        await client.send_json(result)
+    except WebSocketDisconnect:
+        _job_stop_events[name].set()
+        if client in _job_clients[name]:
+            _job_clients[name].remove(client)
+    except RuntimeError:
+        pass
+    except Exception:
+        warn(traceback.format_exc())
+
+
+@app.websocket(endpoints['logs'] + '/{name}/ws')
+async def logs_websocket(name: str, websocket: WebSocket):
+    """
+    Stream logs from a job over a websocket.
+    """
+    await websocket.accept()
+    job = Job(name)
+    _job_clients[name].append(websocket)
+
+    async def monitor_logs():
+        try:
+            callback_function = partial(
+                notify_clients,
+                name,
+                websocket,
+            )
+            input_callback_function = partial(
+                get_input_from_clients,
+                name,
+                websocket,
+            )
+            stop_callback_function = partial(
+                send_stop_message,
+                name,
+                websocket,
+            )
+            await job.monitor_logs_async(
+                callback_function=callback_function,
+                input_callback_function=input_callback_function,
+                stop_callback_function=stop_callback_function,
+                stop_event=_job_stop_events[name],
+                stop_on_exit=True,
+                accept_input=True,
+            )
+        except Exception:
+            warn(traceback.format_exc())
+
+    try:
+        token = await websocket.receive_text()
+        user = await manager.get_current_user(token) if not no_auth else None
+        if user is None and not no_auth:
+            raise fastapi.HTTPException(
+                status_code=401,
+                detail="Invalid credentials.",
+            )
+        monitor_task = asyncio.create_task(monitor_logs())
+        await monitor_task
+    except fastapi.HTTPException:
+        await websocket.send_text("Invalid credentials.")
+        await websocket.close()
+    except WebSocketDisconnect:
+        _job_stop_events[name].set()
+        monitor_task.cancel()
+    except asyncio.CancelledError:
+        pass
+    except Exception:
+        warn(f"Error in logs websocket:\n{traceback.format_exc()}")
+    finally:
+        if websocket in _job_clients[name]:
+            _job_clients[name].remove(websocket)
+        _job_stop_events[name].clear()

meerschaum/api/routes/_pipes.py

@@ -201,13 +201,13 @@ async def fetch_pipes_keys(
 
 @app.get(pipes_endpoint, tags=['Pipes'])
 async def get_pipes(
-        connector_keys : str = "",
-        metric_keys : str = "",
-        location_keys : str = "",
-        curr_user = (
+        connector_keys: str = "",
+        metric_keys: str = "",
+        location_keys: str = "",
+        curr_user=(
             fastapi.Depends(manager) if not no_auth else None
         ),
-        debug : bool = False
+        debug: bool = False,
     ) -> Dict[str, Any]:
     """
     Get all registered Pipes with metadata, excluding parameters.

meerschaum/config/_default.py

@@ -16,6 +16,7 @@ default_meerschaum_config = {
     'api_instance': 'MRSM{meerschaum:instance}',
     'web_instance': 'MRSM{meerschaum:instance}',
     'default_repository': 'api:mrsm',
+    'default_executor': 'local',
     'connectors': {
         'sql': {
             'default': {},

meerschaum/config/_paths.py

@@ -180,6 +180,7 @@ paths = {
     'DAEMON_RESOURCES_PATH'          : ('{ROOT_DIR_PATH}', 'jobs'),
     'LOGS_RESOURCES_PATH'            : ('{ROOT_DIR_PATH}', 'logs'),
     'DAEMON_ERROR_LOG_PATH'          : ('{ROOT_DIR_PATH}', 'daemon_errors.log'),
+    'CHECK_JOBS_LOCK_PATH'           : ('{INTERNAL_RESOURCES_PATH}', 'check-jobs.lock'),
 }
 
 def set_root(root: Union[Path, str]):

meerschaum/config/_shell.py

@@ -76,6 +76,11 @@ default_shell_config = {
                 'magenta',
             ],
         },
+        'executor'       : {
+            'rich'       : {
+                'style'  : 'yellow',
+            },
+        },
         'username'       : {
             'rich'       : {
                 'style'  : 'white',
@@ -112,8 +117,8 @@ default_shell_config = {
     'ascii'              : {
         'intro'          : r"""       ___  ___  __   __   __
  |\/| |__  |__  |__) /__` /  ` |__|  /\  |  |  |\/|
- |  | |___ |___ |  \ .__/ \__, |  | /~~\ \__/  |  |\n""",
-        'prompt'         : '\n [ {username}@{instance} ] > ',
+ |  | |___ |___ |  \ .__/ \__, |  | /~~\ \__/  |  |""" + '\n',
+        'prompt'         : '\n [ {username}@{instance} | {executor_keys} ] > ',
         'ruler'          : '-',
         'close_message'  : 'Thank you for using Meerschaum!',
         'doc_header'     : 'Meerschaum actions (`help <action>` for usage):',
@@ -124,7 +129,7 @@ default_shell_config = {
         'intro'          : """
  █▄ ▄█ ██▀ ██▀ █▀▄ ▄▀▀ ▄▀▀ █▄█ ▄▀▄ █ █ █▄ ▄█
  █ ▀ █ █▄▄ █▄▄ █▀▄ ▄██ ▀▄▄ █ █ █▀█ ▀▄█ █ ▀ █\n""",
-        'prompt'         : '\n [ {username}@{instance} ] ➤ ',
+        'prompt'         : '\n [ {username}@{instance} | {executor_keys} ] ➤ ',
         'ruler'          : '─',
         'close_message'  : ' MRSM{formatting:emoji:hand} Thank you for using Meerschaum! ',
         'doc_header'     : 'Meerschaum actions (`help <action>` for usage):',

meerschaum/config/_version.py

@@ -2,4 +2,4 @@
 Specify the Meerschaum release version.
 """
 
-__version__ = "2.2.7"
+__version__ = "2.3.0.dev3"

meerschaum/config/static/__init__.py

@@ -23,6 +23,8 @@ STATIC_CONFIG: Dict[str, Any] = {
             'pipes': '/pipes',
             'metadata': '/metadata',
             'actions': '/actions',
+            'jobs': '/jobs',
+            'logs': '/logs',
             'users': '/users',
             'login': '/login',
             'connectors': '/connectors',
@@ -40,6 +42,11 @@ STATIC_CONFIG: Dict[str, Any] = {
         },
         'webterm_job_name': '_webterm',
         'default_timeout': 600,
+        'jobs': {
+            'stdin_message': 'MRSM_STDIN',
+            'stop_message': 'MRSM_STOP',
+            'metadata_cache_seconds': 5,
+        },
     },
     'sql': {
         'internal_schema': '_mrsm_internal',
@@ -129,6 +136,9 @@ STATIC_CONFIG: Dict[str, Any] = {
         },
         'exists_timeout_seconds': 5.0,
     },
+    'jobs': {
+        'check_restart_seconds': 1.0,
+    },
     'setup': {
         'name': 'meerschaum',
         'formal_name': 'Meerschaum',