django-sqlite-ops 0.1.0a1__py3-none-any.whl

django_sqlite_ops/checks.py

@@ -0,0 +1,400 @@
+"""정적 시스템 체크 (DESIGN §6-1). 설정만 읽고 DB 를 열지 않는다.
+
+기준값은 ``database.recommended()`` 에서 읽는다. ``sqlite_database()`` 를 쓰지 않은
+설정(직접 쓴 dict, dj-lite 결과)도 같은 기준으로 검사한다.
+"""
+
+import os
+import re
+from collections.abc import Mapping
+from typing import Any
+from urllib.parse import unquote
+
+from django.conf import settings
+from django.core import checks
+
+from .database import DEFAULT_PROFILE, ENGINE, PROFILES, recommended
+
+__all__ = ["TAG", "check_deploy_settings", "check_settings", "register"]
+
+# Tags.database 를 쓰지 않는다. Django 6.1 은 --database 없이 돌면 database 태그 체크를 빼고
+# (6.1.2 django/core/checks/registry.py:89-93), 5.2 는 빼지 않는다(5.2.18 같은 파일의
+# run_checks :72-96 에 그 분기가 없다). 두 지원 버전에서 기본으로 돌도록 자체 태그를 쓴다.
+TAG = "sqlite_ops"
+
+# 식별자: "..." · `...` · [...] 인용, 또는 맨 이름. 값: 인용 문자열, 이름, 정수.
+_IDENT = r"""(?:"(?:[^"]|"")*"|`(?:[^`]|``)*`|\[[^\]]*\]|[A-Za-z_][A-Za-z0-9_$]*)"""
+_VALUE = r"""(?:'(?:[^']|'')*'|"(?:[^"]|"")*"|[A-Za-z_][A-Za-z0-9_$]*|[-+]?\d+)"""
+_PRAGMA = re.compile(
+    rf"""\s*PRAGMA\s+(?:(?P<schema>{_IDENT})\s*\.\s*)?(?P<name>{_IDENT})\s*
+        (?:=\s*(?P<eq>{_VALUE})|\(\s*(?P<call>{_VALUE})\s*\))?\s*""",
+    re.IGNORECASE | re.VERBOSE,
+)
+# SQLite 가 받는 journal_mode 값. 그 밖의 값은 SQLite 가 무시하므로 결과를 단정할 수 없다.
+_JOURNAL_MODES = frozenset({"DELETE", "TRUNCATE", "PERSIST", "MEMORY", "WAL", "OFF"})
+_QUOTES = {"'": "'", '"': '"', "`": "`", "[": "]"}
+
+
+def register() -> None:
+    checks.register(check_settings, TAG)
+    checks.register(check_deploy_settings, TAG, deploy=True)
+
+
+def _profile() -> tuple[str | None, checks.Error | None]:
+    config = getattr(settings, "SQLITE_OPS", {})
+    if not isinstance(config, Mapping):
+        return None, checks.Error(
+            f"SQLITE_OPS must be a dict, got {type(config).__name__}.",
+            hint=f'Use SQLITE_OPS = {{"PROFILE": "{DEFAULT_PROFILE}"}} (DESIGN §6-0).',
+            id="sqlite_ops.E001",
+        )
+    profile = config.get("PROFILE", DEFAULT_PROFILE)
+    if not isinstance(profile, str) or profile not in PROFILES:
+        return None, checks.Error(
+            f"Unknown SQLITE_OPS['PROFILE'] {profile!r}.",
+            hint=f"Use one of: {', '.join(PROFILES)} (DESIGN §6-0).",
+            id="sqlite_ops.E001",
+        )
+    return profile, None
+
+
+def _sqlite_aliases():
+    for alias, config in settings.DATABASES.items():
+        if isinstance(config, Mapping) and config.get("ENGINE") == ENGINE:
+            yield alias, config
+
+
+def _options(config: Mapping[str, Any]) -> Mapping[str, Any]:
+    options = config.get("OPTIONS") or {}
+    return options if isinstance(options, Mapping) else {}
+
+
+def _uri(name: Any) -> tuple[str, dict[str, list[str]]] | None:
+    """``file:`` URI 면 (파일명, 쿼리)를, 아니면 ``None`` 을 돌려준다.
+
+    SQLite 처럼 파일명은 첫 ``?``·``#`` 앞, 쿼리는 ``?`` 뒤 ``#`` 앞이다. 구분자로 먼저 나눈 뒤
+    파일명과 쿼리 키·값을 퍼센트 디코딩한다(인코딩된 ``%3F`` 를 구분자로 보지 않는다).
+    """
+    if isinstance(name, os.PathLike):
+        name = os.fspath(name)
+    if not isinstance(name, str) or not name.startswith("file:"):
+        return None
+    rest = name[len("file:") :]
+    if rest.startswith("//"):
+        # authority 는 "//" 뒤 다음 "/" 까지다(쿼리·프래그먼트 구분자보다 먼저 본다). 로컬
+        # authority 는 떼어 낸다. 그 밖의 authority 는 _uri_authority() 가 판정한다.
+        end = rest.find("/", 2)
+        rest = rest[end:] if end >= 0 else ""
+    rest = rest.split("#", 1)[0]
+    path, _, raw_query = rest.partition("?")
+    query: dict[str, list[str]] = {}
+    for part in raw_query.split("&"):
+        if part:
+            key, _, value = part.partition("=")
+            query.setdefault(unquote(key), []).append(unquote(value))
+    return unquote(path), query
+
+
+def _uri_authority(name: Any) -> str | None:
+    """``file://`` URI 의 authority 가 SQLite 가 받지 않는 값이면 그 값을, 아니면 ``None``.
+
+    SQLite 는 authority 로 빈 문자열과 ``localhost`` 만 받는다(https://www.sqlite.org/uri.html).
+    authority 는 ``//`` 뒤 다음 ``/`` 까지이고, 대소문자를 가리며 퍼센트 디코딩하지 않는다
+    (``LOCALHOST``·``%6cocalhost``·``localhost?mode=ro`` 는 연결 오류, 재현함). Windows 의
+    ``SQLITE_ALLOW_URI_AUTHORITY`` UNC 경로는 흉내 내지 않는다.
+    """
+    if isinstance(name, os.PathLike):
+        name = os.fspath(name)
+    if not isinstance(name, str) or not name.startswith("file://"):
+        return None
+    rest = name[len("file://") :]
+    end = rest.find("/")
+    authority = rest[:end] if end >= 0 else rest
+    return None if authority in ("", "localhost") else authority
+
+
+# SQLite 가 받는 값 (https://www.sqlite.org/uri.html, sqlite3_uri_boolean). 그 밖은 판정하지 않는다.
+_MODES = frozenset({"ro", "rw", "rwc", "memory"})
+_TRUE = frozenset({"1", "yes", "true", "on"})
+_FALSE = frozenset({"0", "no", "false", "off"})
+_ROLE_KEYS = ("mode", "immutable", "vfs")
+
+
+def _role(name: Any) -> tuple[str, str | None]:
+    """별칭의 역할과, 판정할 수 없을 때 그 이유를 돌려준다.
+
+    역할: ``"write"`` · ``"memory"`` · ``"read-only"`` · ``"vfs"`` · ``"unknown"``.
+    역할을 정하는 쿼리 키(``mode``·``immutable``·``vfs``)가 겹치거나 SQLite 표준 표기가 아니면,
+    또는 URI authority 가 빈 값·``localhost`` 가 아니면 ``"unknown"`` 이다. SQLite 의
+    중복·비표준 해석을 흉내 내지 않는다.
+    """
+    if isinstance(name, os.PathLike):
+        name = os.fspath(name)
+    if name == ":memory:":
+        return "memory", None
+    uri = _uri(name)
+    if uri is None:
+        return "write", None
+    authority = _uri_authority(name)
+    if authority is not None:
+        return "unknown", f"URI authority {authority!r} is not empty or 'localhost'"
+    path, query = uri
+    # SQLite 는 디코딩된 NUL 앞까지만 읽는다. 역할 키가 숨을 수 있으니 어느 키든 판정하지 않는다
+    if "\0" in path:
+        return "unknown", "the decoded file name contains NUL (%00)"
+    for key, values in query.items():
+        if "\0" in key or any("\0" in value for value in values):
+            return "unknown", f"query key {key!r} or its value contains NUL (%00)"
+    for key in _ROLE_KEYS:
+        if len(query.get(key, [])) > 1:
+            return "unknown", f"query key {key!r} is given more than once"
+    mode = query.get("mode", [None])[0]
+    if mode is not None and mode not in _MODES:
+        return "unknown", f"mode={mode!r} is not one of {', '.join(sorted(_MODES))}"
+    immutable = query.get("immutable", [None])[0]
+    if immutable is not None and immutable.lower() not in _TRUE | _FALSE:
+        return (
+            "unknown",
+            f"immutable={immutable!r} is not a boolean (1/0, yes/no, true/false, on/off)",
+        )
+    if path == ":memory:" or mode == "memory":
+        return "memory", None
+    if mode == "ro" or (immutable is not None and immutable.lower() in _TRUE):
+        return "read-only", None
+    if query.get("vfs") == ["litestream"]:
+        return "vfs", None
+    return "write", None
+
+
+def _is_litestream_vfs(name: Any) -> bool:
+    uri = _uri(name)
+    return uri is not None and uri[1].get("vfs") == ["litestream"]
+
+
+def _strip_comments(statement: str) -> str:
+    """SQL 주석(``--``, ``/* */``)을 공백으로 바꾼다. 인용 문자열·식별자 안은 그대로 둔다."""
+    out = []
+    i, n = 0, len(statement)
+    while i < n:
+        ch = statement[i]
+        if ch in _QUOTES:
+            close = _QUOTES[ch]
+            j = i + 1
+            while j < n:
+                if statement[j] == close:
+                    if close != "]" and statement[j + 1 : j + 2] == close:
+                        j += 2  # 겹친 인용 부호
+                        continue
+                    break
+                j += 1
+            out.append(statement[i : j + 1])
+            i = j + 1
+        elif statement.startswith("--", i):
+            j = statement.find("\n", i)
+            i = n if j < 0 else j
+            out.append(" ")
+        elif statement.startswith("/*", i):
+            j = statement.find("*/", i + 2)
+            i = n if j < 0 else j + 2
+            out.append(" ")
+        else:
+            out.append(ch)
+            i += 1
+    return "".join(out)
+
+
+def _unquote(token: str) -> str:
+    if token and token[0] in _QUOTES:
+        close = _QUOTES[token[0]]
+        inner = token[1:-1]
+        return inner if close == "]" else inner.replace(close * 2, close)
+    return token
+
+
+def _journal_mode(init_command: Any) -> tuple[str | None, str | None]:
+    """``init_command`` 에서 main 의 ``journal_mode`` 를 읽는다.
+
+    ``(마지막으로 확정된 값(대문자) 또는 None, 형식을 확정할 수 없는 첫 문장 또는 None)``.
+    Django 처럼 ``;`` 로 나눈 문장마다 본다. SQL 파서가 아니므로 ``journal_mode`` 를 언급하는데
+    아는 형식이 아니면 판정할 수 없다고 본다.
+    """
+    if not isinstance(init_command, str):
+        return None, None
+    mode = undetermined = None
+    for statement in init_command.split(";"):
+        cleaned = _strip_comments(statement)
+        if "journal_mode" not in cleaned.lower():
+            continue
+        match = _PRAGMA.fullmatch(cleaned)
+        if match is None:
+            undetermined = undetermined or statement.strip()
+            continue
+        if _unquote(match["name"]).lower() != "journal_mode":
+            continue
+        if match["schema"] and _unquote(match["schema"]).lower() != "main":
+            continue  # 다른 스키마(temp 등)는 이 DB 의 모드를 바꾸지 않는다
+        value = match["eq"] or match["call"]
+        if value is None:
+            continue  # 조회만 한다
+        value = _unquote(value).upper()
+        if value not in _JOURNAL_MODES:
+            undetermined = undetermined or statement.strip()
+            continue
+        mode = value
+    return mode, undetermined
+
+
+def _health_errors() -> list[checks.Error]:
+    """E002: ``SQLITE_OPS["HEALTH"]`` 가 잘못됨. ``HEALTH`` 가 없으면 검사하지 않는다(DESIGN §7)."""
+    from .health import load_config  # health 는 doctor → checks 를 import 한다
+
+    _, errors = load_config()
+    return [
+        checks.Error(
+            message,
+            hint="See README '복제 헬스' and DESIGN §7 for the HEALTH settings.",
+            obj=alias,
+            id="sqlite_ops.E002",
+        )
+        for message, alias in errors
+    ]
+
+
+def _asgi_evidence() -> str | None:
+    """ASGI 로 도는 근거를 돌려준다. 없으면 ``None``(WSGI 로 본다). W003·W005 가 함께 쓴다.
+
+    근거는 ``ASGI_APPLICATION`` 설정, 그리고 명시한 ``SQLITE_OPS["PROFILE"]`` 이다(두 배포
+    프로필은 ASGI 서버로 띄운다, DESIGN §8). 기본값으로 정해진 프로필은 근거가 아니다.
+    ``WSGI_APPLICATION`` 은 ``startproject`` 가 늘 넣으므로 WSGI 근거로 쓰지 않는다. 판단 표와
+    미탐은 DESIGN §6-1.
+    """
+    if getattr(settings, "ASGI_APPLICATION", None):
+        return "ASGI_APPLICATION is set"
+    config = getattr(settings, "SQLITE_OPS", {})
+    if isinstance(config, Mapping) and "PROFILE" in config:
+        return f"SQLITE_OPS['PROFILE'] = {config['PROFILE']!r} is an ASGI deployment profile"
+    return None
+
+
+def check_settings(app_configs=None, **kwargs):
+    """항상 도는 체크: E001(프로필), E002(헬스 설정), W003·W005(별칭의 ``CONN_MAX_AGE``)."""
+    _, error = _profile()
+    if error:
+        return [error]
+    messages: list = _health_errors()
+    asgi = _asgi_evidence()
+    for alias, config in _sqlite_aliases():
+        vfs = _is_litestream_vfs(config.get("NAME"))
+        conn_max_age = config.get("CONN_MAX_AGE", 0)
+        if asgi is None and vfs and conn_max_age is not None:
+            # ASGI 의 VFS 별칭은 미검증이다. WSGI 로 판단될 때만 낸다 (DESIGN §6-1)
+            messages.append(
+                checks.Warning(
+                    f"Litestream VFS database {alias!r} reconnects per request "
+                    "(CONN_MAX_AGE is not None).",
+                    hint=(
+                        f'Set DATABASES["{alias}"]["CONN_MAX_AGE"] = None; measured under WSGI: '
+                        "1,008ms per request with 0, 1.7ms with None (DESIGN §6-0)."
+                    ),
+                    obj=alias,
+                    id="sqlite_ops.W003",
+                )
+            )
+        elif asgi is not None and not vfs and conn_max_age is None:
+            messages.append(
+                checks.Warning(
+                    f"Database {alias!r} has CONN_MAX_AGE = None under ASGI ({asgi}).",
+                    hint=(
+                        "Under ASGI, sync views run in a new thread per request, so the "
+                        "connection is not reused and is not closed at request end; a benchmark "
+                        "saw 810-982 open database file descriptors (limit 1024) and 'unable to "
+                        "open database file' errors (fd exhaustion is the suspected cause). "
+                        f'Set DATABASES["{alias}"]["CONN_MAX_AGE"] = 0 or remove the key. '
+                        "See docs/research/bench-2026-10-08.md and DESIGN §6-1; if this "
+                        "project runs under WSGI, silence sqlite_ops.W005."
+                    ),
+                    obj=alias,
+                    id="sqlite_ops.W005",
+                )
+            )
+    return messages
+
+
+def check_deploy_settings(app_configs=None, **kwargs):
+    """``check --deploy`` 에서만 도는 체크: W001(transaction_mode), W002(journal_mode),
+    W004(별칭 역할을 판정할 수 없음)."""
+    profile, error = _profile()
+    if error:
+        return []  # E001 은 check_settings 가 낸다
+    rec = recommended(profile)
+    want_mode = rec["transaction_mode"].upper()
+    want_journal = str(rec["pragmas"]["journal_mode"]).upper()
+    messages = []
+    for alias, config in _sqlite_aliases():
+        role, reason = _role(config.get("NAME"))
+        if role == "unknown":
+            # 역할을 모르면 쓰기 권고를 내지 않는다. 따르면 연결이 깨질 수 있다(mode=ro 에 WAL)
+            messages.append(
+                checks.Warning(
+                    f"Cannot determine the role of database {alias!r} (write, read-only, "
+                    f"memory or Litestream VFS) from its NAME: {reason}.",
+                    hint=(
+                        "Rewrite NAME as a standard URI: no authority other than "
+                        "'localhost' (file:///path or file:/path), no %00, each query key "
+                        "(mode, immutable, vfs) once, mode=ro|rw|rwc|memory, immutable=1|0, "
+                        "vfs=<name> (DESIGN §6-1)."
+                    ),
+                    obj=alias,
+                    id="sqlite_ops.W004",
+                )
+            )
+            continue
+        if role in ("read-only", "vfs"):
+            # 쓰기 권고가 의미 없거나, 따르면 연결이 깨진다(mode=ro 에 journal_mode=WAL)
+            continue
+        options = _options(config)
+        mode = options.get("transaction_mode")
+        if not isinstance(mode, str) or mode.upper() != want_mode:
+            messages.append(
+                checks.Warning(
+                    f"Database {alias!r} has OPTIONS['transaction_mode'] = {mode!r}, "
+                    f"not {want_mode!r}.",
+                    hint=(
+                        "Use sqlite_database() or set "
+                        f'OPTIONS["transaction_mode"] = "{want_mode}" (DESIGN §6-0).'
+                    ),
+                    obj=alias,
+                    id="sqlite_ops.W001",
+                )
+            )
+        if role == "memory":
+            continue
+        journal, undetermined = _journal_mode(options.get("init_command"))
+        if undetermined is not None:
+            messages.append(
+                checks.Warning(
+                    f"Database {alias!r}: cannot determine journal_mode from "
+                    f"OPTIONS['init_command'] statement {undetermined!r}.",
+                    hint=(
+                        "Use sqlite_database() or write it as "
+                        f'"PRAGMA journal_mode={want_journal}" (DESIGN §6-1).'
+                    ),
+                    obj=alias,
+                    id="sqlite_ops.W002",
+                )
+            )
+        elif journal != want_journal:
+            messages.append(
+                checks.Warning(
+                    f"Database {alias!r} does not set journal_mode={want_journal} in "
+                    "OPTIONS['init_command'].",
+                    hint=(
+                        "Use sqlite_database() or add "
+                        f'"PRAGMA journal_mode={want_journal}" to OPTIONS["init_command"] '
+                        "(DESIGN §6-0)."
+                    ),
+                    obj=alias,
+                    id="sqlite_ops.W002",
+                )
+            )
+    return messages

