fujin-cli 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

fujin/config.py

@@ -1,3 +1,160 @@
+"""
+Fujin uses a ``fujin.toml`` file at the root of your project for configuration. Below are all available configuration options.
+
+app
+---
+The name of your project or application. Must be a valid Python package name.
+
+app_bin
+-------
+Path to your application's executable. Used by the **app** subcommand for remote execution.
+Default: ``.venv/bin/{app}``
+
+version
+--------
+The version of your project to build and deploy. If not specified, automatically parsed from ``pyproject.toml`` under ``project.version``.
+
+python_version
+--------------
+The Python version for your virtualenv. If not specified, automatically parsed from ``.python-version`` file.
+
+versions_to_keep
+----------------
+The number of versions to keep on the host. After each deploy, older versions are pruned based on this setting. By default, it keeps the latest 5 versions,
+set this to `None` to never automatically prune.
+
+build_command
+-------------
+The command to use to build your project's distribution file.
+
+distfile
+--------
+Path to your project's distribution file. This should be the main artifact containing everything needed to run your project on the server.
+Supports version placeholder, e.g., ``dist/app_name-{version}-py3-none-any.whl``
+
+release_command
+---------------
+Optional command to run at the end of deployment (e.g., database migrations).
+
+requirements
+------------
+Path to your requirements file.
+Default: ``requirements.txt``
+
+Webserver
+---------
+
+type
+~~~~
+The reverse proxy implementation to use. Available options:
+
+- ``fujin.proxies.caddy`` (default)
+- ``fujin.proxies.nginx``
+- ``fujin.proxies.dummy`` (disables proxy functionality)
+
+upstream
+~~~~~~~~
+The address where your web application listens for requests. Supports any value compatible with your chosen web proxy:
+
+- HTTP address (e.g., ``localhost:8000``)
+- Unix socket (e.g., ``unix//run/project.sock``)
+
+statics
+~~~~~~~
+
+Defines the mapping of URL paths to local directories for serving static files. The syntax and support for static
+file serving depend on the selected reverse proxy.
+
+Example:
+
+.. code-block:: toml
+
+    [webserver]
+    upstream = "unix//run/project.sock"
+    type = "fujin.proxies.caddy"
+    statics = { "/static/*" = "/var/www/example.com/static/" }
+
+processes
+---------
+
+A mapping of process names to commands that will be managed by the process manager. Define as many processes as needed, but
+when using any proxy other than ``fujin.proxies.dummy``, a ``web`` process must be declared.  Refer to the ``apps_dir``
+setting on the host to understand how ``app_dir`` is determined.
+
+Example:
+
+.. code-block:: toml
+
+    [processes]
+    web = ".venv/bin/gunicorn myproject.wsgi:application"
+
+
+.. note::
+
+    Commands are relative to your ``app_dir``. When generating systemd service files, the full path is automatically constructed.
+
+Host Configuration
+-------------------
+
+ip
+~~
+The IP address or hostname of the remote host.
+
+domain_name
+~~~~~~~~~~~
+The domain name pointing to this host. Used for web proxy configuration.
+
+user
+~~~~
+The login user for running remote tasks. Should have passwordless sudo access for optimal operation.
+
+.. note::
+
+    You can create a user with these requirements using the ``fujin server create-user`` command.
+
+envfile
+~~~~~~~
+Path to the production environment file that will be copied to the host.
+
+apps_dir
+~~~~~~~~
+
+Base directory for project storage on the host. Path is relative to user's home directory.
+Default: ``.local/share/fujin``. This value determines your project's ``app_dir``, which is ``{apps_dir}/{app}``.
+
+password_env
+~~~~~~~~~~~~
+
+Environment variable containing the user's password. Only needed if the user cannot run sudo without a password.
+
+ssh_port
+~~~~~~~~
+
+SSH port for connecting to the host.
+Default: ``22``
+
+key_filename
+~~~~~~~~~~~~
+
+Path to the SSH private key file for authentication. Optional if using your system's default key location.
+
+aliases
+-------
+
+A mapping of shortcut names to Fujin commands. Allows you to create convenient shortcuts for commonly used commands.
+
+Example:
+
+.. code-block:: toml
+
+    [aliases]
+    console = "app exec -i shell_plus" # open an interactive django shell
+    dbconsole = "app exec -i dbshell" # open an interactive django database shell
+    shell = "server exec --appenv -i bash" # SSH into the project directory with environment variables loaded
+
+
+"""
+
 from __future__ import annotations
 
 import os
