Presence API 심화
Presence API의 고급 사용법과 스케일링 전략을 다룹니다.
학습 목표#
- Presence 아키텍처 이해
- 커스텀 메타데이터 활용
- 다중 방 지원
- 타이핑 타임아웃 커스터마이징
- 스케일링 고려사항
Presence 아키텍처#
두 가지 Mixin#
| Mixin | 역할 | 사용 시점 |
|---|---|---|
PresenceMixin |
자신의 상태 브로드캐스트 | 입력 컴포넌트, 채팅 입력창 |
PresenceTrackerMixin |
다른 사용자 추적 | 사용자 목록, 온라인 표시 |
데이터 흐름#
PresenceMixin (User A)
│
├─ presence_join() ──────┐
├─ presence_set_typing() │
└─ presence_leave() ─────┤
│
▼
Broadcast Channel
│
▼
PresenceTrackerMixin (User B)
│
├─ presence_users
├─ presence_online_count
└─ presence_typing_users
탭이 여럿인 사용자#
Presence는 사용자가 아니라 브라우저 탭마다 기록한다. Phoenix Presence와 같은 모양이다. 트래커는 사용자 아래에 탭마다 항목을 하나씩 두고, 템플릿이 읽는 목록은 사용자마다 한 항목으로 합친다.
- 떠남: 같은 사용자가 탭 둘을 열었으면 하나를 닫아도 목록에 남는다. 마지막 탭이 떠날 때 빠진다.
- 상태: 탭 중 하나라도 입력 중이면 그 사용자는 입력 중이다. 그렇지 않고 하나라도 온라인이면 온라인이다. 입력 자동 해제 타이머도 탭마다 따로 돈다 — 한 탭이 멈춰도 다른 탭이 입력 중이면 입력 중으로 남는다.
- 이름과 메타데이터: 가장 최근에 소식이 온 탭의
username·metadata·last_active를 쓴다.
항목은 정확히는 프로듀서(PresenceMixin)마다 하나다 — Phoenix가 track마다 하나를 두는 것과 같다. 프로듀서의
항목은 그 탭과 프로듀서의 이름으로 가리키고, 메시지의 presence_ref에 실린다. 그래서 프로듀서가 둘인 페이지(입력창과
숨길 수 있는 위젯)가 하나를 숨겨 presence_leave()를 불러도, 다른 하나가 입장해 있으면 그 사용자는 목록에 남는다.
트래커(PresenceTrackerMixin)가 presence_track_self()로 올리는 자기 항목은 그 탭의 것이고, 같은 탭 프로듀서의
항목과 따로 있다. 목록은 둘을 사용자 하나로 합친다 — 같은 탭의 프로듀서가 입력 중이면 자기도 입력 중으로 보이고,
그 프로듀서가 떠나도 자기 목록에서 자기는 빠지지 않는다.
프로듀서는 id로 그린다#
프로듀서의 이름은 템플릿이나 페이지가 준 컴포넌트 id다. 그래서 프로듀서는 id를 주어 그려야 한다:
{% component "ChatInput" id="composer" room_id=room.id %}
{% component "ChatRoom" id="room-"|concat:room.id room=room %}
id 없이 그리면({% component "ChatInput" room_id=room.id %}) 그 태그가 TemplateSyntaxError로 실패한다 — 페이지의
첫 렌더에서, 어느 클래스인지와 고치는 법을 적은 문장으로. manage.py check의 wireview.W023이 그중 찾을 수 있는 것을
먼저 알린다 — 렌더가 불러올 템플릿에서 클래스 이름을 따옴표로 적은 태그. 전부는 아니다: 이름을 변수로 고르는 태그와
체크가 찾지 못하는 템플릿은 첫 렌더가 알린다(W023의 범위). 테스트의 mount()도
같다: id 없이 마운트한 프로듀서는 presence_join()에서 ImproperlyConfigured로 실패하므로 mount(ChatInput, id="composer")로
쓴다. 트래커(PresenceTrackerMixin만 쓰는 컴포넌트)에는 id가 필요 없다.
id가 필요한 까닭은 둘이다.
- 같은 탭의 프로듀서 둘을 가른다. 입력창과 숨길 수 있는 위젯처럼 한 탭에 프로듀서가 둘이면 항목도 둘이어야 하나가 떠나도 다른 하나가 사용자를 목록에 남긴다.
- 재연결·다시 그리기에서 같은 항목을 잇는다. 프레임워크가 지어 주는 id(
rx-…)는 그리는 패스마다 새것이라, 재연결한 탭의 입장이 서버가 퇴장 없이 끝나며 남긴 항목을 덮지 못한다. sticky 컴포넌트의 기본 id도 이름이 되지 못한다 — 클래스 하나에 하나뿐이고, 같은 페이지의 둘째 것은rx-id를 받는다.
1.5에서는 id 없이 그린 프로듀서도 동작했다. 옮기는 법은 업그레이드 가이드에 있다.
누가 목록에 오르는가#
다른 사람의 목록에 오르게 하는 것은 프로듀서다. 프로듀서는 presence_join()부터 presence_leave()까지 자기
presence 채널을 듣다가, 나중에 들어온 트래커의 sync 요청에 자기 상태로 답한다(Phoenix의 track과 같다). 그래서 같은
페이지의 트래커가 언제 생겼는지와 상관없이 오른다 — 프로듀서와 트래커가 따로 join되는 형제 루트여도, 트래커가 예외
뒤에 다시 join되어도, sticky 프로듀서가 boost 이동으로 다음 페이지의 트래커와 만나도 같다.
- 프로듀서가 입장해 있는 동안 그 연결은
get_subscriptions()가 무엇을 돌려주든 그 프로듀서의 presence 채널을 함께 듣는다. 믹스인은get_subscriptions()·notification()을 건드리지 않는다 —super()를 부르지 않는 오버라이드도, 앱의 다른 믹스인이나 베이스 클래스가 정한 것도 쓴 그대로다. 입장하기 전에는 듣지 않으므로joined()가 정하는 토픽도 된다. - 그렇게 들은 것은 프레임워크의 일이다. 컴포넌트의
notification()은 그것을 받지 않고(1.5까지와 같다), 그것으로 렌더하지도 않는다.notification()을 오버라이드해도 따로 할 일이 없다. - 컴포넌트가 그 채널을 직접 구독하면(
get_subscriptions()가 돌려준다 — 트래커를 겸하는 클래스가 그렇다)notification()이 presence 메시지를 받고, 바꾼 것은 렌더된다. sync 요청에는 여전히 프레임워크가 한 번 답한다.
트래커만 있는 페이지(presence_join()을 부르는 프로듀서가 없다)는 자기를 목록에 보이지만 다른 사람의 목록에는
오르지 않는다. 들어왔다고도 떠났다고도 알리지 않는 탭이라, 올리면 내릴 수 없다. 보는 사람도 목록에 올리려면 그
페이지에 프로듀서를 둔다.
재연결과 서버 종료#
탭은 페이지를 불러올 때 이름을 하나 만들어 소켓 URL(tab)로 보내고, 재연결해도 같은 이름을 쓴다. presence_ref는
그 이름과 로그인한 사용자로 만든 요약값이다 — 클라이언트가 보낸 값이라, 다른 사용자의 탭 이름을 보내도 자기 사용자의
다른 탭이 될 뿐 남의 항목을 덮지 못한다. 이름 자체는 토픽의 구독자에게 가지 않는다.
- 연결이 끝날 때 퇴장하지 못한 프로듀서: 연결이 끝나면(소켓이 닫힘, 서버가 앱을 취소함 — daphne의 종료와
close timeout) 프레임워크가
leaving()을 부르고, 그 뒤에도 입장해 있는 프로듀서는 대신 퇴장시킨다 —leaving()이 던졌거나 5초 시한을 넘겼거나(퇴장을 발행하던 도중이었어도)presence_leave()를 부르지 않았어도(#211). 단 서버가 그 정리를 끝까지 기다릴 때다 — 아래. 연결이 살아 있는 동안의 마지막leaving()(페이지 이동, 부모가 뺌)도 같다 — 다음 항목(#212). leaving()이 퇴장하지 못했을 때: 프로듀서의 마지막leaving()이presence_leave()전에 예외를 던졌거나 그것을 부르지 않았으면,leaving()이 끝난 뒤 프레임워크가 대신 퇴장시키고 입력 타이머를 멈춘다.leaving()이 이미 퇴장시켰으면 다시 보내지 않는다. 페이지가 아직 요소를 붙들고 있어 묘비로 남은 동안이 아니라, 묘비가 묻혀 마지막leaving()이 돌 때다. 서버가 그것을 끝까지 기다리지 않은 경우는 다음 항목이다.- 서버가
leaving()을 끝까지 기다리지 않고 끝났을 때(Granian의 종료, 크래시, uvicorn이--timeout-graceful-shutdown을 넘겨 내림, daphne의 종료 — 연결이 둘 이상이면 먼저 끝난 하나만 기다린다): 그 프로세스에 붙어 있던 탭의 퇴장은 오지 않을 수 있다. 탭이 다른 프로세스로 재연결해 다시 입장하면 같은presence_ref라 남은 항목을 덮고, 그 탭이 닫힐 때 빠진다. 다시 그려진 프로듀서도 같은 id라 같은 항목이다. - 서버는 살아 있고 네트워크만 끊겼을 때: 탭은 새 소켓으로 다시 입장하고, 서버가 늦게 알아챈 옛 소켓의 퇴장은
버린다. 메시지마다 보낸 프로듀서 인스턴스의 이름(
presence_speaker)이 실려 있어 옛 소켓의 것을 가른다. 두 소켓이 함께 살아 있는 동안 들어온 사람에게는 둘 다 답하므로, 그 사람의 목록은 그 탭을 두 소켓 모두에 기록하고 마지막 소켓이 떠날 때 뺀다. - 숨겼다 다시 보인 프로듀서: 페이지가 프로듀서를 숨겼다 곧 다시 보이면, 다시 보인 것은 같은 id의 새
인스턴스이고 숨긴 것과 항목을 함께 쓴다. 숨긴 것의
leaving()은 그 뒤에 올 수 있지만(페이지의 leave가 늦거나, 페이지가 요소를 붙들고 있어 묘비가 시간이 다 되어 묻힐 때) 보낸 인스턴스가 달라 그 퇴장은 버려진다. - 재연결하지 않은 탭은 남는다. 서버가 퇴장을 알리지 못하고 끝났는데 그 탭이 다시 오지 않으면(그 사이에 닫았거나,
새로고침해 새 이름으로 왔다) 다른 사람의 목록에 그 항목이 남는다. 그 목록을 그린 페이지를 새로고침하면 사라진다.
1.5까지도 있던 한계다. 어느 서버도 종료할 때 퇴장을 보장하지 않으므로 목록의 정확성을 거기에 걸지 않는다. 덜 놓치려면
소켓을 닫아
leaving()을 돌리는 uvicorn으로 드레인한다(SIGTERM 드레인 절차).
이름을 보내지 않는 옛 번들(1.5 이하의 wireview.min.js)로 열린 페이지는 연결을 탭으로 셈한다. 재연결하면 새 항목이
되므로, 그 사이에 서버가 퇴장 없이 끝났으면 옛 항목이 남는다.
롤링 배포로 이 동작 이전(1.5 이하)의 프로세스와 섞이면, 옛 프로세스의 메시지에는 presence_ref가 없다. 새
프로세스는 그런 메시지를 그 사용자의 탭 하나로 받는다. 옛 프로세스에 붙은 탭끼리는 예전처럼 하나로 셈해지고,
새 프로세스에 붙은 탭과는 따로 남는다. 옛 프로세스에서는 트래커가 sync 요청에 답하므로, 트래커만 있는 페이지도
새 프로세스의 목록에 오르고 그 페이지가 닫혀도 내려가지 않는다 — 그 목록의 트래커가 다시 join하면 사라진다.
할 일은 업그레이드 가이드에 있다.
커스텀 메타데이터#
기본 정보 외 추가 데이터#
from django.utils import timezone
class XChatInput(PresenceMixin, Component):
username: str
avatar_url: str
role: str # admin, moderator, user
def _presence_metadata(self) -> dict:
"""추가 메타데이터 반환"""
return {
"avatar_url": self.avatar_url,
"role": self.role,
"joined_at": timezone.now().isoformat(),
}
메타데이터 사용#
{% for user in this.presence_users %}
<div class="user">
<img src="{{ user.metadata.avatar_url }}" alt="{{ user.username }}">
<span class="name">{{ user.username }}</span>
{% if user.metadata.role == 'admin' %}
<span class="badge admin">Admin</span>
{% endif %}
</div>
{% endfor %}
다중 방 지원#
동적 토픽#
class XChatRoom(PresenceMixin, Component):
room_id: int
def _presence_topic(self) -> str:
# 방마다 다른 토픽
return f"chat.room.{self.room_id}"
여러 토픽 구독#
class XGlobalPresence(PresenceTrackerMixin, Component):
"""여러 방의 사용자를 동시에 추적"""
room_ids: list[int]
def get_subscriptions(self) -> set[str]:
# 여러 채널 구독
channels = set()
for room_id in self.room_ids:
channels.add(f"presence.chat.room.{room_id}")
return channels
def _presence_topic(self) -> str:
# 기본 토픽 (필수 구현)
return f"chat.room.{self.room_ids[0]}" if self.room_ids else "global"
@property
def rooms(self) -> list[tuple[int, list]]:
"""(방 번호, 그 방의 사용자) 목록. 템플릿은 인자를 받는 메서드를 부를 수 없으므로 property로 만든다"""
return [(room_id, self.presence_users_in(f"chat.room.{room_id}")) for room_id in self.room_ids]
트래커는 토픽(채널)마다 따로 기록한다. 한 방에서 떠난 사용자는 다른 방에 남아 있으면 그 방의 목록에 그대로 있다.
presence_users·presence_online_count·presence_typing_users·presence_get_user()는 모든 토픽을 합쳐 사용자마다 한 번 센다. 상태는 그 사용자의 모든 탭·모든 방을 합친 것이다(한 방에서라도 입력 중이면 입력 중).presence_users_in(topic)은 한 토픽의 사용자만 돌려준다.topic은_presence_topic()이 돌려주는 모양 (chat.room.1)이고, 채널 이름(presence.chat.room.1)이 아니다.presence_track_self()는 자기 토픽(_presence_topic())에만 자기를 올리고 sync를 요청한다. 다른 방의 사용자는 그 방의 프로듀서가 입장을 알릴 때부터 보인다.
타이핑 타임아웃 커스터마이징#
기본 설정#
from wireview import PresenceConfig
class XChatInput(PresenceMixin, Component):
class Meta:
presence = PresenceConfig(
typing_timeout=3.0, # 3초 후 자동 해제
)
긴 타임아웃#
문서 편집 등 긴 작업:
class XDocEditor(PresenceMixin, Component):
class Meta:
presence = PresenceConfig(
typing_timeout=10.0, # 10초
)
수동 타이핑 해제#
async def on_input(self, text: str):
if text:
await self.presence_set_typing(True)
else:
# 입력이 비면 즉시 해제
await self.presence_set_typing(False)
상태 동기화#
sync_on_join#
새 사용자가 입장하면 기존 사용자 정보 요청:
class Meta:
presence = PresenceConfig(
sync_on_join=True, # 기본값
)
동기화 흐름#
- User B 입장
- User B의 트래커가
presence_sync_request브로드캐스트 - 입장해 있는 프로듀서가 요청 수신 → 자기 항목으로
presence_sync_response전송. User A가 탭 둘을 열었으면 두 탭이 각각 답한다(한 탭에 프로듀서가 둘이면 둘 다). 요청한 트래커와 같은 탭의 프로듀서는 답하지 않는다 — 그 트래커가 자기 항목으로 보인다. 트래커는 답하지 않는다(누가 목록에 오르는가) - User B가 탭마다 받아 사용자 단위로 합친다. 이미 소식을 들은 탭의 답은 버린다 — 탭이 상태를 바꿀 때마다 직접 알리므로, 요청이 큐에서 기다리는 동안 바뀐 상태를 옛 답이 덮지 않게 한다
PresenceUser 객체#
속성#
presence_users·presence_typing_users·presence_get_user()·presence_users_in()이 돌려주는 것은 사용자의 탭들을 합친 항목이다
(탭이 여럿인 사용자).
@dataclass
class PresenceUser:
user_id: str # 고유 식별자
username: str # 표시 이름
state: PresenceState # ONLINE, TYPING, OFFLINE
last_active: float # 마지막 활동 시간
metadata: dict # 커스텀 데이터
메서드#
user.is_typing() # 타이핑 중인지
user.is_online() # 온라인인지 (OFFLINE 제외 모든 상태)
템플릿에서 사용#
{% for user in this.presence_users %}
<li class="{% if user.is_typing %}typing{% endif %}">
{{ user.username }}
{% if user.is_typing %}
<span class="status">typing...</span>
{% elif user.is_online %}
<span class="status online">online</span>
{% endif %}
</li>
{% endfor %}
스케일링 고려사항#
프로세스를 잇는 채널 레이어#
Presence는 채널 레이어로 퍼진다. InMemory 레이어는 프로세스 하나 안에서만 통하므로, 서버 프로세스를 여러 개 띄우면 다른 프로세스에 붙은 사용자는 오류 없이 목록에서 빠진다. 여러 프로세스로 운영할 때는 프로세스를 잇는 레이어를 쓴다. 이 프로젝트가 겨냥하는 것은 channels-nats이고, Redis가 이미 있다면 channels_redis도 된다. 둘의 성능은 대등하다.
import os
CHANNEL_LAYERS = {
"default": {
"BACKEND": "channels_nats.NatsChannelLayer",
"CONFIG": {"servers": [os.environ["NATS_URL"]]},
}
}
설정과 선택 기준은 배포 가이드의 채널 레이어에 있다.
대규모 방 처리#
수천 명이 있는 방에서는:
class XLargeRoom(PresenceTrackerMixin, Component):
# 상위 N명만 표시
@property
def top_users(self) -> list:
return self.presence_users[:50]
@property
def total_count(self) -> int:
return self.presence_online_count
비활성 사용자 정리#
import time
class XOnlineUsers(PresenceTrackerMixin, Component):
@property
def active_users(self) -> list:
# 5분 이내 활동한 사용자만
cutoff = time.time() - 300
return [
u for u in self.presence_users
if u.last_active > cutoff
]
트러블슈팅#
온라인 사용자가 표시되지 않음#
-
구독 확인
def get_subscriptions(self) -> set[str]: return {self._presence_channel()} # 필수 -
토픽 일치 확인
- Producer와 Consumer의
_presence_topic()반환값 동일해야 함
- Producer와 Consumer의
-
Channel Layer 확인
- InMemoryChannelLayer는 다른 프로세스와 공유 안 됨
타이핑이 사라지지 않음#
타임아웃 로직 확인:
async def on_typing(self):
await self.presence_set_typing(True)
# 이후 자동으로 타임아웃됨
퇴장이 감지되지 않음#
leaving() 훅 구현 확인:
async def leaving(self):
await self.presence_leave()
leaving()이 presence_leave()를 부르지 않거나 그 전에 예외를 던져도 프레임워크가 그 뒤에 퇴장시킨다
(재연결과 서버 종료). 그래도 남는다면 그 프로세스가 leaving() 없이 끝났거나 채널 레이어가 퇴장 메시지를 버린 것이다.
고급 패턴#
상태 표시 (자리비움 등)#
from enum import StrEnum
class UserStatus(StrEnum):
ONLINE = "online"
AWAY = "away"
DND = "dnd" # Do Not Disturb
class XStatusIndicator(PresenceMixin, Component):
status: UserStatus = UserStatus.ONLINE
def _presence_metadata(self) -> dict:
return {"status": self.status.value}
async def set_status(self, status: str):
self.status = UserStatus(status)
# 상태 변경 브로드캐스트
await self.presence_join()
마지막 활동 시간#
from datetime import UTC, datetime
from django.utils.timesince import timesince
class XOnlineUsers(PresenceTrackerMixin, Component):
@property
def last_seen(self) -> list[tuple]:
"""(사용자, "3 minutes") 목록. 템플릿은 인자를 받는 메서드를 부를 수 없으므로 property로 만든다"""
return [(user, self._format_last_seen(user)) for user in self.presence_users]
def _format_last_seen(self, user) -> str:
# `_`가 없으면 클라이언트가 부를 수 있는 핸들러로 노출된다
return timesince(datetime.fromtimestamp(user.last_active, tz=UTC))
템플릿은 property를 그대로 돈다:
<ul>
{% for user, ago in this.last_seen %}
<li>{{ user.username }} · {{ ago }} 전</li>
{% endfor %}
</ul>