@geekmidas/constructs 10.0.0-alpha.17 → 10.0.0-alpha.171

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 (485) hide show
  1. package/README.md +246 -158
  2. package/dist/Construct-127M7yrl.d.cts +231 -0
  3. package/dist/Construct-127M7yrl.d.cts.map +1 -0
  4. package/dist/Construct-BMk_CRSD.d.mts +231 -0
  5. package/dist/Construct-BMk_CRSD.d.mts.map +1 -0
  6. package/dist/{Construct-BeYVu_QF.mjs → Construct-CGuc_Ijk.mjs} +8 -9
  7. package/dist/Construct-CGuc_Ijk.mjs.map +1 -0
  8. package/dist/{Construct-DqdlARxq.cjs → Construct-DorKS0Ua.cjs} +8 -9
  9. package/dist/Construct-DorKS0Ua.cjs.map +1 -0
  10. package/dist/{Cron-l4Wlz6G9.d.mts → Cron-BcA8F0S-.d.cts} +16 -9
  11. package/dist/Cron-BcA8F0S-.d.cts.map +1 -0
  12. package/dist/{Cron-zsoSAwZo.d.cts → Cron-z2CiuQT_.d.mts} +15 -8
  13. package/dist/Cron-z2CiuQT_.d.mts.map +1 -0
  14. package/dist/{CronBuilder-D_0HNBTr.mjs → CronBuilder-BJ5LoadF.mjs} +28 -11
  15. package/dist/CronBuilder-BJ5LoadF.mjs.map +1 -0
  16. package/dist/CronBuilder-BZvo34X2.d.cts +47 -0
  17. package/dist/CronBuilder-BZvo34X2.d.cts.map +1 -0
  18. package/dist/{CronBuilder-BdnI6lxF.cjs → CronBuilder-B_NSP-Y5.cjs} +27 -10
  19. package/dist/CronBuilder-B_NSP-Y5.cjs.map +1 -0
  20. package/dist/CronBuilder-BbgKo8OI.d.mts +47 -0
  21. package/dist/CronBuilder-BbgKo8OI.d.mts.map +1 -0
  22. package/dist/Endpoint-52z1P0Ue.cjs +581 -0
  23. package/dist/Endpoint-52z1P0Ue.cjs.map +1 -0
  24. package/dist/{Endpoint-oS-Fe3d_.d.mts → Endpoint-CIDUreMW.d.mts} +104 -23
  25. package/dist/Endpoint-CIDUreMW.d.mts.map +1 -0
  26. package/dist/{Endpoint-DBflWAe4.d.cts → Endpoint-COisi9jw.d.cts} +101 -20
  27. package/dist/Endpoint-COisi9jw.d.cts.map +1 -0
  28. package/dist/Endpoint-sUOU7uLx.mjs +552 -0
  29. package/dist/Endpoint-sUOU7uLx.mjs.map +1 -0
  30. package/dist/{EndpointFactory-Bm3aKRdV.mjs → EndpointFactory-Bzi9Sl7r.mjs} +269 -53
  31. package/dist/EndpointFactory-Bzi9Sl7r.mjs.map +1 -0
  32. package/dist/{index-Cc4kKPag.d.mts → EndpointFactory-CIM80WIK.d.mts} +189 -106
  33. package/dist/EndpointFactory-CIM80WIK.d.mts.map +1 -0
  34. package/dist/{index-C1ZwNOOk.d.cts → EndpointFactory-CfBg6jJE.d.cts} +187 -104
  35. package/dist/EndpointFactory-CfBg6jJE.d.cts.map +1 -0
  36. package/dist/{EndpointFactory-CLvWuHyt.cjs → EndpointFactory-Cf_Cs1ym.cjs} +309 -51
  37. package/dist/EndpointFactory-Cf_Cs1ym.cjs.map +1 -0
  38. package/dist/Function-BIEsY0Hm.d.cts +76 -0
  39. package/dist/Function-BIEsY0Hm.d.cts.map +1 -0
  40. package/dist/Function-BKReud5p.d.mts +76 -0
  41. package/dist/Function-BKReud5p.d.mts.map +1 -0
  42. package/dist/{HonoEndpointAdaptor-92zavCsV.cjs → HonoEndpointAdaptor-BTbqfSaa.cjs} +115 -41
  43. package/dist/HonoEndpointAdaptor-BTbqfSaa.cjs.map +1 -0
  44. package/dist/{HonoEndpointAdaptor-yYaU7jVJ.mjs → HonoEndpointAdaptor-CBVey2cY.mjs} +112 -38
  45. package/dist/HonoEndpointAdaptor-CBVey2cY.mjs.map +1 -0
  46. package/dist/ObjectSubscriberBuilder-Ci_Cc-WZ.d.mts +129 -0
  47. package/dist/ObjectSubscriberBuilder-Ci_Cc-WZ.d.mts.map +1 -0
  48. package/dist/ObjectSubscriberBuilder-DWtLxfAJ.d.cts +129 -0
  49. package/dist/ObjectSubscriberBuilder-DWtLxfAJ.d.cts.map +1 -0
  50. package/dist/ProcessorBuilder-CdLwJK4k.d.mts +216 -0
  51. package/dist/ProcessorBuilder-CdLwJK4k.d.mts.map +1 -0
  52. package/dist/ProcessorBuilder-ClD7tmEe.d.cts +216 -0
  53. package/dist/ProcessorBuilder-ClD7tmEe.d.cts.map +1 -0
  54. package/dist/Queue-9Hh20ZCk.mjs +104 -0
  55. package/dist/Queue-9Hh20ZCk.mjs.map +1 -0
  56. package/dist/{Queue-D9X6OoON.d.mts → Queue-B8HGg439.d.mts} +42 -41
  57. package/dist/Queue-B8HGg439.d.mts.map +1 -0
  58. package/dist/{Queue-DYPB2KWL.d.cts → Queue-C4rijiM7.d.cts} +43 -42
  59. package/dist/Queue-C4rijiM7.d.cts.map +1 -0
  60. package/dist/Queue-W1wueijP.cjs +109 -0
  61. package/dist/Queue-W1wueijP.cjs.map +1 -0
  62. package/dist/QueueBuilder-BDcv9B71.cjs +135 -0
  63. package/dist/QueueBuilder-BDcv9B71.cjs.map +1 -0
  64. package/dist/QueueBuilder-CjULiiDN.d.mts +75 -0
  65. package/dist/QueueBuilder-CjULiiDN.d.mts.map +1 -0
  66. package/dist/QueueBuilder-CrZL8HHs.mjs +118 -0
  67. package/dist/QueueBuilder-CrZL8HHs.mjs.map +1 -0
  68. package/dist/QueueBuilder-Dacm9qAv.d.cts +75 -0
  69. package/dist/QueueBuilder-Dacm9qAv.d.cts.map +1 -0
  70. package/dist/Subscriber-5rCX1Nph.d.cts +83 -0
  71. package/dist/Subscriber-5rCX1Nph.d.cts.map +1 -0
  72. package/dist/Subscriber-CtQXhcL7.d.mts +83 -0
  73. package/dist/Subscriber-CtQXhcL7.d.mts.map +1 -0
  74. package/dist/SubscriberBuilder-CpFhShTJ.mjs +238 -0
  75. package/dist/SubscriberBuilder-CpFhShTJ.mjs.map +1 -0
  76. package/dist/SubscriberBuilder-DJEvNRdD.cjs +261 -0
  77. package/dist/SubscriberBuilder-DJEvNRdD.cjs.map +1 -0
  78. package/dist/Topic-BGoOeCT6.mjs +99 -0
  79. package/dist/Topic-BGoOeCT6.mjs.map +1 -0
  80. package/dist/Topic-DLCZBNwK.cjs +104 -0
  81. package/dist/Topic-DLCZBNwK.cjs.map +1 -0
  82. package/dist/adaptors/aws.cjs +147 -168
  83. package/dist/adaptors/aws.cjs.map +1 -1
  84. package/dist/adaptors/aws.d.cts +57 -48
  85. package/dist/adaptors/aws.d.cts.map +1 -1
  86. package/dist/adaptors/aws.d.mts +58 -49
  87. package/dist/adaptors/aws.d.mts.map +1 -1
  88. package/dist/adaptors/aws.mjs +142 -164
  89. package/dist/adaptors/aws.mjs.map +1 -1
  90. package/dist/adaptors/awsWebsocket.cjs +354 -0
  91. package/dist/adaptors/awsWebsocket.cjs.map +1 -0
  92. package/dist/adaptors/awsWebsocket.d.cts +156 -0
  93. package/dist/adaptors/awsWebsocket.d.cts.map +1 -0
  94. package/dist/adaptors/awsWebsocket.d.mts +156 -0
  95. package/dist/adaptors/awsWebsocket.d.mts.map +1 -0
  96. package/dist/adaptors/awsWebsocket.mjs +347 -0
  97. package/dist/adaptors/awsWebsocket.mjs.map +1 -0
  98. package/dist/adaptors/hono.cjs +1 -1
  99. package/dist/adaptors/hono.d.cts +8 -7
  100. package/dist/adaptors/hono.d.cts.map +1 -1
  101. package/dist/adaptors/hono.d.mts +10 -9
  102. package/dist/adaptors/hono.d.mts.map +1 -1
  103. package/dist/adaptors/hono.mjs +1 -1
  104. package/dist/adaptors/testing.cjs +1174 -41
  105. package/dist/adaptors/testing.cjs.map +1 -1
  106. package/dist/adaptors/testing.d.cts +517 -40
  107. package/dist/adaptors/testing.d.cts.map +1 -1
  108. package/dist/adaptors/testing.d.mts +517 -40
  109. package/dist/adaptors/testing.d.mts.map +1 -1
  110. package/dist/adaptors/testing.mjs +1140 -36
  111. package/dist/adaptors/testing.mjs.map +1 -1
  112. package/dist/auth-CutSfNlr.d.mts +274 -0
  113. package/dist/auth-CutSfNlr.d.mts.map +1 -0
  114. package/dist/auth-b9ADezz9.d.cts +274 -0
  115. package/dist/auth-b9ADezz9.d.cts.map +1 -0
  116. package/dist/auth.cjs +311 -26
  117. package/dist/auth.cjs.map +1 -1
  118. package/dist/auth.d.cts +2 -104
  119. package/dist/auth.d.mts +2 -104
  120. package/dist/auth.mjs +307 -28
  121. package/dist/auth.mjs.map +1 -1
  122. package/dist/cache-9wLNSy3O.d.cts +44 -0
  123. package/dist/cache-9wLNSy3O.d.cts.map +1 -0
  124. package/dist/cache-BFPs_CGs.d.mts +44 -0
  125. package/dist/cache-BFPs_CGs.d.mts.map +1 -0
  126. package/dist/cache.cjs +4 -20
  127. package/dist/cache.cjs.map +1 -1
  128. package/dist/cache.d.cts +2 -43
  129. package/dist/cache.d.mts +2 -43
  130. package/dist/cache.mjs +4 -20
  131. package/dist/cache.mjs.map +1 -1
  132. package/dist/cipher-C1lEFX63.mjs +225 -0
  133. package/dist/cipher-C1lEFX63.mjs.map +1 -0
  134. package/dist/cipher-CVxfwLjk.cjs +332 -0
  135. package/dist/cipher-CVxfwLjk.cjs.map +1 -0
  136. package/dist/cipher-DSDxPRIp.d.cts +106 -0
  137. package/dist/cipher-DSDxPRIp.d.cts.map +1 -0
  138. package/dist/cipher-DSDxPRIp.d.mts +106 -0
  139. package/dist/cipher-DSDxPRIp.d.mts.map +1 -0
  140. package/dist/{construct-interface-DPlxfpoS.d.mts → construct-interface-CVoejIpo.d.cts} +79 -8
  141. package/dist/construct-interface-CVoejIpo.d.cts.map +1 -0
  142. package/dist/{construct-interface-DgXTJcOD.d.cts → construct-interface-Nw5Dt9AC.d.mts} +79 -8
  143. package/dist/construct-interface-Nw5Dt9AC.d.mts.map +1 -0
  144. package/dist/construct-interface.cjs +62 -4
  145. package/dist/construct-interface.cjs.map +1 -1
  146. package/dist/construct-interface.d.cts +2 -2
  147. package/dist/construct-interface.d.mts +2 -2
  148. package/dist/construct-interface.mjs +59 -5
  149. package/dist/construct-interface.mjs.map +1 -1
  150. package/dist/credential-B80mOxwT.mjs +222 -0
  151. package/dist/credential-B80mOxwT.mjs.map +1 -0
  152. package/dist/credential-RlgbzZAc.cjs +257 -0
  153. package/dist/credential-RlgbzZAc.cjs.map +1 -0
  154. package/dist/credential.cjs +7 -129
  155. package/dist/credential.d.cts +2 -58
  156. package/dist/credential.d.mts +2 -58
  157. package/dist/credential.mjs +2 -128
  158. package/dist/crons/index.cjs +127 -1
  159. package/dist/crons/index.cjs.map +1 -1
  160. package/dist/crons/index.d.cts +43 -3
  161. package/dist/crons/index.d.cts.map +1 -1
  162. package/dist/crons/index.d.mts +43 -3
  163. package/dist/crons/index.d.mts.map +1 -1
  164. package/dist/crons/index.mjs +126 -2
  165. package/dist/crons/index.mjs.map +1 -1
  166. package/dist/database/kysely.cjs +3 -194
  167. package/dist/database/kysely.d.cts +2 -149
  168. package/dist/database/kysely.d.mts +2 -149
  169. package/dist/database/kysely.mjs +2 -192
  170. package/dist/email.cjs +24 -17
  171. package/dist/email.cjs.map +1 -1
  172. package/dist/email.d.cts +15 -5
  173. package/dist/email.d.cts.map +1 -1
  174. package/dist/email.d.mts +16 -6
  175. package/dist/email.d.mts.map +1 -1
  176. package/dist/email.mjs +23 -17
  177. package/dist/email.mjs.map +1 -1
  178. package/dist/encryption/kms.cjs +95 -0
  179. package/dist/encryption/kms.cjs.map +1 -0
  180. package/dist/encryption/kms.d.cts +7 -0
  181. package/dist/encryption/kms.d.cts.map +1 -0
  182. package/dist/encryption/kms.d.mts +7 -0
  183. package/dist/encryption/kms.d.mts.map +1 -0
  184. package/dist/encryption/kms.mjs +93 -0
  185. package/dist/encryption/kms.mjs.map +1 -0
  186. package/dist/encryption.cjs +116 -0
  187. package/dist/encryption.cjs.map +1 -0
  188. package/dist/encryption.d.cts +37 -0
  189. package/dist/encryption.d.cts.map +1 -0
  190. package/dist/encryption.d.mts +37 -0
  191. package/dist/encryption.d.mts.map +1 -0
  192. package/dist/encryption.mjs +101 -0
  193. package/dist/encryption.mjs.map +1 -0
  194. package/dist/endpoints/index.cjs +32 -10
  195. package/dist/endpoints/index.d.cts +106 -3
  196. package/dist/endpoints/index.d.cts.map +1 -0
  197. package/dist/endpoints/index.d.mts +106 -3
  198. package/dist/endpoints/index.d.mts.map +1 -0
  199. package/dist/endpoints/index.mjs +6 -4
  200. package/dist/expire-C586zznE.d.cts +38 -0
  201. package/dist/expire-C586zznE.d.cts.map +1 -0
  202. package/dist/expire-C586zznE.d.mts +38 -0
  203. package/dist/expire-C586zznE.d.mts.map +1 -0
  204. package/dist/external-api.cjs +106 -0
  205. package/dist/external-api.cjs.map +1 -0
  206. package/dist/external-api.d.cts +2 -0
  207. package/dist/external-api.d.mts +2 -0
  208. package/dist/external-api.mjs +103 -0
  209. package/dist/external-api.mjs.map +1 -0
  210. package/dist/fake-JI5uN1SF.d.cts +201 -0
  211. package/dist/fake-JI5uN1SF.d.cts.map +1 -0
  212. package/dist/fake-zpuXpBmY.d.mts +201 -0
  213. package/dist/fake-zpuXpBmY.d.mts.map +1 -0
  214. package/dist/file-server.cjs +170 -49
  215. package/dist/file-server.cjs.map +1 -1
  216. package/dist/file-server.d.cts +148 -16
  217. package/dist/file-server.d.cts.map +1 -1
  218. package/dist/file-server.d.mts +148 -16
  219. package/dist/file-server.d.mts.map +1 -1
  220. package/dist/file-server.mjs +168 -51
  221. package/dist/file-server.mjs.map +1 -1
  222. package/dist/functions/index.cjs +1 -1
  223. package/dist/functions/index.d.cts +2 -1
  224. package/dist/functions/index.d.mts +2 -1
  225. package/dist/functions/index.mjs +1 -1
  226. package/dist/{functions-C53GW2eQ.mjs → functions-BvIDQKAA.mjs} +117 -22
  227. package/dist/functions-BvIDQKAA.mjs.map +1 -0
  228. package/dist/{functions-B6qCvfmy.cjs → functions-DLF6-IK8.cjs} +122 -18
  229. package/dist/functions-DLF6-IK8.cjs.map +1 -0
  230. package/dist/inbox-CXLU7h_8.d.cts +195 -0
  231. package/dist/inbox-CXLU7h_8.d.cts.map +1 -0
  232. package/dist/inbox-DYFsLd9A.d.mts +195 -0
  233. package/dist/inbox-DYFsLd9A.d.mts.map +1 -0
  234. package/dist/inbox.cjs +291 -0
  235. package/dist/inbox.cjs.map +1 -0
  236. package/dist/inbox.d.cts +2 -0
  237. package/dist/inbox.d.mts +2 -0
  238. package/dist/inbox.mjs +283 -0
  239. package/dist/inbox.mjs.map +1 -0
  240. package/dist/index-BpE9_6l5.d.mts +115 -0
  241. package/dist/index-BpE9_6l5.d.mts.map +1 -0
  242. package/dist/{index-CeEtxDmK.d.cts → index-DdRjYhiJ.d.cts} +42 -2
  243. package/dist/{index-CeEtxDmK.d.cts.map → index-DdRjYhiJ.d.cts.map} +1 -1
  244. package/dist/{index-CeEtxDmK.d.mts → index-DdRjYhiJ.d.mts} +42 -2
  245. package/dist/{index-CeEtxDmK.d.mts.map → index-DdRjYhiJ.d.mts.map} +1 -1
  246. package/dist/index-zRChehJ9.d.cts +115 -0
  247. package/dist/index-zRChehJ9.d.cts.map +1 -0
  248. package/dist/index.cjs +4 -1
  249. package/dist/index.d.cts +26 -3
  250. package/dist/index.d.cts.map +1 -0
  251. package/dist/index.d.mts +26 -3
  252. package/dist/index.d.mts.map +1 -0
  253. package/dist/index.mjs +3 -2
  254. package/dist/kysely-5PAqFBzo.d.mts +216 -0
  255. package/dist/kysely-5PAqFBzo.d.mts.map +1 -0
  256. package/dist/kysely-Bc9xzaik.mjs +371 -0
  257. package/dist/kysely-Bc9xzaik.mjs.map +1 -0
  258. package/dist/kysely-D7f6J2lh.cjs +384 -0
  259. package/dist/kysely-D7f6J2lh.cjs.map +1 -0
  260. package/dist/kysely-lxNUBSTP.d.cts +216 -0
  261. package/dist/kysely-lxNUBSTP.d.cts.map +1 -0
  262. package/dist/{telemetry-DGcFlVpB.d.cts → lambdaTelemetry-8vnmVZQ5.d.cts} +2 -2
  263. package/dist/lambdaTelemetry-8vnmVZQ5.d.cts.map +1 -0
  264. package/dist/{telemetry-DGcFlVpB.d.mts → lambdaTelemetry-8vnmVZQ5.d.mts} +2 -2
  265. package/dist/lambdaTelemetry-8vnmVZQ5.d.mts.map +1 -0
  266. package/dist/mobile-app.cjs +79 -0
  267. package/dist/mobile-app.cjs.map +1 -0
  268. package/dist/mobile-app.d.cts +78 -0
  269. package/dist/mobile-app.d.cts.map +1 -0
  270. package/dist/mobile-app.d.mts +78 -0
  271. package/dist/mobile-app.d.mts.map +1 -0
  272. package/dist/mobile-app.mjs +78 -0
  273. package/dist/mobile-app.mjs.map +1 -0
  274. package/dist/object-storage.cjs +50 -7
  275. package/dist/object-storage.cjs.map +1 -1
  276. package/dist/object-storage.d.cts +37 -3
  277. package/dist/object-storage.d.cts.map +1 -1
  278. package/dist/object-storage.d.mts +37 -3
  279. package/dist/object-storage.d.mts.map +1 -1
  280. package/dist/object-storage.mjs +49 -9
  281. package/dist/object-storage.mjs.map +1 -1
  282. package/dist/optionalPeers-D7Wt6dnF.mjs +140 -0
  283. package/dist/optionalPeers-D7Wt6dnF.mjs.map +1 -0
  284. package/dist/optionalPeers-DuNQXXe1.cjs +223 -0
  285. package/dist/optionalPeers-DuNQXXe1.cjs.map +1 -0
  286. package/dist/origins-BjxYht13.cjs +96 -0
  287. package/dist/origins-BjxYht13.cjs.map +1 -0
  288. package/dist/origins-Boc9qbo-.mjs +73 -0
  289. package/dist/origins-Boc9qbo-.mjs.map +1 -0
  290. package/dist/pattern-C1CEcglD.mjs +241 -0
  291. package/dist/pattern-C1CEcglD.mjs.map +1 -0
  292. package/dist/pattern-QFaUIr77.cjs +288 -0
  293. package/dist/pattern-QFaUIr77.cjs.map +1 -0
  294. package/dist/privateAddress-Bg5fUsbp.mjs +21 -0
  295. package/dist/privateAddress-Bg5fUsbp.mjs.map +1 -0
  296. package/dist/privateAddress-CqGyuFHn.cjs +26 -0
  297. package/dist/privateAddress-CqGyuFHn.cjs.map +1 -0
  298. package/dist/processors/index.cjs +214 -0
  299. package/dist/processors/index.cjs.map +1 -0
  300. package/dist/processors/index.d.cts +78 -0
  301. package/dist/processors/index.d.cts.map +1 -0
  302. package/dist/processors/index.d.mts +78 -0
  303. package/dist/processors/index.d.mts.map +1 -0
  304. package/dist/processors/index.mjs +193 -0
  305. package/dist/processors/index.mjs.map +1 -0
  306. package/dist/queue/index.cjs +5 -192
  307. package/dist/queue/index.d.cts +3 -53
  308. package/dist/queue/index.d.mts +3 -53
  309. package/dist/queue/index.mjs +3 -190
  310. package/dist/random-password.cjs +86 -0
  311. package/dist/random-password.cjs.map +1 -0
  312. package/dist/random-password.d.cts +30 -0
  313. package/dist/random-password.d.cts.map +1 -0
  314. package/dist/random-password.d.mts +30 -0
  315. package/dist/random-password.d.mts.map +1 -0
  316. package/dist/random-password.mjs +84 -0
  317. package/dist/random-password.mjs.map +1 -0
  318. package/dist/readOnlyStorage-C7bCe-z5.cjs +101 -0
  319. package/dist/readOnlyStorage-C7bCe-z5.cjs.map +1 -0
  320. package/dist/readOnlyStorage-DMCeLuS2.mjs +78 -0
  321. package/dist/readOnlyStorage-DMCeLuS2.mjs.map +1 -0
  322. package/dist/readRequestBody-BmKnPl0a.mjs +293 -0
  323. package/dist/readRequestBody-BmKnPl0a.mjs.map +1 -0
  324. package/dist/{lazyAccessors-Dx9NLwJZ.cjs → readRequestBody-CN9GVdeE.cjs} +141 -47
  325. package/dist/readRequestBody-CN9GVdeE.cjs.map +1 -0
  326. package/dist/{processAudits-D_2W5x8k.cjs → requestLogger-CnoYd-Ah.cjs} +63 -3
  327. package/dist/requestLogger-CnoYd-Ah.cjs.map +1 -0
  328. package/dist/{processAudits-BpRlPQMW.mjs → requestLogger-D2JS7pPM.mjs} +51 -3
  329. package/dist/requestLogger-D2JS7pPM.mjs.map +1 -0
  330. package/dist/rest-api.cjs +100 -73
  331. package/dist/rest-api.cjs.map +1 -1
  332. package/dist/rest-api.d.cts +83 -59
  333. package/dist/rest-api.d.cts.map +1 -1
  334. package/dist/rest-api.d.mts +83 -59
  335. package/dist/rest-api.d.mts.map +1 -1
  336. package/dist/rest-api.mjs +97 -76
  337. package/dist/rest-api.mjs.map +1 -1
  338. package/dist/runSubscriber-HEqXkin1.mjs +117 -0
  339. package/dist/runSubscriber-HEqXkin1.mjs.map +1 -0
  340. package/dist/runSubscriber-sVJfLA0-.cjs +134 -0
  341. package/dist/runSubscriber-sVJfLA0-.cjs.map +1 -0
  342. package/dist/shutdown-BMJmAhSt.cjs +38 -0
  343. package/dist/shutdown-BMJmAhSt.cjs.map +1 -0
  344. package/dist/shutdown-C7xa8x9S.mjs +27 -0
  345. package/dist/shutdown-C7xa8x9S.mjs.map +1 -0
  346. package/dist/site.cjs +140 -10
  347. package/dist/site.cjs.map +1 -1
  348. package/dist/site.d.cts +156 -3
  349. package/dist/site.d.cts.map +1 -1
  350. package/dist/site.d.mts +156 -3
  351. package/dist/site.d.mts.map +1 -1
  352. package/dist/site.mjs +120 -13
  353. package/dist/site.mjs.map +1 -1
  354. package/dist/stages-DaTaoQei.d.cts +73 -0
  355. package/dist/stages-DaTaoQei.d.cts.map +1 -0
  356. package/dist/stages-DaTaoQei.d.mts +73 -0
  357. package/dist/stages-DaTaoQei.d.mts.map +1 -0
  358. package/dist/subscribers/index.cjs +134 -1
  359. package/dist/subscribers/index.cjs.map +1 -0
  360. package/dist/subscribers/index.d.cts +74 -3
  361. package/dist/subscribers/index.d.cts.map +1 -0
  362. package/dist/subscribers/index.d.mts +74 -3
  363. package/dist/subscribers/index.d.mts.map +1 -0
  364. package/dist/subscribers/index.mjs +132 -2
  365. package/dist/subscribers/index.mjs.map +1 -0
  366. package/dist/telemetry-BbLyS7ln.d.cts +57 -0
  367. package/dist/telemetry-BbLyS7ln.d.cts.map +1 -0
  368. package/dist/telemetry-DWX-qKUh.d.mts +57 -0
  369. package/dist/telemetry-DWX-qKUh.d.mts.map +1 -0
  370. package/dist/telemetry.cjs +64 -0
  371. package/dist/telemetry.cjs.map +1 -0
  372. package/dist/telemetry.d.cts +2 -0
  373. package/dist/telemetry.d.mts +2 -0
  374. package/dist/telemetry.mjs +63 -0
  375. package/dist/telemetry.mjs.map +1 -0
  376. package/dist/topic/index.cjs +2 -134
  377. package/dist/topic/index.d.cts +2 -3
  378. package/dist/topic/index.d.mts +2 -3
  379. package/dist/topic/index.mjs +2 -132
  380. package/dist/tracing-Bbj1uoFJ.mjs +127 -0
  381. package/dist/tracing-Bbj1uoFJ.mjs.map +1 -0
  382. package/dist/tracing-C0ooU0V2.cjs +150 -0
  383. package/dist/tracing-C0ooU0V2.cjs.map +1 -0
  384. package/dist/websocket-api-9ndLBolx.d.cts +1207 -0
  385. package/dist/websocket-api-9ndLBolx.d.cts.map +1 -0
  386. package/dist/websocket-api-BPPXF79i.d.mts +1207 -0
  387. package/dist/websocket-api-BPPXF79i.d.mts.map +1 -0
  388. package/dist/websocket-api-C6LGg9-D.mjs +1716 -0
  389. package/dist/websocket-api-C6LGg9-D.mjs.map +1 -0
  390. package/dist/websocket-api-CoKPJJRl.cjs +1895 -0
  391. package/dist/websocket-api-CoKPJJRl.cjs.map +1 -0
  392. package/dist/websocket-api.cjs +42 -0
  393. package/dist/websocket-api.d.cts +2 -0
  394. package/dist/websocket-api.d.mts +2 -0
  395. package/dist/websocket-api.mjs +3 -0
  396. package/dist/worker.cjs +174 -32
  397. package/dist/worker.cjs.map +1 -1
  398. package/dist/worker.d.cts +147 -47
  399. package/dist/worker.d.cts.map +1 -1
  400. package/dist/worker.d.mts +147 -47
  401. package/dist/worker.d.mts.map +1 -1
  402. package/dist/worker.mjs +175 -33
  403. package/dist/worker.mjs.map +1 -1
  404. package/package.json +180 -43
  405. package/dist/Construct-BeYVu_QF.mjs.map +0 -1
  406. package/dist/Construct-DfbwIntp.d.cts +0 -115
  407. package/dist/Construct-DfbwIntp.d.cts.map +0 -1
  408. package/dist/Construct-DqdlARxq.cjs.map +0 -1
  409. package/dist/Construct-l5aOn_jv.d.mts +0 -115
  410. package/dist/Construct-l5aOn_jv.d.mts.map +0 -1
  411. package/dist/Cron-l4Wlz6G9.d.mts.map +0 -1
  412. package/dist/Cron-zsoSAwZo.d.cts.map +0 -1
  413. package/dist/CronBuilder-BdnI6lxF.cjs.map +0 -1
  414. package/dist/CronBuilder-CyT71Nzg.d.cts +0 -41
  415. package/dist/CronBuilder-CyT71Nzg.d.cts.map +0 -1
  416. package/dist/CronBuilder-D_0HNBTr.mjs.map +0 -1
  417. package/dist/CronBuilder-UoNgFe8S.d.mts +0 -41
  418. package/dist/CronBuilder-UoNgFe8S.d.mts.map +0 -1
  419. package/dist/Endpoint-BpZHtJ2W.cjs +0 -1689
  420. package/dist/Endpoint-BpZHtJ2W.cjs.map +0 -1
  421. package/dist/Endpoint-DBflWAe4.d.cts.map +0 -1
  422. package/dist/Endpoint-ONsly_dq.mjs +0 -1671
  423. package/dist/Endpoint-ONsly_dq.mjs.map +0 -1
  424. package/dist/Endpoint-oS-Fe3d_.d.mts.map +0 -1
  425. package/dist/EndpointFactory-Bm3aKRdV.mjs.map +0 -1
  426. package/dist/EndpointFactory-CLvWuHyt.cjs.map +0 -1
  427. package/dist/HonoEndpointAdaptor-92zavCsV.cjs.map +0 -1
  428. package/dist/HonoEndpointAdaptor-yYaU7jVJ.mjs.map +0 -1
  429. package/dist/Queue-D9X6OoON.d.mts.map +0 -1
  430. package/dist/Queue-DYPB2KWL.d.cts.map +0 -1
  431. package/dist/Subscriber-C4heaAyO.d.mts +0 -51
  432. package/dist/Subscriber-C4heaAyO.d.mts.map +0 -1
  433. package/dist/Subscriber-CotDUELC.d.cts +0 -51
  434. package/dist/Subscriber-CotDUELC.d.cts.map +0 -1
  435. package/dist/SubscriberBuilder-BEv0eoHy.d.cts +0 -59
  436. package/dist/SubscriberBuilder-BEv0eoHy.d.cts.map +0 -1
  437. package/dist/SubscriberBuilder-C0ZEtGDI.cjs +0 -125
  438. package/dist/SubscriberBuilder-C0ZEtGDI.cjs.map +0 -1
  439. package/dist/SubscriberBuilder-h7B_cHMr.mjs +0 -114
  440. package/dist/SubscriberBuilder-h7B_cHMr.mjs.map +0 -1
  441. package/dist/SubscriberBuilder-tyH5yTk5.d.mts +0 -59
  442. package/dist/SubscriberBuilder-tyH5yTk5.d.mts.map +0 -1
  443. package/dist/Topic-DEVGo0Dm.d.cts +0 -89
  444. package/dist/Topic-DEVGo0Dm.d.cts.map +0 -1
  445. package/dist/Topic-zk_6Gthr.d.mts +0 -89
  446. package/dist/Topic-zk_6Gthr.d.mts.map +0 -1
  447. package/dist/auth.d.cts.map +0 -1
  448. package/dist/auth.d.mts.map +0 -1
  449. package/dist/cache.d.cts.map +0 -1
  450. package/dist/cache.d.mts.map +0 -1
  451. package/dist/construct-interface-DPlxfpoS.d.mts.map +0 -1
  452. package/dist/construct-interface-DgXTJcOD.d.cts.map +0 -1
  453. package/dist/credential.cjs.map +0 -1
  454. package/dist/credential.d.cts.map +0 -1
  455. package/dist/credential.d.mts.map +0 -1
  456. package/dist/credential.mjs.map +0 -1
  457. package/dist/database/kysely.cjs.map +0 -1
  458. package/dist/database/kysely.d.cts.map +0 -1
  459. package/dist/database/kysely.d.mts.map +0 -1
  460. package/dist/database/kysely.mjs.map +0 -1
  461. package/dist/functions-B6qCvfmy.cjs.map +0 -1
  462. package/dist/functions-C53GW2eQ.mjs.map +0 -1
  463. package/dist/index-B2urf3YI.d.cts +0 -26
  464. package/dist/index-B2urf3YI.d.cts.map +0 -1
  465. package/dist/index-C1ZwNOOk.d.cts.map +0 -1
  466. package/dist/index-Cc4kKPag.d.mts.map +0 -1
  467. package/dist/index-DMCDvnsM.d.mts +0 -26
  468. package/dist/index-DMCDvnsM.d.mts.map +0 -1
  469. package/dist/index-D_frT6MP.d.cts +0 -165
  470. package/dist/index-D_frT6MP.d.cts.map +0 -1
  471. package/dist/index-DcyIYbDS.d.mts +0 -165
  472. package/dist/index-DcyIYbDS.d.mts.map +0 -1
  473. package/dist/lazyAccessors-BHtcqgz2.mjs +0 -211
  474. package/dist/lazyAccessors-BHtcqgz2.mjs.map +0 -1
  475. package/dist/lazyAccessors-Dx9NLwJZ.cjs.map +0 -1
  476. package/dist/processAudits-BpRlPQMW.mjs.map +0 -1
  477. package/dist/processAudits-D_2W5x8k.cjs.map +0 -1
  478. package/dist/queue/index.cjs.map +0 -1
  479. package/dist/queue/index.d.cts.map +0 -1
  480. package/dist/queue/index.d.mts.map +0 -1
  481. package/dist/queue/index.mjs.map +0 -1
  482. package/dist/telemetry-DGcFlVpB.d.cts.map +0 -1
  483. package/dist/telemetry-DGcFlVpB.d.mts.map +0 -1
  484. package/dist/topic/index.cjs.map +0 -1
  485. package/dist/topic/index.mjs.map +0 -1
