orcheems 0.1.0__py3-none-any.whl

orcheems/__init__.py

@@ -0,0 +1,22 @@
+from .operator import Orcheemstrator
+from .task.base import BaseTask
+from .task.decorators import task_registration
+from .login.schema import Credential, LoginResult
+from .login.base import BaseLoginService, cookie_incomplete_handler
+from .login.register import SiteLoginServiceRegister
+from .session.manager import SessionManager
+from .session.schema import SessionStatus, SessionResources
+
+__all__ = [
+    "Orcheemstrator",
+    "BaseTask",
+    "task_registration",
+    "Credential",
+    "LoginResult",
+    "BaseLoginService",
+    "cookie_incomplete_handler",
+    "SiteLoginServiceRegister",
+    "SessionManager",
+    "SessionStatus",
+    "SessionResources",
+]

orcheems/browser.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+import os
+from dotenv import load_dotenv
+from playwright.async_api import async_playwright, Browser, BrowserContext, Playwright
+from typing import Any, Optional, Set
+
+from .config import BROWSER
+
+load_dotenv()
+
+
+class BrowserManager:
+    """ 
+    Managing the Playwright browser lifecycle.
+    
+    Design Principles:
+        - Browser can be shared within a worker/process to save resources.
+        - BrowserContext is NOT shared between users/tasks/sessiones.
+        - Pages are NOT shared between users/tasks/sessions.
+        - A new context should be created using `new_context()` each time a task runs.
+        - If the old session needs to be loaded, pass `storage_state`.
+        - After the task is complete, save the storage_state if necessary and close the context.
+        
+    Recommendations:
+        BrowserManager
+                └── Browser singleton for worker
+                        ├── BrowserContext separated for task A
+                        ├── BrowserContext separated for task B
+                        └── BrowserContext separated for task C
+    """
+    
+    def __init__(self, max_concurrent_contexts: int = 50):
+        self._browser_cfg: dict[str, Any] = BROWSER
+        
+        # Playwright runtime
+        # Only start 1 time on BrowserManager lifecycle
+        self._playwright: Optional[Playwright] = None
+        
+        # Browser Instance
+        self._browser: Optional[Browser] = None
+        
+        # track active contexts for cleanup
+        self._contexts: Set[BrowserContext] = set()
+        self._max_contexts = max_concurrent_contexts
+        
+    @property
+    def is_dev_env(self) -> bool:
+        return os.getenv("APP_ENV", "DEV") == "DEV"
+        
+    @property
+    def is_started(self):
+        """ 
+        Check if Instance is already started or not.
+        """
+        return self._browser is not None and self._browser.is_connected()
+    
+    @property
+    def browser(self) -> Browser:
+        """ 
+        return current browser
+        
+        Only property, no setter, to ensure the lifecycle is managed by BrowserManager.
+        """
+        
+        if not self._browser or not self._browser.is_connected():
+            raise RuntimeError(
+                "Browser has not been started. Call `await browser_manager.start()` first."
+            )
+            
+        return self._browser
+    
+    async def start(self):
+        """ 
+        Start Playwright and launch the browser.
+        
+        If browser is already started, do nothing. Avoid calling start() multiple times.
+        """
+        if self.is_started:
+            return
+        
+        try:
+            if self._playwright is None:
+                self._playwright = await async_playwright().start()
+                
+            self._browser = await self._launch_browser()
+        except Exception as e:
+            raise RuntimeError(f"Failed to start browser: {e}") from e
+        
+    async def close(self):
+        """ 
+        Close browser and stop Playwright runtime.
+        
+        Should be called when shutdown worker/app.
+        Not necessary to call after each task, as browser can be reused.
+        """
+        # Close all active contexts first
+        for context in list(self._contexts):
+            await self.close_context(context)
+        
+        self._contexts.clear()
+        
+        # Then close browser
+        if self._browser is not None:
+            try:
+                await self._browser.close()
+            except Exception as e:
+                print(f"Warning: Error closing browser: {e}")
+            finally:
+                self._browser = None
+            
+        # Finally stop playwright
+        if self._playwright is not None:
+            try:
+                await self._playwright.stop()
+            except Exception as e:
+                print(f"Warning: Error stopping playwright: {e}")
+            finally:
+                self._playwright = None
+            
+    async def __aenter__(self):
+        """ 
+        Allow using:
+        
+            async with BrowserManager() as browser_manager:
+                ...
+                
+        When entering the block -> start the browser.
+        """
+        await self.start()
+        return self
+    
+    async def __aexit__(self, *args: object):
+        """ 
+        When exiting the block -> close the browser.
+        """
+        await self.close()
+        
+    async def _launch_browser(self) -> Browser:
+        """ 
+        Launch Chromium browser.
+        
+        Note:
+            - Shared worker/process
+            - Not shared cookie/session 
+            - Each session will create/use a BrowserContext, which is separated from each other.
+        """
+        if self._playwright is None:
+            raise RuntimeError("Playwright is not started. Call `await browser_manager.start()` first.")
+        
+        launch_args = self._browser_cfg.get("launch_args", [])
+        
+        # If HEADLESS is set in config, use it.
+        # If not, DEV will show browser (headless=False), other environments run headless.
+        headless = self._browser_cfg.get("HEADLESS")
+        if headless is None:
+            headless = not self.is_dev_env
+        
+        try:
+            return await self._playwright.chromium.launch(
+                headless=headless,
+                args=launch_args,
+            )
+        except Exception as e:
+            raise RuntimeError(f"Failed to launch browser: {e}") from e
+        
+    async def new_context(self, **kwargs: Any) -> BrowserContext:
+        """ 
+        Create a new BrowserContext.
+
+        This is the most important point for session isolation.
+
+        Each new context will have its own environment:
+        - its own cookie
+        - its own localStorage
+        - its own sessionStorage
+        - its own permissions
+        - its own context-specific cache
+        - its own pages
+
+        If you want to load a saved session, pass:
+
+            context = await browser_manager.new_context(
+                storage_state="sessions/vnpt/user_001.json"
+            )
+
+        Do not share a context between multiple tasks/users.
+        """
+        if not self.is_started:
+            await self.start()
+        
+        # Check concurrency limit
+        if len(self._contexts) >= self._max_contexts:
+            raise RuntimeError(
+                f"Too many concurrent contexts: {len(self._contexts)}/{self._max_contexts}"
+            )
+        
+        # Default params for browser context
+        defaults: dict[str, Any] = {
+            "viewport": {"width": 1280, "height": 800},
+            "ignore_https_errors": True,
+            "accept_downloads": True,
+        }
+        
+        user_agent = self._browser_cfg.get("USER_AGENT")
+        if user_agent:
+            defaults["user_agent"] = user_agent
+            
+        context_options = {**defaults, **kwargs}
+        
+        try:
+            context = await self.browser.new_context(**context_options)
+            self._contexts.add(context)
+            return context
+        except Exception as e:
+            raise RuntimeError(f"Failed to create new context: {e}") from e
+    
+    async def close_context(self, context: BrowserContext):
+        """ 
+        Close a specific BrowserContext and remove it from tracking.
+        
+        Should be called immediately after a task/session is complete 
+        to free up concurrent slots and memory.
+        """
+        
+        if not context:
+            return
+        
+        try:
+            await context.close()
+        except Exception as e:
+            print(f"Warning: Error closing context: {e}")
+        finally:
+            self._contexts.discard(context)

