@gravito/radiance 1.0.4 → 1.0.5

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 (148) hide show
  1. package/README.md +30 -7
  2. package/dist/core/src/Application.d.ts +256 -0
  3. package/dist/core/src/CommandKernel.d.ts +33 -0
  4. package/dist/core/src/ConfigManager.d.ts +65 -0
  5. package/dist/core/src/Container/RequestScopeManager.d.ts +62 -0
  6. package/dist/core/src/Container/RequestScopeMetrics.d.ts +144 -0
  7. package/dist/core/src/Container.d.ts +153 -0
  8. package/dist/core/src/ErrorHandler.d.ts +66 -0
  9. package/dist/core/src/Event.d.ts +5 -0
  10. package/dist/core/src/EventManager.d.ts +123 -0
  11. package/dist/core/src/GlobalErrorHandlers.d.ts +47 -0
  12. package/dist/core/src/GravitoServer.d.ts +28 -0
  13. package/dist/core/src/HookManager.d.ts +435 -0
  14. package/dist/core/src/Listener.d.ts +4 -0
  15. package/dist/core/src/Logger.d.ts +20 -0
  16. package/dist/core/src/PlanetCore.d.ts +402 -0
  17. package/dist/core/src/RequestContext.d.ts +97 -0
  18. package/dist/core/src/Route.d.ts +36 -0
  19. package/dist/core/src/Router.d.ts +270 -0
  20. package/dist/core/src/ServiceProvider.d.ts +178 -0
  21. package/dist/core/src/adapters/GravitoEngineAdapter.d.ts +27 -0
  22. package/dist/core/src/adapters/bun/BunContext.d.ts +54 -0
  23. package/dist/core/src/adapters/bun/BunNativeAdapter.d.ts +66 -0
  24. package/dist/core/src/adapters/bun/BunRequest.d.ts +31 -0
  25. package/dist/core/src/adapters/bun/BunWebSocketHandler.d.ts +48 -0
  26. package/dist/core/src/adapters/bun/RadixNode.d.ts +19 -0
  27. package/dist/core/src/adapters/bun/RadixRouter.d.ts +32 -0
  28. package/dist/core/src/adapters/bun/index.d.ts +7 -0
  29. package/dist/core/src/adapters/bun/types.d.ts +20 -0
  30. package/dist/core/src/adapters/types.d.ts +235 -0
  31. package/dist/core/src/binary/BinaryUtils.d.ts +105 -0
  32. package/dist/core/src/binary/index.d.ts +5 -0
  33. package/dist/core/src/cli/queue-commands.d.ts +6 -0
  34. package/dist/core/src/compat/async-local-storage.d.ts +7 -0
  35. package/dist/core/src/compat/crypto.d.ts +6 -0
  36. package/dist/core/src/engine/AOTRouter.d.ts +139 -0
  37. package/dist/core/src/engine/FastContext.d.ts +141 -0
  38. package/dist/core/src/engine/Gravito.d.ts +131 -0
  39. package/dist/core/src/engine/MinimalContext.d.ts +102 -0
  40. package/dist/core/src/engine/analyzer.d.ts +113 -0
  41. package/dist/core/src/engine/constants.d.ts +23 -0
  42. package/dist/core/src/engine/index.d.ts +26 -0
  43. package/dist/core/src/engine/path.d.ts +26 -0
  44. package/dist/core/src/engine/pool.d.ts +83 -0
  45. package/dist/core/src/engine/types.d.ts +149 -0
  46. package/dist/core/src/error-handling/RequestScopeErrorContext.d.ts +126 -0
  47. package/dist/core/src/events/BackpressureManager.d.ts +215 -0
  48. package/dist/core/src/events/CircuitBreaker.d.ts +229 -0
  49. package/dist/core/src/events/DeadLetterQueue.d.ts +219 -0
  50. package/dist/core/src/events/EventBackend.d.ts +12 -0
  51. package/dist/core/src/events/EventOptions.d.ts +204 -0
  52. package/dist/core/src/events/EventPriorityQueue.d.ts +63 -0
  53. package/dist/core/src/events/FlowControlStrategy.d.ts +109 -0
  54. package/dist/core/src/events/IdempotencyCache.d.ts +60 -0
  55. package/dist/core/src/events/MessageQueueBridge.d.ts +184 -0
  56. package/dist/core/src/events/PriorityEscalationManager.d.ts +82 -0
  57. package/dist/core/src/events/RetryScheduler.d.ts +104 -0
  58. package/dist/core/src/events/WorkerPool.d.ts +98 -0
  59. package/dist/core/src/events/WorkerPoolConfig.d.ts +153 -0
  60. package/dist/core/src/events/WorkerPoolMetrics.d.ts +65 -0
  61. package/dist/core/src/events/aggregation/AggregationWindow.d.ts +77 -0
  62. package/dist/core/src/events/aggregation/DeduplicationManager.d.ts +135 -0
  63. package/dist/core/src/events/aggregation/EventAggregationManager.d.ts +108 -0
  64. package/dist/core/src/events/aggregation/EventBatcher.d.ts +99 -0
  65. package/dist/core/src/events/aggregation/types.d.ts +117 -0
  66. package/dist/core/src/events/index.d.ts +26 -0
  67. package/dist/core/src/events/observability/EventMetrics.d.ts +132 -0
  68. package/dist/core/src/events/observability/EventTracer.d.ts +68 -0
  69. package/dist/core/src/events/observability/EventTracing.d.ts +161 -0
  70. package/dist/core/src/events/observability/OTelEventMetrics.d.ts +332 -0
  71. package/dist/core/src/events/observability/ObservableHookManager.d.ts +108 -0
  72. package/dist/core/src/events/observability/StreamWorkerMetrics.d.ts +76 -0
  73. package/dist/core/src/events/observability/index.d.ts +24 -0
  74. package/dist/core/src/events/observability/metrics-types.d.ts +16 -0
  75. package/dist/core/src/events/queue-core.d.ts +77 -0
  76. package/dist/core/src/events/task-executor.d.ts +51 -0
  77. package/dist/core/src/events/types.d.ts +134 -0
  78. package/dist/core/src/exceptions/AuthenticationException.d.ts +8 -0
  79. package/dist/core/src/exceptions/AuthorizationException.d.ts +8 -0
  80. package/dist/core/src/exceptions/CircularDependencyException.d.ts +9 -0
  81. package/dist/core/src/exceptions/GravitoException.d.ts +23 -0
  82. package/dist/core/src/exceptions/HttpException.d.ts +9 -0
  83. package/dist/core/src/exceptions/ModelNotFoundException.d.ts +10 -0
  84. package/dist/core/src/exceptions/ValidationException.d.ts +22 -0
  85. package/dist/core/src/exceptions/index.d.ts +7 -0
  86. package/dist/core/src/ffi/NativeAccelerator.d.ts +62 -0
  87. package/dist/core/src/ffi/NativeHasher.d.ts +139 -0
  88. package/dist/core/src/ffi/cbor-fallback.d.ts +96 -0
  89. package/dist/core/src/ffi/hash-fallback.d.ts +33 -0
  90. package/dist/core/src/ffi/index.d.ts +10 -0
  91. package/dist/core/src/ffi/types.d.ts +135 -0
  92. package/dist/core/src/health/HealthProvider.d.ts +67 -0
  93. package/dist/core/src/helpers/Arr.d.ts +19 -0
  94. package/dist/core/src/helpers/Str.d.ts +38 -0
  95. package/dist/core/src/helpers/data.d.ts +25 -0
  96. package/dist/core/src/helpers/errors.d.ts +34 -0
  97. package/dist/core/src/helpers/response.d.ts +41 -0
  98. package/dist/core/src/helpers.d.ts +338 -0
  99. package/dist/core/src/hooks/ActionManager.d.ts +132 -0
  100. package/dist/core/src/hooks/AsyncDetector.d.ts +84 -0
  101. package/dist/core/src/hooks/FilterManager.d.ts +71 -0
  102. package/dist/core/src/hooks/MigrationWarner.d.ts +24 -0
  103. package/dist/core/src/hooks/dlq-operations.d.ts +60 -0
  104. package/dist/core/src/hooks/types.d.ts +107 -0
  105. package/dist/core/src/http/CookieJar.d.ts +51 -0
  106. package/dist/core/src/http/cookie.d.ts +29 -0
  107. package/dist/core/src/http/types.d.ts +395 -0
  108. package/dist/core/src/index.d.ts +565 -0
  109. package/dist/core/src/observability/QueueDashboard.d.ts +136 -0
  110. package/dist/core/src/observability/contracts.d.ts +137 -0
  111. package/dist/core/src/reliability/DeadLetterQueueManager.d.ts +349 -0
  112. package/dist/core/src/reliability/RetryPolicy.d.ts +217 -0
  113. package/dist/core/src/reliability/index.d.ts +6 -0
  114. package/dist/core/src/router/ControllerDispatcher.d.ts +12 -0
  115. package/dist/core/src/router/RequestValidator.d.ts +20 -0
  116. package/dist/core/src/runtime/adapter-bun.d.ts +12 -0
  117. package/dist/core/src/runtime/adapter-deno.d.ts +12 -0
  118. package/dist/core/src/runtime/adapter-node.d.ts +12 -0
  119. package/dist/core/src/runtime/adapter-unknown.d.ts +13 -0
  120. package/dist/core/src/runtime/archive.d.ts +17 -0
  121. package/dist/core/src/runtime/compression.d.ts +21 -0
  122. package/dist/core/src/runtime/deep-equals.d.ts +56 -0
  123. package/dist/core/src/runtime/detection.d.ts +22 -0
  124. package/dist/core/src/runtime/escape.d.ts +34 -0
  125. package/dist/core/src/runtime/index.d.ts +44 -0
  126. package/dist/core/src/runtime/markdown.d.ts +44 -0
  127. package/dist/core/src/runtime/types.d.ts +436 -0
  128. package/dist/core/src/runtime-helpers.d.ts +67 -0
  129. package/dist/core/src/runtime.d.ts +11 -0
  130. package/dist/core/src/security/Encrypter.d.ts +33 -0
  131. package/dist/core/src/security/Hasher.d.ts +29 -0
  132. package/dist/core/src/testing/HttpTester.d.ts +40 -0
  133. package/dist/core/src/testing/TestResponse.d.ts +78 -0
  134. package/dist/core/src/testing/index.d.ts +2 -0
  135. package/dist/core/src/transpiler-utils.d.ts +170 -0
  136. package/dist/core/src/types/events.d.ts +94 -0
  137. package/dist/index.js +1 -294
  138. package/dist/index.js.map +3 -10
  139. package/dist/radiance/src/BroadcastManager.d.ts +124 -0
  140. package/dist/radiance/src/OrbitRadiance.d.ts +98 -0
  141. package/dist/radiance/src/channels/Channel.d.ts +86 -0
  142. package/dist/radiance/src/drivers/AblyDriver.d.ts +73 -0
  143. package/dist/radiance/src/drivers/BroadcastDriver.d.ts +50 -0
  144. package/dist/radiance/src/drivers/PusherDriver.d.ts +95 -0
  145. package/dist/radiance/src/drivers/RedisDriver.d.ts +83 -0
  146. package/dist/radiance/src/drivers/WebSocketDriver.d.ts +89 -0
  147. package/dist/radiance/src/index.d.ts +39 -0
  148. package/package.json +4 -2
