skeleton-framework 0.1.0__py3-none-any.whl

skeleton/infrastructure/gateway/src/service.py

@@ -0,0 +1,123 @@
+import asyncio
+
+from pathlib import Path
+from asyncio.subprocess import Process
+
+from skeleton.infrastructure.gateway.src.context import ServiceContext
+
+# actual runtime services!
+class Service:
+
+    def __init__(self, config: ServiceContext):
+        
+        self.config = config
+        self.proc: Process | None = None
+
+        self.watch_task: asyncio.Task | None = None
+
+        # avoid race conditions & multiple restarts
+        self.restart_lock = asyncio.Lock()
+
+    async def run(self) -> None:
+        await self.start()
+        self.watch_task = asyncio.create_task(self.watch_loop())
+
+    async def start(self) -> None:
+
+        print(
+            f"INFO:     Starting {self.config.name}"
+            f" at http://{self.config.network.host}:"
+            f"{self.config.network.port}"
+        )
+
+        self.proc = await asyncio.create_subprocess_exec(
+            self.config.process.exe, "-m", "uvicorn",
+            f"{self.config.process.module}:{self.config.name}",
+            "--host", f"{self.config.network.host}",
+            "--port", f"{self.config.network.port}",
+            cwd=self.config.process.cwd,
+        )
+
+    # This loop runs forever ...
+    async def watch_loop(self) -> None:
+
+        print(
+            f"INFO      {self.config.name}"
+            f" hot-module reload {self.config.watch.enabled}"
+        )
+
+        if not self.config.watch.enabled:
+            return
+        
+        # lazy import awatch!
+        from watchfiles import awatch # type: ignore
+        
+        try:
+            async for changes in awatch(self.config.watch.directory):
+                # check whether changes contains a file having extension
+                # that corresponds to any of the extensions in the config list!
+                if any(
+                    Path(path).suffix
+                    in self.config.watch.extensions
+                    for _, path in changes
+                ):
+                    await asyncio.sleep(0.25)
+                    await self.restart()
+
+        except asyncio.CancelledError:
+            raise
+
+    # proper cleanup needed!
+    async def stop(self) -> None:
+        # check: does subprocess exist? + still running? (return code None)
+        if self.proc is not None and self.proc.returncode is None:
+            print(
+                f"INFO:     Terminating "
+                f"{self.config.name} at "
+                f"{self.config.network.host} on "
+                f"{self.config.network.port}"
+            )
+            self.proc.terminate()
+            await self.proc.wait()
+
+    # context manager in restart() is equivalent but safer:
+    # 
+    #   await self.restart_lock.acquire()
+    # 
+    #   try:
+    #       await self.stop()
+    #       await self.start()
+    # 
+    #   finally:
+    #       self.restart_lock.release()
+    # 
+    #   # async with context manager is safer
+    async def restart(self) -> None:
+        # async mutex lock => prevent multiple restarts!
+        # ONLY ONE coroutine may enter this block at any instance!
+        async with self.restart_lock:
+            print(
+                f"INFO:     Restarting "
+                f"{self.config.name} at "
+                f"{self.config.network.host} on "
+                f"{self.config.network.port}"
+            )
+            await self.stop()
+            await self.start()
+
+    async def shutdown(self):
+
+        # cancel watcher tasks FIRST!
+        if self.watch_task:
+
+            self.watch_task.cancel()
+
+            try:
+                await self.watch_task
+            except asyncio.CancelledError:
+                pass
+
+        # THEN terminate subprocess!
+        await self.stop()
+        print("INFO:     Graceful shutdown complete!")
+        

skeleton/infrastructure/gateway/src/utils.py

@@ -0,0 +1,48 @@
+from pathlib import Path
+
+from skeleton.infrastructure.common.src.context import RuntimeContext
+
+def build_static_dir(context: RuntimeContext) -> Path:
+    
+    frontend = context.layout.frontend
+    lib = context.config.frontend["lib"]
+
+    build_dir = (
+        lib["src"]
+        if context.mode == "dev"
+        else lib["dist"]
+    )
+
+    return frontend/build_dir/lib["static"]
+
+def normalize_extensions(
+    ext: tuple[str, ...]
+) -> tuple[str, ...]:
+    
+    # store all normalized extensions!
+    normalized_ext: list[str] = []
+
+    for item in ext:
+
+        if not isinstance(item, str):
+            raise TypeError(f"Extension {item} must be a string")
+        
+        # remove any leading/trailing whitespace
+        item = item.strip()
+
+        # check that extension is not a path
+        if "/" in item or "\\" in item:
+            raise ValueError(f"Invalid extension {item}")
+        
+        # check that extension is a proper file type
+        if item == ".":
+            raise ValueError(f"'.' is not a valid extension/file type")
+            
+        # if the item does NOT start with . then pre-pend it!
+        if not item.startswith("."):
+            item = f".{item}"
+
+        # if all is OK!
+        normalized_ext.append(item)
+
+    return tuple(normalized_ext)

