meerschaum 2.9.4__py3-none-any.whl → 3.0.0__py3-none-any.whl

meerschaum/core/Plugin/__init__.py

@@ -6,4 +6,4 @@
 Import the Plugin class.
 """
 
-from meerschaum.plugins import Plugin
+from meerschaum.core.Plugin._Plugin import Plugin

meerschaum/core/Token/_Token.py

@@ -0,0 +1,220 @@
+#! /usr/bin/env python3
+# vim:fenc=utf-8
+
+"""
+Define the properties of a long-lived access token.
+"""
+
+from __future__ import annotations
+
+import base64
+import uuid
+from random import randint
+from typing import Optional, Union, List, Tuple
+from datetime import datetime, timedelta, timezone
+
+import meerschaum as mrsm
+
+_PLACEHOLDER_EXPIRATION = datetime(2000, 1, 1)
+
+class Token:
+    """
+    Tokens (long lived access tokens) may be registered and revoked to provide easier authentication (e.g. IoT devices).
+    Tokens must be tied to a Meerschaum user account.
+    """
+
+    def __init__(
+        self,
+        label: Optional[str] = None,
+        creation: Optional[datetime] = None,
+        expiration: Optional[datetime] = _PLACEHOLDER_EXPIRATION,
+        instance: Optional[str] = None,
+        user: Optional[mrsm.core.User] = None,
+        user_id: Union[int, str, uuid.UUID, None] = None,
+        scopes: Optional[List[str]] = None,
+        is_valid: bool = True,
+        id: Optional[uuid.UUID] = None,
+        secret: Optional[str] = None,
+        secret_hash: Optional[str] = None,
+    ):
+        from meerschaum.utils.dtypes import coerce_timezone, round_time
+        from meerschaum.utils.daemon import get_new_daemon_name
+        from meerschaum._internal.static import STATIC_CONFIG
+        now = datetime.now(timezone.utc)
+        default_expiration_days = mrsm.get_config(
+            'api', 'tokens', 'default_expiration_days',
+        ) or 366
+        default_expiration = round_time(
+            now + timedelta(days=default_expiration_days),
+            timedelta(days=1),
+        )
+        if expiration == _PLACEHOLDER_EXPIRATION:
+            expiration = default_expiration
+        self.creation = coerce_timezone(creation) if creation is not None else None
+        self.expiration = coerce_timezone(expiration) if expiration is not None else None
+        self._instance_keys = str(instance) if instance is not None else None
+        self.label = label or get_new_daemon_name()
+        self._user = user
+        self._user_id = user_id
+        self.scopes = scopes or list(STATIC_CONFIG['tokens']['scopes'])
+        self.is_valid = is_valid
+        self.id = id
+        self.secret = secret
+        self.secret_hash = secret_hash
+
+    def generate_credentials(self) -> Tuple[uuid.UUID, str]:
+        """
+        Generate and return the client ID and secret values for this token.
+        """
+        if self.id and self.secret:
+            return self.id, self.secret
+
+        from meerschaum.utils.misc import generate_password
+        from meerschaum._internal.static import STATIC_CONFIG
+        min_len = STATIC_CONFIG['tokens']['minimum_length']
+        max_len = STATIC_CONFIG['tokens']['maximum_length']
+
+        secret_len = randint(min_len, max_len + 1)
+        self.secret = generate_password(secret_len)
+        self.id = uuid.uuid4()
+        return self.id, self.secret
+
+    def get_api_key(self) -> str:
+        """
+        Return the API key to be sent in the `Authorization` header.
+        """
+        return 'mrsm-key:' + base64.b64encode(f"{self.id}:{self.secret}".encode('utf-8')).decode('utf-8')
+
+    @property
+    def instance_connector(self) -> mrsm.connectors.InstanceConnector:
+        """
+        Return the instance connector to use for this token.
+        """
+        from meerschaum.connectors.parse import parse_instance_keys
+        return parse_instance_keys(self._instance_keys)
+
+    @property
+    def user(self) -> Union[mrsm.core.User, None]:
+        """
+        Return the `User` for this token.
+        """
+        if self._user is not None:
+            return self._user
+
+        if self._user_id is not None:
+            username = self.instance_connector.get_username(self._user_id)
+            if not username:
+                return None
+            _user = mrsm.core.User(
+                username,
+                user_id=self._user_id,
+                instance=str(self.instance_connector),
+            )
+            self._user = _user
+            return _user
+
+        return None
+
+    def register(self, debug: bool = False) -> mrsm.SuccessTuple:
+        """
+        Register the new token to the configured instance.
+        """
+        if self.user is None:
+            return False, "Cannot register a token without a user."
+
+        return self.instance_connector.register_token(self, debug=debug)
+
+    def edit(self, debug: bool = False) -> mrsm.SuccessTuple:
+        """
+        Edit some of the token's attributes (expiration, scopes).
+        """
+        return self.instance_connector.edit_token(self, debug=debug)
+
+    def invalidate(self, debug: bool = False) -> mrsm.SuccessTuple:
+        """
+        Set `is_valid` to False for this token.
+        """
+        self.is_valid = False
+        return self.instance_connector.invalidate_token(self, debug=debug)
+
+    def delete(self, debug: bool = False) -> mrsm.SuccessTuple:
+        """
+        Delete this token from the instance connector.
+        """
+        return self.instance_connector.delete_token(self, debug=debug)
+
+    def exists(self, debug: bool = False) -> bool:
+        """
+        Return `True` if a token's ID exists in the tokens pipe.
+        """
+        if not self.id:
+            return False
+        return self.instance_connector.token_exists(self.id, debug=debug)
+
+    def to_model(self, refresh: bool = False, debug: bool = False) -> 'TokenModel':
+        """
+        Export the current state to a `TokenModel`.
+        """
+        from meerschaum.models import TokenModel
+        in_memory_doc = {
+            'id': self.id,
+            'label': self.label,
+            'creation': self.creation,
+            'expiration': self.expiration,
+            'is_valid': self.is_valid,
+            'user_id': self._user_id,
+            'scopes': self.scopes,
+        }
+        if not refresh:
+            return TokenModel(**in_memory_doc)
+
+        if not self.id:
+            raise ValueError(f"ID is not set for {self}.")
+
+        token_model = self.instance_connector.get_token_model(self.id, debug=debug)
+        if token_model is None:
+            raise ValueError(f"{self} does not exist on instance '{self.instance_connector}'.")
+
+        return token_model
+
+    def get_scopes(self, refresh: bool = False, debug: bool = False) -> List[str]:
+        """
+        Return the scopes for this `Token`.
+        """
+        if not refresh:
+            return self.scopes
+
+        self.scopes = self.instance_connector.get_token_scopes(self, debug=debug)
+        return self.scopes
+
+    def get_expiration_status(self, debug: bool = False) -> bool:
+        """
+        Check the token's expiration against the current timestamp.
+        If it's expired, invalidate the token.
+
+        Returns
+        -------
+        A bool to indication whether the token has expired.
+        A value of `True` means the token is invalid,
+        and `False` indicates a valid token.
+        """
+        expiration = self.expiration
+        if expiration is None:
+            return False
+
+        now = datetime.now(timezone.utc)
+        is_expired = expiration <= now
+        if is_expired:
+            self.is_valid = False
+            invalidate_success, invalidate_msg = self.invalidate(debug=debug)
+            if not invalidate_success:
+                from meerschaum.utils.warnings import warn
+                warn(f"Failed to invalidate {self}:\n{invalidate_msg}")
+
+        return is_expired
+
+    def __str__(self):
+        return self.label
+
+    def __repr__(self):
+        return self.to_model(refresh=False).__repr__().replace('TokenModel(', 'Token(')

meerschaum/core/Token/__init__.py

@@ -0,0 +1,12 @@
+#! /usr/bin/env python3
+# vim:fenc=utf-8
+
+"""
+Define the components of long-lived access tokens.
+"""
+
+from meerschaum.core.Token._Token import Token
+
+__all__ = (
+    'Token',
+)

meerschaum/core/User/_User.py

@@ -7,14 +7,15 @@ User class definition
 """
 
 from __future__ import annotations