django_sqlite_ops/compat/__init__.py

@@ -0,0 +1 @@
+"""외부 패키지 결함에 대한 우리 쪽 호환 패치. 모두 버전 게이트 뒤에 있고 자동 적용하지 않는다."""

django_sqlite_ops/compat/_channels_lite_aio.py

@@ -0,0 +1,49 @@
+"""``AIOSQLiteChannelLayer._receive_single_from_db`` 의 교체본 (DESIGN §9).
+
+channels-lite 0.4.0 원본(``channels_lite/layers/aio.py`` 143–177)을 그대로 옮기고 선점 판정만
+바꿨다. 원본은 ``conn.total_changes > 0`` 으로 판정하는데, 이 값은 연결이 열린 뒤 누적된 변경 수라서
+풀에서 재사용된 연결이면 UPDATE 가 0행이어도 참이 된다. 교체본은 UPDATE 커서의 ``rowcount`` 를 본다.
+
+원본과의 차이가 이 두 줄(UPDATE 결과를 ``cursor`` 에 받는 것과 판정)뿐인지는
+``tests/test_compat_channels_lite.py`` 가 원본 소스와 대조해 확인한다. 이 파일은 channels-lite 를
+import 하므로 ``channels_lite.apply()`` 가 게이트를 통과한 뒤에만 import 한다.
+"""
+
+from channels_lite.layers import ChannelEmpty
+
+
+async def _receive_single_from_db(self, channel):
+    """Pull a single message from the database for the given channel."""
+    async with self.connection() as conn:
+        now = self._to_django_datetime()
+
+        # Find first non-delivered, non-expired message
+        cursor = await conn.execute(
+            """
+            SELECT id, data FROM channels_lite_event
+            WHERE channel_name = ? AND delivered = 0 AND expires_at >= ?
+            ORDER BY expires_at ASC
+            LIMIT 1
+            """,
+            (channel, now),
+        )
+        row = await cursor.fetchone()
+
+        if row:
+            event_id = row[0]
+            data_json = row[1]
+
+            # Mark as delivered
+            cursor = await conn.execute(
+                "UPDATE channels_lite_event SET delivered = 1 WHERE id = ? AND delivered = 0",
+                (event_id,),
+            )
+            await conn.commit()
+
+            # Check if update was successful
+            if cursor.rowcount == 1:
+                message = self.deserialize(data_json)
+                full_channel = self._extract_message_channel(message, channel)
+                return full_channel, message
+
+        raise ChannelEmpty()