skeleton/infrastructure/gateway/src/validation.py

@@ -0,0 +1,89 @@
+from pathlib import Path
+
+from skeleton.infrastructure.gateway.src.config import ServiceConfig
+from skeleton.infrastructure.gateway.src.context import ServiceContext
+
+from skeleton.infrastructure.common.src.utils import (
+    check_file_exists,
+    module_to_path,
+)
+
+class ConfigValidationError(Exception):
+    pass
+
+def validate_service_configs(
+    services: list[ServiceConfig],
+) -> bool:
+
+    used_ports: set[int] = set()
+
+    for service in services:
+        validate_service_root(service.root)
+
+        validate_service_module(
+            service.process.module,
+            service.root,
+        )
+
+        validate_service_port(
+            service.network.port,
+            used_ports,
+        )
+
+    return True
+
+
+def validate_service_contexts(
+    services: list[ServiceContext],
+) -> bool:
+
+    for service in services:
+        validate_service_executable(service.process.exe)
+        validate_service_watch_dir(service.watch.directory)
+        validate_service_cwd(service.process.cwd)
+
+    return True
+
+def validate_service_root(root: Path) -> None:
+    if not root.exists():
+        raise FileNotFoundError(
+            f"service root does not exist: {root}"
+        )
+
+
+def validate_service_module(
+    module: str,
+    root: Path,
+) -> None:
+
+    path = root / module_to_path(module)
+    
+    check_file_exists("module", path)
+
+
+def validate_service_port(
+    port: int,
+    used_ports: set[int],
+) -> None:
+
+    if port in used_ports:
+        raise ConfigValidationError(
+            f"Duplicate port detected: {port}"
+        )
+
+    used_ports.add(port)
+
+def validate_service_executable(exe: Path) -> None:
+    check_file_exists("exe", exe)
+
+def validate_service_cwd(cwd: Path) -> None:
+    if not cwd.exists():
+        raise FileNotFoundError(
+            f"cwd does not exist: {cwd}"
+        )
+
+def validate_service_watch_dir(watch_dir: Path) -> None:
+    if not watch_dir.exists():
+        raise FileNotFoundError(
+            f"watch directory does not exist: {watch_dir}"
+        )

skeleton/infrastructure/layout.json

@@ -0,0 +1,12 @@
+{
+    "layout": {
+
+        "infrastructure": "skeleton/infrastructure",
+        
+        "common": "skeleton/infrastructure/common",
+        "gateway": "skeleton/infrastructure/gateway",
+        "runners": "skeleton/infrastructure/runners",
+
+        "packages": "skeleton/packages"
+    }
+}

skeleton/infrastructure/runners/src/actions.py

@@ -0,0 +1,4 @@
+ACTIONS = {
+    "--start": "start",
+    "--build": "build",
+}

skeleton/infrastructure/runners/src/browser.py

@@ -0,0 +1,18 @@
+import webbrowser
+
+class BrowserOpener():
+    def open(self, url: str):
+        raise NotImplementedError(
+            f"No browser opener implemented!"
+        )
+
+class SystemBrowserOpener(BrowserOpener):
+    def open(self, url: str) -> None:
+        webbrowser.open(url)
+
+def resolve_browser(
+    choice: str
+) -> BrowserOpener | None:
+    if choice == "system":
+        return SystemBrowserOpener()
+    return None

skeleton/infrastructure/runners/src/cmd.py

@@ -0,0 +1,7 @@
+from dataclasses import dataclass
+
+@dataclass(frozen=True, kw_only=True)
+class CMD:
+    action: str
+    targets: list[str]
+    options: dict[str, str | bool]

skeleton/infrastructure/runners/src/command.py

@@ -0,0 +1,7 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+@dataclass(frozen=True, kw_only=True)
+class Command:
+    args: list[str]
+    cwd: Path | None = None