orcheems/config.py

@@ -0,0 +1,13 @@
+# App enviroment to run with browser or s.t else
+APP_ENV = "PROD"
+
+BROWSER = {
+    "USER_AGENT": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+    "LAUNCH_ARGS": [
+        "--no-sandbox",
+        "--disable-setuid-sandbox",
+        "--disable-dev-shm-usage",
+        "--disable-blink-features=AutomationControlled",
+        "--disable-gpu",
+    ]   
+}

orcheems/events.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class SseEvent:
+    type: str
+    data: Any = None
+
+    def encode(self) -> str:
+        payload = json.dumps({"type": self.type, "data": self.data}, ensure_ascii=False)
+        return f"data: {payload}\n\n"

orcheems/log.py

@@ -0,0 +1,234 @@
+"""
+Colored logging cho everyflow-automation.
+Không cần thư viện ngoài — dùng ANSI escape codes thuần.
+
+Usage:
+    # main.py hoặc bất kỳ entry point nào
+    from core.logging_config import setup_logging
+
+    setup_logging()           # mặc định: INFO, màu bật nếu terminal hỗ trợ
+    setup_logging(level="DEBUG")
+    setup_logging(level="DEBUG", force_color=True)   # force màu dù pipe/redirect
+    setup_logging(json=True)                          # JSON mode cho production/k8s
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from datetime import datetime, timezone
+from typing import Literal, Optional
+
+
+# ──────────────────────────────────────────────
+# ANSI color codes
+# ──────────────────────────────────────────────
+class _C:
+    RESET  = "\033[0m"
+    BOLD   = "\033[1m"
+    DIM    = "\033[2m"
+
+    # text colors
+    WHITE  = "\033[97m"
+    GRAY   = "\033[90m"
+
+    BLUE   = "\033[34m"
+    CYAN   = "\033[36m"
+    GREEN  = "\033[32m"
+    YELLOW = "\033[33m"
+    RED    = "\033[31m"
+    PURPLE = "\033[35m"
+
+    # bright variants
+    B_GREEN  = "\033[92m"
+    B_YELLOW = "\033[93m"
+    B_RED    = "\033[91m"
+    B_CYAN   = "\033[96m"
+    B_BLUE   = "\033[94m"
+
+
+_LEVEL_STYLE: dict[int, tuple[str, str]] = {
+    logging.DEBUG:    (_C.PURPLE,   "DEBUG  "),
+    logging.INFO:     (_C.B_GREEN,  "INFO   "),
+    logging.WARNING:  (_C.B_YELLOW, "WARNING"),
+    logging.ERROR:    (_C.B_RED,    "ERROR  "),
+    logging.CRITICAL: (_C.B_RED,    "CRITICAL"),
+}
+
+
+# ──────────────────────────────────────────────
+# Colored formatter
+# ──────────────────────────────────────────────
+class ColoredFormatter(logging.Formatter):
+    """
+    Format:
+        10:42 24/06/26 │ INFO    │ module_name          │ message  key=value
+    """
+
+    MOD_WIDTH  = 22
+    SEP        = f"{_C.GRAY} │ {_C.RESET}"
+
+    def __init__(self, use_color: bool = True) -> None:
+        super().__init__()
+        self.use_color = use_color
+
+    def _c(self, code: str, text: str) -> str:
+        if not self.use_color:
+            return text
+        return f"{code}{text}{_C.RESET}"
+
+    def format(self, record: logging.LogRecord) -> str:
+        ts = datetime.now(timezone.utc).strftime("%H:%M %d/%m/%y")
+        ts_str = self._c(_C.BLUE, ts)
+
+        level_color, level_label = _LEVEL_STYLE.get(
+            record.levelno, (_C.WHITE, record.levelname[:7].ljust(7))
+        )
+        level_str = self._c(level_color, level_label)
+
+        # module name: dùng tên logger, truncate + pad
+        mod_raw = record.name.split(".")[-1]           # lấy phần cuối  e.g. "manager"
+        mod_padded = mod_raw[:self.MOD_WIDTH].ljust(self.MOD_WIDTH)
+        mod_str = self._c(_C.CYAN, mod_padded)
+
+        # message
+        msg = record.getMessage()
+        msg_str = self._c(_C.WHITE, msg)
+
+        # extra key=value pairs được attach qua logger.info("...", extra={...})
+        # hoặc qua LogRecord.xxx attrs đặt thủ công
+        extras = self._format_extras(record)
+
+        sep = self.SEP
+        line = f"{ts_str}{sep}{level_str}{sep}{mod_str}{sep}{msg_str}{extras}"
+
+        # exception traceback (nếu có)
+        if record.exc_info:
+            exc = self.formatException(record.exc_info)
+            line = f"{line}\n{self._c(_C.GRAY, exc)}"
+
+        return line
+
+    def _format_extras(self, record: logging.LogRecord) -> str:
+        """
+        Thu thập các attr không thuộc LogRecord chuẩn để in dạng  key=value.
+
+        Cách dùng:
+            logger.info("session locked", extra={"credential_id": "abc-123", "seconds": 3})
+        """
+        SKIP = {
+            "name", "msg", "args", "levelname", "levelno", "pathname",
+            "filename", "module", "exc_info", "exc_text", "stack_info",
+            "lineno", "funcName", "created", "msecs", "relativeCreated",
+            "thread", "threadName", "processName", "process", "message",
+            "taskName",
+        }
+        parts: list[str] = []
+        for k, v in record.__dict__.items():
+            if k.startswith("_") or k in SKIP:
+                continue
+            key_str   = self._c(_C.B_CYAN,   k)
+            if isinstance(v, str):
+                val_str = self._c(_C.B_GREEN, f"'{v}'")
+            elif isinstance(v, (int, float)):
+                val_str = self._c(_C.YELLOW, str(v))
+            else:
+                val_str = self._c(_C.PURPLE, repr(v))
+            parts.append(f"{key_str}={val_str}")
+
+        return ("  " + "  ".join(parts)) if parts else ""
+
+
+# ──────────────────────────────────────────────
+# JSON formatter (production / k8s / Graylog)
+# ──────────────────────────────────────────────
+class JsonFormatter(logging.Formatter):
+    """Structured JSON — 1 dòng/record, dễ ingest vào Graylog / Loki."""
+
+    SKIP = {
+        "name", "msg", "args", "levelname", "levelno", "pathname",
+        "filename", "module", "exc_info", "exc_text", "stack_info",
+        "lineno", "funcName", "created", "msecs", "relativeCreated",
+        "thread", "threadName", "processName", "process", "message",
+        "taskName",
+    }
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict = {
+            "ts":      datetime.now(timezone.utc).isoformat(),
+            "level":   record.levelname,
+            "logger":  record.name,
+            "message": record.getMessage(),
+        }
+        for k, v in record.__dict__.items():
+            if not k.startswith("_") and k not in self.SKIP:
+                payload[k] = v
+        if record.exc_info:
+            payload["exc"] = self.formatException(record.exc_info)
+        return json.dumps(payload, ensure_ascii=False)
+
+
+# ──────────────────────────────────────────────
+# Setup helper
+# ──────────────────────────────────────────────
+def _supports_color() -> bool:
+    """True nếu stdout là terminal thật và không bị force-disable."""
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("FORCE_COLOR"):
+        return True
+    return hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+
+
+def setup_logging(
+    level: str = "INFO",
+    json: bool = False,
+    force_color: Optional[bool] = None,
+    loggers: Optional[list[str]] = None,
+) -> None:
+    """
+    Cấu hình root logger (và tuỳ chọn một số logger cụ thể).
+
+    Args:
+        level       : Log level — "DEBUG" | "INFO" | "WARNING" | "ERROR"
+        json        : True → dùng JsonFormatter (production/k8s)
+        force_color : None = auto-detect, True = bật, False = tắt
+        loggers     : Danh sách tên logger muốn set riêng level DEBUG,
+                      dù root logger đang ở INFO.
+                      Ví dụ: ["task.app_operator", "session.manager"]
+    
+    Usage:
+        # development
+        setup_logging(level="DEBUG")
+
+        # production / k8s
+        setup_logging(json=True)
+
+        # chỉ debug 2 module cụ thể
+        setup_logging(level="INFO", loggers=["session.manager", "task.base_task"])
+    """
+    use_color = force_color if force_color is not None else _supports_color()
+
+    if json:
+        formatter: logging.Formatter = JsonFormatter()
+    else:
+        formatter = ColoredFormatter(use_color=use_color)
+
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(formatter)
+
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.addHandler(handler)
+    root.setLevel(getattr(logging, level.upper(), logging.INFO))
+
+    # Tắt bớt noise từ thư viện bên ngoài
+    for noisy in ("httpx", "httpcore", "uvicorn.access", "playwright"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+
+    # Sub-logger override
+    if loggers:
+        for name in loggers:
+            logging.getLogger(name).setLevel(logging.DEBUG)

orcheems/login/__init__.py

@@ -0,0 +1,28 @@
+# from .register import SiteLoginServiceRegister
+
+# import importlib                                        
+# import pkgutil
+# from . import sites as sites_pkg
+
+# for _, module_name, _ in pkgutil.iter_modules(sites_pkg.__path__):
+#     importlib.import_module(f"login_service.sites.{module_name}")
+
+# __all__ = ["SiteLoginServiceRegister"]
+
+# from .schema import Credential, LoginResult
+
+from .register import SiteLoginServiceRegister
+from .schema import Credential, LoginResult
+from .base import BaseLoginService, cookie_incomplete_handler
+
+__all__ = [
+    "SiteLoginServiceRegister",
+    "Credential",
+    "LoginResult",
+    "BaseLoginService",
+    "cookie_incomplete_handler",
+]
+
+# Site implementations live in app/sites/ and are discovered by the
+# application at startup — not auto-imported here.
+# In main.py: import app.sites  (triggers @SiteLoginServiceRegister.register)