config_ninja.systemd

  1"""Generate a `systemd` unit file for installation as a service.
  2
  3The following `jinja2` template is used to generate the `systemd` unit file:
  4
  5```jinja
  6.. include:: ./templates/systemd.service.j2
  7```
  8
  9Run the CLI's `install`_ command to install the service:
 10
 11```sh
 12❯ config-ninja self install --env AWS_PROFILE --user
 13Installing /home/ubuntu/.config/systemd/user/config-ninja.service
 14● config-ninja.service - config synchronization daemon
 15     Loaded: loaded (/home/ubuntu/.config/systemd/user/config-ninja.service; disabled; vendor preset: enabled)
 16     Active: active (running) since Sun 2024-01-21 22:37:52 EST; 7ms ago
 17    Process: 20240 ExecStartPre=/usr/local/bin/config-ninja self print (code=exited, status=0/SUCCESS)
 18   Main PID: 20241 (config-ninja)
 19     CGroup: /user.slice/user-1000.slice/user@1000.service/app.slice/config-ninja.service
 20             └─20241 /usr/local/bin/python /usr/local/bin/config-ninja monitor
 21
 22Jan 21 22:37:51 ubuntu config-ninja[20240]:     path: /tmp/config-ninja/settings-subset.toml
 23Jan 21 22:37:51 ubuntu config-ninja[20240]:   source:
 24Jan 21 22:37:51 ubuntu config-ninja[20240]:     backend: local
 25Jan 21 22:37:51 ubuntu config-ninja[20240]:     format: yaml
 26Jan 21 22:37:51 ubuntu config-ninja[20240]:     new:
 27Jan 21 22:37:51 ubuntu config-ninja[20240]:       kwargs:
 28Jan 21 22:37:51 ubuntu config-ninja[20240]:         path: config-ninja-settings.yaml
 29Jan 21 22:37:52 ubuntu config-ninja[20241]: Begin monitoring: ['example-local', 'example-local-template', 'example-appconfig']
 30Jan 21 22:37:52 ubuntu systemd[592]: Started config synchronization daemon.
 31
 32SUCCESS ✅
 33```
 34
 35.. _install: https://bryant-finney.github.io/config-ninja/config_ninja/cli.html#config-ninja-self-install
 36"""  # noqa: RUF002
 37
 38from __future__ import annotations
 39
 40import contextlib
 41import logging
 42import os
 43import typing
 44from pathlib import Path
 45from typing import TYPE_CHECKING
 46
 47import jinja2
 48import sdnotify
 49
 50if TYPE_CHECKING:  # pragma: no cover
 51    import sh
 52else:
 53    try:
 54        import sh
 55    except ImportError:  # pragma: no cover
 56        sh = None
 57
 58SERVICE_NAME = 'config-ninja.service'
 59SYSTEM_INSTALL_PATH = Path('/etc/systemd/system')
 60"""The file path for system-wide installation."""
 61
 62USER_INSTALL_PATH = Path(os.getenv('XDG_CONFIG_HOME') or Path.home() / '.config') / 'systemd' / 'user'
 63"""The file path for user-local installation."""
 64
 65__all__ = ['SYSTEM_INSTALL_PATH', 'USER_INSTALL_PATH', 'Service', 'notify']
 66logger = logging.getLogger(__name__)
 67
 68
 69@contextlib.contextmanager
 70def dummy() -> typing.Iterator[None]:
 71    """Define a dummy context manager to use instead of `sudo`.
 72
 73    There are a few scenarios where `sudo` is unavailable or unnecessary:
 74    - running on Windows
 75    - running in a container without `sudo` installed
 76    - already running as root
 77    """
 78    yield  # pragma: no cover
 79
 80
 81try:
 82    sudo = sh.contrib.sudo
 83except AttributeError:  # pragma: no cover
 84    sudo = dummy()
 85
 86
 87def notify() -> None:  # pragma: no cover
 88    """Notify `systemd` that the service has finished starting up and is ready."""
 89    sock = sdnotify.SystemdNotifier()
 90    sock.notify('READY=1')  # pyright: ignore[reportUnknownMemberType]
 91
 92
 93class Service:
 94    """Manipulate the `systemd` service file for `config-ninja`.
 95
 96    ## User Installation
 97
 98    To install the service for only the current user, pass `user_mode=True` to the initializer:
 99
100    >>> svc = Service('config_ninja', 'systemd.service.j2', user_mode=True)
101    >>> _ = svc.install(
102    ...     config_ninja_cmd='config-ninja', workdir='.', environ={'TESTING': 'true'}
103    ... )
104
105    >>> print(svc.read())
106    [Unit]
107    Description=config synchronization daemon
108    After=network.target
109    <BLANKLINE>
110    [Service]
111    Environment=PYTHONUNBUFFERED=true
112    Environment=TESTING=true
113    ExecStartPre=config-ninja self print
114    ExecStart=config-ninja apply --poll
115    Restart=always
116    RestartSec=30s
117    Type=notify
118    WorkingDirectory=...
119    <BLANKLINE>
120    [Install]
121    Alias=config-ninja.service
122
123    >>> svc.uninstall()
124
125    ## System Installation
126
127    For system-wide installation:
128
129    >>> svc = Service('config_ninja', 'systemd.service.j2', user_mode=False)
130    >>> _ = svc.install(
131    ...     config_ninja_cmd='config-ninja', workdir='.', environ={'TESTING': 'true'}
132    ... )
133
134    >>> svc.uninstall()
135    """
136
137    path: Path
138    """The installation location of the `systemd` unit file."""
139
140    sudo: typing.ContextManager[None]
141
142    tmpl: jinja2.Template
143    """Load the template on initialization."""
144
145    user_mode: bool
146    """Whether to install the service for the full system or just the current user."""
147
148    def __init__(self, provider: str, template: str, user_mode: bool) -> None:
149        """Prepare to render the specified `template` from the `provider` package."""
150        loader = jinja2.PackageLoader(provider)
151        env = jinja2.Environment(autoescape=jinja2.select_autoescape(default=True), loader=loader)
152        self.tmpl = env.get_template(template)
153        self.user_mode = user_mode
154        self.path = (USER_INSTALL_PATH if user_mode else SYSTEM_INSTALL_PATH) / SERVICE_NAME
155
156        if os.geteuid() == 0:
157            self.sudo = dummy()
158        else:
159            self.sudo = sudo
160
161    def _install_system(self, content: str) -> str:
162        logger.info('writing to %s', self.path)
163        sh.mkdir('-p', str(self.path.parent))
164        sh.tee(str(self.path), _in=content, _out='/dev/null')
165
166        logger.info('enabling and starting %s', self.path.name)
167        sh.systemctl.start(self.path.name)
168        return sh.systemctl.status(self.path.name)
169
170    def _install_user(self, content: str) -> str:
171        logger.info('writing to %s', self.path)
172        self.path.parent.mkdir(parents=True, exist_ok=True)
173        self.path.write_text(content, encoding='utf-8')
174
175        logger.info('enabling and starting %s', self.path.name)
176        sh.systemctl.start('--user', self.path.name)
177        return sh.systemctl.status('--user', self.path.name)
178
179    def _uninstall_system(self) -> None:
180        logger.info('stopping and disabling %s', self.path.name)
181        sh.systemctl.disable('--now', self.path.name)
182
183        logger.info('removing %s', self.path)
184        sh.rm(str(self.path))
185
186    def _uninstall_user(self) -> None:
187        logger.info('stopping and disabling %s', self.path.name)
188        sh.systemctl.disable('--user', '--now', self.path.name)
189
190        logger.info('removing %s', self.path)
191        self.path.unlink()
192
193    def install(self, **kwargs: typing.Any) -> str:
194        """Render the `systemd` service file from `kwargs` and install it."""
195        rendered = self.render(**kwargs)
196        if self.user_mode:
197            return self._install_user(rendered)
198
199        if os.geteuid() == 0:
200            return self._install_system(rendered)
201
202        with sudo:
203            return self._install_system(rendered)
204
205    def read(self) -> str:
206        """Read the `systemd` service file."""
207        return self.path.read_text(encoding='utf-8')
208
209    def render(self, **kwargs: typing.Any) -> str:
210        """Render the `systemd` service file from the given parameters."""
211        if workdir := kwargs.get('workdir'):
212            kwargs['workdir'] = Path(workdir).absolute()
213
214        kwargs.setdefault('user_mode', self.user_mode)
215
216        return self.tmpl.render(**kwargs)
217
218    def uninstall(self) -> None:
219        """Disable, stop, and delete the service."""
220        if self.user_mode:
221            return self._uninstall_user()
222
223        if os.geteuid() == 0:
224            return self._uninstall_system()
225
226        with sudo:
227            return self._uninstall_system()