@fluojs/socket.io 1.0.0-beta.1 → 1.0.0-beta.3

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.
Files changed (6) hide show
  1. package/README.ko.md +22 -1
  2. package/README.md +22 -1
  3. package/dist/module.js +1 -1
  4. package/dist/types.d.ts +2 -0
  5. package/dist/types.d.ts.map +1 -1
  6. package/package.json +9 -9
package/README.ko.md CHANGED
@@ -58,6 +58,13 @@ this.rooms.joinRoom(socket.id, 'room:123');
58
58
  this.rooms.broadcastToRoom('room:123', 'event', data);
59
59
  ```
60
60
 
61
+ Room helper는 공유 `WebSocketRoomService` 계약을 따르면서 Socket.IO namespace 인식을 추가합니다. gateway handler 안에서는 현재 `@WebSocketGateway({ path })` namespace를 자동으로 추론합니다. gateway handler 밖에서 room helper를 실행할 때는 같은 이름의 room이 다른 Socket.IO namespace에 존재할 수 있으므로 대상 namespace path를 명시적으로 전달하세요.
62
+
63
+ ```ts
64
+ this.rooms.broadcastToRoom('room:123', 'event', data, '/chat');
65
+ this.rooms.joinRoom(socketId, 'room:123', '/chat');
66
+ ```
67
+
61
68
  ### Raw Socket.IO 서버 접근
62
69
 
63
70
  ```ts
@@ -96,7 +103,15 @@ SocketIoModule.forRoot({
96
103
  });
97
104
  ```
98
105
 
99
- 이제 `cors`를 생략하면 `@fluojs/socket.io`는 `origin: false`를 기본값으로 사용하므로 cross-origin 노출은 명시적 opt-in이 필요합니다. `engine.maxHttpBufferSize`를 생략하면 어댑터가 1 MiB Engine.IO payload 상한을 적용합니다.
106
+ `cors`를 생략하면 `@fluojs/socket.io`는 `{ credentials: false, origin: false }`를 기본값으로 사용하므로 cross-origin 노출은 명시적 opt-in이 필요합니다. `engine.maxHttpBufferSize`를 생략하면 어댑터가 1 MiB Engine.IO payload 상한을 적용합니다. 기본값에는 `buffer.maxPendingMessagesPerSocket: 128`, `buffer.overflowPolicy: 'drop-oldest'`, `shutdown.timeoutMs: 5000`도 포함됩니다.
107
+
108
+ ### Guard 계약
109
+
110
+ `auth.connection`은 namespace connect handler가 실행되기 전에 `SocketIoConnectionGuardContext`를 받습니다. `auth.message`는 message handler가 실행되기 전에 `SocketIoMessageGuardContext`를 받습니다. Guard는 `true`, `false`, 또는 `message`, optional `data`, optional `disconnect`를 가진 `SocketIoGuardRejection`을 반환할 수 있으며, message rejection은 `{ error, data }` 형태의 ACK payload를 사용합니다.
111
+
112
+ ### Bun 전용 참고
113
+
114
+ Bun path는 `@socket.io/bun-engine`을 통해 Socket.IO를 지원하지만 static CORS shape가 필요합니다. CORS delegate function과 `cors.origin` array 안의 boolean entry는 지원하지 않습니다. `@WebSocketGateway({ serverBacked })`는 Bun에서 지원하지 않습니다.
100
115
 
101
116
  ### 모듈 등록
102
117
  `SocketIoModule.forRoot(...)`로 Socket.IO를 등록합니다.
@@ -109,6 +124,11 @@ Socket.IO 등록은 소유 모듈의 import 경로에서 구성하여 namespace/
109
124
  - `SocketIoModule.forRoot({ auth, cors, engine, ... })`
110
125
  - `SOCKETIO_SERVER`
111
126
  - `SOCKETIO_ROOM_SERVICE`
127
+ - `SocketIoRoomService`: 공유 room 계약에 Socket.IO namespace-aware `joinRoom`, `leaveRoom`, `broadcastToRoom`, `getRooms` helper를 더한 타입입니다.
128
+ - `SocketIoLifecycleService`: server와 room-service token 뒤에서 동작하는 lifecycle 기반 구현입니다. 애플리케이션 코드는 일반적으로 `SOCKETIO_SERVER` 또는 `SOCKETIO_ROOM_SERVICE`를 주입하세요.
129
+ - 타입: `SocketIoModuleOptions`, `SocketIoConnectionGuardContext`, `SocketIoConnectionGuard`, `SocketIoMessageGuardContext`, `SocketIoMessageGuard`, `SocketIoGuardRejection`.
130
+
131
+ `SocketIoModuleOptions`는 `auth`, `buffer`, `cors`, `engine`, `shutdown`, `transports`를 포함합니다. 지원되는 server-backed runtime adapter가 필요하며, unsupported/noop adapter는 bootstrap 중 빠르게 실패합니다.
112
132
 
113
133
  ## 지원 플랫폼
114
134
 
@@ -122,3 +142,4 @@ Socket.IO 등록은 소유 모듈의 import 경로에서 구성하여 namespace/
122
142
  ## 예제 소스
123
143
 
124
144
  - `packages/socket.io/src/module.test.ts`
145
+ - `packages/socket.io/src/public-surface.test.ts`
package/README.md CHANGED
@@ -59,6 +59,13 @@ this.rooms.joinRoom(socket.id, 'room:123');
59
59
  this.rooms.broadcastToRoom('room:123', 'event', data);
60
60
  ```