@@ -13,51 +170,45 @@ if sys.version_info >= (3, 11):
 else:
     import tomli as tomllib
 
-try:
-    from enum import StrEnum
-except ImportError:
-    from enum import Enum
-
-    class StrEnum(str, Enum):
-        pass
-
-
-class Hook(StrEnum):
-    PRE_DEPLOY = "pre_deploy"
+from .hooks import HooksDict
 
 
 class Config(msgspec.Struct, kw_only=True):
-    app: str
+    app_name: str = msgspec.field(name="app")
     app_bin: str = ".venv/bin/{app}"
     version: str = msgspec.field(default_factory=lambda: read_version_from_pyproject())
+    versions_to_keep: int | None = 5
     python_version: str = msgspec.field(default_factory=lambda: find_python_version())
     build_command: str
-    _distfile: str = msgspec.field(name="distfile")
-    aliases: dict[str, str]
-    hosts: dict[str, HostConfig]
-    processes: dict[str, str]
+    release_command: str | None = None
+    skip_project_install: bool = False
+    distfile: str
+    aliases: dict[str, str] = msgspec.field(default_factory=dict)
+    host: HostConfig
+    processes: dict[str, str] = msgspec.field(default_factory=dict)
     process_manager: str = "fujin.process_managers.systemd"
     webserver: Webserver
     _requirements: str = msgspec.field(name="requirements", default="requirements.txt")
-    hooks: dict[Hook, str] = msgspec.field(default=dict)
+    hooks: HooksDict = msgspec.field(default_factory=dict)
+    local_config_dir: Path = Path(".fujin")
 
     def __post_init__(self):
-        self.app_bin = self.app_bin.format(app=self.app)
-        self._distfile = self._distfile.format(version=self.version)
+        self.app_bin = self.app_bin.format(app=self.app_name)
+        # self._distfile = self._distfile.format(version=self.version)
 
         if "web" not in self.processes and self.webserver.type != "fujin.proxies.dummy":
             raise ValueError(
                 "Missing web process or set the proxy to 'fujin.proxies.dummy' to disable the use of a proxy"
             )
 
-    @property
-    def distfile(self) -> Path:
-        return Path(self._distfile)
-
     @property
     def requirements(self) -> Path:
         return Path(self._requirements)
 
+    def get_distfile_path(self, version: str | None = None) -> Path:
+        version = version or self.version
+        return Path(self.distfile.format(version=version))
+
     @classmethod
     def read(cls) -> Config:
         fujin_toml = Path("fujin.toml")
@@ -76,17 +227,21 @@ class HostConfig(msgspec.Struct, kw_only=True):
     domain_name: str
     user: str
     _envfile: str = msgspec.field(name="envfile")
-    projects_dir: str = "/home/{user}/.local/share/fujin"
+    apps_dir: str = ".local/share/fujin"
     password_env: str | None = None
     ssh_port: int = 22
     _key_filename: str | None = msgspec.field(name="key_filename", default=None)
-    default: bool = False
 
     def __post_init__(self):
-        self.projects_dir = self.projects_dir.format(user=self.user)
+        self.apps_dir = f"/home/{self.user}/{self.apps_dir}"
 
     def to_dict(self):
-        return {f: getattr(self, f) for f in self.__struct_fields__}
+        d = {f: getattr(self, f) for f in self.__struct_fields__}
+        d.pop("_key_filename")
+        d.pop("_envfile")
+        d["key_filename"] = self.key_filename
+        d["envfile"] = self.envfile
+        return d
 
     @property
     def envfile(self) -> Path:
@@ -107,10 +262,14 @@ class HostConfig(msgspec.Struct, kw_only=True):
             raise ImproperlyConfiguredError(msg)
         return password
 
+    def get_app_dir(self, app_name: str) -> str:
+        return f"{self.apps_dir}/{app_name}"
+
 
 class Webserver(msgspec.Struct):
     upstream: str
     type: str = "fujin.proxies.caddy"
+    statics: dict[str, str] = msgspec.field(default_factory=dict)
 
 
 def read_version_from_pyproject():