skeleton/infrastructure/runners/src/frontend.py

@@ -0,0 +1,35 @@
+from skeleton.infrastructure.runners.src.command import Command
+from skeleton.infrastructure.common.src.context import RuntimeContext
+from skeleton.infrastructure.runners.src.utils import resolve_cmd
+
+def start(
+    context: RuntimeContext,
+    flags: list[str] | None = None
+) -> Command:
+    
+    flags = flags or []
+    
+    return Command(
+        args=[
+            resolve_cmd("npm"),
+            "run", "serve",
+            *flags
+        ],
+        cwd=context.root / context.layout.frontend
+    )
+
+def build(
+    context: RuntimeContext,
+    flags: list[str] | None = None
+) -> Command:
+    
+    flags = flags or []
+
+    return Command(
+        args=[
+            resolve_cmd("npm"),
+            "run", "build",
+            *flags
+        ],
+        cwd=context.root / context.layout.frontend
+    )

skeleton/infrastructure/runners/src/gateway.py

@@ -0,0 +1,104 @@
+from skeleton.infrastructure.common.src.constants import Bootstrap
+from skeleton.infrastructure.common.src.context import RuntimeContext
+
+from skeleton.infrastructure.runners.src.utils import resolve_cmd
+from skeleton.infrastructure.runners.src.command import Command
+
+from skeleton.infrastructure.common.src.utils import (
+    resolve_executable_path
+)
+
+# def start(
+#     context: RuntimeContext,
+#     flags: list[str] | None = None
+# ) -> Command:
+
+#     flags = flags or []
+
+#     module = Bootstrap.GATEWAY_MODULE
+
+#     framework_root = context.layout.infrastructure.parent.parent
+
+#     python_exe = resolve_executable_path(
+#         context.layout.gateway
+#     )
+
+#     args = [
+#         str(python_exe),
+#         "-m", module,
+#         "--root", str(context.root),
+#         "--mode", str(context.mode),
+#     ]
+
+#     if context.options["watch"]:
+#         args.append("--watch")
+
+#     if context.options["open"]:
+#         args.append("--open")
+
+#     return Command(
+#         args=[*args, *flags],
+#         cwd=framework_root,
+#     )
+
+
+import sys
+from pathlib import Path
+
+from skeleton.infrastructure.common.src.constants import Bootstrap
+from skeleton.infrastructure.common.src.context import RuntimeContext
+from skeleton.infrastructure.runners.src.utils import resolve_cmd
+from skeleton.infrastructure.runners.src.command import Command
+from skeleton.infrastructure.common.src.utils import resolve_executable_path
+
+
+def start(
+    context: RuntimeContext,
+    flags: list[str] | None = None,
+) -> Command:
+
+    flags = flags or []
+
+    module = Bootstrap.GATEWAY_MODULE
+    framework_root = context.layout.infrastructure.parent.parent
+
+    # Source-repository development uses its dedicated gateway environment.
+    # An installed framework uses the Python environment containing the package.
+    if (framework_root / "run.py").is_file():
+        python_exe = resolve_executable_path(context.layout.gateway)
+    else:
+        python_exe = Path(sys.executable)
+
+    args = [
+        str(python_exe),
+        "-m", module,
+        "--root", str(context.root),
+        "--mode", str(context.mode),
+    ]
+
+    if context.options["watch"]:
+        args.append("--watch")
+
+    if context.options["open"]:
+        args.append("--open")
+
+    return Command(
+        args=[*args, *flags],
+        cwd=framework_root,
+    )
+
+def build(
+    context: RuntimeContext,
+    flags: list[str] | None = None
+) -> Command:
+
+    flags = flags or []
+
+    return Command(
+        args=[
+            resolve_cmd("npm"),
+            "echo \"Error: no build specified\" && exit 1",
+            *flags
+        ],
+        cwd=context.root
+    )

skeleton/infrastructure/runners/src/hook.py