@@ -0,0 +1,1207 @@
1
+ import { n as StandardSchemaV1 } from "./index-DdRjYhiJ.mjs";
2
+ import { i as Declarable, r as Consumable, t as Authenticator, u as ServicesOf } from "./construct-interface-Nw5Dt9AC.mjs";
3
+ import { n as Telemetry } from "./telemetry-DWX-qKUh.mjs";
4
+ import { ConstructName, Declaration, InvalidHostLabel } from "@geekmidas/manifest";
5
+ import { Service, ServiceRecord, ServiceRegisterOptions } from "@geekmidas/services";
6
+ import { EnvironmentParser } from "@geekmidas/envkit";
7
+ import { Hono } from "hono";
8
+ import { Logger } from "@geekmidas/logger";
9
+ import { InferStandardSchema } from "@geekmidas/schema";
10
+ import { IncomingMessage, Server } from "node:http";
11
+ import { Duplex } from "node:stream";
12
+ //#region src/websocket/publisher.d.ts
13
+ /**
14
+ * Where a publisher's frames go once they are encoded — the one thing a
15
+ * runtime supplies to send to its sockets.
16
+ *
17
+ * On Node it is a `TransportSink`: each id's process, over Redis or memory.
18
+ * On API Gateway it would be the management API's `postToConnection`; under
19
+ * test, a recording. A payload is the frame already serialised, once, however
20
+ * many ids it goes to. An id that is gone is dropped, not an error.
21
+ */
22
+ interface WebSocketSink {
23
+ send(ids: readonly string[], payload: string): Promise<void>;
24
+ /** Every open connection but `except`. */
25
+ broadcast(payload: string, except?: readonly string[]): Promise<void>;
26
+ close(ids: readonly string[], code: number, reason: string): Promise<void>;
27
+ }
28
+ /**
29
+ * What a surface sends its sockets, by action — `WebSocketApiConfig.messages`.
30
+ */
31
+ type WebSocketMessages = Record<string, StandardSchemaV1>;
32
+ /** A surface that declares no messages: any action, any data. */
33
+ type NoMessages = Record<never, never>;
34
+ /** The actions a publisher sends: the declared ones, or any. */
35
+ type MessageAction<TMessages extends WebSocketMessages> = [keyof TMessages] extends [never] ? string : keyof TMessages & string;
36
+ /** What `action`'s data is, as its schema takes it. */
37
+ type MessageData<TMessages extends WebSocketMessages, TAction extends string> = TAction extends keyof TMessages ? StandardSchemaV1.InferInput<TMessages[TAction]> : unknown;
38
+ /** A message sent on an action the surface does not declare. */
39
+ declare class UnknownWebSocketMessage extends Error {
40
+ readonly surface: string;
41
+ readonly action: string;
42
+ readonly declared: readonly string[];
43
+ constructor(surface: string, action: string, declared: readonly string[]);
44
+ }
45
+ /** A message whose data its action's schema refused. */
46
+ declare class InvalidWebSocketMessage extends Error {
47
+ readonly surface: string;
48
+ readonly action: string;
49
+ readonly issues: readonly StandardSchemaV1.Issue[];
50
+ constructor(surface: string, action: string, issues: readonly StandardSchemaV1.Issue[]);
51
+ }
52
+ /**
53
+ * How anything reaches a socket — `services.realtime` in an endpoint, and
54
+ * `sockets` in a route of the surface itself.
55
+ *
56
+ * A message is `{ action, data }`, the shape a client's frames arrive in —
57
+ * or, where the surface names a `frame.discriminator`, flat: `{ [key]: action,
58
+ * ...data }`.
59
+ * Where the surface declares its messages, `action` is one of them and
60
+ * `data` is typed and checked by its schema before anything is sent; where it
61
+ * declares none, any action and any JSON value go. A message is serialised
62
+ * once, whatever the number of sockets it goes to. An id whose process has
63
+ * gone is dropped silently, as API Gateway's `postToConnection` to a closed
64
+ * connection is a no-op the sender rarely wants to handle.
65
+ */
66
+ declare class WebSocketPublisher<TMessages extends WebSocketMessages = NoMessages> {
67
+ /** Where an encoded frame goes. */
68
+ private readonly sink;
69
+ /** The surface's declared messages, which every send is checked by. */
70
+ private readonly declared?;
71
+ /** How the surface writes a frame. Absent, `{ action, data }`. */
72
+ private readonly frame;
73
+ constructor(
74
+ /** Where an encoded frame goes. */
75
+ sink: WebSocketSink,
76
+ /** The surface's declared messages, which every send is checked by. */
77
+ declared?: {
78
+ surface: string;
79
+ messages: TMessages;
80
+ } | undefined,
81
+ /** How the surface writes a frame. Absent, `{ action, data }`. */
82
+ frame?: FrameShape);
83
+ /** Send `action`'s message to each connection. */
84
+ send<TAction extends MessageAction<TMessages>>(ids: string | readonly string[], action: TAction, data: MessageData<TMessages, TAction>): Promise<void>;
85
+ /** Send `action`'s message to every open connection, on every process. */
86
+ broadcast<TAction extends MessageAction<TMessages>>(action: TAction, data: MessageData<TMessages, TAction>, options?: {
87
+ except?: readonly string[];
88
+ }): Promise<void>;
89
+ /** Close each connection, with a close code and reason its client sees. */
90
+ close(ids: string | readonly string[], code?: number, reason?: string): Promise<void>;
91
+ /**
92
+ * The frame, checked by the action's schema where the surface declares
93
+ * its messages.
94
+ *
95
+ * @throws {UnknownWebSocketMessage}, {InvalidWebSocketMessage}, and for a
96
+ * flat frame {WebSocketDataNotAnObject}, {WebSocketDataHasDiscriminator}
97
+ */
98
+ private payload;
99
+ }
100
+ //#endregion
101
+ //#region src/websocket/frame.d.ts
102
+ /** `WebSocketApiConfig.frame`: where a flat frame keeps its action. */
103
+ interface WebSocketFrame {
104
+ /** The key a frame's action lives in — `type` for `{ "type": … }`. */
105
+ discriminator: string;
106
+ }
107
+ /** A frame as the server reads it, whatever shape it arrived in. */
108
+ interface DecodedFrame {
109
+ action: string;
110
+ /** Echoed on the reply. Only an `{ action, data }` frame carries one. */
111
+ id?: string | number;
112
+ data?: unknown;
113
+ }
114
+ /** A declared message whose schema does not describe an object. */
115
+ declare class WebSocketMessageNotAnObject extends Error {
116
+ readonly surface: string;
117
+ readonly action: string;
118
+ readonly discriminator: string;
119
+ constructor(surface: string, action: string, discriminator: string);
120
+ }
121
+ /** A declared message whose schema has a field named the discriminator. */
122
+ declare class WebSocketMessageDeclaresDiscriminator extends Error {
123
+ readonly surface: string;
124
+ readonly action: string;
125
+ readonly discriminator: string;
126
+ constructor(surface: string, action: string, discriminator: string);
127
+ }
128
+ /** Data sent in a flat frame that is not an object. */
129
+ declare class WebSocketDataNotAnObject extends Error {
130
+ readonly surface: string;
131
+ readonly action: string;
132
+ readonly discriminator: string;
133
+ constructor(surface: string, action: string, discriminator: string);
134
+ }
135
+ /** Data sent in a flat frame that carries the discriminator itself. */
136
+ declare class WebSocketDataHasDiscriminator extends Error {
137
+ readonly surface: string;
138
+ readonly action: string;
139
+ readonly discriminator: string;
140
+ constructor(surface: string, action: string, discriminator: string);
141
+ }
142
+ /** How one surface writes and reads its frames. */
143
+ declare class FrameShape {
144
+ readonly surface: string;
145
+ /** The flat frame's key; absent, frames are `{ action, data }`. */
146
+ readonly discriminator?: string | undefined;
147
+ constructor(surface: string,
148
+ /** The flat frame's key; absent, frames are `{ action, data }`. */
149
+ discriminator?: string | undefined);
150
+ /** The key an inbound frame names its action under. */
151
+ get key(): string;
152
+ /**
153
+ * The frame for `action`'s `data`, serialised.
154
+ *
155
+ * @throws {WebSocketDataNotAnObject}, {WebSocketDataHasDiscriminator} for
156
+ * a flat frame whose data cannot sit beside the discriminator.
157
+ */
158
+ encode(action: string, data: unknown, id?: string | number): string;
159
+ /** A parsed frame's action, id and data — `undefined` when it names none. */
160
+ decode(frame: unknown): DecodedFrame | undefined;
161
+ /** The id a frame that names no action carried, to echo on its error. */
162
+ idOf(frame: unknown): string | number | undefined;
163
+ /**
164
+ * Refuse a declared message a flat frame cannot carry: one that is not an
165
+ * object, or that has a field named the discriminator.
166
+ *
167
+ * @throws {WebSocketMessageNotAnObject}, {WebSocketMessageDeclaresDiscriminator}
168
+ */
169
+ check(messages: WebSocketMessages): void;
170
+ }
171
+ //#endregion
172
+ //#region src/websocket/testing.d.ts
173
+ /** One recorded message: its action and data, and the frame on the wire. */
174
+ type RecordedMessage<TMessages extends WebSocketMessages = NoMessages> = [keyof TMessages] extends [never] ? {
175
+ action: string;
176
+ data: unknown;
177
+ frame: Record<string, unknown>;
178
+ } : { [A in keyof TMessages & string]: {
179
+ action: A;
180
+ /** As its schema returned it — what the client receives. */
181
+ data: StandardSchemaV1.InferOutput<TMessages[A]>;
182
+ /** The frame as the client parses it — the wire shape. */
183
+ frame: Record<string, unknown>;
184
+ }; }[keyof TMessages & string];
185
+ /** A `send(ids, …)`, as it was recorded. */
186
+ type RecordedSend<TMessages extends WebSocketMessages = NoMessages> = RecordedMessage<TMessages> & {
187
+ ids: string[];
188
+ };
189
+ /** A `broadcast(…)`, as it was recorded. */
190
+ type RecordedBroadcast<TMessages extends WebSocketMessages = NoMessages> = RecordedMessage<TMessages> & {
191
+ except: string[];
192
+ };
193
+ /** A `close(ids, code, reason)`, as it was recorded. */
194
+ interface RecordedClose {
195
+ ids: string[];
196
+ code: number;
197
+ reason: string;
198
+ }
199
+ /**
200
+ * A sink that keeps what it is handed, decoded by the surface's frame shape,
201
+ * and sends it nowhere.
202
+ */
203
+ declare class RecordingSink implements WebSocketSink {
204
+ private readonly frame;
205
+ readonly sent: RecordedSend<any>[];
206
+ readonly broadcasts: RecordedBroadcast<any>[];
207
+ readonly closed: RecordedClose[];
208
+ constructor(frame: FrameShape);
209
+ send(ids: readonly string[], payload: string): Promise<void>;
210
+ broadcast(payload: string, except?: readonly string[]): Promise<void>;
211
+ close(ids: readonly string[], code: number, reason: string): Promise<void>;
212
+ clear(): void;
213
+ private decode;
214
+ }
215
+ /**
216
+ * A surface's publisher that records rather than sends — what
217
+ * `surface.testPublisher()` returns, of the type `services.<surface>` is.
218
+ *
219
+ * Every send is still checked by the declared `messages` and encoded by the
220
+ * surface's `frame`, so an invalid push fails the spec as it would fail
221
+ * deployed, and `frame` on each record is what the client would parse.
222
+ */
223
+ declare class TestWebSocketPublisher<TMessages extends WebSocketMessages = NoMessages> extends WebSocketPublisher<TMessages> {
224
+ /** Where the records are kept — what `route.request()` builds its core on. */
225
+ readonly recording: RecordingSink;
226
+ constructor(frame: FrameShape, declared?: {
227
+ surface: string;
228
+ messages: TMessages;
229
+ });
230
+ /** Each `send(ids, action, data)`, in order. */
231
+ get sent(): readonly RecordedSend<TMessages>[];
232
+ /** Each `broadcast(action, data, { except })`, in order. */
233
+ get broadcasts(): readonly RecordedBroadcast<TMessages>[];
234
+ /** Each `close(ids, code, reason)`, in order. */
235
+ get closed(): readonly RecordedClose[];
236
+ /** Forget everything recorded so far. */
237
+ clear(): void;
238
+ }
239
+ /** A frame `route.request()` sent was refused before its handler ran. */
240
+ declare class InvalidWebSocketRequest extends Error {
241
+ readonly surface: string;
242
+ readonly action: string;
243
+ /** What the `$error` frame said. */
244
+ readonly reason: string;
245
+ readonly issues?: readonly StandardSchemaV1.Issue[] | undefined;
246
+ constructor(surface: string, action: string,
247
+ /** What the `$error` frame said. */
248
+ reason: string, issues?: readonly StandardSchemaV1.Issue[] | undefined);
249
+ }
250
+ /** What a surface hands its routes' `request()`. */
251
+ interface WebSocketTestSurface {
252
+ readonly id: string;
253
+ core(options: {
254
+ envParser: EnvironmentParser<{}>;
255
+ sink: WebSocketSink;
256
+ modules?: readonly object[];
257
+ }): WebSocketCore<any>;
258
+ readonly envParser: EnvironmentParser<{}>;
259
+ testPublisher(): TestWebSocketPublisher<any>;
260
+ }
261
+ /** Overrides every `request()` takes. */
262
+ interface WebSocketTestCallOptions {
263
+ /**
264
+ * Instances for the route's dependencies, by service name — a test's
265
+ * transaction for `database`. Any it depends on and is not handed here is
266
+ * registered, as deployed.
267
+ */
268
+ services?: Record<string, unknown>;
269
+ /**
270
+ * The handler's `sockets`. Pass `surface.testPublisher()` to assert what
271
+ * it sent; absent, a fresh one that nobody reads.
272
+ */
273
+ sockets?: TestWebSocketPublisher<any>;
274
+ }
275
+ interface TestConnectRequest extends WebSocketTestCallOptions {
276
+ /** The id the connection is given. Absent, `test.<n>`. */
277
+ connectionId?: string;
278
+ /** The handshake's headers — what `.auth()` verifies without a `session`. */
279
+ headers?: ConstructorParameters<typeof Headers>[0];
280
+ /** The upgrade URL's query. */
281
+ query?: string | Record<string, string> | URLSearchParams;
282
+ /**
283
+ * What the surface's `.auth()` would have resolved — `null` for no
284
+ * session. Absent, `.auth()` verifies `headers`, as on a real upgrade.
285
+ */
286
+ session?: unknown;
287
+ }
288
+ interface TestMessageRequest<TBody = unknown> extends WebSocketTestCallOptions {
289
+ /** The connection the frame arrives on. Absent, `test.<n>` with no data. */
290
+ connection?: TestConnection;
291
+ /** The frame's data — checked by the route's `body`, as a frame's is. */
292
+ body: TBody;
293
+ /** The frame's `id`, echoed on its reply. Only `{ action, data }` frames. */
294
+ id?: string | number;
295
+ }
296
+ interface TestDisconnectRequest extends WebSocketTestCallOptions {
297
+ /** The connection that closed. Absent, `test.<n>` with no data. */
298
+ connection?: TestConnection;
299
+ /** Default 1000. */
300
+ code?: number;
301
+ /** Default ''. */
302
+ reason?: string;
303
+ }
304
+ /** A connection a test names: either part may be left to its default. */
305
+ interface TestConnection {
306
+ id?: string;
307
+ data?: Record<string, unknown>;
308
+ }
309
+ /** What a message route's `fullRequest()` resolves with. */
310
+ interface TestMessageResponse<TReturned = unknown> {
311
+ /** The handler's return — the reply, before it was encoded. */
312
+ returned: TReturned;
313
+ /**
314
+ * Every frame written back to the connection, parsed, in order: each
315
+ * `reply()` and the reply to the frame itself.
316
+ */
317
+ frames: unknown[];
318
+ }
319
+ //#endregion
320
+ //#region src/websocket/route.d.ts
321
+ /** One open connection, as a handler sees it. */
322
+ interface Connection {
323
+ readonly id: string;
324
+ /**
325
+ * What the connect handler returned — who the connection is for, the room
326
+ * it joined. `{}` when it returned nothing.
327
+ */
328
+ readonly data: Record<string, unknown>;
329
+ }
330
+ interface BaseContext<TServices extends Service[], TMessages extends WebSocketMessages> {
331
+ services: ServiceRecord<TServices>;
332
+ logger: Logger;
333
+ /** Every socket this surface holds, on whichever process holds it. */
334
+ sockets: WebSocketPublisher<TMessages>;
335
+ }
336
+ interface ConnectContext<TServices extends Service[], TMessages extends WebSocketMessages = NoMessages> extends BaseContext<TServices, TMessages> {
337
+ connectionId: string;
338
+ headers: Headers;
339
+ query: URLSearchParams;
340
+ /**
341
+ * Whose connection it is, from the surface's `.auth()` — `null` when the
342
+ * upgrade carried no session, and when the surface names no authenticator.
343
+ * Throw an `UnauthorizedError` to refuse it.
344
+ */
345
+ session: unknown;
346
+ }
347
+ interface MessageContext<TBody, TServices extends Service[], TMessages extends WebSocketMessages = NoMessages> extends BaseContext<TServices, TMessages> {
348
+ connection: Connection;
349
+ body: TBody;
350
+ /** Send to this connection alone. */
351
+ reply(message: unknown): void;
352
+ }
353
+ interface DisconnectContext<TServices extends Service[], TMessages extends WebSocketMessages = NoMessages> extends BaseContext<TServices, TMessages> {
354
+ connection: Connection;
355
+ code: number;
356
+ reason: string;
357
+ }
358
+ /** What a frame is dispatched on: an action, or the connection's lifecycle. */
359
+ type RouteKind = 'connect' | 'disconnect' | 'message';
360
+ /**
361
+ * A handler bound to a WebSocket surface — what `realtime.route('chat.send')
362
+ * …handle()` returns, and what a file exports.
363
+ *
364
+ * Carries `surface` and `constructs` the way an endpoint does, so discovery
365
+ * records what its process reaches without knowing what a route is.
366
+ */
367
+ declare class WebSocketRoute<TKind extends RouteKind = RouteKind, TSchema extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined, TServices extends Service[] = Service[],
368
+ /** What the handler returns. */
369
+ TReturn = unknown, TMessages extends WebSocketMessages = WebSocketMessages> {
370
+ readonly kind: TKind;
371
+ /** The `action` it answers; `$connect` and `$disconnect` for the lifecycle. */
372
+ readonly action: string;
373
+ /** The surface it was built from — what `request()` builds a core on. */
374
+ readonly surface: WebSocketTestSurface;
375
+ readonly services: readonly Service[];
376
+ /** Construct ids it depends on — its edges in the manifest. */
377
+ readonly constructs: readonly string[];
378
+ readonly handler: (context: never) => unknown;
379
+ readonly schema?: TSchema | undefined;
380
+ readonly __IS_WEBSOCKET_ROUTE__ = true;
381
+ static isRoute(value: unknown): value is WebSocketRoute;
382
+ constructor(kind: TKind,
383
+ /** The `action` it answers; `$connect` and `$disconnect` for the lifecycle. */
384
+ action: string,
385
+ /** The surface it was built from — what `request()` builds a core on. */
386
+ surface: WebSocketTestSurface, services: readonly Service[],
387
+ /** Construct ids it depends on — its edges in the manifest. */
388
+ constructs: readonly string[], handler: (context: never) => unknown, schema?: TSchema | undefined);
389
+ /**
390
+ * Run the handler as its surface would, with no server and no socket —
391
+ * as `endpoint.request()` runs an endpoint.
392
+ *
393
+ * - `connect`: resolves with the connection's `data`, or rejects with what
394
+ * refused it (an `UnauthorizedError` stays a 401).
395
+ * - a message route: `body` is encoded as a frame and checked by the
396
+ * route's schema; resolves with the handler's return, or rejects with
397
+ * what it threw or an `InvalidWebSocketRequest`.
398
+ * - `disconnect`: resolves once the handler has run, or rejects with what
399
+ * it threw.
400
+ */
401
+ request(...[request]: RequestArgs<TKind, TSchema, TServices, TMessages>): Promise<WebSocketRouteResult<TKind, TReturn>>;
402
+ /**
403
+ * A message route's `request()`, with every frame it wrote back to the
404
+ * connection — each `reply()` and the reply itself — beside its return.
405
+ */
406
+ fullRequest(this: WebSocketRoute<'message', TSchema, TServices, TReturn, TMessages>, request: WebSocketRouteRequest<'message', TSchema, TServices, TMessages>): Promise<TestMessageResponse<Awaited<TReturn>>>;
407
+ }
408
+ /** A message route needs a body; the lifecycle's request may be left out. */
409
+ type RequestArgs<TKind extends RouteKind, TSchema extends StandardSchemaV1 | undefined, TServices extends Service[], TMessages extends WebSocketMessages> = TKind extends 'message' ? [request: WebSocketRouteRequest<TKind, TSchema, TServices, TMessages>] : [request?: WebSocketRouteRequest<TKind, TSchema, TServices, TMessages>];
410
+ /** What `request()` takes for each kind of route. */
411
+ type WebSocketRouteRequest<TKind extends RouteKind, TSchema extends StandardSchemaV1 | undefined, TServices extends Service[], TMessages extends WebSocketMessages> = TestCallOverrides<TServices, TMessages> & (TKind extends 'connect' ? Omit<TestConnectRequest, 'services' | 'sockets'> : TKind extends 'disconnect' ? Omit<TestDisconnectRequest, 'services' | 'sockets'> : Omit<TestMessageRequest<TSchema extends StandardSchemaV1 ? StandardSchemaV1.InferInput<TSchema> : unknown>, 'services' | 'sockets'>);
412
+ /** `services` typed by what the route depends on; `sockets` by the surface. */
413
+ interface TestCallOverrides<TServices extends Service[], TMessages extends WebSocketMessages> {
414
+ /**
415
+ * Instances for the route's dependencies — a test's transaction for
416
+ * `database`. Any it depends on and is not handed here is registered.
417
+ */
418
+ services?: Partial<ServiceRecord<TServices>>;
419
+ /** The handler's `sockets` — `surface.testPublisher()` to assert on. */
420
+ sockets?: TestWebSocketPublisher<TMessages>;
421
+ }
422
+ /** What `request()` resolves with for each kind of route. */
423
+ type WebSocketRouteResult<TKind extends RouteKind, TReturn> = TKind extends 'connect' ? ConnectData<Awaited<TReturn>> : TKind extends 'disconnect' ? undefined : Awaited<TReturn>;
424
+ /** A connect handler's return as the connection keeps it: `{}` for nothing. */
425
+ type ConnectData<T> = T extends undefined ? {} : T;
426
+ /** What a handler may return, by kind: connect's becomes `data`. */
427
+ type HandlerReturn<TKind extends RouteKind> = TKind extends 'connect' ? Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined> : unknown;
428
+ /** The builder `connect()`, `disconnect()` and `route()` start. */
429
+ declare class WebSocketRouteBuilder<TKind extends RouteKind, TSchema extends StandardSchemaV1 | undefined = undefined, TServices extends Service[] = [],
430
+ /** The surface's declared messages, which `sockets` sends. */
431
+ TMessages extends WebSocketMessages = NoMessages> {
432
+ private readonly kind;
433
+ private readonly action;
434
+ private readonly surface;
435
+ private readonly _services;
436
+ private readonly _constructs;
437
+ private readonly schema?;
438
+ constructor(kind: TKind, action: string, surface: WebSocketTestSurface, _services?: readonly Service[], _constructs?: readonly string[], schema?: TSchema | undefined);
439
+ /** The schema a frame's `data` must satisfy before the handler runs. */
440
+ body<S extends StandardSchemaV1>(schema: S): WebSocketRouteBuilder<TKind, S, TServices, TMessages>;
441
+ /** What the handler reaches, as `services.<id>` — per route, as an endpoint's. */
442
+ dependsOn<const T extends readonly Consumable[]>(constructs: T): WebSocketRouteBuilder<TKind, TSchema, [...TServices, ...ServicesOf<T>], TMessages>;
443
+ /**
444
+ * The handler. A message handler's return value, when there is one, is
445
+ * sent back to the connection as the reply to that frame; a connect
446
+ * handler's is kept as the connection's `data`.
447
+ */
448
+ handle<TReturn extends HandlerReturn<TKind>>(handler: TKind extends 'connect' ? (context: ConnectContext<TServices, TMessages>) => TReturn : TKind extends 'disconnect' ? (context: DisconnectContext<TServices, TMessages>) => TReturn : (context: MessageContext<TSchema extends StandardSchemaV1 ? InferStandardSchema<TSchema> : unknown, TServices, TMessages>) => TReturn): WebSocketRoute<TKind, TSchema, TServices, TReturn, TMessages>;
449
+ }
450
+ //#endregion
451
+ //#region src/websocket/core.d.ts
452
+ /** Two routes answer one action. */
453
+ declare class DuplicateWebSocketRoute extends Error {
454
+ readonly surface: string;
455
+ readonly action: string;
456
+ constructor(surface: string, action: string);
457
+ }
458
+ interface WebSocketCoreOptions<TMessages extends WebSocketMessages = NoMessages> {
459
+ surface: string;
460
+ /** Every route handed in; those built from another surface are skipped. */
461
+ routes: readonly WebSocketRoute[];
462
+ /** What the surface sends its sockets — see `WebSocketApiConfig.messages`. */
463
+ messages?: TMessages;
464
+ /** The shape its frames take — see `WebSocketApiConfig.frame`. */
465
+ frame?: WebSocketFrame;
466
+ /** Where `sockets` sends, in every handler: the adaptor's own. */
467
+ sink: WebSocketSink;
468
+ envParser: EnvironmentParser<{}>;
469
+ logger: Logger;
470
+ /** What turns a handshake's headers into the `session` connect sees. */
471
+ authenticator?: Authenticator;
472
+ }
473
+ /** A handshake, as the adaptor that received it saw it. */
474
+ interface ConnectRequest {
475
+ /** The id the adaptor gives the connection — sends address it by this. */
476
+ connectionId: string;
477
+ headers: Headers;
478
+ query: URLSearchParams;
479
+ /**
480
+ * Whose connection it is, when the adaptor already knows (a test).
481
+ * Absent, the surface's authenticator verifies `headers`; `null` is no
482
+ * session.
483
+ */
484
+ session?: unknown;
485
+ }
486
+ /**
487
+ * For one call: services to use in place of registering them — a test's
488
+ * transaction for `database`. Only those the route depends on are handed in.
489
+ */
490
+ interface WebSocketCallOptions {
491
+ services?: Record<string, unknown>;
492
+ }
493
+ /** Whether a handshake may become a connection. */
494
+ type ConnectOutcome = {
495
+ accepted: true;
496
+ connection: Connection;
497
+ } | {
498
+ accepted: false;
499
+ /** The status a refused upgrade answers with: the `HttpError`'s, or 500. */
500
+ status: number;
501
+ statusText: string;
502
+ /** What the connect handler, or the authenticator, threw. */
503
+ error: unknown;
504
+ };
505
+ /** Writes one serialised frame to the connection a message arrived on. */
506
+ type WriteFrame = (payload: string) => void;
507
+ /** What became of one inbound frame. Whatever it wrote went through `write`. */
508
+ type MessageOutcome = {
509
+ ok: true;
510
+ action: string;
511
+ id?: string | number;
512
+ /** The handler's return — sent back as the reply when defined. */
513
+ returned: unknown;
514
+ } | {
515
+ ok: false;
516
+ /** Absent when the frame named no action. */
517
+ action?: string;
518
+ id?: string | number;
519
+ /** What the `$error` frame said. */
520
+ message: string;
521
+ issues?: readonly StandardSchemaV1.Issue[];
522
+ /** What the handler threw, when it got that far. */
523
+ error?: unknown;
524
+ };
525
+ type DisconnectOutcome = {
526
+ ok: true;
527
+ } | {
528
+ ok: false;
529
+ error: unknown;
530
+ };
531
+ declare class WebSocketCore<TMessages extends WebSocketMessages = NoMessages> {
532
+ private readonly options;
533
+ readonly surface: string;
534
+ /** How frames are read and written — what an adaptor decodes replies by. */
535
+ readonly frame: FrameShape;
536
+ /** `sockets` in every handler. */
537
+ readonly sockets: WebSocketPublisher<TMessages>;
538
+ private readonly routes;
539
+ private readonly lifecycle;
540
+ /**
541
+ * @throws {DuplicateWebSocketRoute} when two routes answer one action, and
542
+ * the frame checks of `FrameShape.check` for declared messages.
543
+ */
544
+ constructor(options: WebSocketCoreOptions<TMessages>);
545
+ /**
546
+ * Run the connect handler for a handshake: accepted with the connection's
547
+ * `data` (what the handler returned, `{}` for nothing), or refused with
548
+ * the status of the `HttpError` it threw — 500 for anything else. A surface
549
+ * with no connect handler accepts every handshake, and verifies no session.
550
+ */
551
+ connect(request: ConnectRequest, options?: WebSocketCallOptions): Promise<ConnectOutcome>;
552
+ /**
553
+ * Parse, validate and run one inbound frame. The reply — the handler's
554
+ * return, encoded — and every `$error` are written with `write`; an error
555
+ * is a frame, never a close. A binary frame is refused: frames are text.
556
+ */
557
+ message(connection: Connection, raw: string | Uint8Array, write: WriteFrame, options?: WebSocketCallOptions): Promise<MessageOutcome>;
558
+ /**
559
+ * Run the disconnect handler for a connection that has closed. What it
560
+ * throws is logged and returned, never thrown: the socket is gone either
561
+ * way.
562
+ */
563
+ disconnect(connection: Connection, close: {
564
+ code: number;
565
+ reason: string;
566
+ }, options?: WebSocketCallOptions): Promise<DisconnectOutcome>;
567
+ /** Run a handler with its services, inside a request context of its own. */
568
+ private run;
569
+ /** The route's services: the overrides it names, the rest registered. */
570
+ private services;
571
+ private error;
572
+ }
573
+ //#endregion
574
+ //#region src/websocket/limits.d.ts
575
+ /** Close codes the limits close a socket with. */
576
+ declare const LIMIT_CLOSE: {
577
+ /** Policy violation: it kept sending past its rate, or its identity has too many sockets. */
578
+ readonly policy: 1008;
579
+ };
580
+ /**
581
+ * What one client may ask of the surface. Every limit is on by default; set
582
+ * one to `false` to lift it.
583
+ */
584
+ interface WebSocketLimits<TData = Record<string, unknown>> {
585
+ /**
586
+ * Handshakes one client address may start in a minute, across every
587
+ * replica. Past it, an upgrade is answered 429 with `Retry-After` before
588
+ * the connect handler — and the session lookup it makes — runs.
589
+ * Default 120.
590
+ */
591
+ handshakesPerMinute?: number | false;
592
+ /**
593
+ * Handshakes one client address may have in flight at once — waiting on
594
+ * the connect handler. Past it, 429. Default 16.
595
+ */
596
+ inFlightHandshakes?: number | false;
597
+ /**
598
+ * Open sockets one client address may hold, across every replica. Past
599
+ * it, a new upgrade is answered 429. Default 256: many people share an
600
+ * address behind a NAT.
601
+ */
602
+ connectionsPerIp?: number | false;
603
+ /**
604
+ * Frames one socket may send a second, refilled continuously. Past it, a
605
+ * frame is dropped and the socket is sent one `$error`; if it keeps
606
+ * sending before its budget refills, it is closed with 1008. Default 50.
607
+ */
608
+ messagesPerSecond?: number | false;
609
+ /** Frames a socket may send at once before the rate applies. Default 100. */
610
+ burst?: number;
611
+ /**
612
+ * Who a connection is, for {@link maxConnections}: a key read from what
613
+ * the connect handler returned — `(data) => data.userId`. Absent, or
614
+ * `undefined` for a connection, its sockets are not counted per identity.
615
+ */
616
+ maxConnectionsPer?: (data: TData) => string | undefined;
617
+ /**
618
+ * Sockets one identity may hold, across every replica. Default 16, and
619
+ * only with {@link maxConnectionsPer}.
620
+ */
621
+ maxConnections?: number;
622
+ /**
623
+ * What a socket over {@link maxConnections} does: `'refuse'` answers the
624
+ * new upgrade 429; `'closeOldest'` lets it in and closes that identity's
625
+ * oldest sockets with 1008 — a user who opened a new tab keeps it.
626
+ * Default `'refuse'`.
627
+ */
628
+ overflow?: 'refuse' | 'closeOldest';
629
+ }
630
+ /** The limits with every default filled in; `undefined` is off. */
631
+ interface ResolvedWebSocketLimits {
632
+ handshakesPerMinute?: number;
633
+ inFlightHandshakes?: number;
634
+ connectionsPerIp?: number;
635
+ messagesPerSecond?: number;
636
+ burst: number;
637
+ maxConnectionsPer?: (data: Record<string, unknown>) => string | undefined;
638
+ maxConnections: number;
639
+ overflow: 'refuse' | 'closeOldest';
640
+ }
641
+ declare const DEFAULT_WEBSOCKET_LIMITS: {
642
+ readonly handshakesPerMinute: 120;
643
+ readonly inFlightHandshakes: 16;
644
+ readonly connectionsPerIp: 256;
645
+ readonly messagesPerSecond: 50;
646
+ readonly burst: 100;
647
+ readonly maxConnections: 16;
648
+ };
649
+ /** A limit that is not a whole number of at least one. */
650
+ declare class InvalidWebSocketLimit extends Error {
651
+ readonly surface: string;
652
+ readonly limit: string;
653
+ readonly value: unknown;
654
+ constructor(surface: string, limit: string, value: unknown);
655
+ }
656
+ /**
657
+ * Fill in the defaults.
658
+ *
659
+ * @throws {InvalidWebSocketLimit} for a limit that is not a positive integer.
660
+ */
661
+ declare function resolveLimits(surface: string, limits?: WebSocketLimits<any>): ResolvedWebSocketLimits;
662
+ /**
663
+ * Where a surface's limits are counted. Every replica of a surface must see
664
+ * the same store for a limit to hold across them: the Redis transport's own
665
+ * Redis, or — in one process — memory.
666
+ */
667
+ interface WebSocketLimitStore {
668
+ /**
669
+ * Count one more hit in the window `key` names, opening a window of
670
+ * `windowMs` on the first. Atomic: concurrent handshakes are each counted.
671
+ */
672
+ hit(key: string, windowMs: number): Promise<{
673
+ count: number;
674
+ resetMs: number;
675
+ }>;
676
+ /**
677
+ * Hold `member` in the set `key` until `ttlMs` from now — or until
678
+ * {@link release}d — and return every member still held, oldest first.
679
+ * A member a dead process never released lapses when its time is up.
680
+ */
681
+ hold(key: string, member: string, ttlMs: number): Promise<string[]>;
682
+ /** Let `member` go. */
683
+ release(key: string, member: string): Promise<void>;
684
+ /** Hold each of `held` for another `ttlMs`. */
685
+ renew(held: readonly {
686
+ key: string;
687
+ member: string;
688
+ }[], ttlMs: number): Promise<void>;
689
+ }
690
+ /**
691
+ * In one process. Two servers on one `memory://` channel — replicas in a
692
+ * test — share it, as they share the channel.
693
+ */
694
+ declare class MemoryLimitStore implements WebSocketLimitStore {
695
+ private readonly windows;
696
+ /** key → member → [opened, expires] */
697
+ private readonly sets;
698
+ hit(key: string, windowMs: number): Promise<{
699
+ count: number;
700
+ resetMs: number;
701
+ }>;
702
+ hold(key: string, member: string, ttlMs: number): Promise<string[]>;
703
+ release(key: string, member: string): Promise<void>;
704
+ renew(held: readonly {
705
+ key: string;
706
+ member: string;
707
+ }[], ttlMs: number): Promise<void>;
708
+ }
709
+ /** The subset of an ioredis client the Redis store uses. */
710
+ interface RedisEvalClient {
711
+ eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
712
+ }
713
+ /**
714
+ * Over Redis — the transport's own — so every replica counts in one place.
715
+ * Each operation is one script, so concurrent handshakes on any replica are
716
+ * each counted.
717
+ */
718
+ declare class RedisLimitStore implements WebSocketLimitStore {
719
+ private readonly client;
720
+ private readonly prefix;
721
+ /** member as handed in → member as stored, with its opening time. */
722
+ private readonly stored;
723
+ constructor(client: RedisEvalClient, prefix: string);
724
+ private key;
725
+ private storedAs;
726
+ hit(key: string, windowMs: number): Promise<{
727
+ count: number;
728
+ resetMs: number;
729
+ }>;
730
+ hold(key: string, member: string, ttlMs: number): Promise<string[]>;
731
+ release(key: string, member: string): Promise<void>;
732
+ renew(held: readonly {
733
+ key: string;
734
+ member: string;
735
+ }[], ttlMs: number): Promise<void>;
736
+ }
737
+ /**
738
+ * A socket's inbound budget: `burst` frames at once, refilled at `rate` a
739
+ * second.
740
+ */
741
+ declare class TokenBucket {
742
+ private readonly rate;
743
+ private readonly burst;
744
+ private tokens;
745
+ private at;
746
+ constructor(rate: number, burst: number);
747
+ /** Spend one token, if there is one. */
748
+ take(now?: number): boolean;
749
+ /** Whether it has refilled completely since it last ran dry. */
750
+ get full(): boolean;
751
+ }
752
+ //#endregion
753
+ //#region src/websocket/transport.d.ts
754
+ /** What one process is asked to do with the sockets it holds. */
755
+ type Delivery = {
756
+ kind: 'send';
757
+ ids: readonly string[];
758
+ payload: string;
759
+ } | {
760
+ kind: 'broadcast';
761
+ payload: string;
762
+ except?: readonly string[];
763
+ } | {
764
+ kind: 'close';
765
+ ids: readonly string[];
766
+ code: number;
767
+ reason: string;
768
+ };
769
+ interface WebSocketTransport {
770
+ /** Deliver to one instance, or to every instance when it is `'*'`. */
771
+ publish(instance: string, delivery: Delivery): Promise<void>;
772
+ /** Receive what is published to `instance`, and every broadcast. */
773
+ subscribe(instance: string, receive: (delivery: Delivery) => void): Promise<void>;
774
+ close(): Promise<void>;
775
+ /**
776
+ * Where the surface's limits are counted — somewhere every process on
777
+ * this transport sees, so a limit holds across them. Absent, each
778
+ * process counts its own.
779
+ */
780
+ limits?(): WebSocketLimitStore;
781
+ }
782
+ /**
783
+ * A publisher's sink over a transport: a send goes to the instance each
784
+ * connection id names, a broadcast to every instance. What `services.<id>`
785
+ * sends through, and what the Node adaptor's own `sockets` do.
786
+ */
787
+ declare class TransportSink implements WebSocketSink {
788
+ private readonly transport;
789
+ /**
790
+ * Delivers to this process's own sockets without a round trip through
791
+ * the transport — set by the process that holds them.
792
+ */
793
+ private readonly local?;
794
+ constructor(transport: WebSocketTransport,
795
+ /**
796
+ * Delivers to this process's own sockets without a round trip through
797
+ * the transport — set by the process that holds them.
798
+ */
799
+ local?: {
800
+ instance: string;
801
+ deliver(delivery: Delivery): void;
802
+ } | undefined);
803
+ send(ids: readonly string[], payload: string): Promise<void>;
804
+ broadcast(payload: string, except?: readonly string[]): Promise<void>;
805
+ close(ids: readonly string[], code: number, reason: string): Promise<void>;
806
+ /** One delivery per process that holds any of `ids`. */
807
+ private each;
808
+ }
809
+ /** A connection string names no transport this package knows. */
810
+ declare class UnsupportedWebSocketTransport extends Error {
811
+ readonly connectionString: string;
812
+ constructor(connectionString: string);
813
+ }
814
+ /**
815
+ * In one process: the server and whoever sends meet in a map, keyed by the
816
+ * channel the connection string names.
817
+ */
818
+ declare class MemoryTransport implements WebSocketTransport {
819
+ private readonly channel;
820
+ private readonly subscribed;
821
+ constructor(channel: string);
822
+ publish(instance: string, delivery: Delivery): Promise<void>;
823
+ subscribe(instance: string, receive: (delivery: Delivery) => void): Promise<void>;
824
+ close(): Promise<void>;
825
+ limits(): WebSocketLimitStore;
826
+ }
827
+ /** The subset of an ioredis client the transport uses. */
828
+ interface RedisClient {
829
+ publish(channel: string, message: string): Promise<number>;
830
+ subscribe(...channels: string[]): Promise<unknown>;
831
+ on(event: 'message', listener: (channel: string, message: string) => void): unknown;
832
+ duplicate(): RedisClient;
833
+ quit(): Promise<unknown>;
834
+ eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
835
+ }
836
+ /**
837
+ * Over Redis pub/sub: one channel per instance and one for broadcasts, under
838
+ * a prefix that keeps two surfaces — or two projects on one Redis — apart.
839
+ * Channels are not scoped by database index, so the prefix is what does it.
840
+ *
841
+ * Publishing and subscribing take separate connections, because a connection
842
+ * that has subscribed can do nothing else.
843
+ */
844
+ declare class RedisTransport implements WebSocketTransport {
845
+ private readonly client;
846
+ private readonly prefix;
847
+ private subscriber?;
848
+ private closed?;
849
+ constructor(client: RedisClient, prefix: string);
850
+ private channel;
851
+ publish(instance: string, delivery: Delivery): Promise<void>;
852
+ subscribe(instance: string, receive: (delivery: Delivery) => void): Promise<void>;
853
+ /** Counted in this Redis, under the transport's prefix. */
854
+ limits(): WebSocketLimitStore;
855
+ /** Idempotent: the server and a shutdown hook may both close it. */
856
+ close(): Promise<void>;
857
+ }
858
+ /**
859
+ * The transport a connection string names.
860
+ *
861
+ * `redis://` and `rediss://` take an optional `channel` query parameter, the
862
+ * prefix every channel is named under; `memory://<channel>` is in-process.
863
+ * Absent, the channel is `fallback` — the surface's own.
864
+ */
865
+ declare function transportFromConnectionString(connectionString: string, fallback: string): Promise<WebSocketTransport>;
866
+ //#endregion
867
+ //#region src/websocket/server.d.ts
868
+ /** Close codes a client sees. */
869
+ declare const CLOSE: {
870
+ readonly normal: 1000;
871
+ /**
872
+ * It kept sending past its message rate, or its identity opened more
873
+ * sockets than `limits.maxConnections` and this was the oldest.
874
+ */
875
+ readonly policy: 1008;
876
+ /** The process is stopping; reconnect and land on another. */
877
+ readonly serviceRestart: 1012;
878
+ /** It stopped reading, and what was queued for it passed the limit. */
879
+ readonly tooSlow: 1013;
880
+ };
881
+ interface WebSocketServerOptions<TMessages extends WebSocketMessages = NoMessages> {
882
+ /**
883
+ * The surface's core, over the sink this process sends through — its own
884
+ * sockets directly, every other process's over `transport`.
885
+ */
886
+ core(sink: WebSocketSink): WebSocketCore<TMessages>;
887
+ transport: WebSocketTransport;
888
+ /**
889
+ * Origins a browser may open a socket from. A request with an `Origin`
890
+ * not in the list is refused with 403; one with none — a server, a load
891
+ * generator — is not a browser, and is let through unless
892
+ * `requireOrigin` is set.
893
+ */
894
+ trustedOrigins: readonly string[];
895
+ /**
896
+ * Refuse, with 403, an upgrade that sends no `Origin`. Every browser
897
+ * sends one and a native client sends the socket's own; a server or a
898
+ * script sends none. Off by default: the limits hold either way.
899
+ */
900
+ requireOrigin?: boolean;
901
+ /**
902
+ * The surface's own public address, `<ID>_URL`. Its origin is always
903
+ * trusted: a native client (React Native's `WebSocket`) sends the socket's
904
+ * own origin as its `Origin`.
905
+ */
906
+ url?: string;
907
+ /** How often each socket is pinged; one that missed the last is dropped. */
908
+ heartbeatMs?: number;
909
+ /** The largest frame accepted, in bytes. */
910
+ maxPayload?: number;
911
+ /** Queued bytes a socket may hold before it is closed as too slow. */
912
+ maxBufferedBytes?: number;
913
+ /**
914
+ * What one client may ask of it — `resolveLimits(id, config.limits)`.
915
+ * Absent, the defaults.
916
+ */
917
+ limits?: ResolvedWebSocketLimits;
918
+ /** Where a limit store that cannot be reached is reported. */
919
+ logger?: Logger;
920
+ }
921
+ declare class WebSocketSurfaceServer<TMessages extends WebSocketMessages = NoMessages> {
922
+ private readonly wss;
923
+ private readonly options;
924
+ /** This process, as connection ids name it. */
925
+ readonly instance: string;
926
+ /** Where each handshake, frame and close is handed. */
927
+ readonly core: WebSocketCore<TMessages>;
928
+ private readonly held;
929
+ private readonly heartbeat;
930
+ private readonly heartbeatMs;
931
+ private readonly trusted;
932
+ private readonly sink;
933
+ private readonly limits;
934
+ private readonly store;
935
+ private next;
936
+ private closing;
937
+ private constructor();
938
+ static start<TMessages extends WebSocketMessages = NoMessages>(options: WebSocketServerOptions<TMessages>): Promise<WebSocketSurfaceServer<TMessages>>;
939
+ /** `sockets` in a route: local sends skip the transport. */
940
+ get publisher(): WebSocketPublisher<TMessages>;
941
+ /** How many sockets this process holds. */
942
+ get size(): number;
943
+ /** Take over `server`'s upgrades. */
944
+ attach(server: Server): void;
945
+ /**
946
+ * Upgrade one request, or refuse it with a status line. The cheap checks
947
+ * come first — the Origin, the client's handshake rate, its handshakes in
948
+ * flight and its open sockets — so a flood is refused before the connect
949
+ * handler, and the session lookup it makes, runs.
950
+ */
951
+ upgrade(request: IncomingMessage, socket: Duplex, head: Buffer): Promise<void>;
952
+ private open;
953
+ /**
954
+ * Whether a frame is within its socket's budget. The first past it is
955
+ * answered with one `$error`; another before the budget has refilled
956
+ * closes the socket with 1008.
957
+ */
958
+ private admit;
959
+ /**
960
+ * Take a place in `lease`'s count — or none, when that would put it past
961
+ * `max`. A store that cannot be reached lets the handshake through.
962
+ */
963
+ private claim;
964
+ private release;
965
+ /**
966
+ * How long a socket's place in a count outlives its process, should it
967
+ * die without giving it back: three heartbeats, each of which renews it.
968
+ */
969
+ private get connectionTtl();
970
+ /** The store's answer — or nothing, logged, when it fails. */
971
+ private guard;
972
+ /** Write, unless the socket has stopped reading and its queue is full. */
973
+ private write;
974
+ /** What the transport, or a local publisher, asked of this process. */
975
+ private deliver;
976
+ /**
977
+ * Drop every socket that missed the last ping, and ping the rest — whose
978
+ * places in the limits' counts are renewed.
979
+ */
980
+ private beat;
981
+ /**
982
+ * Stop: refuse new upgrades, close every socket with `code` — 1012 tells
983
+ * a client to reconnect, and it lands on a process that is still up — and
984
+ * leave the transport.
985
+ */
986
+ close(code?: number, reason?: string): Promise<void>;
987
+ }
988
+ //#endregion
989
+ //#region src/websocket/drivers.d.ts
990
+ /** What reaches a surface's sockets for one publisher-string scheme. */
991
+ interface WebSocketSinkDriver {
992
+ /** The scheme it handles, with its colon: `'apigateway:'`. */
993
+ readonly scheme: string;
994
+ /** The sink for a publisher string of that scheme. */
995
+ sink(connectionString: string): WebSocketSink;
996
+ }
997
+ /** Make a sink available for its scheme. Idempotent. */
998
+ declare function registerWebSocketSinkDriver(driver: WebSocketSinkDriver): void;
999
+ /**
1000
+ * A surface's publisher string names a scheme this process registered no
1001
+ * sink for — `apigateway:` in an entry not built for AWS.
1002
+ */
1003
+ declare class UnregisteredWebSocketScheme extends Error {
1004
+ readonly surface: string;
1005
+ readonly scheme: string;
1006
+ constructor(surface: string, scheme: string);
1007
+ }
1008
+ //#endregion
1009
+ //#region src/websocket-api.d.ts
1010
+ interface WebSocketApiConfig<TMessages extends WebSocketMessages = NoMessages> {
1011
+ /** The app that serves it, relative to the workspace root. */
1012
+ path: string;
1013
+ /**
1014
+ * What it sends its sockets, by action — each with the schema its `data`
1015
+ * is checked by before it is sent.
1016
+ *
1017
+ * ```ts
1018
+ * messages: {
1019
+ * announcement: z.object({ text: z.string() }),
1020
+ * 'chat.said': z.object({ from: z.string(), text: z.string() }),
1021
+ * }
1022
+ * ```
1023
+ *
1024
+ * The publisher is typed by it — `services.realtime.broadcast(
1025
+ * 'announcement', { text })` — in an endpoint and in a route's `sockets`
1026
+ * alike. Absent, any action and any data go, unchecked.
1027
+ */
1028
+ messages?: TMessages;
1029
+ /**
1030
+ * The shape its frames take. Absent, `{ "action": …, "id"?: …, "data": … }`.
1031
+ *
1032
+ * With a `discriminator`, frames are flat — the action under that key and
1033
+ * the data's fields beside it, both ways, `$error` replies included:
1034
+ *
1035
+ * ```ts
1036
+ * frame: { discriminator: 'type' },
1037
+ * // realtime.send(ids, 'chat.message.created', { chatId, message })
1038
+ * // wire: {"type":"chat.message.created","chatId":"…","message":{…}}
1039
+ * ```
1040
+ *
1041
+ * Every message must then be an object schema that has no field of that
1042
+ * name; one that is not is refused when the surface is built. A flat frame
1043
+ * carries no `id`: every other field is the data.
1044
+ */
1045
+ frame?: WebSocketFrame;
1046
+ /** The label it answers on. Absent, its id kebab-cased. */
1047
+ subdomain?: string;
1048
+ /**
1049
+ * More labels it answers on under the stage's domain, exactly as on its
1050
+ * own — `['rest']` serves `rest.myapp.com` beside `api.myapp.com`. Its own
1051
+ * label stays canonical: `<ID>_URL`, clients and OpenAPI are built on it.
1052
+ */
1053
+ aliases?: readonly string[];
1054
+ /** How many processes serve it on one machine. Default 1. */
1055
+ replicas?: number;
1056
+ logger?: Logger;
1057
+ envParser?: EnvironmentParser<{}>;
1058
+ telemetry?: Telemetry;
1059
+ /** Seconds between pings; a socket that misses one is dropped. Default 30. */
1060
+ heartbeat?: number;
1061
+ /**
1062
+ * The largest frame accepted, in bytes. Default 1 MiB. A surface that
1063
+ * only pushes — its clients write over HTTP — declares no routes and
1064
+ * sets this small.
1065
+ */
1066
+ maxPayload?: number;
1067
+ /**
1068
+ * What one client may ask of it: handshakes a minute, handshakes in
1069
+ * flight and open sockets per client address, frames a second per
1070
+ * socket, and — with `maxConnectionsPer` — sockets per identity. All but
1071
+ * the last are on by default; on the Redis transport they hold across
1072
+ * every replica. See `WebSocketLimits`.
1073
+ *
1074
+ * ```ts
1075
+ * limits: {
1076
+ * messagesPerSecond: 20,
1077
+ * maxConnectionsPer: (data) => data.userId as string,
1078
+ * maxConnections: 5,
1079
+ * overflow: 'closeOldest',
1080
+ * }
1081
+ * ```
1082
+ */
1083
+ limits?: WebSocketLimits;
1084
+ /**
1085
+ * Refuse, with 403, an upgrade that sends no `Origin` — which no browser
1086
+ * and no native client omits, but a script does. Default false: a server
1087
+ * may hold a socket too, and the limits apply to it either way.
1088
+ */
1089
+ requireOrigin?: boolean;
1090
+ }
1091
+ /** A replica count that is not a whole number of at least one. */
1092
+ declare class InvalidReplicaCount extends Error {
1093
+ readonly id: string;
1094
+ readonly replicas: number;
1095
+ constructor(id: string, replicas: number);
1096
+ }
1097
+ declare class WebSocketApi<TName extends string = string, TMessages extends WebSocketMessages = NoMessages> implements Declarable<TName> {
1098
+ private readonly config;
1099
+ /** Internal: how `.auth()` carries the authenticator into its copy. */
1100
+ readonly authenticator?: Authenticator | undefined;
1101
+ readonly id: TName;
1102
+ readonly keys: {
1103
+ url: string;
1104
+ trustedOrigins: string;
1105
+ publisherConnectionString: string;
1106
+ };
1107
+ readonly logger: Logger;
1108
+ readonly envParser: EnvironmentParser<{}>;
1109
+ readonly telemetry?: Telemetry;
1110
+ /**
1111
+ * The shape its frames take — `{ action, data }`, or flat under
1112
+ * `discriminator`. What a client of the surface decodes by.
1113
+ */
1114
+ readonly frame: {
1115
+ readonly discriminator?: string;
1116
+ };
1117
+ /** What one client may ask of it, defaults filled in. */
1118
+ readonly limits: ResolvedWebSocketLimits;
1119
+ /**
1120
+ * The surface as a dependency: `services.<id>` is its publisher, so an
1121
+ * endpoint sends to a socket the way a route beside it does.
1122
+ */
1123
+ readonly service: Service<Uncapitalize<TName>, WebSocketPublisher<TMessages>>;
1124
+ constructor(id: ConstructName<TName>, config: WebSocketApiConfig<TMessages>,
1125
+ /** Internal: how `.auth()` carries the authenticator into its copy. */
1126
+ authenticator?: Authenticator | undefined);
1127
+ /** The handler a connection's upgrade runs: refuse it, or say who it is. */
1128
+ connect(): WebSocketRouteBuilder<'connect', undefined, [], TMessages>;
1129
+ /** The handler a closed connection runs. */
1130
+ disconnect(): WebSocketRouteBuilder<'disconnect', undefined, [], TMessages>;
1131
+ /**
1132
+ * The handler for frames whose `action` — or, for flat frames, whose
1133
+ * discriminator — is `action`. `$default` answers
1134
+ * any action nothing else does.
1135
+ */
1136
+ route(action: string): WebSocketRouteBuilder<'message', undefined, [], TMessages>;
1137
+ /** What authenticates a connection — its session reaches `connect()`. */
1138
+ auth(construct: Authenticator): WebSocketApi<TName, TMessages>;
1139
+ /**
1140
+ * Serve it: the routes exported by `modules` that were built from this
1141
+ * surface, on whatever HTTP server `attach` is handed.
1142
+ *
1143
+ * `app` answers plain HTTP — the generated entry puts `/health` in front
1144
+ * of it — and `attach` takes over the server's upgrades. The sockets are
1145
+ * closed with 1012 when the server shuts down.
1146
+ */
1147
+ server(options: ServiceRegisterOptions & {
1148
+ modules?: readonly object[];
1149
+ }): Promise<{
1150
+ app: Hono;
1151
+ attach(server: Server): void;
1152
+ /** Close every socket with 1012, so the HTTP server can close. */
1153
+ release(): Promise<void>;
1154
+ server: WebSocketSurfaceServer<TMessages>;
1155
+ }>;
1156
+ /**
1157
+ * The surface with no socket in it — what every runtime serves. The
1158
+ * routes exported by `modules` that were built from this surface answer
1159
+ * its frames; `sink` is where its handlers' `sockets` send.
1160
+ *
1161
+ * `server()` is the Node adaptor over it. Another runtime (a Lambda
1162
+ * behind API Gateway, a test) builds one with a sink of its own and
1163
+ * calls `connect()`, `message()` and `disconnect()` per connection id.
1164
+ *
1165
+ * @throws {DuplicateWebSocketRoute} when two routes answer one action.
1166
+ */
1167
+ core(options: {
1168
+ envParser: EnvironmentParser<{}>;
1169
+ sink: WebSocketSink;
1170
+ modules?: readonly object[];
1171
+ }): WebSocketCore<TMessages>;
1172
+ /**
1173
+ * The surface's publisher over `sink` — typed, checked and encoded as
1174
+ * `services.<id>` is. What an adaptor with a sink of its own (MSW, a
1175
+ * Lambda) hands the code that sends to its connections.
1176
+ */
1177
+ publisher(sink: WebSocketSink): WebSocketPublisher<TMessages>;
1178
+ /**
1179
+ * A publisher of the type `services.<id>` is, that records rather than
1180
+ * sends — hand it to an endpoint's spec, or to a route's `request()` as
1181
+ * `sockets`, and assert on `sent`, `broadcasts` and `closed`.
1182
+ *
1183
+ * Every send is checked by the declared `messages` and encoded by `frame`,
1184
+ * as deployed: an invalid push rejects, and each record carries the
1185
+ * frame a client would parse.
1186
+ *
1187
+ * ```ts
1188
+ * const realtime = surface.testPublisher();
1189
+ * await sendMessage.request({ services: { realtime }, … });
1190
+ * expect(realtime.sent).toEqual([
1191
+ * { ids: ['a.1'], action: 'chat.sent', data: { text: 'hi' }, frame: … },
1192
+ * ]);
1193
+ * ```
1194
+ */
1195
+ testPublisher(): TestWebSocketPublisher<TMessages>;
1196
+ /**
1197
+ * The per-address limits the edge in front of it enforces too, so a
1198
+ * flood is refused before it reaches a replica.
1199
+ */
1200
+ private get edgeLimits();
1201
+ /** The declared messages, with the surface they are checked for. */
1202
+ private get declared();
1203
+ declare(): Declaration[];
1204
+ }
1205
+ //#endregion
1206
+ export { TestConnectRequest as $, DisconnectOutcome as A, MessageContext as B, ResolvedWebSocketLimits as C, resolveLimits as D, WebSocketLimits as E, WebSocketCoreOptions as F, WebSocketRouteRequest as G, TestCallOverrides as H, WriteFrame as I, RecordedBroadcast as J, WebSocketRouteResult as K, ConnectContext as L, MessageOutcome as M, WebSocketCallOptions as N, ConnectOutcome as O, WebSocketCore as P, RecordingSink as Q, Connection as R, RedisLimitStore as S, WebSocketLimitStore as T, WebSocketRoute as U, RouteKind as V, WebSocketRouteBuilder as W, RecordedMessage as X, RecordedClose as Y, RecordedSend as Z, transportFromConnectionString as _, WebSocketPublisher as _t, UnregisteredWebSocketScheme as a, WebSocketTestSurface as at, LIMIT_CLOSE as b, CLOSE as c, WebSocketFrame as ct, Delivery as d, InvalidWebSocketMessage as dt, TestConnection as et, MemoryTransport as f, MessageAction as ft, WebSocketTransport as g, WebSocketMessages as gt, UnsupportedWebSocketTransport as h, UnknownWebSocketMessage as ht, WebSocketApiConfig as i, TestWebSocketPublisher as it, DuplicateWebSocketRoute as j, ConnectRequest as k, WebSocketServerOptions as l, WebSocketMessageDeclaresDiscriminator as lt, TransportSink as m, NoMessages as mt, InvalidReplicaCount as n, TestMessageRequest as nt, WebSocketSinkDriver as o, WebSocketDataHasDiscriminator as ot, RedisTransport as p, MessageData as pt, InvalidWebSocketRequest as q, WebSocketApi as r, TestMessageResponse as rt, registerWebSocketSinkDriver as s, WebSocketDataNotAnObject as st, InvalidHostLabel as t, TestDisconnectRequest as tt, WebSocketSurfaceServer as u, WebSocketMessageNotAnObject as ut, DEFAULT_WEBSOCKET_LIMITS as v, WebSocketSink as vt, TokenBucket as w, MemoryLimitStore as x, InvalidWebSocketLimit as y, DisconnectContext as z };
1207
+ //# sourceMappingURL=websocket-api-BPPXF79i.d.mts.map