django_sqlite_ops/compat/channels_lite.py

@@ -0,0 +1,132 @@
+"""channels-lite aio 레이어의 중복 배달 호환 패치 (DESIGN §9).
+
+``AIOSQLiteChannelLayer._receive_single_from_db`` 는 선점 성공을 ``conn.total_changes > 0`` 으로
+판정한다. 풀에서 재사용된 연결이 앞서 쓰기를 했으면 경쟁에서 진 수신자도 같은 메시지를 받는다.
+이 모듈은 그 메서드 하나를 ``cursor.rowcount == 1`` 로 판정하는 교체본으로 바꾼다.
+
+- **버전 게이트**: 설치된 channels-lite 가 검증한 판(:data:`VERIFIED_VERSION`)이고 원본 메서드의
+  소스가 검증한 소스(:data:`VERIFIED_SOURCE_SHA256`)와 같을 때만 바꾼다. 아니면 바꾸지 않고 사유를
+  :func:`status` 로 알려 준다(``sqlite_doctor`` 의 채널 섹션).
+- **명시 적용**: 자동으로 적용하지 않는다. ``SQLITE_OPS = {"PATCH_CHANNELS_LITE_AIO": True}`` 이면
+  앱 ``ready()`` 에서, 아니면 :func:`apply` 를 직접 부를 때만 적용한다. :func:`apply` 는 멱등이다.
+- channels-lite 를 import 할 뿐 DB 는 열지 않는다.
+"""
+
+import hashlib
+import inspect
+import threading
+from collections.abc import Mapping
+from dataclasses import dataclass
+from importlib import metadata
+
+__all__ = [
+    "SETTING",
+    "VERIFIED_SOURCE_SHA256",
+    "VERIFIED_VERSION",
+    "Status",
+    "apply",
+    "enabled",
+    "status",
+]
+
+SETTING = "PATCH_CHANNELS_LITE_AIO"
+VERIFIED_VERSION = "0.4.0"
+# channels-lite 0.4.0 의 ``inspect.getsource(AIOSQLiteChannelLayer._receive_single_from_db)``.
+VERIFIED_SOURCE_SHA256 = "bc15cbf6a5a737eb4b9f4877440857d603dd1fbdb6ec32487aee68374fc6170d"
+
+_METHOD = "_receive_single_from_db"
+_MARK = "__sqlite_ops_patch__"
+_lock = threading.Lock()
+
+
+@dataclass(frozen=True, slots=True)
+class Status:
+    """패치 상태. ``applicable`` 은 게이트 통과 여부, ``applied`` 는 이 프로세스에서 적용 여부다."""
+
+    installed: bool
+    version: str | None
+    applicable: bool
+    applied: bool
+    reason: str
+
+
+def _version() -> str | None:
+    try:
+        return metadata.version("channels-lite")
+    except metadata.PackageNotFoundError:
+        return None
+
+
+def _layer_class():
+    """``(클래스, None)`` 또는 ``(None, 사유)``."""
+    try:
+        from channels_lite.layers.aio import AIOSQLiteChannelLayer
+    except ImportError as exc:
+        return None, f"aio layer is not importable ({exc}); install channels-lite[aio]"
+    return AIOSQLiteChannelLayer, None
+
+
+def _gate(cls) -> str | None:
+    """게이트를 통과하면 ``None``, 아니면 사유. 이미 바꾼 클래스는 원본 소스로 판정한다."""
+    method = getattr(cls, _METHOD)
+    original = getattr(method, "__wrapped_original__", method)
+    try:
+        source = inspect.getsource(original)
+    except (OSError, TypeError) as exc:
+        return f"source of {_METHOD} is not available ({exc}); cannot verify"
+    if hashlib.sha256(source.encode()).hexdigest() != VERIFIED_SOURCE_SHA256:
+        return f"{_METHOD} differs from the verified channels-lite {VERIFIED_VERSION} source"
+    return None
+
+
+def status() -> Status:
+    """현재 상태를 돌려준다. 아무것도 바꾸지 않는다."""
+    version = _version()
+    if version is None:
+        return Status(False, None, False, False, "channels-lite is not installed")
+    if version != VERIFIED_VERSION:
+        return Status(
+            True,
+            version,
+            False,
+            False,
+            f"channels-lite {version} is not verified (verified: =={VERIFIED_VERSION}); "
+            "patch not applied",
+        )
+    cls, reason = _layer_class()
+    if cls is None:
+        return Status(True, version, False, False, reason)
+    reason = _gate(cls)
+    if reason is not None:
+        return Status(True, version, False, False, reason + "; patch not applied")
+    if getattr(getattr(cls, _METHOD), _MARK, False):
+        return Status(True, version, True, True, "applied")
+    return Status(True, version, True, False, "not applied in this process")
+
+
+def apply() -> bool:
+    """게이트를 통과하면 패치를 적용하고 ``True``, 아니면 아무것도 바꾸지 않고 ``False``.
+
+    두 번 불러도 한 번만 바꾼다. channels-lite 가 없으면 조용히 ``False`` 다.
+    """
+    with _lock:
+        current = status()
+        if current.applied:
+            return True
+        if not current.applicable:
+            return False
+        from channels_lite.layers.aio import AIOSQLiteChannelLayer
+
+        from ._channels_lite_aio import _receive_single_from_db as patched
+
+        # 원본은 게이트 판정(_gate)이 다시 볼 수 있도록 교체본에 붙여 둔다
+        patched.__wrapped_original__ = getattr(AIOSQLiteChannelLayer, _METHOD)
+        patched.__qualname__ = f"AIOSQLiteChannelLayer.{_METHOD}"
+        setattr(patched, _MARK, True)
+        setattr(AIOSQLiteChannelLayer, _METHOD, patched)
+        return True
+
+
+def enabled(config: object) -> bool:
+    """``SQLITE_OPS`` 에서 패치가 켜져 있는지. 정확히 ``True`` 일 때만 켠다."""
+    return isinstance(config, Mapping) and config.get(SETTING) is True