+
 import os
 import hashlib
 import hmac
+import uuid
 from binascii import b2a_base64, a2b_base64, Error as _BinAsciiError
 
 import meerschaum as mrsm
-from meerschaum.utils.typing import Optional, Dict, Any, Union
-from meerschaum.config.static import STATIC_CONFIG
+from meerschaum.utils.typing import Optional, Dict, Any, Union, List
 from meerschaum.utils.warnings import warn
 
 
@@ -40,7 +41,7 @@ def hash_password(
 
     rounds: Optional[int], default None
         If provided, use this number of rounds to generate the hash.
-        Defaults to 3,000,000.
+        Defaults to 1,000,000.
         
     Returns
     -------
@@ -48,6 +49,7 @@ def hash_password(
     See the `passlib` documentation on the string format:
     https://passlib.readthedocs.io/en/stable/lib/passlib.hash.pbkdf2_digest.html#format-algorithm
     """
+    from meerschaum._internal.static import STATIC_CONFIG
     hash_config = STATIC_CONFIG['users']['password_hash']
     if password is None:
         password = ''
@@ -64,7 +66,7 @@ def hash_password(
     ) 
     return (
         f"$pbkdf2-{hash_config['algorithm_name']}"
-        + f"${hash_config['pbkdf2_sha256__default_rounds']}"
+        + f"${rounds}"
         + '$' + ab64_encode(salt).decode('utf-8')
         + '$' + ab64_encode(pw_hash).decode('utf-8')
     )
@@ -89,16 +91,16 @@ def verify_password(
     -------
     A `bool` indicating whether `password` matches `password_hash`.
     """
+    from meerschaum._internal.static import STATIC_CONFIG
     if password is None or password_hash is None:
         return False
-    hash_config = STATIC_CONFIG['users']['password_hash']
     try:
         digest, rounds_str, encoded_salt, encoded_checksum = password_hash.split('$')[1:]
         algorithm_name = digest.split('-')[-1]
         salt = ab64_decode(encoded_salt)
         checksum = ab64_decode(encoded_checksum)
         rounds = int(rounds_str)
-    except Exception as e:
+    except Exception:
         warn(f"Failed to extract context from password hash '{password_hash}'. Is it corrupted?")
         return False
 
@@ -177,7 +179,7 @@ class User:
         type: Optional[str] = None,
         email: Optional[str] = None,
         attributes: Optional[Dict[str, Any]] = None,
-        user_id: Optional[int] = None,
+        user_id: Union[int, str, uuid.UUID, None] = None,
         instance: Optional[str] = None
     ):
         if password is None:
@@ -188,7 +190,7 @@ class User:
         self.type = type
         self._attributes = attributes
         self._user_id = user_id
-        self._instance_keys = str(instance)
+        self._instance_keys = str(instance) if instance is not None else None
 
     def __repr__(self):
         return str(self)
@@ -203,14 +205,14 @@ class User:
         return self._attributes
 
     @property
-    def instance_connector(self) -> 'mrsm.connectors.Connector':
+    def instance_connector(self) -> mrsm.connectors.InstanceConnector:
         from meerschaum.connectors.parse import parse_instance_keys
         if '_instance_connector' not in self.__dict__:
             self._instance_connector = parse_instance_keys(self._instance_keys)
         return self._instance_connector
 
     @property
-    def user_id(self) -> Union[int, str, None]:
+    def user_id(self) -> Union[int, str, uuid.UUID, None]:
         """NOTE: This causes recursion with the API,
               so don't try to get fancy with read-only attributes.
         """
@@ -231,3 +233,26 @@ class User:
 
         self._password_hash = hash_password(self.password)
         return self._password_hash
+
+    def get_attributes(self, refresh: bool = False, debug: bool = False) -> Dict[str, Any]:
+        """
+        Return the user's attributes.
+        """
+        if not refresh:
+            return self.attributes
+        self._attributes = self.instance_connector.get_user_attributes(self, debug=debug) or {}
+        return self._attributes
+
+    def get_scopes(self, refresh: bool = False, debug: bool = False) -> List[str]:
+        """
+        Return the scopes for this user.
+        """
+        from meerschaum._internal.static import STATIC_CONFIG
+        _attributes = self.get_attributes(refresh=refresh, debug=debug)
+        return _attributes.get('scopes', None) or list(STATIC_CONFIG['tokens']['scopes'])
+
+    def register(self, debug: bool = False, **kwargs: Any) -> mrsm.SuccessTuple:
+        """
+        Register a user to the instance connector.
+        """
+        return self.instance_connector.register_user(self, debug=debug, **kwargs)

meerschaum/core/User/__init__.py

@@ -9,7 +9,15 @@ Manager users' metadata via the User class
 from typing import Optional
 
 import meerschaum as mrsm
-from meerschaum.core.User._User import User
+from meerschaum.core.User._User import User, hash_password, verify_password
+
+
+__all__ = (
+    'User',
+    'hash_password',
+    'verify_password',
+    'is_user_allowed_to_execute',
+)
 
 
 def is_user_allowed_to_execute(

meerschaum/core/__init__.py

@@ -9,3 +9,4 @@ Import the core class definitions into the parent module.
 from meerschaum.core.Pipe import Pipe
 from meerschaum.core.Plugin import Plugin
 from meerschaum.core.User import User
+from meerschaum.core.Token import Token

meerschaum/jobs/_Executor.py

@@ -10,28 +10,72 @@ from __future__ import annotations
 from abc import abstractmethod
 
 from meerschaum.connectors import Connector
-from meerschaum.utils.typing import List, Dict, SuccessTuple, TYPE_CHECKING, Optional, Any
+from meerschaum.utils.typing import (
+    List, Dict, SuccessTuple, TYPE_CHECKING, Optional, Any, Union, Callable,
+)
 
 if TYPE_CHECKING:
     from meerschaum.jobs import Job
+    from datetime import datetime
 
 class Executor(Connector):
     """
     Define the methods for managing jobs.
     """
 
+    @abstractmethod
+    def get_job_names(self, debug: bool = False) -> List[str]:
+        """
+        Return a list of existing jobs, including hidden ones.
+        """
+
     @abstractmethod
     def get_job_exists(self, name: str, debug: bool = False) -> bool:
         """
         Return whether a job exists.
         """
-    
+
+    @abstractmethod
+    def get_jobs(self, debug: bool = False) -> Dict[str, Job]:
+        """
+        Return a dictionary of existing jobs.
+        """
+
+    @abstractmethod
+    def get_job_metadata(self, name: str, debug: bool = False) -> Dict[str, Any]:
+        """
+        Return a job's metadata.
+        """
+
+    @abstractmethod
+    def get_job_properties(self, name: str, debug: bool = False) -> Dict[str, Any]:
+        """
+        Return the underlying daemon's properties.
+        """
     @abstractmethod
-    def get_jobs(self) -> Dict[str, Job]:
+    def get_job_status(self, name: str, debug: bool = False) -> str:
         """
-        Return a dictionary of names -> Jobs.
+        Return the job's status.
         """
 
+    @abstractmethod
+    def get_job_began(self, name: str, debug: bool = False) -> Union[str, None]:
+        """
+        Return when a job began running.
+        """
+
+    @abstractmethod
+    def get_job_ended(self, name: str, debug: bool = False) -> Union[str, None]:
+        """
+        Return when a job stopped running.
+        """
+
+    @abstractmethod
+    def get_job_paused(self, name: str, debug: bool = False) -> Union[str, None]:
+        """
+        Return a job's `paused` timestamp, if it exists.
+        """
+    
     @abstractmethod
     def create_job(
         self,
@@ -73,3 +117,43 @@ class Executor(Connector):
         """
         Return a job's log output.
         """
+
+    @abstractmethod
+    def get_job_stop_time(self, name: str, debug: bool = False) -> Union[datetime, None]:
+        """
+        Return the job's manual stop time.
+        """
+
+    @abstractmethod
+    async def monitor_logs_async(
+        self,
+        name: str,
+        callback_function: Callable[[Any], Any],
+        input_callback_function: Callable[[], str],
+        stop_callback_function: Callable[[SuccessTuple], str],
+        stop_on_exit: bool = False,
+        strip_timestamps: bool = False,
+        accept_input: bool = True,
+        debug: bool = False,
+    ):
+        """
+        Monitor a job's log files and await a callback with the changes.
+        """
+
+    @abstractmethod
+    def monitor_logs(self, *args, **kwargs):
+        """
+        Monitor a job's log files.
+        """
+
+    @abstractmethod
+    def get_job_is_blocking_on_stdin(self, name: str, debug: bool = False) -> bool:
+        """
+        Return whether a job is blocking on stdin.
+        """
+
+    @abstractmethod
+    def get_job_prompt_kwargs(self, name: str, debug: bool = False) -> Dict[str, Any]:
+        """
+        Return the kwargs to the blocking prompt.
+        """