@kispi/chat 0.2.3 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +77 -250
- package/README.md +67 -242
- package/dist/{chunk-5QQRM7BH.js → chunk-WSBOTTBM.js} +21 -3
- package/dist/index.cjs +63 -40
- package/dist/index.d.cts +141 -388
- package/dist/index.d.ts +141 -388
- package/dist/index.js +46 -36
- package/dist/server/index.cjs +37 -9
- package/dist/server/index.d.cts +20 -14
- package/dist/server/index.d.ts +20 -14
- package/dist/server/index.js +22 -8
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -10,7 +10,8 @@
|
|
|
10
10
|
npm install @kispi/chat
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
이 문서가 **표면 전체**를 적는다.
|
|
13
|
+
이 문서가 **표면 전체**를 적는다. 여기 없는 것은 내부 구현이고, 다음 버전에
|
|
14
|
+
말 없이 바뀐다.
|
|
14
15
|
|
|
15
16
|
---
|
|
16
17
|
|
|
@@ -20,12 +21,9 @@ npm install @kispi/chat
|
|
|
20
21
|
|
|
21
22
|
| 옵션 | 타입 | |
|
|
22
23
|
|---|---|---|
|
|
23
|
-
| `url` | `string` | **필수.** 오리진만 준다. SDK가 `/v1/ws?v=1`을 붙인다 |
|
|
24
24
|
| `key` | `string` | **필수.** `pk_`. 공개값이라 브라우저에 넣어도 된다 |
|
|
25
25
|
| `token` | `() => string \| Promise<string>` | **필수.** 백엔드가 서명한 유저 토큰. 접속할 때마다, 그리고 REST가 401을 받을 때 다시 부르므로 만료된 것이 재사용되지 않는다. 던지면 백오프로 다시 부르고, **`ChatError`를 던지면 다시 부르지 않는다**(아래) |
|
|
26
|
-
| `
|
|
27
|
-
| `externalToken` | `() => string \| Promise<string>` | external 모드. 주면 **`token`보다 우선한다**(서버의 판정 순서와 같다). **서버가 아직 거절하므로 오늘은 쓸 곳이 없다** |
|
|
28
|
-
| `WebSocket` | `new (url) => WebSocketLike` | 전역 대신 쓸 구현. 테스트에서 주입한다 |
|
|
26
|
+
| `WebSocket` | `new (url) => WebSocketLike` | 전역 대신 쓸 구현 |
|
|
29
27
|
| `fetch` | `typeof fetch` | 위와 같음 |
|
|
30
28
|
|
|
31
29
|
`token`을 브라우저에서 만들지 않는다. 서명에 `sk_`가 필요하고, `sk_`가
|
|
@@ -38,7 +36,7 @@ npm install @kispi/chat
|
|
|
38
36
|
| `state` | `'connecting' \| 'open' \| 'reconnecting' \| 'closed'` |
|
|
39
37
|
| `user` | 접속한 사람. `{id, name, avatar?}` — **서버가 토큰에서 받아들인 신원**(hello가 준 것)이다. 토큰 응답을 따로 파싱하지 말고 이것을 쓴다. `connect()`/`reconnect()`가 끝나면 채워져 있다 |
|
|
40
38
|
| `connectionId` | 지원 문의와 강제 종료에 쓰는 식별자 |
|
|
41
|
-
| `hello` | 서버가 접속 때 준 것
|
|
39
|
+
| `hello` | 서버가 접속 때 준 것 전부. `limits`(실효 한도), `unread`(`{total, mentions, roomsCapped?}`, **없는 것은 0이 아니라 '못 셌다'이니 `unread()`로 복구한다**), `warnings`, `serverTime`, `heartbeatMs` |
|
|
42
40
|
|
|
43
41
|
| 메서드 | |
|
|
44
42
|
|---|---|
|
|
@@ -46,13 +44,12 @@ npm install @kispi/chat
|
|
|
46
44
|
| `close()` | 끊는다. 이건 재접속하지 않는다. 다시 붙으려면 `connect()` |
|
|
47
45
|
| `reconnect()` | **다시 인증한다**: `token()`을 다시 불러 소켓을 바꾼다. 방 핸들과 구독, `messages`는 그대로이고 상태는 `open → reconnecting → open`이다(`closed`를 거치지 않는다). 닉네임·아바타를 바꾼 뒤에 쓴다(아래) |
|
|
48
46
|
| `room(roomId)` | 방 핸들. 같은 id면 같은 객체 |
|
|
49
|
-
| `roomByKey(key)` | 키로 여는 방 핸들. 구독할 때 서버가 id를 알려 준다. **방을 만들지 않는다** — 없는 키면 `subscribe()`가 `not_found`로
|
|
47
|
+
| `roomByKey(key)` | 키로 여는 방 핸들. 구독할 때 서버가 id를 알려 준다. **방을 만들지 않는다** — 없는 키면 `subscribe()`가 `not_found`로 거절한다. 방은 백엔드가 `rooms.ensure()`로 만든다 |
|
|
50
48
|
| `rooms.list({cursor?, limit?})` | 내가 멤버인 방 + unread + 마지막 메시지 |
|
|
51
49
|
| `rooms.discover({type?, cursor?, limit?})` | 공개 방 탐색 |
|
|
52
50
|
| `rooms.members(roomId).list/add/remove` | 멤버 관리 |
|
|
53
|
-
| `unread()` |
|
|
51
|
+
| `unread()` | `{total, mentions, roomsCapped?, rooms}`. `chat.hello?.unread`와 **같은 이름**이다 |
|
|
54
52
|
| `updateMe(meta)` | 내 `meta`. **`name`과 `avatar`는 토큰 claim에서 온다** |
|
|
55
|
-
| `send(type, data?, timeoutMs?)` | 날 프레임. 표면에 없는 것을 부를 때만 |
|
|
56
53
|
|
|
57
54
|
| 이벤트 | |
|
|
58
55
|
|---|---|
|
|
@@ -77,7 +74,7 @@ off()
|
|
|
77
74
|
| `id` / `key` | 방 식별자. 키로 열었으면 구독 전까지 `id`가 없다 |
|
|
78
75
|
| `lastSeq` | 서버가 알려 준 방의 마지막 seq |
|
|
79
76
|
| `presence` | `{count, users?, capped?}` |
|
|
80
|
-
| `hasOlder` | `loadOlder()`로 더 읽을 과거가 있는지. 첫 `loadOlder()` 전에 "이전 메시지" 버튼을 그릴지 정할 때 쓴다. `loadOlder()`의 `hasMore`와 같은
|
|
77
|
+
| `hasOlder` | `loadOlder()`로 더 읽을 과거가 있는지. 첫 `loadOlder()` 전에 "이전 메시지" 버튼을 그릴지 정할 때 쓴다. `loadOlder()`의 `hasMore`와 같은 판정이고, 목록이 비었으면 `false`. `messages` 이벤트 때 다시 읽는다 |
|
|
81
78
|
|
|
82
79
|
| 메서드 | |
|
|
83
80
|
|---|---|
|
|
@@ -93,29 +90,34 @@ off()
|
|
|
93
90
|
| `typing()` | 입력 중. 던지지 않는다 |
|
|
94
91
|
| `join()` / `leave()` | 멤버십 |
|
|
95
92
|
| `presenceList()` | 지금 이 방에 있는 사람 |
|
|
96
|
-
| `resume()` | 재접속 후 다시 구독. SDK가 알아서 부른다 |
|
|
97
93
|
|
|
98
|
-
이벤트 이름은 **와이어의 이름
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
94
|
+
이벤트 이름은 **와이어의 이름 그대로**이고, 페이로드는 타입 선언에 있다.
|
|
95
|
+
|
|
96
|
+
| 이벤트 | 페이로드 |
|
|
97
|
+
|---|---|
|
|
98
|
+
| `message.created` / `message.updated` | `Message`. `created`에는 `thread`가 없고 `reactions`가 비어 있다 |
|
|
99
|
+
| `message.deleted` | `{id, seq}`. `seq`는 그 메시지가 **발행될 때** 받은 값이다 |
|
|
100
|
+
| `reaction.added` / `reaction.removed` | `{messageId, emoji, count, userId?}` |
|
|
101
|
+
| `thread.updated` | `{rootId, count, lastSeq?, lastAt?}` |
|
|
102
|
+
| `presence` | `{count, joined?, left?, users?, capped?}`. `joined`/`left`는 증분, `users`는 교체다 |
|
|
103
|
+
| `typing` | `{userId}` |
|
|
104
|
+
| `read` | `{userId, seq, threadId?}` |
|
|
105
|
+
| `member.joined` / `member.left` | `{userId, role?}` |
|
|
106
|
+
| `room.updated` | 방 객체(`unknown` — 서버 표현 그대로다) |
|
|
107
|
+
| `room.deleted` | `{roomId}` |
|
|
108
|
+
| `custom` | `rooms.custom(roomId, payload)`이 보낸 객체 그대로 |
|
|
102
109
|
|
|
103
110
|
와이어에 대응물이 없는 셋을 SDK가 더 낸다.
|
|
104
111
|
|
|
105
112
|
| 이벤트 | 언제 |
|
|
106
113
|
|---|---|
|
|
107
114
|
| `messages` | 목록이 바뀔 때마다. **매번 새 배열이고, 내보낸 배열은 다시 건드리지 않는다** |
|
|
108
|
-
| `error` | 히스토리를 읽거나 구멍을 메우는 데 실패했다. **방이 스스로 다시
|
|
115
|
+
| `error` | 히스토리를 읽거나 구멍을 메우는 데 실패했다. **방이 스스로 다시 구독한다.** 사람이 누를 재시도 버튼은 `subscribe()` |
|
|
109
116
|
| `reset` | 커서가 보존 기간보다 오래돼 목록을 버리고 다시 채웠다. **렌더한 것을 버려야 한다** |
|
|
110
117
|
|
|
111
118
|
### 알아 둘 것
|
|
112
119
|
|
|
113
|
-
**`messages`는
|
|
114
|
-
배열과 그 안의 행 객체는 이후에 고쳐지지 않는다. 그래서 참조로 비교하는 상태에 그대로
|
|
115
|
-
넣으면 된다. 행도 마찬가지로, 이벤트(수정, 삭제, 리액션, 스레드)가 바꾼 행만 새 객체이고
|
|
116
|
-
나머지 행은 참조가 그대로다 — **참조가 같으면 바뀌지 않은 것**이니 행 단위 memo에 써도
|
|
117
|
-
된다. 반대는 약속하지 않는다: `reload()`와 재접속 따라잡기는 같은 내용의 행을 서버에서
|
|
118
|
-
새로 받아 오므로, 참조가 달라도 내용은 같을 수 있다.
|
|
120
|
+
**`messages`는 매번 새 배열이고, 바뀐 행만 새 객체다.** 참조로 비교하는 상태에 그대로 넣는다.
|
|
119
121
|
|
|
120
122
|
```ts
|
|
121
123
|
// Svelte 5
|
|
@@ -131,164 +133,27 @@ const messages = shallowRef<Message[]>([])
|
|
|
131
133
|
room.on('messages', m => (messages.value = m))
|
|
132
134
|
```
|
|
133
135
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
그 행의 `myReactions`를 고치고 `messages`를 내보낸다. 그래서 누른 느낌이 왕복만큼
|
|
145
|
-
늦지 않는다 — 누른 값은 (나, 이모지)로 이미 정해져 있고 서버는 멱등이라, ack가
|
|
146
|
-
새로 알려 줄 것이 없다. 서버가 거절하거나(한도, 권한) ack가 못 오면(타임아웃,
|
|
147
|
-
끊김) 되돌린다. 단, 그 사이 더 새로운 값이 자리를 차지했으면 그대로 둔다: 뒤에 누른
|
|
148
|
-
값, 내 `userId`가 실린 `reaction.*` 이벤트, `reload()`나 재접속이 가져온 페이지가
|
|
149
|
-
모두 대기 중인 낙관값을 이긴다. 거절이 낡은 값을 되살리는 일은 없다.
|
|
150
|
-
**이 필드의 주인은 SDK다** — 위에 자기 낙관 계층을 덧대면 주인이 둘이 된다.
|
|
151
|
-
|
|
152
|
-
**개수(`reactions[].count`)는 늘 서버 값이다.** 로컬에서 ±1하지 않는다. ack를
|
|
153
|
-
기다리는 사이 남이 같은 이모지를 누르면 로컬 계산은 서버가 보낼 수와 어긋나고,
|
|
154
|
-
그 차이를 고쳐 줄 이벤트는 이미 지나갔다. 개수는 `reaction.*` 이벤트가 옮긴다.
|
|
155
|
-
|
|
156
|
-
**발행(`send()`)은 일부러 낙관적이지 않다.** `before_publish` 훅이 본문을 바꿀 수
|
|
157
|
-
있어서(이모지 필터, 링크 치환) 미리 그릴 값이 클라이언트에 없다. 메시지는
|
|
158
|
-
`message.created`가 올 때 목록에 들어간다. 보내는 중 표시가 필요하면 그것은 소비자의
|
|
159
|
-
화면 상태이고, 리액션과 달리 SDK가 대신 정해 줄 수 없다.
|
|
160
|
-
|
|
161
|
-
**과거는 `loadOlder()`로 같은 목록에 붙인다.** `history()`는 목록을 건드리지 않는
|
|
162
|
-
직접 읽기라, 그 결과를 라이브 목록과 합치고 중복을 거르고 `reset`과 재접속을
|
|
163
|
-
처리하는 일이 전부 소비자 몫이 된다. `loadOlder()`는 그 행들을 `messages`에 넣으므로
|
|
164
|
-
정렬·중복 제거·삭제·리액션·재접속이 다른 행과 똑같이 적용된다. 동시에 여러 번
|
|
165
|
-
불러도 요청은 하나이고, `hasMore`가 `false`면 방(또는 보존 기간)의 맨 앞이다.
|
|
166
|
-
`reset`이나 `reload()`는 붙인 과거도 함께 버린다.
|
|
167
|
-
|
|
168
|
-
**`hasOlder`와 `loadOlder()`는 SDK의 목록을 말한다, 당신의 창이 아니라.** SDK는
|
|
169
|
-
`room.messages`를 줄이지 않는다 — 500건을 들고 있으면 500건이 다 거기 있다. 화면
|
|
170
|
-
성능 때문에 받은 배열을 100건으로 잘라 그리고 있다면, 더 보여 줄 400건은 서버가
|
|
171
|
-
아니라 `room.messages`에 있다. 그때 `hasOlder`가 `false`인 것은 맞는 답이다(방의
|
|
172
|
-
맨 앞이라는 뜻이다). 창을 넓히는 일은 `room.messages`를 다시 읽는 것이고, 서버에
|
|
173
|
-
묻는 것은 그 다음이다.
|
|
174
|
-
|
|
175
|
-
```ts
|
|
176
|
-
showLoadMore(room.hasOlder)
|
|
177
|
-
const { hasMore } = await room.loadOlder()
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
**보내도 되는 때는 `await room.subscribe()`가 끝난 때다.** 다만 기다리지 않고
|
|
181
|
-
`send`해도 된다 — 구독이 진행 중이면 `send`(와 `react`, `markRead`, `loadOlder` 등)가
|
|
182
|
-
그것을 기다렸다가 나간다. 구독이 실패하면 그 에러로 거절한다. 구독한 적도 없는
|
|
183
|
-
`roomByKey` 방은 id를 모르므로 곧바로 `closed`로 거절한다. `chat.state`가
|
|
184
|
-
`reconnecting`인 동안의 발행도 `closed`로 거절한다 — SDK는 보낼 것을 쌓아 두지 않는다.
|
|
185
|
-
|
|
186
|
-
**키로 연다고 방이 생기지 않는다.** `roomByKey(key).subscribe()`는 있는 방을 찾기만
|
|
187
|
-
하고, 없으면 `not_found`다. 방은 백엔드가 `sk_`로 만든다
|
|
188
|
-
(`@kispi/chat/server`의 `rooms.ensure({key, type})` — 있으면 그대로 돌려주는
|
|
189
|
-
get-or-create라 페이지를 열 때마다 불러도 된다). 앱 설정 `client_room_create`를 켜면
|
|
190
|
-
유저 토큰으로도 `PUT /v1/rooms`를 부를 수 있지만(허용 타입·키 패턴·하루 50개
|
|
191
|
-
한도), `pk_`는 공개값이라 누구나 방을 찍어낼 수 있는 문이 된다. 기본은 꺼져 있고,
|
|
192
|
-
끄는 쪽을 권한다.
|
|
193
|
-
|
|
194
|
-
**연결은 알아서 돌아온다.** 소켓이 끊기거나 `token()`이 던지면 지수 백오프(0.5초에서
|
|
195
|
-
30초까지, 지터)로 다시 붙는다. **첫 `connect()`도 같다** — 실패하면 `await`는 거절해서
|
|
196
|
-
호출자가 알게 하고, 재시도는 백그라운드에서 이어진다(`state`가 `reconnecting`, 붙으면
|
|
197
|
-
`open`). 서버의 접속 한도(`rate_limited`)와 서버 장애(`internal`)도 같은 길로 다시
|
|
198
|
-
붙는다(한도는 서버가 말한 만큼 기다린다). 그래서 재시도 루프를 직접 짤 필요가 없다.
|
|
199
|
-
|
|
200
|
-
방은 **연결을 기다리지 말고 먼저 구독해 둔다.** `subscribe()`는 붙을 때까지 기다렸다가
|
|
201
|
-
나가므로, 첫 `connect()`가 실패해도 백그라운드 재시도가 붙는 순간 방이 채워진다.
|
|
202
|
-
`await chat.connect()` 뒤에 `subscribe()`를 두면 connect가 거절될 때 구독 줄에 닿지
|
|
203
|
-
않는다.
|
|
204
|
-
|
|
205
|
-
```ts
|
|
206
|
-
const room = chat.roomByKey('lobby')
|
|
207
|
-
room.on('messages', render)
|
|
208
|
-
chat.connect().catch(showOffline) // 실패해도 재시도는 계속된다
|
|
209
|
-
await room.subscribe() // 붙은 뒤 끝난다
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
멈추는 것은 셋이다. `close()`, 서버의 인증 거절(`unauthorized`, `forbidden` — 같은
|
|
213
|
-
토큰을 반복하는 것은 서버를 두드리는 일이다), 그리고 **`token()`이 `ChatError`를 던질
|
|
214
|
-
때**다. 밴이나 끝난 세션처럼 다시 해도 소용없는 실패는 그렇게 알린다:
|
|
215
|
-
|
|
216
|
-
```ts
|
|
217
|
-
token: async () => {
|
|
218
|
-
const res = await fetch('/api/chat-token')
|
|
219
|
-
if (res.status === 403) throw new ChatError('forbidden', 'banned') // 다시 하지 않는다
|
|
220
|
-
if (!res.ok) throw new Error(`token ${res.status}`) // 백오프로 다시 한다
|
|
221
|
-
return (await res.json()).token
|
|
222
|
-
}
|
|
223
|
-
```
|
|
224
|
-
|
|
225
|
-
뒤의 둘은 `state`를 `closed`로 두고 `chat.on('error')`로 이유를 낸다. 재접속 중이나
|
|
226
|
-
REST의 토큰 갱신 중이라 거절을 받을 호출자가 없어도 그렇다. 다시 붙으려면 `connect()`.
|
|
227
|
-
|
|
228
|
-
**닉네임을 바꾸면 `reconnect()`.** 서버는 이름·아바타를 접속할 때 토큰 claim에서
|
|
229
|
-
한 번 읽는다. 그래서 백엔드에서 이름을 바꿔도 이 접속의 다음 메시지는 옛 이름이다.
|
|
230
|
-
`reconnect()`는 `token()`을 다시 불러 새 claim으로 다시 인증하고, 방은 가진 것에서
|
|
231
|
-
이어서 따라잡는다. `close()` + `connect()`도 되지만 `closed`를 거쳐(오프라인 화면이
|
|
232
|
-
깜빡인다) 페이지 리스너까지 떼어 낸다. 옛 소켓에서 ack를 기다리던 프레임은 `closed`로
|
|
233
|
-
거절된다. 끝나면 `chat.user`가 새 신원이다.
|
|
234
|
-
|
|
235
|
-
```ts
|
|
236
|
-
await api.updateNickname(name) // 백엔드가 다음 token()에 새 이름을 싣게 한다
|
|
237
|
-
await chat.reconnect()
|
|
238
|
-
chat.user?.name // 새 이름
|
|
239
|
-
```
|
|
240
|
-
|
|
241
|
-
**토큰 만료는 SDK가 처리한다.** 소켓은 접속할 때 한 번만 인증하므로 토큰이 만료돼도
|
|
242
|
-
멀쩡하지만, REST는 요청마다 토큰을 본다. REST가 401을 받으면 SDK가 `token()`을 다시
|
|
243
|
-
불러 **한 번** 재시도한다. 두 번째 401(오리진, 폐기된 토큰, 밴)은 그대로 던진다.
|
|
244
|
-
주기적으로 재접속할 필요가 없다.
|
|
245
|
-
|
|
246
|
-
SDK는 토큰을 캐시하지도, 꺼내 주지도 않는다. 캐시는 `token()` 안에서 한다(부를
|
|
247
|
-
때마다 백엔드를 칠 필요는 없다). **이 토큰을 자기 백엔드 API의 인증으로 다시 쓰지
|
|
248
|
-
않는다** — 채팅 엔진에 내라고 만든 것이고, 둘을 섞으면 한쪽에 새어 나간 토큰이 다른
|
|
249
|
-
쪽의 열쇠가 된다. 자기 API에는 자기 세션을 쓴다.
|
|
250
|
-
|
|
251
|
-
**정렬과 구멍 메우기는 SDK가 한다.** 프레임이 순서 없이 오거나 재접속으로 구간을
|
|
252
|
-
놓치면 REST로 채운다. 한 페이지(100)를 넘는 구멍도 전부 채운다.
|
|
253
|
-
|
|
254
|
-
**재접속이 복구하는 것은 메시지뿐이다.** 히스토리 라우트가 메시지 하나라서,
|
|
255
|
-
끊긴 동안 **오래된 메시지**에 달린 리액션이나 바뀐 방 이름은 반영되지 않는다.
|
|
256
|
-
그럴 때는 `await room.reload()`.
|
|
257
|
-
|
|
258
|
-
**`typing`은 보낸 사람에게도 온다.** "X가 입력 중"을 그린다면 자기 `userId`를
|
|
259
|
-
건너뛴다.
|
|
260
|
-
|
|
261
|
-
**`reset`을 무시하면 안 된다.** 옛 목록에 이어 붙이면 아무도 메우지 않는 구멍이
|
|
262
|
-
남는다.
|
|
136
|
+
- **`reset`을 무시하면 안 된다.** 옛 목록에 이어 붙이면 아무도 메우지 않는 구멍이 남는다.
|
|
137
|
+
- **과거는 `loadOlder()`로 같은 목록에 붙인다.** `history()`는 목록을 건드리지 않는 직접
|
|
138
|
+
읽기이므로 합치고 중복을 거르는 일이 소비자 몫이 된다.
|
|
139
|
+
- **`typing`은 보낸 사람에게도 온다.** "X가 입력 중"을 그린다면 자기 `userId`를 건너뛴다.
|
|
140
|
+
- **연결은 알아서 돌아온다.** 끊기면 지수 백오프로 다시 붙으니 재시도 루프를 짜지 않는다.
|
|
141
|
+
- **토큰 만료는 SDK가 처리한다.** REST가 401을 받으면 `token()`을 다시 불러 한 번
|
|
142
|
+
재시도한다. 주기적으로 재접속할 필요가 없다.
|
|
143
|
+
- **`token()`이 `ChatError`를 던지면 멈춘다.** 밴처럼 다시 해도 소용없는 실패를 그렇게 알린다.
|
|
144
|
+
- **닉네임·아바타를 바꿨으면 `reconnect()`.** 서버는 그 값을 접속할 때 토큰 claim에서
|
|
145
|
+
한 번 읽는다.
|
|
263
146
|
|
|
264
147
|
### 브라우저에서 쓸 때
|
|
265
148
|
|
|
266
|
-
`pk_`의
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
```sh
|
|
270
|
-
chat-server app create my-app --origins https://example.com
|
|
271
|
-
chat-server key create <app-id> pk --origins https://staging.example.com
|
|
272
|
-
```
|
|
273
|
-
|
|
274
|
-
스킴·호스트·포트가 **정확히** 맞아야 한다. `https://example.com`과
|
|
275
|
-
`https://www.example.com`은 다른 오리진이고, `http://localhost:3000`과
|
|
276
|
-
`http://127.0.0.1:3000`도 다른 오리진이다. 개발용 오리진은 따로 넣는다.
|
|
277
|
-
|
|
278
|
-
**Node에서는 이 설정 없이도 된다.** WHATWG `fetch`와 `WebSocket`은 브라우저 밖에서
|
|
279
|
-
`Origin`을 보내지 않고, 엔진은 `Origin`이 없는 요청을 통과시킨다. 그래서 Node에서
|
|
280
|
-
초록이던 코드가 브라우저에서만 401이 나는 일이 생긴다 — 이 절이 그 이유다.
|
|
149
|
+
`pk_`의 허용 오리진에 **페이지의 오리진을 넣어야 한다.** 이것 하나다 — 서버가 CORS 헤더를
|
|
150
|
+
직접 내므로 프록시를 건드릴 일은 없다. 오리진은 콘솔의 키 화면에서 편집한다.
|
|
281
151
|
|
|
282
|
-
|
|
152
|
+
스킴·호스트·포트가 **정확히** 맞아야 한다. `https://example.com`과 `https://www.example.com`,
|
|
153
|
+
`http://localhost:3000`과 `http://127.0.0.1:3000`이 서로 다른 오리진이다. 개발용은 따로 넣는다.
|
|
283
154
|
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
```
|
|
287
|
-
|
|
288
|
-
**소켓만 되고 REST만 안 되는 것처럼 보이면 여기를 본다.** WebSocket은 CORS 대상이
|
|
289
|
-
아니라서 접속과 라이브 메시지는 멀쩡히 도는데, 히스토리·unread·재접속 구멍 메우기가
|
|
290
|
-
REST라서 그것만 조용히 실패한다. 증상은 "메시지는 오는데 스크롤을 올리면 비어
|
|
291
|
-
있다"로 나타난다.
|
|
155
|
+
목록에 없는 오리진에서는 REST만이 아니라 **접속부터 401이다.** 인증 거절은 SDK가 다시
|
|
156
|
+
시도하지 않으므로 클라이언트가 `closed`에서 멈추고, 이유는 `chat.on('error')`로 온다.
|
|
292
157
|
|
|
293
158
|
### 에러
|
|
294
159
|
|
|
@@ -306,7 +171,7 @@ try {
|
|
|
306
171
|
|
|
307
172
|
| 필드 | |
|
|
308
173
|
|---|---|
|
|
309
|
-
| `code` | `unauthorized`, `
|
|
174
|
+
| `code` | 알려진 값의 유니온(`ChatErrorCode`)이라 오타가 컴파일에서 잡힌다. 서버: `unauthorized`, `forbidden`, `not_found`, `invalid`, `too_large`, `rate_limited`, `banned`, `moderation_denied`, `cursor_too_old`, `internal`. SDK: `timeout`, `closed`. 서버가 새 코드를 내도 좁혀 놓은 타입이 막지 않는다 |
|
|
310
175
|
| `retryAfterMs` | 한도에 걸렸을 때 서버가 알려 준 대기 시간 |
|
|
311
176
|
| `appCode` | `before_publish` 웹훅이 거절하며 붙인 소비자 쪽 코드 |
|
|
312
177
|
| `status` | REST 호출에서 난 에러면 HTTP 상태 |
|
|
@@ -321,9 +186,7 @@ try {
|
|
|
321
186
|
import { createChatServer } from '@kispi/chat/server'
|
|
322
187
|
|
|
323
188
|
const chat = createChatServer({
|
|
324
|
-
|
|
325
|
-
secretKey: process.env.CHAT_SECRET_KEY!,
|
|
326
|
-
keyId: process.env.CHAT_KEY_ID!,
|
|
189
|
+
secretKey: process.env.CHAT_SECRET_KEY!, // sk_…
|
|
327
190
|
webhookSecret: process.env.CHAT_WEBHOOK_SECRET,
|
|
328
191
|
guestSecret: process.env.CHAT_GUEST_SECRET, // guest()를 쓸 때만
|
|
329
192
|
})
|
|
@@ -354,25 +217,16 @@ app.post('/api/chat-token', (req, res) => {
|
|
|
354
217
|
})
|
|
355
218
|
```
|
|
356
219
|
|
|
357
|
-
**브라우저가 돌려준 `userId`를 그대로
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
형식 검사(`g_` + UUID 정규식)는 이것을 막지 못한다. UUID가 추측하기 어려운 것은
|
|
361
|
-
공개된 값 앞에서는 아무 의미가 없다.
|
|
362
|
-
|
|
363
|
-
`guest()`는 브라우저가 id 대신 **자격증명**을 들게 한다. `g1.<userId>.<MAC>`이고 MAC은
|
|
364
|
-
`guestSecret`으로 만든다. 돌아온 자격증명이 검증되면 그 안의 id로, 없거나 틀리면
|
|
365
|
-
새 게스트(`g_` + 무작위 22자, `created: true`)로 서명한다. 가능하면 `httpOnly` 쿠키에
|
|
366
|
-
두어 페이지의 스크립트가 읽지 못하게 한다.
|
|
220
|
+
**브라우저가 돌려준 `userId`를 그대로 서명하지 않는다.** `guest()`는 브라우저가 id 대신
|
|
221
|
+
**자격증명**을 들게 한다 — 검증되면 그 안의 id로, 없거나 틀리면 새 게스트(`created: true`)로
|
|
222
|
+
서명한다. 가능하면 `httpOnly` 쿠키에 둔다.
|
|
367
223
|
|
|
368
224
|
| | |
|
|
369
225
|
|---|---|
|
|
370
|
-
| `guestSecret` | 32자 이상. 백엔드에만 둔다. **`sk_`에서 유도하지 않는다**
|
|
226
|
+
| `guestSecret` | 32자 이상. 백엔드에만 둔다. **`sk_`에서 유도하지 않는다** |
|
|
371
227
|
| 교체 | 배열로 준다: `[새것, 옛것]`. 첫 번째로 서명하고 전부로 검증한다. 옛것으로 검증된 자격증명은 같은 `userId`로 새로 서명해 돌려주므로 다음 방문에 옮겨 간다 |
|
|
372
|
-
| 유출 | 비밀이 새면 누구든 아무 게스트가 될 수 있다. 옛것을 목록에서 **빼면** 모든 게스트가 새 사람이 된다 — 신원을 잃는 것이 사칭보다 낫다 |
|
|
373
228
|
|
|
374
|
-
게스트 id는 `g_`로 시작한다. 로그인 유저의 id
|
|
375
|
-
겹치지 않는다.
|
|
229
|
+
게스트 id는 `g_`로 시작한다. 로그인 유저의 id를 `g_`로 시작하지 않게 하면 겹치지 않는다.
|
|
376
230
|
|
|
377
231
|
### 나머지
|
|
378
232
|
|
|
@@ -380,40 +234,32 @@ app.post('/api/chat-token', (req, res) => {
|
|
|
380
234
|
|---|---|
|
|
381
235
|
| `rooms` | `ensure({key?, type, name?, meta?, members?})`, `ensureDM([a, b])`, `get`, `update`, `delete`, `custom(roomId, payload)`, `presence(roomId, {full?})`, `members.list/add/remove` |
|
|
382
236
|
| `messages` | `send(roomId, {sender, text?, kind?, attachments?, appMeta?, replyTo?, threadId?, clientMessageId?})`, `list`, `delete` |
|
|
383
|
-
| `users` | `list({cursor?, limit?})`, `update`, `
|
|
384
|
-
| `events` | `list({after?, limit?})` —
|
|
385
|
-
| `webhooks` | `verify(headers, rawBody, {now?, tolerance?})` |
|
|
237
|
+
| `users` | `list({cursor?, limit?})`, `update(userId, {name?, avatar?, meta?})`, `withdraw(userId, {purgeMessages?})`, `purgeMessages(userId)`, `ban(userId, {until, reason?})`, `unban(userId)`, `revokeTokens(userId)`, `disconnect(userId, {connectionId?, reason?})` |
|
|
238
|
+
| `events` | `list({after?, limit?})` — 놓친 웹훅 이벤트를 따라잡는다 |
|
|
239
|
+
| `webhooks` | `verify(headers, rawBody, {now?, tolerance?})` — `tolerance`는 밀리초 |
|
|
240
|
+
|
|
241
|
+
`rooms.ensure`는 get-or-create다 — 있으면 그대로 돌려주므로 페이지를 열 때마다 불러도 된다.
|
|
386
242
|
|
|
387
243
|
`rooms.presence(roomId)`는 `{count}`이고, `{full: true}`면 `users`(최대 1000명, 잘리면
|
|
388
244
|
`capped: true`)가 붙는다. 빈 방은 404가 아니라 `{count: 0}`이다.
|
|
389
245
|
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
`
|
|
246
|
+
`rooms.custom(roomId, payload)`은 **저장되지 않는 제어 신호**다. `payload`는 JSON 객체이고
|
|
247
|
+
그대로 `room.on('custom', ...)`에 도착한다. 히스토리도 unread도 웹훅도 남지 않으니, 재접속해도
|
|
248
|
+
받아야 하는 신호는 `messages.send(roomId, {kind:'system', ...})`으로 보낸다.
|
|
249
|
+
|
|
250
|
+
`users.ban`의 `until`은 **unix 밀리초이고 필수다.** 무기한 밴은 먼 미래 시각을 직접 고른다.
|
|
251
|
+
|
|
252
|
+
`users.purgeMessages(userId)`는 그 유저의 메시지를 거두되 **탈퇴시키지 않는다.** 한 번에
|
|
253
|
+
상한만큼만 하므로 `purgeCapped`가 `true`인 동안 다시 부르고, 스팸이면 **밴을 먼저** 한다.
|
|
395
254
|
|
|
396
255
|
```ts
|
|
397
256
|
await chat.users.ban(userId, { until: Date.now() + 7 * 86_400_000, reason: 'spam' })
|
|
398
257
|
while ((await chat.users.purgeMessages(userId)).purgeCapped) {}
|
|
399
258
|
```
|
|
400
259
|
|
|
401
|
-
`users.
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
`users.*`는 그 사람이 **한 번이라도 접속한 뒤에만** 통한다. 유저는 접속으로
|
|
405
|
-
생긴다.
|
|
406
|
-
|
|
407
|
-
`users.list`는 콘솔용이다. uid 역순, `limit` 기본 50 최대 100, `cursor`는 불투명
|
|
408
|
-
문자열이고 빈 문자열이 마지막 페이지다. **탈퇴한 유저도 나오고 `deletedAt`이 그
|
|
409
|
-
표시다** — 살아 있는 유저만 원하면 그것으로 거른다. 방 안의 목록들(멤버·리액션·읽음)이
|
|
410
|
-
탈퇴자의 id를 감추는 것과 반대인데, 그쪽은 **다른 유저**가 읽는 목록이고 이쪽은
|
|
411
|
-
`sk_`가 있어야 하므로 상대가 그 id를 발급한 백엔드 자신이기 때문이다.
|
|
412
|
-
|
|
413
|
-
`rooms.custom(roomId, payload)`은 **저장되지 않는 제어 신호**다. `payload`는 JSON
|
|
414
|
-
객체이고 그대로 `room.on('custom', ...)`에 도착한다. 히스토리도 unread도 웹훅도
|
|
415
|
-
남지 않으니, 그 순간 접속해 있지 않은 사람은 영영 모른다 — 재접속해도 받아야 하는
|
|
416
|
-
신호라면 `messages.send(roomId, {kind:'system', ...})`이다.
|
|
260
|
+
`users.list`는 최신순이고 `limit` 기본 50 최대 100, `cursor`는 불투명 문자열이며 빈
|
|
261
|
+
문자열이 마지막 페이지다. **탈퇴한 유저도 나오고 `deletedAt`이 그 표시다.**
|
|
262
|
+
`users.*`는 그 사람이 **한 번이라도 접속한 뒤에만** 통한다 — 유저는 접속으로 생긴다.
|
|
417
263
|
|
|
418
264
|
### 웹훅
|
|
419
265
|
|
|
@@ -426,30 +272,9 @@ app.post('/chat-hook', express.raw({ type: 'application/json' }), (req, res) =>
|
|
|
426
272
|
})
|
|
427
273
|
```
|
|
428
274
|
|
|
429
|
-
**raw 바디여야 한다.**
|
|
430
|
-
직렬화한 것은 다른 문자열이다.
|
|
431
|
-
|
|
432
|
-
**서명은 헤더도 덮는다.** 정규 문자열이
|
|
433
|
-
`` `${t}\n${event}\n${delivery}\n${rawBody}` ``이고 순서가 고정이다. 그래서
|
|
434
|
-
`verify`는 `X-Chat-Event`와 `X-Chat-Delivery`를 **검증 전에** 읽고, 헤더만
|
|
435
|
-
바꿔치기한 재전송은 통과하지 못한다 — `X-Chat-Delivery`가 중복 제거 키이므로
|
|
436
|
-
그것이 서명 밖에 있으면 캡처한 배달 하나가 얼마든지 새 이벤트로 셀 수 있다.
|
|
437
|
-
|
|
438
|
-
세 가지를 지킨다. `verify`가 서명과 시각(기본 5분)을 보고, **중복 제거는 직접**
|
|
439
|
-
해야 하며(`delivery`로), 10초 안에 2xx로 답해야 한다. 넘기면 실패로 치고 백오프가
|
|
440
|
-
시작된다.
|
|
275
|
+
**raw 바디여야 한다.** 파싱했다가 다시 직렬화한 것은 다른 문자열이라 검증에 실패한다.
|
|
441
276
|
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
## 개발
|
|
445
|
-
|
|
446
|
-
```sh
|
|
447
|
-
pnpm install
|
|
448
|
-
pnpm build # ESM + CJS + 타입 선언
|
|
449
|
-
pnpm exec vitest run
|
|
450
|
-
pnpm exec tsc --noEmit
|
|
451
|
-
```
|
|
277
|
+
세 가지를 지킨다. `verify`가 서명과 시각(기본 5분)을 보고, **중복 제거는 직접** 해야 하며
|
|
278
|
+
(`delivery`로), 10초 안에 2xx로 답해야 한다. 넘기면 실패로 치고 백오프가 시작된다.
|
|
452
279
|
|
|
453
|
-
|
|
454
|
-
흉내 낼 필요가 없고, 통합 계열 파일은 아예 **살아 있는 서버**에 붙는다. 실행에는
|
|
455
|
-
Postgres와 Redis가 필요하다.
|
|
280
|
+
다른 언어로 검증하는 규격은 [웹훅 문서](https://chat.gravex.app/docs/webhooks)에 있다.
|
|
@@ -1,3 +1,11 @@
|
|
|
1
|
+
// src/endpoint.ts
|
|
2
|
+
var ChatEndpoint = "wss://api.chat.gravex.app";
|
|
3
|
+
function restURLFrom(socketURL) {
|
|
4
|
+
if (socketURL.startsWith("wss://")) return `https://${socketURL.slice("wss://".length)}`;
|
|
5
|
+
if (socketURL.startsWith("ws://")) return `http://${socketURL.slice("ws://".length)}`;
|
|
6
|
+
return socketURL;
|
|
7
|
+
}
|
|
8
|
+
|
|
1
9
|
// src/errors.ts
|
|
2
10
|
var ChatError = class extends Error {
|
|
3
11
|
code;
|
|
@@ -5,7 +13,13 @@ var ChatError = class extends Error {
|
|
|
5
13
|
retryAfterMs;
|
|
6
14
|
/** The consumer's own code, when a before_publish hook denied this. */
|
|
7
15
|
appCode;
|
|
8
|
-
/**
|
|
16
|
+
/**
|
|
17
|
+
* The HTTP status, when this came from a REST call.
|
|
18
|
+
*
|
|
19
|
+
* 읽기 전용이다. 이 값은 실패를 만든 응답의 성질이지 나중에 붙이는
|
|
20
|
+
* 꼬리표가 아니고, 쓸 수 있게 두면 소비자가 고쳐 쓴 상태가 SDK가
|
|
21
|
+
* 붙인 것과 구별되지 않는다.
|
|
22
|
+
*/
|
|
9
23
|
status;
|
|
10
24
|
constructor(code, message, extra) {
|
|
11
25
|
super(message);
|
|
@@ -13,9 +27,10 @@ var ChatError = class extends Error {
|
|
|
13
27
|
this.code = code;
|
|
14
28
|
if (extra?.retryAfterMs !== void 0) this.retryAfterMs = extra.retryAfterMs;
|
|
15
29
|
if (extra?.appCode !== void 0) this.appCode = extra.appCode;
|
|
30
|
+
if (extra?.status !== void 0) this.status = extra.status;
|
|
16
31
|
}
|
|
17
32
|
};
|
|
18
|
-
function errorFrom(data, fallback = "the server refused the request") {
|
|
33
|
+
function errorFrom(data, fallback = "the server refused the request", status) {
|
|
19
34
|
if (typeof data === "object" && data !== null) {
|
|
20
35
|
const d = data;
|
|
21
36
|
const inner = d["error"] ?? d;
|
|
@@ -24,12 +39,15 @@ function errorFrom(data, fallback = "the server refused the request") {
|
|
|
24
39
|
const extra = {};
|
|
25
40
|
if (typeof inner["retryAfterMs"] === "number") extra.retryAfterMs = inner["retryAfterMs"];
|
|
26
41
|
if (typeof inner["appCode"] === "string") extra.appCode = inner["appCode"];
|
|
42
|
+
if (status !== void 0) extra.status = status;
|
|
27
43
|
return new ChatError(code, message, extra);
|
|
28
44
|
}
|
|
29
|
-
return new ChatError("internal", fallback);
|
|
45
|
+
return new ChatError("internal", fallback, status === void 0 ? void 0 : { status });
|
|
30
46
|
}
|
|
31
47
|
|
|
32
48
|
export {
|
|
49
|
+
ChatEndpoint,
|
|
50
|
+
restURLFrom,
|
|
33
51
|
ChatError,
|
|
34
52
|
errorFrom
|
|
35
53
|
};
|