@@ -0,0 +1,53 @@
+import time, threading
+
+from skeleton.infrastructure.common.src.context import RuntimeContext
+from skeleton.infrastructure.runners.src.browser import resolve_browser
+
+def create_dev_portal(context: RuntimeContext):
+
+    delay = 2.0
+    servers = context.config.servers["servers"]
+
+    gateway = servers["gateway"]
+    backend = servers["backend"]
+
+    gateway_host = gateway["host"]
+    gateway_port = gateway["port"]
+    gateway_url = f"http://{gateway_host}:{gateway_port}"
+
+    # for opening backend documentation
+    # valid options include "docs"/"redoc"
+    docs = context.config.services["services"]["backend"]["docs"]
+    
+    backend_host = backend["host"]
+    backend_port = backend["port"]
+    backend_url = f"http://{backend_host}:{backend_port}/{docs}"
+    
+    opener = resolve_browser("system")
+
+    urls = [
+        gateway_url,
+        backend_url,
+    ]
+    
+    # self-object as first arg
+    def hook(manager):
+        
+        if opener is None:
+            return
+        
+        def _open():
+            time.sleep(delay)
+
+            for url in urls:
+                opener.open(url)
+
+        # When ctrl + C for shutdown:
+        # Exception ignored on threading shutdown:
+        # Traceback (most recent call last):
+        # File "C:\Users\Lambda\AppData\Local\Programs\Python\Python313\Lib\threading.py", line 1540, in _shutdown
+        #     _thread_shutdown()
+        threading.Thread(target=_open, daemon=True).start()
+
+    return hook
+

skeleton/infrastructure/runners/src/main.py

@@ -0,0 +1,78 @@
+from pathlib import Path
+
+from skeleton.infrastructure.runners.src.cmd import CMD
+from skeleton.infrastructure.runners.src.process import ProcessManager
+
+from skeleton.infrastructure.common.src.constants import Bootstrap
+from skeleton.infrastructure.common.src.context import RuntimeContext
+
+from skeleton.infrastructure.common.src.config import load_runtime_config
+from skeleton.infrastructure.common.src.layout import build_layout
+from skeleton.infrastructure.common.src.env import build_env
+
+from skeleton.infrastructure.runners.src.parser import parse
+
+from skeleton.infrastructure.runners.src.services import SERVICES
+from skeleton.infrastructure.runners.src.services import DEFAULT_TARGETS
+
+def run(
+    framework_root: Path,
+    project_root: Path,
+    argv: list[str],
+):
+
+    raw = parse(argv)
+
+    raw["options"]["root"] = str(project_root)
+
+    if not raw["targets"]:
+        raw["targets"] = list(DEFAULT_TARGETS.copy())
+
+    cmd = CMD(**raw)
+
+    MODE = str(cmd.options.get("mode", "dev"))
+
+    env = build_env(project_root, MODE)
+
+    layout = build_layout(
+        project_root / Bootstrap.LAYOUT,
+        project_root=project_root,
+        framework_root=framework_root,
+    )
+
+    config = load_runtime_config(
+        layout.common / Bootstrap.CONFIG_FILE_EXT,
+        project_root,
+        framework_root,
+        layout,
+    )
+
+    context = RuntimeContext(
+        root=project_root,
+        mode=MODE,
+        args=argv,
+        env=env,
+        layout=layout,
+        config=config,
+        options=cmd.options,
+    )
+
+    manager = ProcessManager(context)
+
+    if context.options.get("open") and context.mode == "dev":
+
+        from skeleton.infrastructure.runners.src.hook import (
+            create_dev_portal
+        )
+
+        manager.register_hook(
+            create_dev_portal(context),
+            "after_start"
+        )
+
+    for target in cmd.targets:
+        service = SERVICES[target]
+        handler = getattr(service, cmd.action)
+        manager.register(handler(context))
+
+    manager.start()

skeleton/infrastructure/runners/src/packages.py

@@ -0,0 +1,35 @@
+from skeleton.infrastructure.runners.src.command import Command
+from skeleton.infrastructure.common.src.context import RuntimeContext
+from skeleton.infrastructure.runners.src.utils import resolve_cmd
+
+def start(
+    context: RuntimeContext,
+    flags: list[str] | None = None
+) -> Command:
+    
+    flags = flags or []
+
+    return Command(
+        args=[
+            resolve_cmd("npm"),
+            "run", "packages:watch",
+            *flags
+        ],
+        cwd=context.root
+    )
+
+def build(
+    context: RuntimeContext,
+    flags: list[str] | None = None
+) -> Command:
+    
+    flags = flags or []
+    
+    return Command(
+        args=[
+            resolve_cmd("npm"),
+            "run", "packages:build",
+            *flags
+        ],
+        cwd=context.root
+    )