System Checks

에러 없이 조용히 실패하는 설정과 코드를 manage.py check가 wireview.W* 경고로 알리게 하는 Django system checks다.

wireview의 함정 중 상당수는 에러를 내지 않는다. sync 핸들러는 클라이언트가 부를 때까지 조용하고, wireview.min.js가 없으면 페이지가 그냥 정적으로 남고, WIREVIEW의 키를 잘못 쓰면 말없이 무시된다. 신호가 없으면 사람도 에이전트도 고칠 수 없다.

이 검사들을 Django의 checks 프레임워크에 등록해 두면 manage.py check, runserver, CI에 자동으로 걸린다. 새 명령을 기억할 필요가 없다는 것이 핵심이다.

이 검사들은 대개 파이썬 쪽만 본다(템플릿을 읽는 것은 W011·W019·W022·W023). 템플릿 안의 틀린 이름(모르는 필터·핸들러·컴포넌트, 닫히지 않은 블록)은 manage.py wireview_check_templates가 Node.js로 편집기 확장과 같은 진단을 돌려 잡는다 — 편집기 지원.

$ python manage.py check
System check identified some issues:

WARNINGS:
<class 'todo.live.XTodoList'>: (wireview.W001) Event handler 'todo.live.XTodoList.total' is not async.
	HINT: The client can call 'total', and wireview awaits the result, so the call fails
	with TypeError. Make it 'async def', or rename it to '_total' if it is an internal
	helper rather than a handler.

검사 목록#

