File & Document Events

[son-hyejun]

📑 File & Document Events Overview

Category	Event (String)	Direction	Payload Schema	Link
File	file:update	🔁	FileUpdatePayload	file:update
Awareness	awareness:update	🔁	AwarenessUpdatePayload	awareness:update
Document	doc:request	⬆️	-	doc:request
Awareness	awareness:request	⬆️	-	awareness:request

• ⬆️ C -> S: 클라이언트가 서버로 송신 (Request/Emit)
• ⬇️ S -> C: 서버가 클라이언트로 송신 (Response/Broadcast)
• 🔁 C <-> S: 양방향 통신

---

📄 File & Document 상세 명세

file:update

Direction

• Client ↔ Server (파일 변경사항 동기화, 양방향)

Used In (Files)

• packages\common\src\constants\socket-events.ts
• packages\common\src\schemas\socket\file.schema.ts
• apps\client\src\stores\socket-events\file.ts
• apps\server\src\modules\collaboration\collaboration.gateway.ts
• apps\server\src\modules\collaboration\collaboration.service.ts

Schema (Zod) fileUpdatePayloadSchema

z.object({
  message: z.instanceof(Uint8Array),
});

TypeScript Type

type FileUpdatePayload = {
  message: Uint8Array; // Y.js update message (binary encoded)
};

Description

• Y.js 기반 CRDT 문서 동기화를 위한 업데이트 메시지
• 클라이언트가 파일을 수정하면 서버로 전송
• 서버는 같은 방의 다른 참가자들에게 브로드캐스트
• Editor 권한이 있는 참가자만 전송 가능 (PermissionGuard)

---

awareness:update

Direction

• Client ↔ Server (Awareness 상태 동기화, 양방향)

Used In (Files)

• packages\common\src\constants\socket-events.ts
• packages\common\src\schemas\socket\file.schema.ts
• apps\client\src\stores\socket-events\file.ts
• apps\server\src\modules\collaboration\collaboration.gateway.ts
• apps\server\src\modules\collaboration\collaboration.service.ts

Schema (Zod) awarenessUpdatePayloadSchema

z.object({
  message: z.instanceof(Uint8Array),
});

TypeScript Type

type AwarenessUpdatePayload = {
  message: Uint8Array; // Y.js awareness update message (binary encoded)
};

Description

• Y.js Awareness 정보 동기화 (커서 위치, 선택 영역, 사용자 상태 등)
• 클라이언트의 awareness 상태가 변경되면 서버로 전송
• 서버는 같은 방의 다른 참가자들에게 브로드캐스트
• Editor 권한이 있는 참가자만 전송 가능 (PermissionGuard)

---

doc:request

Direction

• Client → Server (문서 초기 상태 요청)

Used In (Files)

• packages\common\src\constants\socket-events.ts
• apps\client\src\stores\socket-events\file.ts
• apps\server\src\modules\collaboration\collaboration.gateway.ts
• apps\server\src\modules\collaboration\collaboration.service.ts

Schema (Zod)

• Payload 없음

Description

• 클라이언트가 방에 입장한 후 문서의 초기 상태를 요청
• 서버는 room:doc 이벤트로 Y.Doc 초기 상태를 응답

---

awareness:request

Direction

• Client → Server (Awareness 초기 상태 요청)

Used In (Files)

• packages\common\src\constants\socket-events.ts
• apps\client\src\stores\socket-events\file.ts
• apps\server\src\modules\collaboration\collaboration.gateway.ts
• apps\server\src\modules\collaboration\collaboration.service.ts

Schema (Zod)

• Payload 없음

Description

• 클라이언트가 방에 입장한 후 awareness의 초기 상태를 요청
• 서버는 room:awareness 이벤트로 awareness 초기 상태를 응답

[son-hyejun]

• ⬆️ C -> S: 클라이언트가 서버로 송신 (Request/Emit)
• ⬇️ S -> C: 서버가 클라이언트로 송신 (Response/Broadcast)
• 🔁 C <-> S: 양방향 통신