RAHHH

backend/lib/python3.12/site-packages/twisted/python/systemd.py

@@ -0,0 +1,154 @@
+# -*- test-case-name: twisted.python.test.test_systemd -*-
+# Copyright (c) Twisted Matrix Laboratories.
+# See LICENSE for details.
+
+"""
+Integration with systemd.
+
+Currently only the minimum APIs necessary for using systemd's socket activation
+feature are supported.
+"""
+
+
+__all__ = ["ListenFDs"]
+
+from os import getpid
+from typing import Dict, List, Mapping, Optional, Sequence
+
+from attrs import Factory, define
+
+
+@define
+class ListenFDs:
+    """
+    L{ListenFDs} provides access to file descriptors inherited from systemd.
+
+    Typically L{ListenFDs.fromEnvironment} should be used to construct a new
+    instance of L{ListenFDs}.
+
+    @cvar _START: File descriptors inherited from systemd are always
+        consecutively numbered, with a fixed lowest "starting" descriptor.  This
+        gives the default starting descriptor.  Since this must agree with the
+        value systemd is using, it typically should not be overridden.
+
+    @ivar _descriptors: A C{list} of C{int} giving the descriptors which were
+        inherited.
+
+    @ivar _names: A L{Sequence} of C{str} giving the names of the descriptors
+        which were inherited.
+    """
+
+    _descriptors: Sequence[int]
+    _names: Sequence[str] = Factory(tuple)
+
+    _START = 3
+
+    @classmethod
+    def fromEnvironment(
+        cls,
+        environ: Optional[Mapping[str, str]] = None,
+        start: Optional[int] = None,
+    ) -> "ListenFDs":
+        """
+        @param environ: A dictionary-like object to inspect to discover
+            inherited descriptors.  By default, L{None}, indicating that the
+            real process environment should be inspected.  The default is
+            suitable for typical usage.
+
+        @param start: An integer giving the lowest value of an inherited
+            descriptor systemd will give us.  By default, L{None}, indicating
+            the known correct (that is, in agreement with systemd) value will be
+            used.  The default is suitable for typical usage.
+
+        @return: A new instance of C{cls} which can be used to look up the
+            descriptors which have been inherited.
+        """
+        if environ is None:
+            from os import environ as _environ
+
+            environ = _environ
+        if start is None:
+            start = cls._START
+
+        if str(getpid()) == environ.get("LISTEN_PID"):
+            descriptors: List[int] = _parseDescriptors(start, environ)
+            names: Sequence[str] = _parseNames(environ)
+        else:
+            descriptors = []
+            names = ()
+
+        # They may both be missing (consistent with not running under systemd
+        # at all) or they may both be present (consistent with running under
+        # systemd 227 or newer).  It is not allowed for only one to be present
+        # or for the values to disagree with each other (per
+        # systemd.socket(5), systemd will use a default value based on the
+        # socket unit name if the socket unit doesn't explicitly define a name
+        # with FileDescriptorName).
+        if len(names) != len(descriptors):
+            return cls([], ())
+
+        return cls(descriptors, names)
+
+    def inheritedDescriptors(self) -> List[int]:
+        """
+        @return: The configured descriptors.
+        """
+        return list(self._descriptors)
+
+    def inheritedNamedDescriptors(self) -> Dict[str, int]:
+        """
+        @return: A mapping from the names of configured descriptors to
+            their integer values.
+        """
+        return dict(zip(self._names, self._descriptors))
+
+
+def _parseDescriptors(start: int, environ: Mapping[str, str]) -> List[int]:
+    """
+    Parse the I{LISTEN_FDS} environment variable supplied by systemd.
+
+    @param start: systemd provides only a count of the number of descriptors
+        that have been inherited.  This is the integer value of the first
+        inherited descriptor.  Subsequent inherited descriptors are numbered
+        counting up from here.  See L{ListenFDs._START}.
+
+    @param environ: The environment variable mapping in which to look for the
+        value to parse.
+
+    @return: The integer values of the inherited file descriptors, in order.
+    """
+    try:
+        count = int(environ["LISTEN_FDS"])
+    except (KeyError, ValueError):
+        return []
+    else:
+        descriptors = list(range(start, start + count))
+
+        # Remove the information from the environment so that a second
+        # `ListenFDs` cannot find the same information.  This is a precaution
+        # against some application code accidentally trying to handle the same
+        # inherited descriptor more than once - which probably wouldn't work.
+        #
+        # This precaution is perhaps somewhat questionable since it is up to
+        # the application itself to know whether its handling of the file
+        # descriptor will actually be safe.  Also, nothing stops an
+        # application from getting the same descriptor more than once using
+        # multiple calls to `ListenFDs.inheritedDescriptors()` on the same
+        # `ListenFDs` instance.
+        del environ["LISTEN_PID"], environ["LISTEN_FDS"]
+        return descriptors
+
+
+def _parseNames(environ: Mapping[str, str]) -> Sequence[str]:
+    """
+    Parse the I{LISTEN_FDNAMES} environment variable supplied by systemd.
+
+    @param environ: The environment variable mapping in which to look for the
+        value to parse.
+
+    @return: The names of the inherited descriptors, in order.
+    """
+    names = environ.get("LISTEN_FDNAMES", "")
+    if len(names) > 0:
+        return tuple(names.split(":"))
+    return ()