Chrome Extension v0.1.0

Entry Sync

엔트리(Entry)의 망가진 실시간 변수와 리스트를 대체하는
강력한 실시간 동기화 확장 프로그램

⚠️ 문제: Entry의 실시간 변수가 자꾸 망가져요

엔트리(playentry.org)에서 프로젝트를 만들다 보면 실시간 변수와 실시간 리스트가 제대로 동기화되지 않는 문제를 자주 겪게 됩니다.

🔄 변수 업데이트 누락

다른 탭이나 사용자에서 변경한 값이 반영되지 않거나, 아예 변수가 사라짐

🧩 리스트 깨짐

리스트 항목이 중복되거나, 순서가 뒤섞이거나, 아예 빈 배열로 초기화됨

🔌 연결 불안정

일정 시간이 지나면 동기화가 끊기고, 재연결이 제대로 되지 않음

🛑 제한된 확장성

Entry 자체 실시간 기능은 내부 구현이 복잡하고 디버깅이 어려움

✅ 해결: Entry Sync

Entry Sync는 Entry의 깨지기 쉬운 실시간 변수/리스트 시스템을 완전히 대체합니다. Supabase를 백엔드로 사용하여 안정적이고 빠른 실시간 동기화를 제공합니다.

❌ Entry 기본 실시간
불안정한 연결
데이터 누락 빈번
리스트 동기화 불가
디버깅 어려움
재연결 안 됨
✅ Entry Sync
안정적인 WebSocket 연결
데이터 정합성 보장
리스트 전체 동기화
팝업으로 상태 확인 가능
자동 재연결
💡 개선 효과
연결 유지 시간 무제한
Read-After-Write 검증
push/setArray/insert 등 전체 연산 지원
실시간 연결 상태 표시
Offscreen 문서로 WebSocket 유지

✨ 주요 기능

🔁

실시간 변수 동기화

?! 접두사가 붙은 변수의 값이 모든 탭과 사용자 간 실시간으로 동기화됩니다. 변경 즉시 Supabase DB에 저장되고 WebSocket으로 브로드캐스트됩니다.

📋

실시간 리스트 동기화

?! 접두사가 붙은 리스트의 추가, 삭제, 삽입, 변경, 전체 설정 등 모든 연산을 실시간 동기화합니다. 리스트 연산은 직렬화되어 경합 조건(race condition)이 발생하지 않습니다.

🩺

헬스체크 자동 복구

Entry가 변수값을 0으로 초기화하는 버그를 자동 감지하여 랜덤 값으로 복구합니다. ?! 변수 또는 리스트가 0이 되면 1초 이내에 감지하여 복원합니다.

🔐

ALLOW+SEND 패턴

변수/리스트 변경을 차단하지 않고 허용한 후 변경사항을 전송합니다. Entry의 정상적인 작동을 방해하지 않으면서 동기화가 이루어집니다.

🔄

Read-After-Write 검증

변경사항을 DB에 저장한 후 다시 읽어서(Read-After-Write) 실제 저장된 값으로 브로드캐스트합니다. 데이터 정합성을 보장합니다.

⚡

Realtime WebSocket

MV3 Offscreen Document에서 WebSocket을 유지하여 서비스 워커가 종료되어도 연결이 끊기지 않습니다. 브로드캐스트는 발신자 탭을 제외하고 전달되어 무한 루프를 방지합니다.

🏗️ 아키텍처

확장 프로그램의 데이터 흐름은 다음과 같습니다:

┌─────────────────────────────────────────────────────────────────┐ │ Entry Runtime (MAIN World) │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Variable.prototype.setValue ← monkey-patch │ │ │ │ ListVariable.prototype.* ← monkey-patch │ │ │ │ ↓ window.postMessage │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ Content Script (Isolated World) │ │ Bridge: window.postMessage → chrome.runtime.sendMessage │ │ Inject inject.js into MAIN world via <script> tag │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ Service Worker (background.js) │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ VAR_CHANGED → Supabase REST API (upsert) │ │ │ │ LIST_CHANGED → Supabase REST API (updateListWithOp) │ │ │ │ INIT_SYNC → fetchVars() + fetchLists() │ │ │ │ syncState (in-memory Map) for popup display │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ Offscreen Document (offscreen.js) │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ RealtimeClient (WebSocket to Supabase) │ │ │ │ var:update / list:update broadcast │ │ │ │ _senderTabId로 발신자 제외 전달 │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘
핵심 원칙: Supabase가 단일 진실 공급원(SSOT)입니다. 모든 데이터는 Supabase PostgreSQL에 저장되고, 변경사항은 Realtime WebSocket으로 전파됩니다.

📖 사용 방법

설치

Chrome 웹 스토어에서 Entry Sync를 설치합니다.

https://playentry.org에서 엔트리 프로젝트를 엽니다.

변수 또는 리스트 이름 앞에 ?!를 붙입니다 (예: ?!score, ?!items).

여러 탭이나 다른 사용자와 동일한 프로젝트를 열면 자동으로 실시간 동기화됩니다.

변수명 규칙

✅ 동기화 대상

?!score, ?!hp, ?!items, ?!message
?!로 시작하는 이름 → 실시간 동기화

❌ 동기화 제외

score, hp, temp
?!가 없는 일반 이름 → 동기화 안 됨

참고: ?! 변수/리스트가 0이 되면 헬스체크가 자동으로 감지하여 랜덤 값(1000~9999)으로 복구합니다. 이는 Entry가 변수를 0으로 초기화하는 버그를 우회하기 위한 것입니다.

지원 연산

변수

setValue

리스트

appendValue, deleteValue, insertValue, replaceValue, setArray

📊 팝업 상태 확인

확장 프로그램 아이콘을 클릭하면 현재 동기화 상태와 ?! 변수/리스트 목록을 실시간으로 확인할 수 있습니다. 연결 상태(Connected/Disconnected)와 각 변수의 현재값, 리스트의 항목 수가 표시됩니다.