fujin/connection.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from functools import partial
+from typing import TYPE_CHECKING
+
+import cappa
+from fabric import Connection
+from invoke import Responder
+from invoke.exceptions import UnexpectedExit
+from paramiko.ssh_exception import (
+    AuthenticationException,
+    NoValidConnectionsError,
+    SSHException,
+)
+
+if TYPE_CHECKING:
+    from fujin.config import HostConfig
+
+
+def _get_watchers(host: HostConfig) -> list[Responder]:
+    if not host.password:
+        return []
+    return [
+        Responder(
+            pattern=r"\[sudo\] password:",
+            response=f"{host.password}\n",
+        ),
+        Responder(
+            pattern=rf"\[sudo\] password for {host.user}:",
+            response=f"{host.password}\n",
+        ),
+    ]
+
+
+@contextmanager
+def host_connection(host: HostConfig) -> Connection:
+    connect_kwargs = None
+    if host.key_filename:
+        connect_kwargs = {"key_filename": str(host.key_filename)}
+    elif host.password:
+        connect_kwargs = {"password": host.password}
+    conn = Connection(
+        host.ip,
+        user=host.user,
+        port=host.ssh_port,
+        connect_kwargs=connect_kwargs,
+    )
+    try:
+        conn.run = partial(
+            conn.run,
+            env={
+                "PATH": f"/home/{host.user}/.cargo/bin:/home/{host.user}/.local/bin:$PATH"
+            },
+            watchers=_get_watchers(host),
+        )
+        yield conn
+    except AuthenticationException as e:
+        msg = f"Authentication failed for {host.user}@{host.ip} -p {host.ssh_port}.\n"
+        if host.key_filename:
+            msg += f"An SSH key was provided at {host.key_filename.resolve()}. Please verify its validity and correctness."
+        elif host.password:
+            msg += f"A password was provided through the environment variable {host.password_env}. Please ensure it is correct for the user {host.user}."
+        else:
+            msg += "No password or SSH key was provided. Ensure your current host has SSH access to the target host."
+        raise cappa.Exit(msg, code=1) from e
+    except (UnexpectedExit, NoValidConnectionsError) as e:
+        raise cappa.Exit(str(e), code=1) from e
+    except SSHException as e:
+        raise cappa.Exit(
+            f"{e}, possible causes: incorrect user, or either you or the server may be offline",
+            code=1,
+        ) from e
+    finally:
+        conn.close()

fujin/hooks.py

@@ -1,15 +1,55 @@
 from dataclasses import dataclass
 
-from fujin.config import Config
-from fujin.host import Host
-from fujin.config import Hook
+from fujin.connection import Connection
+from rich import print as rich_print
+
+try:
+    from enum import StrEnum
+except ImportError:
+    from enum import Enum
+
+    class StrEnum(str, Enum):
+        pass
+
+
+class Hook(StrEnum):
+    PRE_DEPLOY = "pre_deploy"
+    POST_DEPLOY = "post_deploy"
+    PRE_BOOTSTRAP = "pre_bootstrap"
+    POST_BOOTSTRAP = "post_bootstrap"
+    PRE_TEARDOWN = "pre_teardown"
+    POST_TEARDOWN = "post_teardown"
+
+
+HooksDict = dict[Hook, dict]
 
 
 @dataclass(frozen=True, slots=True)
 class HookManager:
-    config: Config
-    host: Host
+    app_name: str
+    hooks: HooksDict
+    conn: Connection
+
+    def _run_hook(self, type_: Hook) -> None:
+        if hooks := self.hooks.get(type_):
+            for name, command in hooks.items():
+                rich_print(f"[blue]Running {type_} hook {name} [/blue]")
+                self.conn.run(command, pty=True)
+
+    def pre_deploy(self) -> None:
+        self._run_hook(Hook.PRE_DEPLOY)
+
+    def post_deploy(self) -> None:
+        self._run_hook(Hook.POST_DEPLOY)
+
+    def pre_bootstrap(self) -> None:
+        self._run_hook(Hook.PRE_BOOTSTRAP)
+
+    def post_bootstrap(self) -> None:
+        self._run_hook(Hook.POST_BOOTSTRAP)
+
+    def pre_teardown(self) -> None:
+        self._run_hook(Hook.PRE_TEARDOWN)
 
-    def pre_deploy(self):
-        if pre_deploy := self.config.hooks.get(Hook.PRE_DEPLOY):
-            self.host.run(pre_deploy)
+    def post_teardown(self) -> None:
+        self._run_hook(Hook.POST_TEARDOWN)

fujin/process_managers/__init__.py

@@ -1,18 +1,21 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Protocol
+from typing import Protocol
+from typing import TYPE_CHECKING
+
+from fujin.connection import Connection
 
 if TYPE_CHECKING:
     from fujin.config import Config