@@ -0,0 +1,170 @@
1
+ /**
2
+ * @fileoverview Transpiler 工具庫 - AST 層級代碼分析
3
+ *
4
+ * 使用 Bun.Transpiler API 進行精確的 handler 函式分析,
5
+ * 相比傳統字串匹配,精確度從 ~85% 提升至 ~99%。
6
+ *
7
+ * 核心策略:
8
+ * 1. 使用 transformSync() 標準化代碼格式(統一縮排、引號等)
9
+ * 2. 對轉換後的代碼使用精確的正規表達式匹配 member expression
10
+ * 3. 區分 API 呼叫(.req.header())與變數名稱(const header = ...)
11
+ * 4. 支援解構賦值模式(const { header } = ctx.req)
12
+ * 5. 快取 Transpiler 實例(性能提升 5.9x)+ LRU 快取結果(額外 128x)
13
+ *
14
+ * @module @gravito/core/transpiler-utils
15
+ * @since 3.1.0
16
+ */
17
+ /**
18
+ * TranspilerCache - 管理 Bun.Transpiler 實例與結果快取
19
+ *
20
+ * 避免重複建立 Transpiler(每次建立約需 40µs),
21
+ * 並快取 transformSync 結果(重用快取比每次 transform 快 128x)。
22
+ *
23
+ * @example
24
+ * ```typescript
25
+ * const cache = TranspilerCache.getInstance()
26
+ * const transformed = cache.transform(handlerSource)
27
+ * ```
28
+ */
29
+ export declare class TranspilerCache {
30
+ private static instance;
31
+ /** 共享的 Bun.Transpiler 實例(避免重複建立) */
32
+ private readonly transpiler;
33
+ /** LRU 快取:原始代碼 → 轉換結果 */
34
+ private readonly cache;
35
+ /** 快取大小上限 */
36
+ private readonly maxSize;
37
+ /** 快取 TTL(毫秒),預設 5 分鐘 */
38
+ private readonly ttlMs;
39
+ private constructor();
40
+ /**
41
+ * 取得單例實例
42
+ * 確保全程只建立一個 Transpiler 實例
43
+ */
44
+ static getInstance(): TranspilerCache;
45
+ /**
46
+ * 重置單例(主要用於測試)
47
+ */
48
+ static resetInstance(): void;
49
+ /**
50
+ * 轉換代碼並快取結果
51
+ *
52
+ * 先嘗試從快取取得,若未命中則呼叫 transformSync 並儲存結果。
53
+ * 快取已滿時淘汰最舊的條目(近似 LRU)。
54
+ *
55
+ * 處理兩個 Bun.Transpiler 邊緣案例:
56
+ * 1. 箭頭函式表達式:`async (ctx) => ...` → transformSync 返回空字串
57
+ * 解法:包裝成 `const __fn = <source>` 後再轉換
58
+ * 2. 匿名函式表達式:`function(ctx) {...}` → transformSync 拋出 Parse error
59
+ * 解法:同樣包裝後轉換
60
+ *
61
+ * @param source - 原始 handler 函式字串
62
+ * @returns 轉換後的標準化代碼,若完全失敗則回傳 null
63
+ */
64
+ transform(source: string): string | null;
65
+ /**
66
+ * 實際執行 transformSync,處理箭頭函式和匿名函式的邊緣案例
67
+ *
68
+ * @param source - 原始代碼字串
69
+ * @returns 轉換後的代碼,或失敗時回傳 null
70
+ */
71
+ private doTransform;
72
+ /**
73
+ * 將代碼包裝成賦值語句後再 transform
74
+ *
75
+ * 用於處理無法直接 transform 的函式表達式。
76
+ * 包裝格式:`const __fn = <source>`
77
+ *
78
+ * @param source - 原始函式字串
79
+ * @returns 包裝後的轉換結果,或失敗時回傳 null
80
+ */
81
+ private transformWrapped;
82
+ /**
83
+ * 取得目前快取大小
84
+ */
85
+ get size(): number;
86
+ /**
87
+ * 清除所有快取條目
88
+ */
89
+ clear(): void;
90
+ }
91
+ /**
92
+ * Transpiler 分析的返回結果
93
+ * 與 HandlerAnalysis 介面對應
94
+ */
95
+ export interface TranspilerAnalysisResult {
96
+ usesHeaders: boolean;
97
+ usesQuery: boolean;
98
+ usesBody: boolean;
99
+ usesParams: boolean;
100
+ isAsync: boolean;
101
+ }
102
+ /**
103
+ * 使用 Bun.Transpiler 進行精確的 handler 靜態分析
104
+ *
105
+ * 相比字串匹配,此函式能正確區分:
106
+ * - API 呼叫(`ctx.req.header(name)`)vs 變數名稱(`const header = '...'`)
107
+ * - 解構賦值(`const { header } = ctx.req`)
108
+ * - Minified 代碼(transformSync 先標準化)
109
+ * - 箭頭函式與匿名函式(包裝策略處理 Bun.Transpiler 邊緣案例)
110
+ *
111
+ * 若 Transpiler 轉換失敗,會自動 fallback 到字串匹配模式。
112
+ *
113
+ * ## isAsync 特殊處理
114
+ *
115
+ * `isAsync` 直接從原始碼偵測 `async` 關鍵字,而不是從 transformSync 結果:
116
+ * - 箭頭函式 `async (ctx) => ...` 的 transformSync 返回空字串
117
+ * - `async` 關鍵字本身不存在假陽性問題
118
+ *
119
+ * @param source - handler 函式的字串表示(通常來自 handler.toString())
120
+ * @returns 分析結果,或在 fallback 模式下的近似結果
121
+ *
122
+ * @example
123
+ * ```typescript
124
+ * const handler = async (ctx) => {
125
+ * const name = ctx.req.query('name')
126
+ * return ctx.json({ name })
127
+ * }
128
+ * const result = analyzeHandlerWithTranspiler(handler.toString())
129
+ * // result.usesQuery === true
130
+ * // result.usesHeaders === false(即使有 'header' 字串,也不會誤判)
131
+ * // result.isAsync === true(即使是箭頭函式也能正確偵測)
132
+ * ```
133
+ */
134
+ export declare function analyzeHandlerWithTranspiler(source: string): TranspilerAnalysisResult;
135
+ /**
136
+ * 測試 handler 源代碼是否存取特定的 req 成員屬性
137
+ *
138
+ * 工具函式,方便在 Gravito.ts 等地方進行特定屬性的快速檢測。
139
+ *
140
+ * @param source - handler 函式的字串表示
141
+ * @param property - 要測試的屬性名稱(如 'header', 'query', 'body')
142
+ * @returns 若該屬性被存取則回傳 true
143
+ *
144
+ * @example
145
+ * ```typescript
146
+ * const src = handler.toString()
147
+ * if (hasReqMemberAccess(src, 'header')) {
148
+ * // handler 存取了 header
149
+ * }
150
+ * ```
151
+ */
152
+ export declare function hasReqMemberAccess(source: string, property: string): boolean;
153
+ /**
154
+ * 判斷 handler 是否為非同步函式
155
+ *
156
+ * 直接從原始碼偵測 `async` 關鍵字,不依賴 transformSync 結果,
157
+ * 因為箭頭函式的 transformSync 返回空字串。
158
+ * `async` 關鍵字本身不存在假陽性問題。
159
+ *
160
+ * @param source - handler 函式的字串表示
161
+ * @returns 若為 async 函式則回傳 true
162
+ */
163
+ export declare function isAsyncHandler(source: string): boolean;
164
+ /**
165
+ * 預熱 Transpiler 快取
166
+ *
167
+ * 在應用啟動時呼叫,觸發 Transpiler 實例建立,
168
+ * 避免第一個請求時的冷啟動延遲。
169
+ */
170
+ export declare function warmupTranspilerCache(): void;
@@ -0,0 +1,94 @@
1
+ /**
2
+ * Event system type definitions.
3
+ */
4
+ /**
5
+ * Listener interface.
6
+ *
7
+ * All event listeners must implement this interface.
8
+ */
9
+ export interface Listener<TEvent extends Event = Event> {
10
+ /**
11
+ * Handle an event.
12
+ * @param event - Event instance
13
+ */
14
+ handle(event: TEvent): Promise<void> | void;
15
+ }
16
+ /**
17
+ * Marker interface for listeners that should be queued.
18
+ *
19
+ * Listeners implementing this interface can be dispatched asynchronously via a queue.
20
+ */
21
+ export interface ShouldQueue {
22
+ /**
23
+ * Queue name (optional).
24
+ */
25
+ queue?: string;
26
+ /**
27
+ * Connection name (optional).
28
+ */
29
+ connection?: string;
30
+ /**
31
+ * Delay before execution (seconds).
32
+ */
33
+ delay?: number;
34
+ }
35
+ /**
36
+ * Marker interface for events that should be broadcast.
37
+ *
38
+ * Events implementing this interface can be automatically broadcast to clients.
39
+ */
40
+ export interface ShouldBroadcast {
41
+ /**
42
+ * Define the broadcast channel.
43
+ * @returns Channel name or channel object
44
+ */
45
+ broadcastOn(): string | Channel;
46
+ /**
47
+ * Define broadcast payload (optional).
48
+ * If omitted, public event properties will be used.
49
+ * @returns Broadcast payload
50
+ */
51
+ broadcastWith?(): Record<string, unknown>;
52
+ /**
53
+ * Define the broadcast event name (optional).
54
+ * If omitted, the event class name will be used.
55
+ * @returns Event name
56
+ */
57
+ broadcastAs?(): string;
58
+ }
59
+ /**
60
+ * Channel interface.
61
+ */
62
+ export interface Channel {
63
+ /**
64
+ * Channel name.
65
+ */
66
+ name: string;
67
+ /**
68
+ * Channel type.
69
+ */
70
+ type: 'public' | 'private' | 'presence';
71
+ }
72
+ /**
73
+ * Base event class.
74
+ *
75
+ * All events should extend this class.
76
+ */
77
+ export declare abstract class Event {
78
+ /**
79
+ * Whether this event should be broadcast.
80
+ */
81
+ shouldBroadcast(): boolean;
82
+ /**
83
+ * Get broadcast channel.
84
+ */
85
+ getBroadcastChannel(): string | Channel | null;
86
+ /**
87
+ * Get broadcast payload.
88
+ */
89
+ getBroadcastData(): Record<string, unknown>;
90
+ /**
91
+ * Get broadcast event name.
92
+ */
93
+ getBroadcastEventName(): string;
94
+ }
package/dist/index.js CHANGED
@@ -1,296 +1,3 @@
1
- // src/BroadcastManager.ts
2
- class BroadcastManager {
3
- core;
4
- driver = null;
5
- authCallback;
6
- throwOnError = true;
7
- constructor(core) {
8
- this.core = core;
9
- }
10
- setThrowOnError(throwOnError) {
11
- this.throwOnError = throwOnError;
12
- }
13
- setDriver(driver) {
14
- this.driver = driver;
15
- }
16
- setAuthCallback(callback) {
17
- this.authCallback = callback;
18
- }
19
- async broadcast(_event, channel, data, eventName) {
20
- if (!this.driver) {
21
- this.core.logger.warn("[BroadcastManager] No broadcast driver set, skipping broadcast");
22
- return;
23
- }
24
- try {
25
- await this.driver.broadcast(channel, eventName, data);
26
- } catch (error) {
27
- this.core.logger.error(`[BroadcastManager] Failed to broadcast event ${eventName}:`, error);
28
- if (this.throwOnError) {
29
- throw error;
30
- }
31
- }
32
- }
33
- async authorizeChannel(channel, socketId, userId) {
34
- if (this.authCallback) {
35
- const authorized = await this.authCallback(channel, socketId, userId);
36
- if (!authorized) {
37
- return null;
38
- }
39
- }
40
- if (this.driver?.authorizeChannel) {
41
- return await this.driver.authorizeChannel(channel, socketId, userId);
42
- }
43
- if (channel.startsWith("private-") || channel.startsWith("presence-")) {
44
- return null;
45
- }
46
- return { auth: "" };
47
- }
48
- }
49
- // src/channels/Channel.ts
50
- class PublicChannel {
51
- name;
52
- type = "public";
53
- constructor(name) {
54
- this.name = name;
55
- }
56
- }
57
-
58
- class PrivateChannel {
59
- name;
60
- type = "private";
61
- constructor(name) {
62
- this.name = name;
63
- }
64
- }
65
-
66
- class PresenceChannel {
67
- name;
68
- type = "presence";
69
- constructor(name) {
70
- this.name = name;
71
- }
72
- }
73
- // src/drivers/AblyDriver.ts
74
- class AblyDriver {
75
- config;
76
- baseUrl = "https://rest.ably.io";
77
- constructor(config) {
78
- this.config = config;
79
- }
80
- async broadcast(channel, event, data) {
81
- const path = `/channels/${channel.name}/messages`;
82
- const auth = btoa(this.config.apiKey);
83
- const response = await fetch(`${this.baseUrl}${path}`, {
84
- method: "POST",
85
- headers: {
86
- Authorization: `Basic ${auth}`,
87
- "Content-Type": "application/json"
88
- },
89
- body: JSON.stringify({
90
- name: event,
91
- data
92
- })
93
- });
94
- if (!response.ok) {
95
- const error = await response.text();
96
- throw new Error(`Failed to broadcast via Ably: ${error}`);
97
- }
98
- }
99
- async authorizeChannel(channel, _socketId, userId) {
100
- return {
101
- auth: this.config.apiKey,
102
- ...channel.startsWith("presence-") && userId ? {
103
- channel_data: JSON.stringify({
104
- clientId: userId.toString()
105
- })
106
- } : {}
107
- };
108
- }
109
- }
110
- // src/drivers/PusherDriver.ts
111
- class PusherDriver {
112
- config;
113
- baseUrl;
114
- constructor(config) {
115
- this.config = config;
116
- const cluster = this.config.cluster || "mt1";
117
- this.baseUrl = `https://api-${cluster}.pusher.com`;
118
- }
119
- async broadcast(channel, event, data) {
120
- const path = `/apps/${this.config.appId}/events`;
121
- const body = {
122
- name: event,
123
- channel: channel.name,
124
- data: JSON.stringify(data)
125
- };
126
- const timestamp = Math.floor(Date.now() / 1000);
127
- const queryString = new URLSearchParams({
128
- auth_key: this.config.key,
129
- auth_timestamp: timestamp.toString(),
130
- auth_version: "1.0",
131
- body_md5: this.md5(JSON.stringify(body))
132
- });
133
- const authString = `POST
134
- ${path}
135
- ${queryString.toString()}`;
136
- const authSignature = await this.hmacSHA256(authString, this.config.secret);
137
- queryString.append("auth_signature", authSignature);
138
- const response = await fetch(`${this.baseUrl}${path}?${queryString.toString()}`, {
139
- method: "POST",
140
- headers: {
141
- "Content-Type": "application/json"
142
- },
143
- body: JSON.stringify(body)
144
- });
145
- if (!response.ok) {
146
- const error = await response.text();
147
- throw new Error(`Failed to broadcast via Pusher: ${error}`);
148
- }
149
- }
150
- async authorizeChannel(channel, socketId, userId) {
151
- const stringToSign = `${socketId}:${channel}`;
152
- const signature = await this.hmacSHA256(stringToSign, this.config.secret);
153
- if (channel.startsWith("presence-")) {
154
- const channelData = JSON.stringify({
155
- user_id: userId?.toString(),
156
- user_info: {}
157
- });
158
- return {
159
- auth: `${this.config.key}:${signature}`,
160
- channel_data: channelData
161
- };
162
- }
163
- return {
164
- auth: `${this.config.key}:${signature}`
165
- };
166
- }
167
- async hmacSHA256(message, secret) {
168
- const encoder = new TextEncoder;
169
- const keyData = encoder.encode(secret);
170
- const messageData = encoder.encode(message);
171
- const key = await crypto.subtle.importKey("raw", keyData, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
172
- const signature = await crypto.subtle.sign("HMAC", key, messageData);
173
- const hashArray = Array.from(new Uint8Array(signature));
174
- return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
175
- }
176
- md5(str) {
177
- const hasher = new Bun.CryptoHasher("md5");
178
- hasher.update(str);
179
- return hasher.digest("hex");
180
- }
181
- }
182
- // src/drivers/RedisDriver.ts
183
- class RedisDriver {
184
- config;
185
- redis = null;
186
- constructor(config) {
187
- this.config = config;
188
- }
189
- setRedisClient(client) {
190
- this.redis = client;
191
- }
192
- async broadcast(channel, event, data) {
193
- if (!this.redis) {
194
- throw new Error("Redis client not set. Please install a Redis client and call setRedisClient()");
195
- }
196
- const prefix = this.config.keyPrefix || "gravito:broadcast:";
197
- const channelName = `${prefix}${channel.name}`;
198
- const message = JSON.stringify({
199
- event,
200
- data,
201
- channel: channel.name,
202
- type: channel.type
203
- });
204
- await this.redis.publish(channelName, message);
205
- }
206
- }
207
- // src/drivers/WebSocketDriver.ts
208
- class WebSocketDriver {
209
- config;
210
- constructor(config) {
211
- this.config = config;
212
- }
213
- async broadcast(channel, event, data) {
214
- const message = JSON.stringify({
215
- channel: channel.name,
216
- event,
217
- data
218
- });
219
- let connections = this.config.getConnections();
220
- if (this.config.filterConnectionsByChannel) {
221
- connections = this.config.filterConnectionsByChannel(channel.name);
222
- }
223
- for (const connection of connections) {
224
- if (connection.readyState === 1) {
225
- try {
226
- connection.send(message);
227
- } catch (error) {
228
- this.config.logger?.warn("WebSocket broadcast failed", {
229
- channel: channel.name,
230
- event,
231
- error: error instanceof Error ? error.message : "Unknown error"
232
- });
233
- }
234
- }
235
- }
236
- }
237
- }
238
- // src/OrbitRadiance.ts
239
- class OrbitRadiance {
240
- options;
241
- constructor(options) {
242
- this.options = options;
243
- }
244
- static configure(options) {
245
- return new OrbitRadiance(options);
246
- }
247
- async install(core) {
248
- const manager = new BroadcastManager(core);
249
- if (this.options.throwOnError !== undefined) {
250
- manager.setThrowOnError(this.options.throwOnError);
251
- }
252
- let driver;
253
- switch (this.options.driver) {
254
- case "pusher":
255
- driver = new PusherDriver(this.options.config);
256
- break;
257
- case "ably":
258
- driver = new AblyDriver(this.options.config);
259
- break;
260
- case "redis": {
261
- driver = new RedisDriver(this.options.config);
262
- const redisClient = core.container.make("redis");
263
- if (redisClient) {
264
- driver.setRedisClient(redisClient);
265
- }
266
- break;
267
- }
268
- case "websocket": {
269
- const wsConfig = this.options.config;
270
- if (!wsConfig.logger) {
271
- wsConfig.logger = core.logger;
272
- }
273
- driver = new WebSocketDriver(wsConfig);
274
- break;
275
- }
276
- default:
277
- throw new Error(`Unsupported broadcast driver: ${this.options.driver}`);
278
- }
279
- manager.setDriver(driver);
280
- if (this.options.authorizeChannel) {
281
- manager.setAuthCallback(this.options.authorizeChannel);
282
- }
283
- core.container.instance("broadcast", manager);
284
- if (core.events) {
285
- core.events.setBroadcastManager({
286
- broadcast: async (event, channel, data, eventName) => {
287
- await manager.broadcast(event, channel, data, eventName);
288
- }
289
- });
290
- }
291
- core.logger.info(`[OrbitRadiance] Installed with ${this.options.driver} driver`);
292
- }
293
- }
294
1
  export {
295
2
  WebSocketDriver,
296
3
  RedisDriver,
@@ -303,4 +10,4 @@ export {
303
10
  AblyDriver
304
11
  };
305
12
 
306
- //# debugId=3151C12BCA217F2764756E2164756E21
13
+ //# debugId=00053E5676168F4764756E2164756E21
package/dist/index.js.map CHANGED
@@ -1,16 +1,9 @@
1
1
  {
2
2
  "version": 3,
3
- "sources": ["../src/BroadcastManager.ts", "../src/channels/Channel.ts", "../src/drivers/AblyDriver.ts", "../src/drivers/PusherDriver.ts", "../src/drivers/RedisDriver.ts", "../src/drivers/WebSocketDriver.ts", "../src/OrbitRadiance.ts"],
3
+ "sources": [],
4
4
  "sourcesContent": [
5
- "import type { PlanetCore } from '@gravito/core'\nimport type { BroadcastDriver } from './drivers/BroadcastDriver'\n\n/**\n * Channel authorization callback.\n *\n * Used to verify if a user has permission to join a specific broadcast channel.\n *\n * @param channel - The name of the channel to authorize\n * @param socketId - The unique identifier for the client connection\n * @param userId - The identifier of the user requesting access\n * @returns True if the user is authorized to join the channel\n */\nexport type ChannelAuthorizationCallback = (\n channel: string,\n socketId: string,\n userId?: string | number\n) => Promise<boolean>\n\n/**\n * Central manager for real-time event broadcasting.\n *\n * Orchestrates the delivery of events to various broadcast drivers and handles\n * channel authorization logic. It acts as a bridge between Gravito's event system\n * and external real-time services.\n *\n * @example\n * ```typescript\n * const manager = new BroadcastManager(core);\n * manager.setDriver(new PusherDriver(config));\n * await manager.broadcast(null, { name: 'orders', type: 'public' }, { id: 1 }, 'OrderCreated');\n * ```\n */\nexport class BroadcastManager {\n private driver: BroadcastDriver | null = null\n private authCallback?: ChannelAuthorizationCallback\n private throwOnError = true\n\n constructor(private core: PlanetCore) {}\n\n /**\n * Configure error handling behavior for broadcast operations.\n *\n * Determines whether failures in the underlying broadcast driver should\n * propagate as exceptions or be silently logged.\n *\n * @param throwOnError - Enable or disable exception propagation on failure\n *\n * @example\n * ```typescript\n * manager.setThrowOnError(false); // Log errors instead of throwing\n * ```\n */\n setThrowOnError(throwOnError: boolean): void {\n this.throwOnError = throwOnError\n }\n\n /**\n * Assign the active broadcast delivery driver.\n *\n * Sets the driver responsible for the actual transmission of event data\n * to the real-time service (e.g., Pusher, Ably, Redis).\n *\n * @param driver - The broadcast driver implementation to use\n *\n * @example\n * ```typescript\n * manager.setDriver(new RedisDriver(config));\n * ```\n */\n setDriver(driver: BroadcastDriver): void {\n this.driver = driver\n }\n\n /**\n * Register a custom authorization logic for private channels.\n *\n * Provides a hook to implement business-specific permission checks\n * before allowing a client to subscribe to restricted channels.\n *\n * @param callback - The authorization logic implementation\n *\n * @example\n * ```typescript\n * manager.setAuthCallback(async (channel, socketId, userId) => {\n * return userId === 'admin';\n * });\n * ```\n */\n setAuthCallback(callback: ChannelAuthorizationCallback): void {\n this.authCallback = callback\n }\n\n /**\n * Transmit an event payload to a specific channel.\n *\n * Forwards the event data to the configured driver. If no driver is set,\n * the broadcast is skipped with a warning.\n *\n * @param _event - The original event instance (reserved for future use)\n * @param channel - Target channel metadata including name and visibility type\n * @param data - The serializable payload to be transmitted\n * @param eventName - The name of the event as it will appear on the client\n * @throws {Error} If the driver fails and throwOnError is enabled\n *\n * @example\n * ```typescript\n * await manager.broadcast(\n * null,\n * { name: 'private-user.1', type: 'private' },\n * { message: 'Hello' },\n * 'UserMessage'\n * );\n * ```\n */\n async broadcast(\n _event: unknown,\n channel: { name: string; type: string },\n data: Record<string, unknown>,\n eventName: string\n ): Promise<void> {\n if (!this.driver) {\n this.core.logger.warn('[BroadcastManager] No broadcast driver set, skipping broadcast')\n return\n }\n\n try {\n await this.driver.broadcast(channel, eventName, data)\n } catch (error) {\n this.core.logger.error(`[BroadcastManager] Failed to broadcast event ${eventName}:`, error)\n if (this.throwOnError) {\n throw error\n }\n }\n }\n\n /**\n * Validate client access to a specific channel.\n *\n * Executes the registered authorization callback and, if available,\n * delegates to the driver's native authorization mechanism.\n *\n * @param channel - The name of the channel to authorize\n * @param socketId - The unique identifier for the client connection\n * @param userId - The identifier of the user requesting access\n * @returns The authorization payload or null if access is denied\n *\n * @example\n * ```typescript\n * const auth = await manager.authorizeChannel('private-user.1', '123.456', 'user_1');\n * ```\n */\n async authorizeChannel(\n channel: string,\n socketId: string,\n userId?: string | number\n ): Promise<{ auth: string; channel_data?: string } | null> {\n // Check authorization callback first.\n if (this.authCallback) {\n const authorized = await this.authCallback(channel, socketId, userId)\n if (!authorized) {\n return null\n }\n }\n\n // If the driver supports authorization, use it.\n if (this.driver?.authorizeChannel) {\n return await this.driver.authorizeChannel(channel, socketId, userId)\n }\n\n // Default deny for private/presence channels.\n if (channel.startsWith('private-') || channel.startsWith('presence-')) {\n return null\n }\n\n // Public channels do not require authorization.\n return { auth: '' }\n }\n}\n",
6
- "/**\n * Base channel interface representing a broadcast destination.\n *\n * Channels segregate broadcast traffic. Different channel types imply different\n * access control rules and behaviors.\n */\nexport interface Channel {\n /**\n * The unique identifier for the channel.\n *\n * @remarks\n * For private/presence channels, this typically includes a prefix like 'private-' or 'presence-'.\n */\n name: string\n\n /**\n * The security level and behavior type of the channel.\n */\n type: 'public' | 'private' | 'presence'\n}\n\n/**\n * A public channel open to any subscriber.\n *\n * Public channels require no authorization. Any client can subscribe and listen\n * to events broadcast on these channels.\n *\n * @example\n * ```typescript\n * const channel = new PublicChannel('orders');\n * ```\n */\nexport class PublicChannel implements Channel {\n type = 'public' as const\n\n /**\n * Creates a new PublicChannel instance.\n *\n * @param name - The name of the channel (without prefixes).\n */\n constructor(public name: string) {}\n}\n\n/**\n * A private channel requiring authorization.\n *\n * Private channels are secured and require the client to provide an authentication\n * signature (usually via an auth endpoint) before subscription is allowed.\n * Suitable for sensitive user data.\n *\n * @example\n * ```typescript\n * const channel = new PrivateChannel('user.123');\n * // Driver may prefix this as 'private-user.123'\n * ```\n */\nexport class PrivateChannel implements Channel {\n type = 'private' as const\n\n /**\n * Creates a new PrivateChannel instance.\n *\n * @param name - The name of the channel.\n */\n constructor(public name: string) {}\n}\n\n/**\n * A presence channel that tracks online users.\n *\n * Presence channels extend private channels by adding the ability to know *who*\n * is subscribed. They are commonly used for chat rooms, \"user is typing\" indicators,\n * and online user lists.\n *\n * @example\n * ```typescript\n * const channel = new PresenceChannel('chat.room.1');\n * // Driver may prefix this as 'presence-chat.room.1'\n * ```\n */\nexport class PresenceChannel implements Channel {\n type = 'presence' as const\n\n /**\n * Creates a new PresenceChannel instance.\n *\n * @param name - The name of the channel.\n */\n constructor(public name: string) {}\n}\n",
7
- "import type { BroadcastDriver } from './BroadcastDriver'\n\n/**\n * Configuration options for the Ably broadcast driver.\n */\nexport interface AblyDriverConfig {\n /**\n * The Ably API key.\n *\n * Format: \"appId.keyId:secret\"\n */\n apiKey: string\n}\n\n/**\n * Ably broadcast driver implementation.\n *\n * Uses the Ably REST API to publish messages to channels.\n * Suitable for high-reliability global messaging without managing infrastructure.\n *\n * @remarks\n * This driver uses standard HTTP fetch for publishing and does not require the full Ably SDK.\n * Presence authorization is implemented using a basic compatible format.\n *\n * @example\n * ```typescript\n * const driver = new AblyDriver({\n * apiKey: 'APP_ID.KEY_ID:SECRET'\n * });\n * ```\n */\nexport class AblyDriver implements BroadcastDriver {\n private baseUrl = 'https://rest.ably.io'\n\n /**\n * Creates a new AblyDriver instance.\n *\n * @param config - The Ably connection configuration.\n */\n constructor(private config: AblyDriverConfig) {}\n\n /**\n * Broadcast an event to an Ably channel.\n *\n * @param channel - The target channel metadata.\n * @param event - The name of the event.\n * @param data - The event payload.\n * @throws {Error} If the Ably API request fails.\n *\n * @example\n * ```typescript\n * await driver.broadcast({ name: 'orders', type: 'public' }, 'OrderCreated', { id: 123 });\n * ```\n */\n async broadcast(\n channel: { name: string; type: string },\n event: string,\n data: Record<string, unknown>\n ): Promise<void> {\n const path = `/channels/${channel.name}/messages`\n const auth = btoa(this.config.apiKey)\n\n const response = await fetch(`${this.baseUrl}${path}`, {\n method: 'POST',\n headers: {\n Authorization: `Basic ${auth}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n name: event,\n data,\n }),\n })\n\n if (!response.ok) {\n const error = await response.text()\n throw new Error(`Failed to broadcast via Ably: ${error}`)\n }\n }\n\n /**\n * Authorize a client for a private or presence channel.\n *\n * @param channel - The channel name.\n * @param _socketId - The socket ID (unused by Ably REST auth in this simple mode).\n * @param userId - The user ID (used for presence).\n * @returns The authorization object.\n *\n * @example\n * ```typescript\n * const auth = await driver.authorizeChannel('presence-chat', 'socket-1', 'user-1');\n * ```\n */\n async authorizeChannel(\n channel: string,\n _socketId: string,\n userId?: string | number\n ): Promise<{ auth: string; channel_data?: string }> {\n // Ably uses a different authorization mechanism.\n // This is only a basic implementation.\n return {\n auth: this.config.apiKey,\n ...(channel.startsWith('presence-') && userId\n ? {\n channel_data: JSON.stringify({\n clientId: userId.toString(),\n }),\n }\n : {}),\n }\n }\n}\n",
8
- "import type { BroadcastDriver } from './BroadcastDriver'\n\n/**\n * Configuration for the Pusher broadcast driver.\n */\nexport interface PusherDriverConfig {\n /**\n * The application ID provided by Pusher.\n */\n appId: string\n\n /**\n * The public application key.\n */\n key: string\n\n /**\n * The secret key for signing requests.\n */\n secret: string\n\n /**\n * The Pusher cluster to connect to (e.g., 'mt1', 'eu').\n * @defaultValue 'mt1'\n */\n cluster?: string\n\n /**\n * Whether to force TLS (HTTPS) for API requests.\n * @defaultValue true\n */\n useTLS?: boolean\n}\n\n/**\n * Pusher broadcast driver implementation.\n *\n * Interacts with the Pusher HTTP API to trigger events on channels.\n * It handles request signing, authentication generation for private channels,\n * and HTTP communication using the native Fetch API.\n *\n * @remarks\n * This driver avoids heavy dependencies by implementing the necessary crypto\n * signatures (HMAC-SHA256 and MD5) using standard Web Crypto or Bun APIs.\n *\n * @example\n * ```typescript\n * const driver = new PusherDriver({\n * appId: '123456',\n * key: 'my-app-key',\n * secret: 'my-app-secret',\n * cluster: 'us2'\n * });\n * ```\n */\nexport class PusherDriver implements BroadcastDriver {\n private baseUrl: string\n\n /**\n * Creates a new PusherDriver instance.\n *\n * @param config - The Pusher connection configuration.\n */\n constructor(private config: PusherDriverConfig) {\n const cluster = this.config.cluster || 'mt1'\n this.baseUrl = `https://api-${cluster}.pusher.com`\n }\n\n /**\n * Broadcast an event to a channel via the Pusher API.\n *\n * @param channel - The target channel metadata.\n * @param event - The name of the event.\n * @param data - The event payload.\n * @throws {Error} If the Pusher API returns a non-200 response.\n *\n * @example\n * ```typescript\n * await driver.broadcast({ name: 'news', type: 'public' }, 'BreakingNews', { title: 'Hello' });\n * ```\n */\n async broadcast(\n channel: { name: string; type: string },\n event: string,\n data: Record<string, unknown>\n ): Promise<void> {\n const path = `/apps/${this.config.appId}/events`\n const body = {\n name: event,\n channel: channel.name,\n data: JSON.stringify(data),\n }\n\n const timestamp = Math.floor(Date.now() / 1000)\n const queryString = new URLSearchParams({\n auth_key: this.config.key,\n auth_timestamp: timestamp.toString(),\n auth_version: '1.0',\n body_md5: this.md5(JSON.stringify(body)),\n })\n\n const authString = `POST\\n${path}\\n${queryString.toString()}`\n const authSignature = await this.hmacSHA256(authString, this.config.secret)\n\n queryString.append('auth_signature', authSignature)\n\n const response = await fetch(`${this.baseUrl}${path}?${queryString.toString()}`, {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify(body),\n })\n\n if (!response.ok) {\n const error = await response.text()\n throw new Error(`Failed to broadcast via Pusher: ${error}`)\n }\n }\n\n /**\n * Generate an authorization signature for private or presence channels.\n *\n * @param channel - The name of the channel.\n * @param socketId - The client's socket ID.\n * @param userId - The user ID (required for presence channels).\n * @returns The auth object expected by Pusher client libraries.\n *\n * @example\n * ```typescript\n * const auth = await driver.authorizeChannel('private-user.1', '123.456');\n * ```\n */\n async authorizeChannel(\n channel: string,\n socketId: string,\n userId?: string | number\n ): Promise<{ auth: string; channel_data?: string }> {\n const stringToSign = `${socketId}:${channel}`\n const signature = await this.hmacSHA256(stringToSign, this.config.secret)\n\n if (channel.startsWith('presence-')) {\n const channelData = JSON.stringify({\n user_id: userId?.toString(),\n user_info: {},\n })\n return {\n auth: `${this.config.key}:${signature}`,\n channel_data: channelData,\n }\n }\n\n return {\n auth: `${this.config.key}:${signature}`,\n }\n }\n\n private async hmacSHA256(message: string, secret: string): Promise<string> {\n // Uses the Web Crypto API.\n const encoder = new TextEncoder()\n const keyData = encoder.encode(secret)\n const messageData = encoder.encode(message)\n\n const key = await crypto.subtle.importKey(\n 'raw',\n keyData,\n { name: 'HMAC', hash: 'SHA-256' },\n false,\n ['sign']\n )\n\n const signature = await crypto.subtle.sign('HMAC', key, messageData)\n const hashArray = Array.from(new Uint8Array(signature))\n return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('')\n }\n\n private md5(str: string): string {\n const hasher = new Bun.CryptoHasher('md5')\n hasher.update(str)\n return hasher.digest('hex')\n }\n}\n",
9
- "import type { BroadcastDriver } from './BroadcastDriver'\n\n/**\n * Configuration options for the Redis broadcast driver.\n */\nexport interface RedisDriverConfig {\n /**\n * The Redis connection URL.\n * @example 'redis://localhost:6379'\n */\n url?: string\n\n /**\n * The Redis host address.\n */\n host?: string\n\n /**\n * The Redis port number.\n */\n port?: number\n\n /**\n * The Redis password for authentication.\n */\n password?: string\n\n /**\n * The Redis database index.\n */\n db?: number\n\n /**\n * The prefix to use for Pub/Sub channels.\n * @defaultValue 'gravito:broadcast:'\n */\n keyPrefix?: string\n}\n\n/**\n * Redis broadcast driver implementation.\n *\n * Leverages Redis Pub/Sub to broadcast messages. This is ideal for internal\n * microservices or when managing your own WebSocket server fleet that subscribes to Redis.\n *\n * @remarks\n * This driver is an adapter and requires an external Redis client instance to be injected.\n * It is compatible with any Redis client that exposes a `publish` method.\n *\n * @example\n * ```typescript\n * const driver = new RedisDriver({ keyPrefix: 'app:' });\n * driver.setRedisClient(redis);\n * ```\n */\nexport class RedisDriver implements BroadcastDriver {\n private redis: {\n publish(channel: string, message: string): Promise<number>\n } | null = null\n\n /**\n * Creates a new RedisDriver instance.\n *\n * @param config - The Redis configuration options.\n */\n constructor(private config: RedisDriverConfig) {\n // The Redis client should be injected from the outside.\n // This class only provides the adapter interface.\n }\n\n /**\n * Inject the Redis client instance.\n *\n * @param client - A compatible Redis client (must have a publish method).\n */\n setRedisClient(client: { publish(channel: string, message: string): Promise<number> }): void {\n this.redis = client\n }\n\n /**\n * Broadcast an event to a Redis channel.\n *\n * @param channel - The target channel metadata.\n * @param event - The name of the event.\n * @param data - The event payload.\n * @throws {Error} If the Redis client has not been set.\n *\n * @example\n * ```typescript\n * await driver.broadcast({ name: 'system', type: 'public' }, 'Alert', { msg: 'Down' });\n * ```\n */\n async broadcast(\n channel: { name: string; type: string },\n event: string,\n data: Record<string, unknown>\n ): Promise<void> {\n if (!this.redis) {\n throw new Error(\n 'Redis client not set. Please install a Redis client and call setRedisClient()'\n )\n }\n\n const prefix = this.config.keyPrefix || 'gravito:broadcast:'\n const channelName = `${prefix}${channel.name}`\n const message = JSON.stringify({\n event,\n data,\n channel: channel.name,\n type: channel.type,\n })\n\n await this.redis.publish(channelName, message)\n }\n}\n",
10
- "import type { Logger } from '@gravito/core'\nimport type { BroadcastDriver } from './BroadcastDriver'\n\n/**\n * Interface representing a WebSocket connection.\n *\n * Abstracts the native WebSocket or similar connection object to allow\n * different underlying implementations (e.g., standard WebSocket, uWebSockets.js).\n */\nexport interface WebSocketConnection {\n /**\n * Send a message to the client.\n *\n * @param data - The stringified message payload.\n */\n send(data: string): void\n\n /**\n * Close the connection.\n */\n close(): void\n\n /**\n * The current state of the connection (1 = OPEN).\n */\n readyState: number\n}\n\n/**\n * Configuration for the WebSocket broadcast driver.\n */\nexport interface WebSocketDriverConfig {\n /**\n * Retrieve all active WebSocket connections.\n *\n * This function is called on every broadcast to get the list of recipients.\n */\n getConnections(): WebSocketConnection[]\n\n /**\n * Optional strategy to filter connections based on channel subscriptions.\n *\n * @param channel - The name of the channel to filter by.\n */\n filterConnectionsByChannel?(channel: string): WebSocketConnection[]\n\n /**\n * Logger instance for reporting broadcast failures.\n */\n logger?: Logger\n}\n\n/**\n * Native WebSocket broadcast driver.\n *\n * Broadcasts events directly to connected WebSocket clients.\n * Ideal for single-node deployments or simple setups where you want to\n * avoid external dependencies like Pusher or Redis.\n *\n * @remarks\n * This driver iterates over all (or filtered) connections and sends the message.\n * It is not scalable across multiple nodes without an additional sync mechanism (like Redis).\n *\n * @example\n * ```typescript\n * const driver = new WebSocketDriver({\n * getConnections: () => Array.from(wss.clients),\n * logger: console\n * });\n * ```\n */\nexport class WebSocketDriver implements BroadcastDriver {\n /**\n * Creates a new WebSocketDriver instance.\n *\n * @param config - Driver configuration.\n */\n constructor(private config: WebSocketDriverConfig) {}\n\n /**\n * Broadcast an event to WebSocket clients.\n *\n * @param channel - The target channel metadata.\n * @param event - The name of the event.\n * @param data - The event payload.\n *\n * @example\n * ```typescript\n * await driver.broadcast({ name: 'chat', type: 'public' }, 'NewMessage', { text: 'Hi' });\n * ```\n */\n async broadcast(\n channel: { name: string; type: string },\n event: string,\n data: Record<string, unknown>\n ): Promise<void> {\n const message = JSON.stringify({\n channel: channel.name,\n event,\n data,\n })\n\n let connections = this.config.getConnections()\n\n // If channel filtering is supported, use it.\n if (this.config.filterConnectionsByChannel) {\n connections = this.config.filterConnectionsByChannel(channel.name)\n }\n\n // Send to all connections.\n for (const connection of connections) {\n if (connection.readyState === 1) {\n // WebSocket.OPEN\n try {\n connection.send(message)\n } catch (error) {\n this.config.logger?.warn('WebSocket broadcast failed', {\n channel: channel.name,\n event,\n error: error instanceof Error ? error.message : 'Unknown error',\n })\n }\n }\n }\n }\n}\n",
11
- "import type { GravitoOrbit, PlanetCore } from '@gravito/core'\nimport { BroadcastManager } from './BroadcastManager'\nimport type { AblyDriverConfig } from './drivers/AblyDriver'\nimport { AblyDriver } from './drivers/AblyDriver'\nimport type { BroadcastDriver } from './drivers/BroadcastDriver'\nimport type { PusherDriverConfig } from './drivers/PusherDriver'\nimport { PusherDriver } from './drivers/PusherDriver'\nimport type { RedisDriverConfig } from './drivers/RedisDriver'\nimport { RedisDriver } from './drivers/RedisDriver'\nimport type { WebSocketDriverConfig } from './drivers/WebSocketDriver'\nimport { WebSocketDriver } from './drivers/WebSocketDriver'\n\n/**\n * Configuration options for the Radiance broadcasting orbit.\n *\n * Defines the delivery provider, its specific credentials, and optional\n * hooks for security and error handling.\n *\n * @public\n */\nexport interface OrbitRadianceOptions {\n /**\n * The underlying delivery service provider.\n *\n * - pusher: Industry standard WebSocket service\n * - ably: High-reliability global edge network\n * - redis: Pub/Sub for internal microservices\n * - websocket: Direct server-to-client communication\n */\n driver: 'pusher' | 'ably' | 'redis' | 'websocket'\n\n /**\n * Provider-specific connection and authentication settings.\n */\n config: PusherDriverConfig | AblyDriverConfig | RedisDriverConfig | WebSocketDriverConfig\n\n /**\n * Hook for implementing custom channel access control.\n *\n * @param channel - The name of the channel being accessed\n * @param socketId - The unique client connection identifier\n * @param userId - The authenticated user's identifier\n * @returns True if the subscription request should be granted\n */\n authorizeChannel?: (\n channel: string,\n socketId: string,\n userId?: string | number\n ) => Promise<boolean>\n\n /**\n * Control whether broadcast failures should interrupt the execution flow.\n * @defaultValue true\n */\n throwOnError?: boolean\n}\n\n/**\n * OrbitRadiance provides real-time event broadcasting capabilities.\n *\n * It abstracts various delivery providers (Pusher, Ably, etc.) and integrates\n * seamlessly with Gravito's Event system. When installed, it enables automatic\n * broadcasting of events that implement the `ShouldBroadcast` interface.\n *\n * @example\n * ```typescript\n * const radiance = OrbitRadiance.configure({\n * driver: 'pusher',\n * config: { appId: '...', key: '...', secret: '...' }\n * });\n * core.addOrbit(radiance);\n * ```\n * @public\n */\nexport class OrbitRadiance implements GravitoOrbit {\n private options: OrbitRadianceOptions\n\n constructor(options: OrbitRadianceOptions) {\n this.options = options\n }\n\n /**\n * Create a new OrbitRadiance instance with the specified configuration.\n *\n * This static factory method is the preferred way to initialize the orbit\n * before adding it to the PlanetCore.\n *\n * @param options - The configuration settings for the broadcaster\n * @returns A configured OrbitRadiance instance\n *\n * @example\n * ```typescript\n * const orbit = OrbitRadiance.configure({\n * driver: 'redis',\n * config: { url: 'redis://localhost:6379' }\n * });\n * ```\n */\n static configure(options: OrbitRadianceOptions): OrbitRadiance {\n return new OrbitRadiance(options)\n }\n\n /**\n * Initialize and register the broadcasting system into the core.\n *\n * Sets up the BroadcastManager, initializes the selected driver, and\n * hooks into the EventManager to enable automatic event broadcasting.\n *\n * @param core - The PlanetCore instance where the orbit is being installed\n * @throws {Error} If an unsupported driver is specified in options\n */\n async install(core: PlanetCore): Promise<void> {\n const manager = new BroadcastManager(core)\n\n if (this.options.throwOnError !== undefined) {\n manager.setThrowOnError(this.options.throwOnError)\n }\n\n // Create and set driver.\n let driver: BroadcastDriver\n\n switch (this.options.driver) {\n case 'pusher':\n driver = new PusherDriver(this.options.config as PusherDriverConfig)\n break\n case 'ably':\n driver = new AblyDriver(this.options.config as AblyDriverConfig)\n break\n case 'redis': {\n driver = new RedisDriver(this.options.config as RedisDriverConfig)\n // If a Redis client is provided via core container, set it.\n const redisClient = core.container.make('redis') as\n | { publish(channel: string, message: string): Promise<number> }\n | undefined\n if (redisClient) {\n ;(driver as RedisDriver).setRedisClient(redisClient)\n }\n break\n }\n case 'websocket': {\n const wsConfig = this.options.config as WebSocketDriverConfig\n if (!wsConfig.logger) {\n wsConfig.logger = core.logger\n }\n driver = new WebSocketDriver(wsConfig)\n break\n }\n default:\n throw new Error(`Unsupported broadcast driver: ${this.options.driver}`)\n }\n\n manager.setDriver(driver)\n\n // Set auth callback.\n if (this.options.authorizeChannel) {\n manager.setAuthCallback(this.options.authorizeChannel)\n }\n\n // Register into core container\n core.container.instance('broadcast', manager)\n\n // Integrate with EventManager.\n if (core.events) {\n core.events.setBroadcastManager({\n broadcast: async (event: any, channel: any, data: any, eventName: any) => {\n await manager.broadcast(event, channel, data, eventName)\n },\n })\n }\n\n core.logger.info(`[OrbitRadiance] Installed with ${this.options.driver} driver`)\n }\n}\n\n// Module augmentation for GravitoVariables\ndeclare module '@gravito/core' {\n interface GravitoVariables {\n /** Broadcaster manager for real-time events */\n broadcast?: BroadcastManager\n }\n}\n"
12
5
  ],
13
- "mappings": "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",
14
- "debugId": "3151C12BCA217F2764756E2164756E21",
6
+ "mappings": "",
7
+ "debugId": "00053E5676168F4764756E2164756E21",
15
8
  "names": []
16
9
  }