kitty-logger 0.2.0.dev2__tar.gz → 0.2.0.dev3__tar.gz

{kitty_logger-0.2.0.dev2/src/kitty_logger.egg-info → kitty_logger-0.2.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kitty_logger
-Version: 0.2.0.dev2
+Version: 0.2.0.dev3
 Summary: Cross-process logging via a dedicated log server process and SocketHandler.
 Author: Kitty
 License: MIT
@@ -55,13 +55,15 @@ if __name__ == "__main__":
 ## API
 
 - `setup_logging(log_file=None, level=logging.INFO, host="127.0.0.1", port=0, stream=True, console_fmt=..., file_fmt=..., datefmt=None) -> (host, port)`
-  启动日志服务子进程（始终使用 `spawn`）。幂等。已通过 `atexit` 注册清理。
-  `port=0` 让操作系统挑选空闲端口；返回真实绑定到的 `(host, port)`。
+  通过 `subprocess.Popen` 启动一个独立的日志服务子进程（不依赖
+  `multiprocessing`，因此**不会回头执行用户主脚本的任何顶层代码**）。
+  幂等。已通过 `atexit` 注册清理。`port=0` 让操作系统挑选空闲端口；返回
+  真实绑定到的 `(host, port)`。
   **`host` 必须是 loopback**——绑定非 loopback 地址会直接 `ValueError`。
   同时把主进程内 `logging.getLogger("kitty")` 这一个 logger 初始化好——挂上
   `SocketHandler`、设置 level、关闭 `propagate`。**不动 root logger**。
-  在 `multiprocessing` 启动的子进程里再次调用本函数会自动 no-op，仅返回
-  从父进程继承的 `(host, port)`，因此可以直接放在模块顶层而不必用
+  在用户用 `multiprocessing` 启动的子进程里再次调用本函数会自动 no-op，
+  仅返回从父进程继承的 `(host, port)`，因此可以直接放在模块顶层而不必用
   `if __name__ == "__main__":` 包裹。
 - `getLogger(name=None) -> logging.Logger`
   返回挂在 `kitty` 命名空间下的 logger：`getLogger("foo")` 实际拿到的是

{kitty_logger-0.2.0.dev2 → kitty_logger-0.2.0.dev3}/README.md

@@ -42,13 +42,15 @@ if __name__ == "__main__":
 ## API
 
 - `setup_logging(log_file=None, level=logging.INFO, host="127.0.0.1", port=0, stream=True, console_fmt=..., file_fmt=..., datefmt=None) -> (host, port)`
-  启动日志服务子进程（始终使用 `spawn`）。幂等。已通过 `atexit` 注册清理。
-  `port=0` 让操作系统挑选空闲端口；返回真实绑定到的 `(host, port)`。
+  通过 `subprocess.Popen` 启动一个独立的日志服务子进程（不依赖
+  `multiprocessing`，因此**不会回头执行用户主脚本的任何顶层代码**）。
+  幂等。已通过 `atexit` 注册清理。`port=0` 让操作系统挑选空闲端口；返回
+  真实绑定到的 `(host, port)`。
   **`host` 必须是 loopback**——绑定非 loopback 地址会直接 `ValueError`。
   同时把主进程内 `logging.getLogger("kitty")` 这一个 logger 初始化好——挂上
   `SocketHandler`、设置 level、关闭 `propagate`。**不动 root logger**。
-  在 `multiprocessing` 启动的子进程里再次调用本函数会自动 no-op，仅返回
-  从父进程继承的 `(host, port)`，因此可以直接放在模块顶层而不必用
+  在用户用 `multiprocessing` 启动的子进程里再次调用本函数会自动 no-op，
+  仅返回从父进程继承的 `(host, port)`，因此可以直接放在模块顶层而不必用
   `if __name__ == "__main__":` 包裹。
 - `getLogger(name=None) -> logging.Logger`
   返回挂在 `kitty` 命名空间下的 logger：`getLogger("foo")` 实际拿到的是

{kitty_logger-0.2.0.dev2 → kitty_logger-0.2.0.dev3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kitty_logger"
-version = "0.2.0.dev2"
+version = "0.2.0.dev3"
 description = "Cross-process logging via a dedicated log server process and SocketHandler."
 readme = "README.md"
 requires-python = ">=3.12"

{kitty_logger-0.2.0.dev2 → kitty_logger-0.2.0.dev3}/src/kitty_logger/__init__.py

@@ -33,4 +33,4 @@ from ._client import getLogger
 from ._setup import setup_logging, shutdown_logging
 
 __all__ = ["setup_logging", "shutdown_logging", "getLogger"]
-__version__ = "0.2.0.dev2"
+__version__ = "0.2.0.dev3"

kitty_logger-0.2.0.dev3/src/kitty_logger/_server.py

@@ -0,0 +1,153 @@
+"""日志服务子进程的核心组件（与启动方式无关）。
+
+服务进程通过 ``python -m kitty_logger._server_main`` 由 :func:`kitty_logger.setup_logging`
+间接拉起，本模块只提供与"具体如何起进程"无关的纯逻辑：
+
+- :func:`_bind_loopback`：在 loopback 地址上绑定一个 ``AF_INET`` 监听 socket。
+- :class:`_LogRecordSocketReceiver`：基于 :class:`socketserver.ThreadingTCPServer`
+  的接收器，复用外部已 ``bind`` 好的 socket。
+- :func:`_build_handlers`：根据用户参数组装落地用的 handler 列表。
+"""
+
+import logging
+import pickle
+import socket
+import socketserver
+import struct
+import sys
+from logging.handlers import TimedRotatingFileHandler
+from typing import cast, final, override
+
+from ._formatters import ColorFormatter, FileFormatter
+
+# 这三个符号由同包内的 ``_server_main`` 模块导入复用；以下划线开头是因为它们
+# 不属于库的公共 API（仅 kitty_logger 内部使用）。pyright 对下划线名默认按
+# "模块内私有"处理，看不到跨模块引用，因此显式通过 ``__all__`` 声明为本模块
+# 的对外导出，避免 reportUnusedFunction / reportUnusedClass 误报。
+__all__ = ["_bind_loopback", "_LogRecordSocketReceiver", "_build_handlers"]
+
+# 单条 LogRecord 序列化后字节数上限。任何正常 LogRecord 都远小于此值；
+# 超过即视为协议错位或异常流量，直接断开连接，避免一次性分配巨大缓冲区
+# 触发 OOM。
+_MAX_RECORD_BYTES = 16 * 1024 * 1024
+
+
+def _bind_loopback(
+    host: str, port: int, backlog: int = 128
+) -> tuple[socket.socket, str, int]:
+    """创建并绑定一个 ``AF_INET`` TCP 监听 socket，返回 ``(sock, bound_host, bound_port)``。
+
+    把"AF_INET 的 ``getsockname`` 一定返回 ``tuple[str, int]``"这个静态
+    事实集中收敛在这里，调用方不必再写 ``cast``。
+    """
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    sock.bind((host, port))
+    sock.listen(backlog)
+    bound_host, bound_port = cast(tuple[str, int], sock.getsockname())
+    return sock, bound_host, bound_port
+
+
+def _recv_exact(conn: socket.socket, n: int) -> bytes | None:
+    """从 ``conn`` 上读满 ``n`` 字节；对端已关闭则返回 ``None``。
+
+    单次 ``recv`` 不保证读够请求长度（TCP 半包），且对端关闭时
+    ``recv`` 会立刻返回 ``b""``。任何"按长度循环 recv"的实现都必须显式
+    处理 EOF，否则在客户端中途断连时会陷入死循环。
+    """
+    buf = bytearray()
+    while len(buf) < n:
+        try:
+            chunk = conn.recv(n - len(buf))
+        except (ConnectionError, OSError):
+            return None
+        if not chunk:
+            return None
+        buf.extend(chunk)
+    return bytes(buf)
+
+
+@final
+class _LogRecordStreamHandler(socketserver.StreamRequestHandler):
+    """处理一个客户端连接上的连续 LogRecord 流。
+
+    协议沿用标准库 :class:`logging.handlers.SocketHandler`：
+    ``[uint32 大端长度][pickle 字节]``，可在同一连接上重复出现。
+    """
+
+    @override
+    def handle(self) -> None:
+        conn = cast(socket.socket, self.connection)
+        while True:
+            header = _recv_exact(conn, 4)
+            if header is None:
+                break
+            slen = cast(int, struct.unpack(">L", header)[0])
+            if slen == 0 or slen > _MAX_RECORD_BYTES:
+                break
+            body = _recv_exact(conn, slen)
+            if body is None:
+                break
+            try:
+                obj = cast(object, pickle.loads(body))
+            except Exception:
+                # 单条记录损坏不应连累整条连接；继续读下一条。
+                continue
+            if not isinstance(obj, dict):
+                continue
+            record = logging.makeLogRecord(cast(dict[str, object], obj))
+            logging.getLogger(record.name).handle(record)
+
+
+@final
+class _LogRecordSocketReceiver(socketserver.ThreadingTCPServer):
+    """基于 :class:`socketserver.ThreadingTCPServer` 的接收器。
+
+    复用外部已 ``bind`` 好的监听 socket，本类不再自己 ``bind``/``listen``。
+    """
+
+    allow_reuse_address: bool = True
+    daemon_threads: bool = True
+
+    @override
+    def __init__(self, listening_sock: socket.socket) -> None:
+        addr = cast(tuple[str, int], listening_sock.getsockname()[:2])
+        # 走父类正常流程以建立 BaseServer 内部状态（shutdown 标志等），
+        # 但通过 ``bind_and_activate=False`` 跳过它自己的 bind/listen——
+        # 这个 socket 已经由调用方绑好。
+        super().__init__(addr, _LogRecordStreamHandler, bind_and_activate=False)
+        # 父类构造时仍会 ``self.socket = socket.socket(...)`` 占坑，
+        # 这里替换成真正复用的 socket，并把临时占位关闭掉。
+        try:
+            self.socket.close()
+        except OSError:
+            pass
+        self.socket = listening_sock
+        self.server_address = addr
+
+
+def _build_handlers(
+    log_file: str | None,
+    stream: bool,
+    console_fmt: str,
+    file_fmt: str,
+    datefmt: str | None,
+) -> list[logging.Handler]:
+    """根据用户传入的参数组合出落地用的 handler 列表。"""
+    handlers: list[logging.Handler] = []
+    if log_file:
+        # 按天轮转，每天 0 点切一份，最多保留 365 天历史。
+        fh = TimedRotatingFileHandler(
+            log_file,
+            when="midnight",
+            interval=1,
+            backupCount=365,
+            encoding="utf-8",
+        )
+        fh.setFormatter(FileFormatter(fmt=file_fmt, datefmt=datefmt))
+        handlers.append(fh)
+    if stream:
+        sh = logging.StreamHandler(stream=sys.stderr)
+        sh.setFormatter(ColorFormatter(fmt=console_fmt, datefmt=datefmt))
+        handlers.append(sh)
+    return handlers

kitty_logger-0.2.0.dev3/src/kitty_logger/_server_main.py

@@ -0,0 +1,129 @@
+"""kitty_logger 服务子进程入口。
+
+通过 ``python -m kitty_logger._server_main`` 启动，由
+:func:`kitty_logger.setup_logging` 内部用 :class:`subprocess.Popen` 拉起。
+本模块不是给最终用户的接口。
+
+握手 / 生命周期协议
+--------------------
+
+整套机制只用三条标准管道，不需要 ``pass_fds``，所以天然跨平台：
+
+* ``stdin``  — 父→子，**parent-alive**：父进程保持 write 端打开但不写。
+  父进程任何原因退出（``exit`` / ``kill -9`` / 段错误），内核会关掉它持有
+  的写端 fd，子进程在本端 ``read()`` 立刻返回 ``b""`` → 触发优雅退出。
+* ``stdout`` — 子→父，**启动握手**：子进程 ``bind+listen`` 成功后写出
+  ``"PORT <port>\\n"`` 然后 ``close``，握手即结束；之后不再使用 stdout
+  以避免后续误用 ``print`` 污染父进程的读端。
+* ``stderr`` — 子→父，**日志落地**：直接继承父进程的 stderr/tty。
+  ``--stream`` 控制是否给 root logger 挂上 :class:`logging.StreamHandler`。
+
+命令行参数对应 :func:`kitty_logger.setup_logging` 的同名参数。
+"""
+
+import argparse
+import logging
+import sys
+import threading
+
+from ._server import _LogRecordSocketReceiver, _bind_loopback, _build_handlers
+
+
+def _parse_args() -> argparse.Namespace:
+    ap = argparse.ArgumentParser(prog="kitty_logger._server_main", add_help=False)
+    ap.add_argument("--host", required=True)
+    ap.add_argument("--port", type=int, required=True)
+    ap.add_argument("--level", type=int, required=True)
+    ap.add_argument("--log-file", default=None)
+    ap.add_argument("--stream", action="store_true")
+    ap.add_argument("--console-fmt", required=True)
+    ap.add_argument("--file-fmt", required=True)
+    ap.add_argument("--datefmt", default=None)
+    return ap.parse_args()
+
+
+def _emit_handshake(port: int) -> None:
+    """把 ``"PORT <port>\\n"`` 写到 stdout 并主动 close。
+
+    主动 close 等于显式宣告"握手结束"——之后任何对 ``sys.stdout`` 的
+    误用都不会再污染父进程的读端，父进程的 ``readline()`` 也只会看到
+    我们刚写的这一行。
+    """
+    sys.stdout.write(f"PORT {port}\n")
+    sys.stdout.flush()
+    try:
+        sys.stdout.close()
+    except OSError:
+        pass
+
+
+def _emit_handshake_error(msg: str) -> None:
+    """启动失败时通过 stdout 报错，让父端 ``readline()`` 看到非 ``PORT`` 行。"""
+    try:
+        sys.stdout.write(f"ERROR {msg}\n")
+        sys.stdout.flush()
+        sys.stdout.close()
+    except OSError:
+        pass
+
+
+def main() -> None:
+    args = _parse_args()
+
+    # 先 bind+listen，这一步任何失败都通过 stdout 上报给父进程，让 setup_logging
+    # 能在主进程线程中以 ``RuntimeError`` 形式抛出，而不是父子双方各自卡住。
+    try:
+        sock, _bound_host, bound_port = _bind_loopback(args.host, args.port)
+    except OSError as e:
+        _emit_handshake_error(f"bind failed: {e}")
+        sys.exit(2)
+
+    _emit_handshake(bound_port)
+
+    # spawn 出来的全新解释器，root logger 默认无 handler；保险起见仍清一遍
+    # 以便重复初始化场景下保持幂等。
+    root = logging.getLogger()
+    for h in list(root.handlers):
+        root.removeHandler(h)
+    for h in _build_handlers(
+        args.log_file, args.stream, args.console_fmt, args.file_fmt, args.datefmt
+    ):
+        root.addHandler(h)
+    root.setLevel(args.level)
+
+    server = _LogRecordSocketReceiver(sock)
+
+    def _watch_parent_alive() -> None:
+        """父进程持有 stdin 的写端；任何原因（正常退出 / SIGKILL / 段错误）
+        让父进程消失，内核都会关掉它的 fd，本端 ``read()`` 会立刻返回
+        ``b""``（EOF）。借此触发自我退出，避免变成孤儿进程。
+
+        正常生命周期下父进程也通过 ``proc.stdin.close()`` 主动触发同一
+        条 EOF 路径，把"父退出 / 父主动 shutdown" 收敛为同一种处理。
+        """
+        try:
+            while True:
+                data = sys.stdin.buffer.read(64)
+                if not data:
+                    break
+        except (OSError, ValueError):
+            pass
+        finally:
+            server.shutdown()
+
+    threading.Thread(
+        target=_watch_parent_alive, name="kitty-logger-parent-watch", daemon=True
+    ).start()
+
+    try:
+        server.serve_forever()
+    finally:
+        try:
+            server.server_close()
+        except OSError:
+            pass
+        logging.shutdown()
+
+
+if __name__ == "__main__":
+    main()

{kitty_logger-0.2.0.dev2 → kitty_logger-0.2.0.dev3}/src/kitty_logger/_setup.py

@@ -6,13 +6,12 @@ import logging
 import multiprocessing as mp
 import os
 import socket
-from multiprocessing.process import BaseProcess
-from multiprocessing.synchronize import Event as MpEvent
-from typing import Literal, TypedDict, TypeGuard, cast
+import subprocess
+import sys
+from typing import IO, Literal, TypedDict, TypeGuard, cast
 
 from ._env import ENV_HOST, ENV_LEVEL, ENV_PORT
 from ._formatters import DEFAULT_CONSOLE_FMT, DEFAULT_FILE_FMT
-from ._server import run_server
 
 
 class _NotRunningState(TypedDict):
@@ -20,17 +19,13 @@ class _NotRunningState(TypedDict):
     host: None
     port: None
     proc: None
-    shutdown_event: None
-    parent_alive_send: None
 
 
 class _RunningState(TypedDict):
     running: Literal[True]
     host: str
     port: int
-    proc: BaseProcess
-    shutdown_event: MpEvent
-    parent_alive_send: socket.socket
+    proc: subprocess.Popen[bytes]
 
 
 type _ServerState = _NotRunningState | _RunningState
@@ -42,8 +37,6 @@ def _make_not_running_state() -> _NotRunningState:
         "host": None,
         "port": None,
         "proc": None,
-        "shutdown_event": None,
-        "parent_alive_send": None,
     }
 
 
@@ -103,20 +96,65 @@ def _check_loopback_only(host: str) -> None:
         )
 
 