-    from fujin.host import Host
 
 
 class ProcessManager(Protocol):
-    host: Host
-    config: Config
     service_names: list[str]
 
-    def get_service_name(self, name: str): ...
+    @classmethod
+    def create(cls, config: Config, conn: Connection) -> ProcessManager: ...
+
+    def get_service_name(self, process_name: str): ...
 
     def install_services(self) -> None: ...
 
@@ -24,6 +27,14 @@ class ProcessManager(Protocol):
 
     def stop_services(self, *names) -> None: ...
 
+    def is_enabled(self, *names) -> dict[str, bool]: ...
+
+    def is_active(self, *names) -> dict[str, bool]: ...
+
     def service_logs(self, name: str, follow: bool = False): ...
 
     def reload_configuration(self) -> None: ...
+
+    def get_configuration_files(
+        self, ignore_local: bool = False
+    ) -> list[tuple[str, str]]: ...

fujin/process_managers/systemd.py

@@ -5,101 +5,151 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from fujin.config import Config
-from fujin.host import Host
-
-
-@dataclass(frozen=True, slots=True)
-class SystemdFile:
-    name: str
-    body: str
+from fujin.connection import Connection
 
 
 @dataclass(frozen=True, slots=True)
 class ProcessManager:
-    config: Config
-    host: Host
+    conn: Connection
+    app_name: str
+    processes: dict[str, str]
+    app_dir: str
+    user: str
+    is_using_unix_socket: bool
+    local_config_dir: Path
+
+    @classmethod
+    def create(cls, config: Config, conn: Connection):
+        return cls(
+            processes=config.processes,
+            app_name=config.app_name,
+            app_dir=config.host.get_app_dir(config.app_name),
+            conn=conn,
+            user=config.host.user,
+            is_using_unix_socket="unix" in config.webserver.upstream
+            and config.webserver.type != "fujin.proxies.dummy",
+            local_config_dir=config.local_config_dir,
+        )
 
     @property
     def service_names(self) -> list[str]:
-        return [self.get_service_name(name) for name in self.config.processes]
+        services = [self.get_service_name(name) for name in self.processes]
+        if self.is_using_unix_socket:
+            services.append(f"{self.app_name}.socket")
+        return services
+
+    def get_service_name(self, process_name: str):
+        if process_name == "web":
+            return f"{self.app_name}.service"
+        return f"{self.app_name}-{process_name}.service"
 
-    def get_service_name(self, name: str):
-        if name == "web":
-            return self.config.app
-        return f"{self.config.app}-{name}.service"
+    def run_pty(self, *args, **kwargs):
+        return self.conn.run(*args, **kwargs, pty=True)
 
     def install_services(self) -> None:
         conf_files = self.get_configuration_files()