ID 무엇을 잡나 조용히 실패하는 방식
wireview.W001 이벤트 핸들러가 async가 아님 클라이언트가 부르면 TypeError. 부르기 전까지는 아무 신호도 없다
wireview.W002 wireview가 await하는 콜백의 오버라이드가 async가 아님 (joined, leaving, update, destroy, mutation, notification, params_changed, handle_async, handle_hook_event, on_upload_complete) wireview가 await하므로 콜백이 아예 실행되지 않는다
wireview.W003 두 클래스가 같은 단순 이름으로 등록됨 import 시 경고 한 번뿐. 템플릿은 둘 중 하나로만 해석된다
wireview.W004 wireview/wireview.min.js를 staticfiles가 못 찾음 JS가 로드되지 않아 페이지가 정적으로 남는다. 404 외에는 신호가 없다
wireview.W005 (없어짐) USE_HMIN과 함께 #100에서 없어졌다. 번호는 다시 쓰지 않는다
wireview.W006 기본 채널 레이어가 InMemoryChannelLayer 다중 프로세스에서 브로드캐스트가 같은 프로세스에만 닿고 오류는 나지 않는다
wireview.W007 Meta.on_mount에 올린 클래스에 on_mount가 없거나 async가 아님 훅이 말없이 건너뛰어져, 인증 가드로 올린 훅이 아무것도 막지 않는다
wireview.W008 UPLOAD_TEMP_DIR이 가리키는 경로에 임시 파일을 만들 수 없음 설정은 첫 청크가 올 때에야 읽힌다. 기동 시에는 아무 신호가 없고, 업로드가 하나씩 ImproperlyConfigured로 실패한다. Windows에서는 os.access가 ACL을 보지 않아 쓰기 금지를 감지하지 못한다
wireview.W009 SIGNING_KEY가 빈 문자열이거나, 키 없이 fallback만 설정됨 Signer(key="")는 조용히 SECRET_KEY로 되돌아간다. 아무것도 깨지지 않는 것이 문제다 — SECRET_KEY를 돌리면 진행 중인 업로드와 열린 페이지의 data-state가 같이 죽는다
wireview.W010 경계가 선언됐는데 context_processors.request가 꺼져 있거나, Meta.live_sessions가 아무도 선언하지 않은 이름을 가리키거나, 경계가 있는 프로젝트에서 Meta.on_mount로만 자신을 지키는 컴포넌트가 소속을 선언하지 않음 프로세서가 없으면 경계가 통째로 조용히 꺼진다. 오타는 join 거절과 reload로 나타나 서명 문제처럼 보인다. 선언이 없는 컴포넌트는 경계 밖 페이지에서도 마운트된다
wireview.W011 템플릿의 wire-hook="X"를 등록하는 훅 파일이 수집된 것 중에 없음 클라이언트가 콘솔 경고 한 줄만 남긴다. 컴포넌트는 정상으로 렌더되고 동작 하나가 빠진다
wireview.W012 CHANNEL_LAYERS에 default 레이어가 없음 페이지는 HTTP로 정상 렌더되는데 WebSocket 연결이 전부 거절되어 어떤 컴포넌트도 살아나지 않는다. Channels에는 기본 레이어가 없다
wireview.W013 runserver로 기동하는데 그 명령이 Django의 WSGI 서버 그대로임 (daphne가 없거나 INSTALLED_APPS에서 너무 아래에 있음) 페이지는 그려지고 오류도 없다. WebSocket 업그레이드가 거절되어 버튼이 아무 반응도 하지 않고, 흔적은 브라우저 콘솔 한 줄뿐이다
wireview.W014 settings.WIREVIEW에 wireview가 읽지 않는 키가 있음 오타나 업그레이드로 없어진 키는 조용히 무시된다. 비슷한 키 이름이나 없어진 키의 대안을 알려 준다(#100)
wireview.W015 AUTO_BROADCAST의 model·model_pk·related·m2m 중 하나를 켰는데 senders가 비어 있음 비어 있는 senders는 아무 모델도 알리지 않는다. 구독한 컴포넌트의 mutation()이 한 번도 불리지 않고 오류도 없다. 알릴 모델을 적고, 보낼 필드를 줄이려면 매핑으로 적으라고 알려 준다(설정)
wireview.W016 RECONNECT_* 값을 클라이언트가 쓸 수 없음(음수, None, 1보다 작은 RECONNECT_GROW_FACTOR), int·float가 아닌 값(문자열 등), 또는 대기가 설정대로 되지 않음: 대기가 0이거나, 첫 재연결 대기(RECONNECT_MIN_DELAY_MS + RECONNECT_JITTER_MS)가 RECONNECT_MAX_DELAY_MS를 넘거나, 대기가 브라우저 타이머 상한(2³¹−1ms)을 넘음 클라이언트는 읽을 수 없는 값을 기본값으로 바꿔 쓰므로 설정이 아무 일도 하지 않는다. 대기 0은 서버가 죽은 동안 쉬지 않는 재연결이다. 상한을 넘는 대기는 상한으로 잘려, 흩으려던 페이지들이 상한에서 다시 한꺼번에 붙는다(배포)
wireview.W017 AUTO_BROADCAST의 model·model_pk·related·m2m 중 하나를 켜고 senders가 사용자 모델(AbstractBaseUser의 하위 클래스)을 비밀번호 해시가 실리게 알림(집합 형태·"__all__"·password를 적은 목록), 또는 세션 모델(AbstractBaseSession의 하위 클래스)을 어떤 형태로든 알림 저장할 때마다 비밀번호 해시나 세션 키가 채널 레이어(브로커)로 간다. 이름으로 짐작하지 않고 확실한 두 경우만, 페이로드가 실제로 싣는 필드로 본다 — 사용자 모델의 다중 테이블 상속 자식은 제 테이블만 보내므로 조용하다. 사용자 모델에는 senders를 매핑으로 바꿔 보낼 필드를 적으라고, 세션 모델에는 pk가 곧 세션 키라 필드를 적어도 줄지 않으니 senders에서 빼라고 알려 준다(설정)
wireview.W018 사용자 컴포넌트의 공개 메서드가 프레임워크 클래스(wireview·Pydantic)의 멤버와 이름이 같음. 오버라이드하라고 둔 콜백(W002의 이름들, get_subscriptions, new, update_many)과 Pydantic이 예약한 model_ 이름(model_post_init, model_dump …)은 빼고 본다 프레임워크가 가진 이름은 사용자가 다시 정의해도 클라이언트가 부를 수 없다. Phoenix를 옮긴 async def validate(Pydantic BaseModel의 메서드)가 대표다. {% on %} 바인딩은 렌더 때 멈추지만 defer()와 훅의 직접 push는 서버 로그 한 줄로 버려진다. 마이너 릴리스가 같은 이름의 멤버를 더해도 이렇게 된다(호환성)
wireview.W019 Meta.shared_render를 선언했는데 공유할 수 없는 컴포넌트: LiveComponent, Meta.temporary_assigns·Meta.slots·Meta.live_sessions가 있음, 필드의 타입이 모델이나 QuerySet을 말함, 템플릿이 다른 컴포넌트·슬롯·업로드를 그림({% component %}·{% live_component %}·{% render_slot %}·{% upload_input %} …), 템플릿이 user·session·this.user·this.session·request·perms·csrf_token·messages를 읽음(필터 인자와 {% firstof %} 같은 태그의 변수, {% blocktranslate %}의 본문, wireview의 {% cond %}·{% class %}의 식, 태그가 어디에 두든 그 본문과 인자까지 — 템플릿을 파서로 다시 읽어 파서가 만든 것과 태그가 토큰째 가져간 {{ }}를 모두 본다. 같은 이름의 필드·property는 빼고 본다), 태그가 토큰째 가져간 {{ }}나 {% cond %}의 식을 읽을 수 없음, 다시 파싱한 트리가 렌더의 트리와 다름, 템플릿에 {% debug %}가 있음, 템플릿에 매핑 인자 없는 {% querystring %}이 있음(Django 5.2의 {% querystring None … %} 포함. 페이지의 쿼리를 읽는다, #210), 템플릿이 렌더 전에는 이름을 알 수 없는 템플릿을 불러옴({% include part %}·{% extends base %}·{% func kind %}, 등록되지 않은 함수 컴포넌트, 불러올 수 없는 템플릿). 템플릿은 렌더가 닿는 것을 모두 본다: {% include %}한 것, {% extends %}의 부모, 함수 컴포넌트와 inclusion 태그의 템플릿, 템플릿 조각("파일#조각" — Django 6의 것과 django-template-partials의 것, 조각은 렌더가 쓰는 파일에서 자기 {% partialdef %} 안만 — 그 안에 Django·wireview·그 조각 라이브러리 밖의 태그가 있거나 같은 조각 이름이 둘이면 파일 전체). 컴포넌트 자기 템플릿을 불러올 수 없어도 공유하지 않는다(운영에서는 재시작까지) 선언은 아무 일도 하지 않는다. 그 클래스의 렌더는 연결마다 그대로이고, 첫 렌더 때 서버 로그 한 줄이 남을 뿐이다. 성능을 기대하고 붙인 선언이 조용히 꺼져 있다. property와 템플릿 태그·필터의 파이썬 코드 안(태그가 파서를 거치지 않고 스스로 만든 노드·변수, {% get_admin_log … for_user user %}처럼 이름을 문자열로 들고 컨텍스트를 읽는 것 포함)은 보지 않는다 — 그것은 VERIFY_SHARED_RENDER가 렌더 때 잡는다(shared-render). W019가 없다고 안전한 것은 아니다
wireview.W020 ASGI_APPLICATION에서 wireview 컨슈머까지 가는 WebSocket 라우트 위에 Channels의 SessionMiddleware가 없음(AuthMiddlewareStack·SessionMiddlewareStack이 넣는다). Channels의 라우터와 .inner·.application을 가진 층(Channels의 미들웨어, Origin 검사기, BaseMiddleware의 하위 클래스)을 지나 컨슈머에 닿을 때만 본다 — 둘 다 없는 층(프로젝트가 만든 평범한 ASGI 클래스, 함수)을 만나면 말하지 않는다. 그래서 scope["session"]을 스스로 채우는 프로젝트의 BaseMiddleware도 경고를 받는다 — 그때는 SILENCED_SYSTEM_CHECKS에 넣는다 페이지는 그려지고 오류도 없다. 소켓의 핸드셰이크에 세션도 사용자도 없어 컴포넌트의 self.session은 비어 있고 user는 늘 익명이며, 다른 탭이 신분을 바꾼 뒤의 이동을 알아채지 못한다(live_session, #209)
wireview.W021 SESSION_COOKIE_PATH나 CSRF_COOKIE_PATH(CSRF_USE_SESSIONS가 아닐 때)가 소켓 경로 /__wireview__를 덮지 않음(RFC 6265의 path-match: /와 /__wireview__만 덮는다). 소켓은 FORCE_SCRIPT_NAME과 상관없이 호스트의 루트에 열린다 — 서브 경로 배포는 지원하지 않는다(호환성). /로 시작하지 않는 경로와 쿠키 도메인은 보지 않는다. 힌트는 /로 넓히라고 하지만, 그 쿠키는 같은 호스트의 다른 앱에도 실린다 브라우저가 그 쿠키를 소켓에 싣지 않아 핸드셰이크는 페이지와 다른 신분이 된다. 1.6부터 세션 쿠키가 닿지 않으면 로그인한 사용자의 컴포넌트가 마운트되지 않는다 — 페이지가 새로고침하고 HTTP 렌더 그대로 흐리게 남는다. CSRF 쿠키가 닿지 않으면 boost 이동마다 소켓을 한 번 더 열고, 라이브 렌더의 폼은 CSRF 토큰 없이 그려진다(live_session, #209)
wireview.W022 컴포넌트(Meta.template_name)나 함수 컴포넌트(@function_component(template=...))의 템플릿을 Django가 아닌 템플릿 엔진(Jinja2 등)이 먼저 찾음. TEMPLATES에서 그 엔진이 DjangoTemplates보다 앞에 있고 같은 이름을 찾을 수 있을 때 생긴다. 그 엔진이 찾고 컴파일하지 못한 경우(Django 태그를 만난 Jinja2의 TemplateSyntaxError — Django의 로더는 다음 엔진에 묻지 않고 그 오류를 던진다)도 그 엔진을 알린다. 어느 엔진도 찾지 못하는 템플릿은 보지 않는다(렌더가 알린다). 스트림·Broadcast 항목 템플릿은 코드가 돌 때에야 이름을 알 수 있어 보지 않는다 컴포넌트 템플릿은 Django 템플릿 엔진만 그린다(호환성, #210). 첫 렌더가 ImproperlyConfigured로 실패한다. 1.5까지 컴포넌트 자기 템플릿은 그 엔진이 그렸지만 {% tag_header %}도 마커도 없어 페이지가 join하지 못했다. 함수 컴포넌트와 스트림·Broadcast 항목 템플릿은 그 엔진이 그렸고 라이브 렌더에서도 그려졌다 — 이제 오류다(깨짐, 업그레이드)
wireview.W023 템플릿이 Presence 프로듀서(PresenceMixin)를 id 없이 그림 — {% component 'X' %}·{% component_block 'X' %}에 id=가 없다. id=''·id=None도 id가 없는 것으로 본다(태그가 그렇게 거절한다). 렌더가 불러올 템플릿만 본다: Django 엔진마다 템플릿 디렉터리 아래 *.html 파일의 이름으로 그 엔진이 실제로 고르는 템플릿(다른 디렉터리가 같은 이름으로 덮어쓴 파일은 보지 않는다), 컴포넌트·함수 컴포넌트의 자기 템플릿, 그리고 거기서 렌더가 닿는 템플릿 — {% include %}, {% extends %}의 부모(같은 이름의 부모 포함), 함수 컴포넌트와 inclusion 태그의 템플릿(후보 목록이면 렌더가 고르는 첫 후보, 불러와지는 첫 것) — 을 W019와 같은 길로 걷는다. 클래스 이름을 따옴표로 적은 태그만 본다. 이름을 변수로 고르는 태그와 템플릿, 디렉터리를 말하지 않는 로더에만 있고 어디서도 닿지 않는 템플릿, 코드가 문자열로 만든 템플릿, 컴파일되지 않는 템플릿은 보지 못한다 — 그것들은 첫 렌더가 알린다 프로듀서의 Presence 항목은 그 id로 가리킨다 — 같은 탭의 프로듀서 둘을 가르고 재연결·다시 그리기에서 같은 항목을 잇는다(#212). id 없이 그리면 그 태그가 TemplateSyntaxError로 실패한다(깨짐, 업그레이드, 프로듀서는 id로 그린다)
wireview.W024 연결의 인바운드 상한이 어떤 연결도 살아남지 못하는 값: INBOUND_MAX_BYTES·CONNECTION_MAX_COMPONENTS가 1보다 작음, INBOUND_RATE_PER_SECOND가 0 이하, 빈도를 켰는데(INBOUND_RATE_PER_SECOND가 None이 아님) INBOUND_BURST가 1보다 작음, 또는 그중 하나가 None도 int·float도 아님(문자열·bool·튜플 등). 작다는 이유로는 알리지 않는다 — INBOUND_BURST = 1도, 초당 0.001개도 선택이다. float는 숫자로 쓰인다. NaN은 모든 비교가 거짓이라 그 상한을 끄므로(닫지 않는다) 알리지 않는다 서버는 정상으로 기동하고 페이지도 그려지는데, 모든 연결이 첫 프레임(빈도·크기)이나 첫 join(컴포넌트 수)에서 1009·1008로 닫히고 페이지는 재연결 백오프 간격으로 끝없이 다시 붙는다. 문자열은 그 값을 읽는 프레임마다 예외를 던진다 — float()가 읽는 빈도·버스트 문자열("50")은 지금 동작하지만 W016처럼 함께 알린다(설정, #230)
wireview.W025 AUTO_BROADCAST의 model·model_pk·related 중 하나를 켜고 senders의 모델이 Django 6.1의 DB_CASCADE·DB_SET_NULL·DB_SET_DEFAULT를 on_delete로 둔 관계의 자식 쪽임(그 FK가 그 모델에 있다). 부모 모델이 senders에 있는 것은 알리지 않는다 — 부모의 삭제는 보통대로 알려진다. Django 6.1 전에는 그런 on_delete가 없으므로 아무것도 하지 않는다 부모를 지우면 데이터베이스가 그 모델의 행을 지우거나(DB_CASCADE) 그 FK를 NULL·db_default로 바꾸고(DB_SET_NULL·DB_SET_DEFAULT), Django는 그 행들에 pre_delete도 post_save도 보내지 않는다. 구독한 컴포넌트는 아무것도 듣지 못하고 화면에 지워진 행이 남는다. Python 쪽 변형(CASCADE·SET_NULL·SET_DEFAULT)으로 두거나, 부모를 지우는 코드가 직접 알리라고(broadcast()로) 알려 준다(알림이 가지 않는 변경)

전부 Warning이다. manage.py check의 기본 --fail-level은 ERROR이므로 이 검사들이 빌드를 깨지 않는다. 오탐 하나면 팀 전체가 검사를 무시하기 시작하므로 확신이 설 때까지 등급을 올리지 않는다.

W006만 --deploy인 이유#

단일 프로세스 개발 환경에서 InMemory 레이어는 옳은 선택이다. 검사 시점에는 배포 시 프로세스가 몇 개일지 알 수 없다. 그래서 manage.py check --deploy에서만 뜨는 배포 검사로 등록했다. 개발 중에 매번 뜨는 경고는 정보가 아니라 소음이다.

$ python manage.py check --deploy
?: (wireview.W006) The default channel layer is InMemoryChannelLayer.

W012는 왜 --deploy가 아닌가#

W006과 같은 설정을 보지만 묻는 것이 다르다. InMemory는 프로세스가 하나면 옳고, 레이어가 아예 없는 것은 프로세스가 하나여도 틀리다. Channels는 CHANNEL_LAYERS에 default가 없으면 InMemory로 물러서지 않고 None을 돌려주며, 그 경우 컨슈머에 channel_name도 만들지 않는다. 예전에는 connect()가 소켓을 accept한 뒤 그 속성을 읽다가 AttributeError로 죽었고, 그 트레이스백은 설정도 해법도 말해 주지 않았다(#87).

지금은 두 곳에서 같은 문장으로 말한다. 검사가 기동 전에 알려 주고, 검사를 거치지 않는 경로 (uvicorn myproject.asgi:application을 직접 띄운 경우)에서는 컨슈머가 accept 전에 ImproperlyConfigured로 연결을 거절한다. 문장의 정본은 wireview/core/transport.py의 NO_CHANNEL_LAYER 하나다.

단일 프로세스라면 고칠 것은 세 줄이다.

CHANNEL_LAYERS = {
    "default": {"BACKEND": "channels.layers.InMemoryChannelLayer"},
}

W013은 runserver를 띄울 때만 뜬다#

Django의 runserver는 WSGI 서버다. ASGI로 바뀌는 것은 daphne 같은 앱이 명령을 갈아 끼울 때뿐이고, 명령은 INSTALLED_APPS에서 먼저 나오는 앱의 것이 이기므로 daphne는 django.contrib.staticfiles와 whitenoise.runserver_nostatic보다 위에 있어야 한다. 아래에 두면 설치는 됐는데 여전히 WSGI다.

이 검사는 프로세스가 runserver로 시작됐을 때만 본다(sys.argv[1], Django가 하위 명령을 읽는 방식 그대로). INSTALLED_APPS의 runserver는 uvicorn으로 띄우는 프로젝트에 대해 아무것도 말해 주지 않기 때문이다 — 평소의 manage.py check나 CI에서는 뜨지 않는다. runserver는 기동할 때 검사를 돌리므로 경고는 기동 로그 맨 위에 나온다.

$ python manage.py runserver
?: (wireview.W013) runserver (from 'django.contrib.staticfiles') is a WSGI server, so no WebSocket connection reaches wireview.

판정은 제공자 이름 목록이 아니라 로드되는 명령이 Django의 inner_run을 그대로 쓰는가다. staticfiles와 whitenoise는 stock 명령을 감싸기만 하므로 잡히고, ASGI 서버는 inner_run을 바꿔야 하므로 이 검사가 모르는 ASGI 제공자도 오탐하지 않는다.

W016은 클라이언트와 같은 규칙으로 본다#

{% wireview_header %}는 RECONNECT_* 값을 문자열로 메타 태그에 싣고, 클라이언트(reconnect.mjs)는 유한한 숫자이고 하한(대기는 0, RECONNECT_GROW_FACTOR는 1) 이상인 값만 받는다. 나머지는 경고 없이 기본값으로 바꾼다 — 잘못된 설정이 촘촘한 재연결 루프가 되는 것보다 낫지만, 그래서 설정이 먹지 않았다는 신호가 아무 데도 없다(#134).

int·float, None, bool에 대해서는 두 판정이 같다: 검사가 통과시킨 값은 클라이언트가 같은 숫자로 쓰고, 검사가 경고하는 값만 클라이언트가 버린다. tests/test_checks.py가 실제 헤더를 렌더해 reconnect.mjs에 넣고 이것을 확인한다.

그 밖의 값, 특히 환경 변수에서 int() 없이 읽은 문자열도 경고하지만 클라이언트가 무엇을 하는지는 말하지 않는다. 클라이언트는 JavaScript의 Number()로 읽어 "30000"은 30000으로 쓰고 "1,000"·"30s"는 버린다. 검사가 그 문법을 흉내 내지 않으므로 "기본값을 쓴다"고 단정하지 않고, 아래의 관계 판정도 하지 않는다 — 클라이언트가 쓰는 값을 모르기 때문이다. 하나만 예외다. 대기 0은 한쪽 값만으로 정해진다 — RECONNECT_MIN_DELAY_MS와 RECONNECT_JITTER_MS가 둘 다 0이거나 RECONNECT_MAX_DELAY_MS가 0이면 나머지가 무엇이든 모든 대기가 0이므로, 문자열이 곁에 있어도 이것은 알린다. Decimal처럼 int·float가 아닌 수도 문자열과 같이 다룬다(헤더가 str()로 싣는 값을 검사가 보증하지 않는다).

나머지 경고는 클라이언트가 실제로 쓰는 값(버린 값 대신 기본값)으로 대기를 따진다.

  • 대기 0. 첫 대기의 끝(RECONNECT_MIN_DELAY_MS + RECONNECT_JITTER_MS)이나 RECONNECT_MAX_DELAY_MS가 0이면 모든 재시도가 곧바로 나간다. 서버가 죽어 있는 동안 페이지마다 쉬지 않고 연결을 시도한다.
  • 상한에 잘리는 첫 대기. 첫 대기는 RECONNECT_MIN_DELAY_MS부터 그 값에 RECONNECT_JITTER_MS를 더한 값까지인데 어떤 대기도 RECONNECT_MAX_DELAY_MS를 넘지 못한다. 넘는 쪽을 뽑은 페이지는 모두 상한에서 함께 다시 붙어, 지터가 흩으려던 무리가 그대로 돌아온다. 최소 대기부터 상한을 넘으면 모든 대기가 상한이고 앞의 두 설정은 아무 효과가 없다.
  • 브라우저 타이머 상한. 브라우저는 setTimeout의 대기를 32비트 정수로 받는다(WebIDL long). 2³¹−1ms(약 24.8일)를 넘는 대기는 2³²로 나눈 나머지가 되어, 2³¹부터 2³²ms까지는 곧바로 나가고 그 위는 엉뚱하게 짧아진다(Chromium 실측). RECONNECT_GROW_FACTOR가 1보다 크면 대기가 결국 상한까지 자라므로 상한을, 1이면 첫 대기의 끝을 본다.
$ python manage.py check
?: (wireview.W016) The first reconnect waits 1000 to 21000 ms but no wait is longer than RECONNECT_MAX_DELAY_MS (10000 ms), so pages that draw a wait above 10000 ms all reconnect at 10000 ms together, which the jitter was to spread apart.

W010이 세 가지를 보는 이유#

첫째는 전제 조건이다. 템플릿 태그는 페이지의 경계를 context["request"]에서 읽으므로 django.template.context_processors.request가 꺼져 있으면 기능 전체가 말없이 꺼진다 — 헤더는 빈 이름을 심고, 모든 상태가 경계 없이 서명되고, Meta.live_sessions를 선언한 컴포넌트는 자기 페이지에서 사라진다. 페이지는 200으로 그려지고 아무것도 예외를 던지지 않는다.

경계는 옵트인이다. 그 결과 실수가 두 방향으로 난다.

이름이 어긋나면 조용하지 않지만 엉뚱하게 보인다. Meta.live_sessions = {"admn"}인 컴포넌트가 실린 페이지는 join에서 "unknown live_session"으로 거절되고 브라우저가 reload한다 — 화면에는 서명이 깨진 것처럼 보인다. 검사가 오타를 이름으로 짚는다.

반대로 선언을 빠뜨리면 아무 신호가 없다. Meta.on_mount 훅으로만 자신을 지키는 컴포넌트는 경계 밖 페이지에서도 마운트되고, 훅은 돌지만 "여기 있으면 안 된다"고 말하는 것은 아무것도 없다. 이 경고는 프로젝트가 live_session을 하나라도 선언한 뒤에만 뜬다. 선언하기 전에는 속할 곳이 없으므로 모든 컴포넌트가 원래 있던 자리에 있는 것이다.

$ python manage.py check
<class 'billing.live.XInvoice'>: (wireview.W010) billing.live.XInvoice guards itself with
Meta.on_mount but declares no Meta.live_sessions.

정말로 어디서나 마운트되어도 되는 컴포넌트라면 그것이 옳은 상태다 — 그때는 SILENCED_SYSTEM_CHECKS가 아니라 그 사실을 코드에 적는 편이 낫다.

이 검사가 보호 대상을 전부 찾아 주지는 않는다. 자기 훅이 없고 페이지의 authorize에만 의존하던 컴포넌트는 여기에 걸리지 않는다 — 검사가 볼 수 있는 것은 클래스이지 그 클래스가 어느 페이지에 얹히는지가 아니다. 경계를 도입하는 배포에서는 목록을 직접 확인해야 한다 (live_session의 전환 절차).

W011이 놓치는 것#

양쪽을 소스에서 읽는다. 템플릿에서 wire-hook="..."를 정규식으로 찾고, 수집된 훅 파일에서 wireview.hooks.<이름> = 을 정규식으로 찾는다. 그래서 둘 다 못 보는 것이 있다.

  • 렌더 시점에 만들어지는 이름(wire-hook="{{ name }}")은 건너뛴다.
  • 자기 번들로 훅을 등록하는 프로젝트의 이름은 알 수 없다.

첫째 때문에 놓치는 쪽이 있고, 둘째 때문에 오탐이 날 수 있다. 그래서 경고이고, 힌트가 SILENCED_SYSTEM_CHECKS 를 알려 준다. 어느 앱도 규약 경로에 훅 파일을 두지 않았다면 비교할 대상이 없다는 뜻이므로 이 검사는 아무 말도 하지 않는다.

W007이 보안 검사인 이유#

Meta.on_mount 훅은 라이프사이클 훅 문서의 첫 예제부터 인증 가드다. 그런데 _run_on_mount_hooks는 on_mount가 없는 항목을 예외 없이 건너뛴다. 메서드 이름 오타 하나(onmount)면 가드가 사라진 컴포넌트가 정상적으로 마운트된다. 클라이언트에는 아무 신호도 없다. async를 빠뜨린 훅은 조용하지는 않지만 마운트 도중 TypeError로 터진다.

$ python manage.py check
<class 'billing.live.XInvoice'>: (wireview.W007) 'AuthHook.on_mount' in billing.live.XInvoice.Meta.on_mount is not async.
	HINT: wireview awaits every on_mount hook, so a sync one fails with TypeError while
	the component is mounting. Declare it as 'async def on_mount'.

특정 검사만 돌리기#

모든 검사에 wireview 태그가 붙어 있다.

python manage.py check --tag wireview

끄기#

Django 표준대로 SILENCED_SYSTEM_CHECKS를 쓴다.

SILENCED_SYSTEM_CHECKS = ["wireview.W006"]  # InMemory 레이어를 쓰는 단일 프로세스 배포라면

검사는 디스패처와 같은 규칙을 쓴다#

W001은 "노출되는 핸들러"를 자체 판정하지 않는다. wireview/core/handlers.py의 is_client_callable — 클라이언트 이벤트를 받는 디스패처가 쓰는 그 판정 — 을 그대로 호출한다(#127). 판정 로직을 복사했다면 규칙이 바뀔 때 검사가 조용히 거짓말을 하게 된다.

노출 규칙 자체는 LiveComponent 문서에 있다. 요약하면 _로 시작하지 않으면서 사용자 코드가 정의한 이름만 노출되고, 프레임워크(wireview.*)와 Pydantic이 소유한 이름은 오버라이드해도 노출되지 않는다.

노출 목록을 직접 보고 싶으면 같은 헬퍼를 쓴다.

from wireview import iter_exposed_handlers
from myapp.live import TodoList

print([name for name, _ in iter_exposed_handlers(TodoList)])

검사하지 않는 것#

상태 필드의 JSON 직렬화 가능성은 뺐다. 상태는 model_dump_json으로 직렬화되고 Pydantic은 커스텀 serializer, field_serializer, wireview의 Django 모델 지원까지 고려해 런타임에 판단한다. 정적으로 흉내 내면 오탐이 나온다 — 정상 컴포넌트에 경고를 띄우는 검사는 없느니만 못하다. 이건 런타임에 터지므로 조용한 실패도 아니다.

Broadcast(문서)도 검사하지 않는다. 어떤 클래스·토픽·템플릿으로 발행하는지는 코드가 돌 때에야 알 수 있다. 대신 조용히 실패할 수 있는 곳은 발행하는 곳에서 오류로 막는다 — 대상 클래스의 Meta.subscriptions에 없는 토픽(get_subscriptions()를 오버라이드하지 않았을 때), 패치 그룹 이름이 될 수 없는 토픽(84자 초과, 허용되지 않는 글자), JSON이 아닌 push_event 페이로드, 보는 사람을 읽는 항목 템플릿. 다음 번호는 wireview.W026부터다.

관련 문서#