-def _bind_ipv4_listener(
-    host: str, port: int, backlog: int = 128
-) -> tuple[socket.socket, str, int]:
-    """创建并绑定一个 ``AF_INET`` TCP 监听 socket。
+def _read_handshake(stdout: IO[bytes], proc: subprocess.Popen[bytes]) -> int:
+    """从服务子进程的 stdout 读一行握手信息，返回服务真实绑定的端口。
 
-    把"AF_INET 的 ``getsockname`` 一定返回 ``tuple[str, int]``"这个静态
-    事实集中在这里收敛，调用方就不再需要写 ``cast``。
+    协议在 :mod:`kitty_logger._server_main` 模块顶部说明。本函数把所有
+    非 ``"PORT <int>"`` 情况都收敛成 :class:`RuntimeError`：握手通道既然
+    被设计成 stdout，就不允许除握手以外的任何字节出现。
     """
-    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
-    sock.bind((host, port))
-    sock.listen(backlog)
-    bound_host, bound_port = cast(tuple[str, int], sock.getsockname())
-    return sock, bound_host, bound_port
+    line = stdout.readline()
+    if not line:
+        # readline 返回空字节即对端 close 且没写任何东西——子进程在握手前
+        # 就退出了。等子进程结束以拿到 returncode 一并报告。
+        rc = proc.wait(timeout=2.0) if proc.poll() is None else proc.returncode
+        raise RuntimeError(
+            f"kitty_logger 服务子进程在握手前就退出了（exit code {rc}）。"
+        )
+    text = line.decode("utf-8", errors="replace").rstrip("\r\n")
+    if text.startswith("PORT "):
+        try:
+            return int(text.split(" ", 1)[1])
+        except (ValueError, IndexError):
+            pass
+    if text.startswith("ERROR "):
+        raise RuntimeError(f"kitty_logger 服务子进程启动失败：{text[len('ERROR '):]}")
+    raise RuntimeError(f"kitty_logger 服务子进程握手协议异常，收到：{text!r}")
+
+
+def _build_server_argv(
+    host: str,
+    port: int,
+    level: int,
+    log_file: str | None,
+    stream: bool,
+    console_fmt: str,
+    file_fmt: str,
+    datefmt: str | None,
+) -> list[str]:
+    """把 ``setup_logging`` 的参数翻译成服务子进程的命令行参数。"""
+    argv = [
+        sys.executable,
+        "-m",
+        "kitty_logger._server_main",
+        "--host",
+        host,
+        "--port",
+        str(port),
+        "--level",
+        str(level),
+        "--console-fmt",
+        console_fmt,
+        "--file-fmt",
+        file_fmt,
+    ]
+    if log_file is not None:
+        argv += ["--log-file", log_file]
+    if stream:
+        argv += ["--stream"]
+    if datefmt is not None:
+        argv += ["--datefmt", datefmt]
+    return argv
 
 
 def setup_logging(
@@ -131,7 +169,7 @@ def setup_logging(
 ) -> tuple[str, int]:
     """在主进程里启动跨进程日志服务，返回服务真实绑定到的 ``(host, port)``。
 