-        for conf_file in conf_files:
-            self.host.sudo(
-                f"echo '{conf_file.body}' | sudo tee /etc/systemd/system/{conf_file.name}",
+        for filename, content in conf_files:
+            self.run_pty(
+                f"echo '{content}' | sudo tee /etc/systemd/system/{filename}",
                 hide="out",
             )
 
-        self.host.sudo(f"systemctl enable --now {self.config.app}.socket")
-        for name in self.service_names:
-            # the main web service is launched by the socket service
-            if name != f"{self.config.app}.service":
-                self.host.sudo(f"systemctl enable {name}")
+        for name in self.processes:
+            if name == "web" and self.is_using_unix_socket:
+                self.run_pty(f"sudo systemctl enable --now {self.app_name}.socket")
+            else:
+                self.run_pty(f"sudo systemctl enable {self.get_service_name(name)}")
 
-    def get_configuration_files(self) -> list[SystemdFile]:
+    def get_configuration_files(
+        self, ignore_local: bool = False
+    ) -> list[tuple[str, str]]:
         templates_folder = (
             Path(importlib.util.find_spec("fujin").origin).parent / "templates"
         )
         web_service_content = (templates_folder / "web.service").read_text()
         web_socket_content = (templates_folder / "web.socket").read_text()
-        other_service_content = (templates_folder / "other.service").read_text()
+        simple_service_content = (templates_folder / "simple.service").read_text()
+        if not self.is_using_unix_socket:
+            web_service_content = web_service_content.replace(
+                "Requires={app_name}.socket\n", ""
+            )
+
         context = {
-            "app": self.config.app,
-            "user": self.host.config.user,
-            "project_dir": self.host.project_dir(self.config.app),
+            "app_name": self.app_name,
+            "user": self.user,
+            "app_dir": self.app_dir,
         }
 
         files = []
-        for name, command in self.config.processes.items():
+        for name, command in self.processes.items():
+            template = web_service_content if name == "web" else simple_service_content
             name = self.get_service_name(name)
-            if name == "web":
-                body = web_service_content.format(**context, command=command)
-                files.append(
-                    SystemdFile(
-                        name=f"{self.config.app}.socket",
-                        body=web_socket_content.format(**context),
-                    )
-                )
-            else:
-                body = other_service_content.format(**context, command=command)
-            files.append(SystemdFile(name=name, body=body))
+            local_config = self.local_config_dir / name
+            body = (
+                local_config.read_text()
+                if local_config.exists() and not ignore_local
+                else template.format(**context, command=command)
+            )
+            files.append((name, body))
+        # if using unix then we are sure a web process was defined and the proxy is not dummy
+        if self.is_using_unix_socket:
+            name = f"{self.app_name}.socket"
+            local_config = self.local_config_dir / name
+            body = (
+                local_config.read_text()
+                if local_config.exists() and not ignore_local
+                else web_socket_content.format(**context)
+            )
+            files.append((name, body))
         return files
 
     def uninstall_services(self) -> None:
         self.stop_services()
-        self.host.sudo(f"systemctl disable {self.config.app}.socket")
         for name in self.service_names:
-            # was never enabled in the first place, look at the code above
-            if name != f"{self.config.app}.service":
-                self.host.sudo(f"systemctl disable {name}")
+            self.run_pty(f"sudo systemctl disable {name}", warn=True)
+            self.run_pty(f"sudo rm /etc/systemd/system/{name}", warn=True)
 
     def start_services(self, *names) -> None:
         names = names or self.service_names
         for name in names:
             if name in self.service_names:
-                self.host.sudo(f"systemctl start {name}")
+                self.run_pty(f"sudo systemctl start {name}")
 
     def restart_services(self, *names) -> None:
         names = names or self.service_names
         for name in names:
             if name in self.service_names:
-                self.host.sudo(f"systemctl restart {name}")
+                self.run_pty(f"sudo systemctl restart {name}")
 
     def stop_services(self, *names) -> None:
         names = names or self.service_names
         for name in names:
             if name in self.service_names:
-                self.host.sudo(f"systemctl stop {name}")
+                self.run_pty(f"sudo systemctl stop {name}")
+
+    def is_enabled(self, *names) -> dict[str, bool]:
+        names = names or self.service_names
+        return {
+            name: self.run_pty(
+                f"sudo systemctl is-enabled {name}", warn=True, hide=True
+            ).stdout.strip()
+            == "enabled"
+            for name in names
+        }
+
+    def is_active(self, *names) -> dict[str, bool]:
+        names = names or self.service_names
+        return {
+            name: self.run_pty(
+                f"sudo systemctl is-active {name}", warn=True, hide=True
+            ).stdout.strip()
+            == "active"
+            for name in names
+        }
 
     def service_logs(self, name: str, follow: bool = False):
         # TODO: add more options here
-        self.host.sudo(f"journalctl -u {name} -r {'-f' if follow else ''}")
+        self.run_pty(f"sudo journalctl -u {name} {'-f' if follow else ''}", warn=True)
 
     def reload_configuration(self) -> None:
-        self.host.sudo(f"systemctl daemon-reload")
+        self.run_pty(f"sudo systemctl daemon-reload")

fujin/proxies/__init__.py

@@ -1,18 +1,35 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Protocol
+from pathlib import Path
+from typing import Protocol
 
-if TYPE_CHECKING:
-    from fujin.config import Config
-    from fujin.host import Host
+from fujin.config import Config
+from fujin.config import HostConfig
+from fujin.connection import Connection
 
 
 class WebProxy(Protocol):
-    host: Host
-    config: Config
+    config_file: Path
+
+    @classmethod
+    def create(cls, config: Config, conn: Connection) -> WebProxy: ...
 
     def install(self) -> None: ...
 
+    def uninstall(self) -> None: ...
+
     def setup(self) -> None: ...
 
     def teardown(self) -> None: ...
+
+    def start(self) -> None: ...
+
+    def stop(self) -> None: ...
+
+    def status(self) -> None: ...
+
+    def restart(self) -> None: ...
+
+    def logs(self) -> None: ...
+
+    def export_config(self) -> None: ...