61
61
 
62
+ Room helpers follow the shared `WebSocketRoomService` contract and add Socket.IO namespace awareness. Inside a gateway handler the current `@WebSocketGateway({ path })` namespace is inferred automatically. When room helpers run outside gateway handler context, pass the namespace path explicitly so room operations target the intended Socket.IO namespace instead of a same-named room elsewhere.
63
+
64
+ ```typescript
65
+ this.rooms.broadcastToRoom('room:123', 'event', data, '/chat');
66
+ this.rooms.joinRoom(socketId, 'room:123', '/chat');
67
+ ```
68
+
62
69
  ### Accessing the Raw Server
63
70
  You can inject the underlying Socket.IO `Server` instance for low-level control.
64
71
 
@@ -98,7 +105,15 @@ SocketIoModule.forRoot({
98
105
  });
99
106
  ```
100
107
 
101
- When `cors` is omitted, `@fluojs/socket.io` now defaults to `origin: false` so cross-origin exposure stays opt-in. When `engine.maxHttpBufferSize` is omitted, the adapter applies a bounded 1 MiB Engine.IO payload limit.
108
+ When `cors` is omitted, `@fluojs/socket.io` defaults to `{ credentials: false, origin: false }` so cross-origin exposure stays opt-in. When `engine.maxHttpBufferSize` is omitted, the adapter applies a bounded 1 MiB Engine.IO payload limit. Defaults also include `buffer.maxPendingMessagesPerSocket: 128`, `buffer.overflowPolicy: 'drop-oldest'`, and `shutdown.timeoutMs: 5000`.
109
+
110
+ ### Guard contracts
111
+
112
+ `auth.connection` receives `SocketIoConnectionGuardContext` before namespace connect handlers run. `auth.message` receives `SocketIoMessageGuardContext` before message handlers run. Guards can return `true`, `false`, or a `SocketIoGuardRejection` with `message`, optional `data`, and optional `disconnect`; message rejections use ACK payloads shaped as `{ error, data }`.
113
+
114
+ ### Bun-specific notes
115
+
116
+ The Bun path supports Socket.IO through `@socket.io/bun-engine`, but it requires static CORS shapes: no CORS delegate functions and no boolean entries inside `cors.origin` arrays. `@WebSocketGateway({ serverBacked })` is not supported on Bun.
102
117
 
103
118
  ### Module registration
104
119
  Register Socket.IO with `SocketIoModule.forRoot(...)`.
@@ -111,6 +126,11 @@ Register Socket.IO through module imports in the owning module so namespace/mess
111
126
  - `SocketIoModule.forRoot({ auth, cors, engine, ... })`: Configures namespace/message guards plus explicit CORS and Engine.IO payload bounds.
112
127
  - `SOCKETIO_SERVER`: Token to inject the raw Socket.IO `Server`.
113
128
  - `SOCKETIO_ROOM_SERVICE`: Token to inject the `SocketIoRoomService`.
129
+ - `SocketIoRoomService`: Shared room contract plus Socket.IO namespace-aware `joinRoom`, `leaveRoom`, `broadcastToRoom`, and `getRooms` helpers.
130
+ - `SocketIoLifecycleService`: Lifecycle-backed implementation behind the server and room-service tokens; application code should usually inject `SOCKETIO_SERVER` or `SOCKETIO_ROOM_SERVICE` instead.
131
+ - Types: `SocketIoModuleOptions`, `SocketIoConnectionGuardContext`, `SocketIoConnectionGuard`, `SocketIoMessageGuardContext`, `SocketIoMessageGuard`, `SocketIoGuardRejection`.
132
+
133
+ `SocketIoModuleOptions` covers `auth`, `buffer`, `cors`, `engine`, `shutdown`, and `transports`. A supported server-backed runtime adapter is required; unsupported/noop adapters fail fast during bootstrap.
114
134
 
115
135
  ## Supported Platforms
116
136
 
@@ -124,3 +144,4 @@ Register Socket.IO through module imports in the owning module so namespace/mess
124
144
  ## Example Sources
125
145
 
126
146
  - `packages/socket.io/src/module.test.ts`
147
+ - `packages/socket.io/src/public-surface.test.ts`
package/dist/module.js CHANGED
@@ -44,7 +44,7 @@ export class SocketIoModule {
44
44
  class SocketIoRuntimeModule extends SocketIoModule {}
45
45
  return defineModule(SocketIoRuntimeModule, {
46
46
  exports: [SOCKETIO_ROOM_SERVICE, SOCKETIO_SERVER],
47
- global: true,
47
+ global: options.global ?? true,
48
48
  providers: createSocketIoProviderSet(options)
49
49
  });
50
50
  }
package/dist/types.d.ts CHANGED
@@ -86,6 +86,8 @@ export type SocketIoMessageGuard = (context: SocketIoMessageGuardContext) => Pro
86
86
  * Options accepted by {@link SocketIoModule.forRoot}.
87
87
  */
88
88
  export interface SocketIoModuleOptions {
89
+ /** Whether Socket.IO providers should be visible globally. Defaults to `true`. */
90
+ global?: boolean;
89
91
  /**
90
92
  * Optional auth guards evaluated before namespace connections and inbound message handlers proceed.
91
93
  */
package/dist/types.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -9,7 +9,7 @@
9
9
  "realtime",
10
10
  "platform"
11
11
  ],
12
- "version": "1.0.0-beta.1",
12
+ "version": "1.0.0-beta.3",
13
13
  "private": false,
14
14
  "license": "MIT",
15
15
  "repository": {
@@ -37,11 +37,11 @@
37
37
  ],
38
38
  "dependencies": {
39
39
  "@socket.io/bun-engine": "^0.1.0",
40
- "@fluojs/core": "^1.0.0-beta.1",
41
- "@fluojs/runtime": "^1.0.0-beta.1",
42
- "@fluojs/http": "^1.0.0-beta.1",
43
- "@fluojs/websockets": "^1.0.0-beta.1",
44
- "@fluojs/di": "^1.0.0-beta.1"
40
+ "@fluojs/core": "^1.0.0-beta.4",
41
+ "@fluojs/di": "^1.0.0-beta.6",
42
+ "@fluojs/http": "^1.0.0-beta.10",
43
+ "@fluojs/runtime": "^1.0.0-beta.11",
44
+ "@fluojs/websockets": "^1.0.0-beta.5"
45
45
  },
46
46
  "peerDependencies": {
47
47
  "socket.io": "^4.0.0"
@@ -50,9 +50,9 @@
50
50
  "socket.io": "^4.8.1",
51
51
  "socket.io-client": "^4.8.1",
52
52
  "vitest": "^3.2.4",
53
- "@fluojs/platform-express": "^1.0.0-beta.1",
54
- "@fluojs/platform-fastify": "^1.0.0-beta.1",
55
- "@fluojs/platform-nodejs": "^1.0.0-beta.1"
53
+ "@fluojs/platform-express": "^1.0.0-beta.6",
54
+ "@fluojs/platform-fastify": "^1.0.0-beta.8",
55
+ "@fluojs/platform-nodejs": "^1.0.0-beta.4"
56
56
  },
57
57
  "scripts": {
58
58
  "prebuild": "node ../../tooling/scripts/clean-dist.mjs",