-    在一个独立的 ``spawn`` 子进程里运行 TCP 接收器，把所有
+    在一个独立的 :class:`subprocess.Popen` 子进程里运行 TCP 接收器，把所有
     :class:`logging.LogRecord` 写到 ``log_file`` 和/或 ``stderr``。同时把
     ``KITTY_LOGGER_HOST`` / ``KITTY_LOGGER_PORT`` / ``KITTY_LOGGER_LEVEL``
     写入 :data:`os.environ`，使得后续 ``spawn`` 出来的子进程可以无配置地
@@ -141,16 +179,6 @@ def setup_logging(
     无颜色的 :class:`FileFormatter`，两者均使用毫秒级时间戳。
 
     幂等：重复调用直接返回已记录的 ``(host, port)``，不会重复启动子进程。
-    在 ``multiprocessing`` 启动的子进程里调用本函数时，会自动判断当前
-    不是原始主进程并直接返回从父进程继承的 ``(host, port)``，本身不再
-    启动新的日志服务——这意味着用户可以把 ``setup_logging()`` 直接放在
-    模块顶层而不必用 ``if __name__ == "__main__":`` 包裹。
-
-    本函数同时把主进程内 ``logging.getLogger("kitty")`` 这一个 logger
-    初始化好——挂上指向日志服务的 :class:`SocketHandler`、设置 level、
-    并把 ``propagate`` 关掉。所有通过 :func:`kitty_logger.getLogger`
-    取到的子 logger 都挂在 ``kitty`` 这棵子树下，借标准库的祖先链冒泡到
-    ``kitty`` 的这个 handler 上，无需自己额外配置。
 
     :param log_file: 日志文件路径；``None`` 表示不落盘。
     :param level: 服务端 root logger 的级别，同时也是主进程 ``kitty``
@@ -177,18 +205,20 @@ def setup_logging(
        请使用 ``multiprocessing.get_context("spawn")``，或在顶层用
        ``if __name__ == "__main__":`` 守卫配合默认 ``spawn`` 行为。
     """
-    # ``multiprocessing`` 启动出来的子进程里再次执行 setup_logging（典型
-    # 场景：spawn bootstrap 通过 ``_fixup_main_from_path`` 重新 import 主
-    # 脚本，从而触发主脚本顶层那行 ``kitty_logger.setup_logging(...)``）
-    # 一律走 no-op：日志服务只该在原始主进程里跑一份；子进程通过继承的
-    # ENV 找服务地址，``getLogger`` 第一次被调用时再按需挂 SocketHandler。
+    # ``multiprocessing.Process`` 启动出来的 spawn 子进程在 bootstrap 阶段会
+    # 通过 ``_fixup_main_from_path`` 重新执行用户主脚本顶层；如果用户把
+    # ``setup_logging(...)`` 写在了模块顶层，本函数会在每个 worker 子进程里
+    # 也被调到。此时不应再起一份服务，而是直接返回从父进程继承的 ENV——
+    # 让 worker 的 getLogger 自动连上原始服务即可。
+    # 注意：本库自己 ``Popen`` 拉起的服务子进程不会触发这条路径，因为它
+    # 跑的是 ``-m kitty_logger._server_main``，并不会回头执行用户主脚本。
     if mp.parent_process() is not None:
         host_env = os.environ.get(ENV_HOST)
         port_env = os.environ.get(ENV_PORT)
         if not host_env or not port_env:
             raise RuntimeError(
-                "kitty_logger 在子进程里被调用 setup_logging，但没有从父进程"
-                "继承到 KITTY_LOGGER_HOST / KITTY_LOGGER_PORT 环境变量。"
+                "kitty_logger 在 multiprocessing 子进程里被调用 setup_logging，"
+                "但没有从父进程继承到 KITTY_LOGGER_HOST / KITTY_LOGGER_PORT 环境变量。"
                 "请确保父进程已经先调用 setup_logging() 后再 spawn 本进程。"
             )
         return host_env, int(port_env)
@@ -199,57 +229,79 @@ def setup_logging(
 
     _check_loopback_only(host)
 
-    # 在父进程里直接 bind，使 ``port=0`` 也能同步拿到真实端口；然后把
-    # 已绑定的 socket 交给服务子进程使用。
-    listening_sock, bound_host, bound_port = _bind_ipv4_listener(host, port)
+    argv = _build_server_argv(
+        host=host,
+        port=port,
+        level=level,
+        log_file=log_file,
+        stream=stream,
+        console_fmt=console_fmt,
+        file_fmt=file_fmt,
+        datefmt=datefmt,
+    )
+    # 把本包所在目录拼进子进程的 ``PYTHONPATH``，保证子进程的解释器能
+    # ``import`` 到 ``kitty_logger._server_main``。已经 ``pip install`` 装到
+    # site-packages 的场景下这步是冗余但无害的；开发场景（仅靠
+    # ``pytest --pythonpath=src`` 把 ``src/`` 临时拼到 pytest 自己的 sys.path）
+    # 则必须显式传递，否则全新启动的子解释器看不到包路径。
+    pkg_parent = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    child_env = os.environ.copy()
+    existing = child_env.get("PYTHONPATH", "")
+    child_env["PYTHONPATH"] = pkg_parent + (os.pathsep + existing if existing else "")
+
+    # 三条管道的角色见 :mod:`kitty_logger._server_main` 模块文档：
+    #   stdin  = 父→子，仅用于探活（父挂掉子读到 EOF）；
+    #   stdout = 子→父，仅用于一次握手；
+    #   stderr = 子→父，直通父的 stderr/tty，由服务端 StreamHandler 落地日志。
+    proc: subprocess.Popen[bytes] = subprocess.Popen(
+        argv,
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=None,
+        env=child_env,
+    )
+    # ``readline`` 用 buffered IO；为保证我们看到子进程的 ``flush+close``
+    # 之后立刻拿到那一行，要走二进制接口手动解码。
+    stdout = cast(IO[bytes], proc.stdout)
+    try:
+        bound_port = _read_handshake(stdout, proc)
+    except BaseException:
+        # 握手失败时主动结束子进程，避免留下孤儿。
+        try:
+            if proc.stdin is not None:
+                proc.stdin.close()
+        except OSError:
+            pass
+        try:
+            proc.kill()
+        except OSError:
+            pass
+        try:
+            proc.wait(timeout=2.0)
+        except subprocess.TimeoutExpired:
+            pass
+        raise
+    # 握手通道在父侧也立刻关掉，子侧已 close，保留只是浪费 fd。
+    try:
+        stdout.close()
+    except OSError:
+        pass
 
-    # 父进程存活监测：父进程持有 send 端，子进程持有 recv 端。父进程哪怕
-    # 被 ``kill -9`` 也会让内核 close 它的 fd，子进程在另一端会读到 EOF。
-    parent_alive_send, parent_alive_recv = socket.socketpair()
+    bound_host = host
 
-    # ENV 必须在 ``proc.start()`` 之前写入：spawn 出的服务子进程虽然通过
-    # kwargs 拿到了所有运行参数，但它在 bootstrap 阶段会用
-    # ``_fixup_main_from_path`` 重新 import 主脚本，主脚本顶层若间接触发
-    # ``kitty_logger.getLogger(...)``（例如某个被顶层 import 的库在模块级
-    # 调用了 getLogger），此时子进程必须已经能从 ENV 读到服务地址，否则
-    # 子进程会在 import 阶段抛 RuntimeError 而异常退出。
+    # 这一段必须在 spawn 任何后代之前完成：后代要靠这些 ENV 找服务地址。
+    # ``Popen`` 不会像 ``multiprocessing.Process`` 那样去 re-import 主脚本，
+    # 因此本函数本身可以放在模块顶层，无需 ``if __name__ == "__main__":``
+    # 守卫——服务子进程不会回头执行用户主脚本的任何顶层代码。
     os.environ[ENV_HOST] = bound_host
     os.environ[ENV_PORT] = str(bound_port)
     os.environ[ENV_LEVEL] = str(level)
 
-    ctx = mp.get_context("spawn")
-    shutdown_event = ctx.Event()
-    proc = ctx.Process(
-        target=run_server,
-        kwargs=dict(
-            listening_sock=listening_sock,
-            shutdown_event=shutdown_event,
-            parent_alive_recv=parent_alive_recv,
-            level=level,
-            log_file=log_file,
-            stream=stream,
-            console_fmt=console_fmt,
-            file_fmt=file_fmt,
-            datefmt=datefmt,
-        ),
-        name="kitty-logger-server",
-        daemon=False,
-    )
-    proc.start()
-
-    # 父进程不再需要这两个 socket 副本：
-    # - listening_sock 已经完全交给子进程；
-    # - parent_alive_recv 必须只由子进程持有，否则 EOF 永远不会到来。
-    listening_sock.close()
-    parent_alive_recv.close()
-
     new_state: _RunningState = {
         "running": True,
         "host": bound_host,
         "port": bound_port,
         "proc": proc,
-        "shutdown_event": shutdown_event,
-        "parent_alive_send": parent_alive_send,
     }
     _state = new_state
 
@@ -306,36 +358,42 @@ def shutdown_logging(timeout: float = 5.0) -> None:
     if not _is_running(state=_state):
         return
 
-    event: MpEvent = _state["shutdown_event"]
-    proc: BaseProcess = _state["proc"]
-    parent_alive_send: socket.socket = _state["parent_alive_send"]
+    proc: subprocess.Popen[bytes] = _state["proc"]
     host: str = _state["host"]
     port: int = _state["port"]
 
     _state = _make_not_running_state()
 
+    # 关掉 stdin 的写端 = 子进程那侧 ``read()`` 立刻得到 EOF，
+    # 触发 ``server.shutdown()`` 走优雅退出路径。这是首选信号。
+    if proc.stdin is not None:
+        try:
+            proc.stdin.close()
+        except OSError:
+            pass
+
     try:
-        event.set()
-    except Exception:
-        pass
-    # 主动关闭父端 socket，作为 mp.Event 的兜底关闭信号——子进程的
-    # ``_watch_parent_alive`` 线程会立刻读到 EOF。
-    try:
-        parent_alive_send.close()
-    except OSError:
-        pass
+        proc.wait(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        try:
+            proc.terminate()
+        except OSError:
+            pass
+        try:
+            proc.wait(timeout=1.0)
+        except subprocess.TimeoutExpired:
+            pass
 
-    proc.join(timeout)
-    if proc.is_alive():
-        proc.terminate()
-        proc.join(1.0)
-    if proc.is_alive():
+    if proc.poll() is None:
         # ``terminate`` 没杀掉（被 IO 阻塞在不可中断状态）：兜底 kill。
         try:
             proc.kill()
-        except Exception:
+        except OSError:
+            pass
+        try:
+            proc.wait(timeout=1.0)
+        except subprocess.TimeoutExpired:
             pass
-        proc.join(1.0)
 
     # 服务进程已经死了，本进程里指向它的 SocketHandler 必须全部取下，
     # 否则后续 logging 调用会向一个失效端口发送，触发静默丢日志。

{kitty_logger-0.2.0.dev2 → kitty_logger-0.2.0.dev3/src/kitty_logger.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kitty_logger
-Version: 0.2.0.dev2
+Version: 0.2.0.dev3
 Summary: Cross-process logging via a dedicated log server process and SocketHandler.
 Author: Kitty
 License: MIT
@@ -55,13 +55,15 @@ if __name__ == "__main__":
 ## API
 
 - `setup_logging(log_file=None, level=logging.INFO, host="127.0.0.1", port=0, stream=True, console_fmt=..., file_fmt=..., datefmt=None) -> (host, port)`
-  启动日志服务子进程（始终使用 `spawn`）。幂等。已通过 `atexit` 注册清理。
-  `port=0` 让操作系统挑选空闲端口；返回真实绑定到的 `(host, port)`。
+  通过 `subprocess.Popen` 启动一个独立的日志服务子进程（不依赖
+  `multiprocessing`，因此**不会回头执行用户主脚本的任何顶层代码**）。
+  幂等。已通过 `atexit` 注册清理。`port=0` 让操作系统挑选空闲端口；返回
+  真实绑定到的 `(host, port)`。
   **`host` 必须是 loopback**——绑定非 loopback 地址会直接 `ValueError`。
   同时把主进程内 `logging.getLogger("kitty")` 这一个 logger 初始化好——挂上
   `SocketHandler`、设置 level、关闭 `propagate`。**不动 root logger**。
-  在 `multiprocessing` 启动的子进程里再次调用本函数会自动 no-op，仅返回
-  从父进程继承的 `(host, port)`，因此可以直接放在模块顶层而不必用
+  在用户用 `multiprocessing` 启动的子进程里再次调用本函数会自动 no-op，
+  仅返回从父进程继承的 `(host, port)`，因此可以直接放在模块顶层而不必用
   `if __name__ == "__main__":` 包裹。
 - `getLogger(name=None) -> logging.Logger`
   返回挂在 `kitty` 命名空间下的 logger：`getLogger("foo")` 实际拿到的是

{kitty_logger-0.2.0.dev2 → kitty_logger-0.2.0.dev3}/src/kitty_logger.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ src/kitty_logger/_client.py
 src/kitty_logger/_env.py
 src/kitty_logger/_formatters.py
 src/kitty_logger/_server.py
+src/kitty_logger/_server_main.py
 src/kitty_logger/_setup.py
 src/kitty_logger.egg-info/PKG-INFO
 src/kitty_logger.egg-info/SOURCES.txt

{kitty_logger-0.2.0.dev2 → kitty_logger-0.2.0.dev3}/tests/test_kitty_logger.py

@@ -310,50 +310,6 @@ def test_child_logger_propagates_to_kitty(tmp_path: Path):
     _wait_for_lines(log_path, lambda t: "from-foo-bar" in t and "kitty.foo.bar" in t)
 
 
-def test_server_resilient_to_module_level_getlogger_in_user_script(tmp_path: Path):
-    """回归：用户主脚本顶层 import 的库在模块级调用 kitty_logger.getLogger(...)
-    时，服务子进程在 ``spawn`` bootstrap 阶段也会触发该模块级调用，从而把
-    服务自身的 ``kitty`` logger 挂上一个指向本服务监听端口的 SocketHandler，
-    使得接收到的 record 顺着祖先链被发回服务自身、永远不落地。
-    ``run_server`` 必须在开始 serve 之前把 ``kitty`` logger 还原成无 handler、
-    propagate=True 的状态。
-    """
-    import subprocess
-    import sys as _sys
-
-    fake_lib = tmp_path / "fake_lib.py"
-    fake_lib.write_text(
-        "import kitty_logger\n" "log = kitty_logger.getLogger(__name__)\n",
-        encoding="utf-8",
-    )
-
-    log_file = tmp_path / "app.log"
-    main_py = tmp_path / "main.py"
-    main_py.write_text(
-        "import sys, logging, time\n"
-        f"sys.path.insert(0, {str(tmp_path)!r})\n"
-        "from kitty_logger import setup_logging, getLogger\n"
-        "if __name__ == '__main__':\n"
-        f"    setup_logging(log_file={str(log_file)!r}, stream=False, level=logging.DEBUG)\n"
-        "import fake_lib  # noqa: E402,F401  -- 模块级 getLogger 触发回归路径\n"
-        "if __name__ == '__main__':\n"
-        "    getLogger('user').info('real-user-log')\n"
-        "    time.sleep(1)\n",
-        encoding="utf-8",
-    )
-
-    result = subprocess.run(
-        [_sys.executable, str(main_py)],
-        capture_output=True,
-        text=True,
-        timeout=20,
-    )
-    assert result.returncode == 0, f"stderr={result.stderr}"
-
-    text = _wait_for_lines(log_file, lambda t: "real-user-log" in t)
-    assert "kitty.user" in text
-
-
 def _spawn_worker_calling_setup(idx: int, log_file: str) -> None:
     """子进程里也调一次 setup_logging：应该是 no-op，仅返回从 ENV 继承的端点。"""
     h, p = kitty_logger.setup_logging(log_file=log_file, stream=False)

kitty_logger-0.2.0.dev2/src/kitty_logger/_server.py

@@ -1,228 +0,0 @@
-"""日志服务子进程实现。
-
-工作模型：
-
-1. 父进程在 :func:`kitty_logger.setup_logging` 中先 ``bind`` 一个 TCP
-   监听 socket，再连同其他参数一起传给一个 ``spawn`` 启动的子进程。
-2. 子进程在 :func:`run_server` 里基于这个 socket 跑 ``ThreadingTCPServer``，
-   反序列化客户端通过 :class:`logging.handlers.SocketHandler` 发来的
-   ``LogRecord`` 字节流，再用本进程里配置的 handler（FileHandler /
-   StreamHandler）落地。
-"""
-
-import logging
-import pickle
-import socket
-import socketserver
-import struct
-import sys
-import threading
-from logging.handlers import TimedRotatingFileHandler
-from multiprocessing.synchronize import Event as MpEvent
-from typing import cast, final, override
-
-from ._formatters import ColorFormatter, FileFormatter
-
-# 单条 LogRecord 序列化后字节数上限。任何正常 LogRecord 都远小于此值；
-# 超过即视为协议错位或异常流量，直接断开连接，避免一次性分配巨大缓冲区
-# 触发 OOM。
-_MAX_RECORD_BYTES = 16 * 1024 * 1024
-
-
-def _recv_exact(conn: socket.socket, n: int) -> bytes | None:
-    """从 ``conn`` 上读满 ``n`` 字节；对端已关闭则返回 ``None``。
-
-    单次 ``recv`` 不保证读够请求长度（TCP 半包），且对端关闭时
-    ``recv`` 会立刻返回 ``b""``。任何"按长度循环 recv"的实现都必须显式
-    处理 EOF，否则在客户端中途断连时会陷入死循环。
-    """
-    buf = bytearray()
-    while len(buf) < n:
-        try:
-            chunk = conn.recv(n - len(buf))
-        except (ConnectionError, OSError):
-            return None
-        if not chunk:
-            return None
-        buf.extend(chunk)
-    return bytes(buf)
-
-
-@final
-class _LogRecordStreamHandler(socketserver.StreamRequestHandler):
-    """处理一个客户端连接上的连续 LogRecord 流。
-
-    协议沿用标准库 :class:`logging.handlers.SocketHandler`：
-    ``[uint32 大端长度][pickle 字节]``，可在同一连接上重复出现。
-    """
-
-    @override
-    def handle(self) -> None:
-        conn = cast(socket.socket, self.connection)
-        while True:
-            header = _recv_exact(conn, 4)
-            if header is None:
-                break
-            slen = cast(int, struct.unpack(">L", header)[0])
-            if slen == 0 or slen > _MAX_RECORD_BYTES:
-                break
-            body = _recv_exact(conn, slen)
-            if body is None:
-                break
-            try:
-                obj = cast(object, pickle.loads(body))
-            except Exception:
-                # 单条记录损坏不应连累整条连接；继续读下一条。
-                continue
-            if not isinstance(obj, dict):
-                continue
-            record = logging.makeLogRecord(cast(dict[str, object], obj))
-            logging.getLogger(record.name).handle(record)
-
-
-@final
-class _LogRecordSocketReceiver(socketserver.ThreadingTCPServer):
-    """基于 :class:`socketserver.ThreadingTCPServer` 的接收器。
-
-    复用父进程已 ``bind`` 好的监听 socket，本类不再自己 ``bind``/``listen``。
-    """
-
-    allow_reuse_address: bool = True
-    daemon_threads: bool = True
-
-    @override
-    def __init__(self, listening_sock: socket.socket) -> None:
-        addr = cast(tuple[str, int], listening_sock.getsockname()[:2])
-        # 走父类正常流程以建立 BaseServer 内部状态（shutdown 标志等），
-        # 但通过 ``bind_and_activate=False`` 跳过它自己的 bind/listen——
-        # 这个 socket 已经由父进程绑好。
-        super().__init__(addr, _LogRecordStreamHandler, bind_and_activate=False)
-        # 父类构造时仍会 ``self.socket = socket.socket(...)`` 占坑，
-        # 这里替换成真正复用的 socket，并把临时占位关闭掉。
-        try:
-            self.socket.close()
-        except OSError:
-            pass
-        self.socket = listening_sock
-        self.server_address = addr
-
-
-def _build_handlers(
-    log_file: str | None,
-    stream: bool,
-    console_fmt: str,
-    file_fmt: str,
-    datefmt: str | None,
-) -> list[logging.Handler]:
-    """根据用户传入的参数组合出落地用的 handler 列表。"""
-    handlers: list[logging.Handler] = []
-    if log_file:
-        # 按天轮转，每天 0 点切一份，最多保留 365 天历史。
-        fh = TimedRotatingFileHandler(
-            log_file,
-            when="midnight",
-            interval=1,
-            backupCount=365,
-            encoding="utf-8",
-        )
-        fh.setFormatter(FileFormatter(fmt=file_fmt, datefmt=datefmt))
-        handlers.append(fh)
-    if stream:
-        sh = logging.StreamHandler(stream=sys.stderr)
-        sh.setFormatter(ColorFormatter(fmt=console_fmt, datefmt=datefmt))
-        handlers.append(sh)
-    return handlers
-
-
-def run_server(
-    listening_sock: socket.socket,
-    shutdown_event: MpEvent,
-    parent_alive_recv: socket.socket,
-    level: int,
-    log_file: str | None,
-    stream: bool,
-    console_fmt: str,
-    file_fmt: str,
-    datefmt: str | None,
-) -> None:
-    """日志服务子进程入口函数。
-
-    通过 :mod:`multiprocessing` 在 ``spawn`` 出来的全新解释器里运行；
-    所有依赖参数显式从 ``kwargs`` 进入，不依赖父进程的全局状态。
-
-    :param listening_sock: 已经由父进程 ``bind`` + ``listen`` 好的 socket。
-    :param shutdown_event: 父进程通知子进程正常退出用的事件。
-    :param parent_alive_recv: ``socketpair`` 的接收端，用来侦测父进程死亡。
-    :param level: 服务端 root logger 级别。
-    :param log_file: 日志文件路径；``None`` 表示不落盘。
-    :param stream: 是否同时输出到 ``stderr``。
-    :param console_fmt: 控制台 handler 的 format 字符串。
-    :param file_fmt: 文件 handler 的 format 字符串。
-    :param datefmt: 时间戳的 ``strftime`` 格式；``None`` 走默认值。
-    """
-    # 子进程是 ``spawn`` 出来的全新解释器，root logger 默认无 handler；
-    # 但仍保险地清掉一遍以便重复初始化场景下的幂等性。
-    root = logging.getLogger()
-    for h in list(root.handlers):
-        root.removeHandler(h)
-    for h in _build_handlers(log_file, stream, console_fmt, file_fmt, datefmt):
-        root.addHandler(h)
-    root.setLevel(level)
-
-    # 防御 ``spawn`` bootstrap：服务子进程在 ``_fixup_main_from_path`` 重新
-    # import 用户主脚本时，主脚本顶层 import 的第三方库可能在模块级调用
-    # ``kitty_logger.getLogger(...)``。由于父进程已经把 KITTY_LOGGER_HOST/
-    # PORT/LEVEL 写进 ENV，本服务子进程里的 ``_ensure_kitty_handler()`` 会
-    # 顺利地往 ``kitty`` logger 上挂一个指向本服务自己监听端口的
-    # :class:`SocketHandler`，并把 ``propagate`` 关掉。结果是：本服务接收
-    # 到记录后调 ``logging.getLogger(record.name).handle(record)``，记录
-    # 沿祖先链冒泡到 ``kitty`` 时被这个 handler 捞走，原样发回给本服务
-    # 自身（形成网络回环），同时因为 ``propagate=False`` 而不会再到达
-    # root 上配置好的落地 handler，外部表现为日志凭空消失。
-    # 因此在开始 serve 之前，强制把 ``kitty`` logger 还原成"无 handler、
-    # propagate=True、level=NOTSET"，让记录稳稳地冒泡到 root。
-    kitty = logging.getLogger("kitty")
-    for h in list(kitty.handlers):
-        kitty.removeHandler(h)
-        try:
-            h.close()
-        except OSError:
-            pass
-    kitty.propagate = True
-    kitty.setLevel(logging.NOTSET)
-
-    server = _LogRecordSocketReceiver(listening_sock)
-
-    def _wait_shutdown() -> None:
-        _ = shutdown_event.wait()
-        server.shutdown()
-
-    def _watch_parent_alive() -> None:
-        # 父进程持有 socketpair 的发送端；任意原因（正常退出 / SIGKILL /
-        # 段错误）使父进程消失，内核都会关闭它的 fd，本端 ``recv`` 会立刻
-        # 返回空字节（EOF）。借此触发自我退出，避免变成孤儿进程。
-        try:
-            while True:
-                data = parent_alive_recv.recv(64)
-                if not data:
-                    break
-        except OSError:
-            pass
-        finally:
-            try:
-                parent_alive_recv.close()
-            except OSError:
-                pass
-        shutdown_event.set()
-
-    threading.Thread(target=_wait_shutdown, daemon=True).start()
-    threading.Thread(target=_watch_parent_alive, daemon=True).start()
-
-    try:
-        server.serve_forever()
-    finally:
-        try:
-            server.server_close()
-        except OSError:
-            pass
-        logging.shutdown()