webspresso 0.0.104 → 0.0.106

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 (233) hide show
  1. package/.agents/AGENTS.md +21 -2
  2. package/.agents/ARCHITECTURE.md +23 -0
  3. package/.agents/CACHE.md +147 -0
  4. package/.agents/CLI.md +220 -8
  5. package/.agents/EARLY_HINTS.md +120 -0
  6. package/.agents/FLAGS.md +118 -0
  7. package/.agents/HEALTH.md +118 -0
  8. package/.agents/LIMITS.md +109 -0
  9. package/.agents/LOGGING.md +93 -0
  10. package/.agents/METRICS.md +127 -0
  11. package/.agents/MIGRATION_JOBS.md +95 -0
  12. package/.agents/ORM.md +155 -1
  13. package/.agents/PLUGINS.md +38 -3
  14. package/.agents/QUEUE.md +42 -0
  15. package/.agents/RATE_LIMIT.md +147 -0
  16. package/.agents/RESILIENCE.md +235 -0
  17. package/.agents/SCALE_OUT.md +109 -0
  18. package/.agents/SECRETS.md +117 -0
  19. package/AGENTS.md +16 -0
  20. package/README.md +2 -2
  21. package/bin/commands/add-aws.js +396 -0
  22. package/bin/commands/add-ci.js +523 -0
  23. package/bin/commands/add-cloudflare.js +240 -0
  24. package/bin/commands/add-cloudrun.js +381 -0
  25. package/bin/commands/add-docker.js +6 -6
  26. package/bin/commands/add-migration-job.js +396 -0
  27. package/bin/commands/assets-sync.js +209 -0
  28. package/bin/commands/client-generate.js +52 -0
  29. package/bin/commands/console.js +53 -0
  30. package/bin/commands/db-migrate.js +47 -2
  31. package/bin/commands/db-studio.js +84 -0
  32. package/bin/commands/deploy-check.js +242 -13
  33. package/bin/commands/dev.js +1 -1
  34. package/bin/commands/export.js +87 -0
  35. package/bin/commands/new.js +5 -5
  36. package/bin/commands/openapi.js +1 -1
  37. package/bin/commands/secrets-pull.js +208 -0
  38. package/bin/commands/start.js +1 -1
  39. package/bin/utils/db.js +7 -1
  40. package/bin/utils/project.js +2 -2
  41. package/bin/webspresso.js +22 -0
  42. package/core/app.js +421 -0
  43. package/core/auth/authenticate.js +93 -0
  44. package/core/auth/hash.js +5 -4
  45. package/core/auth/index.js +34 -4
  46. package/core/auth/jwt.js +5 -54
  47. package/core/auth/magic-link.js +4 -5
  48. package/core/auth/manager.js +53 -10
  49. package/core/auth/middleware.js +16 -68
  50. package/core/auth/oauth.js +8 -17
  51. package/core/auth/redis-session.js +1008 -0
  52. package/core/auth/sessions.js +156 -0
  53. package/core/auth/totp.js +2 -1
  54. package/core/cache/byte-size.js +123 -0
  55. package/core/cache/cdn.js +296 -0
  56. package/core/cache/index.js +33 -0
  57. package/core/cache/lru.js +477 -0
  58. package/core/cache/tagged-lru.js +354 -0
  59. package/core/commands/registry.js +6 -20
  60. package/core/console/commands.js +148 -0
  61. package/core/console/context.js +260 -0
  62. package/core/console/eval.js +70 -0
  63. package/core/console/index.js +22 -0
  64. package/core/console/repl.js +102 -0
  65. package/core/early-hints/index.js +267 -0
  66. package/core/errors/domain.js +49 -0
  67. package/core/errors/http.js +31 -0
  68. package/core/errors/index.js +10 -0
  69. package/core/errors/normalize.js +88 -2
  70. package/core/events/discovery.js +6 -24
  71. package/core/events/dispatcher.js +9 -7
  72. package/core/events/signal.js +7 -0
  73. package/core/export/discovery.js +191 -0
  74. package/core/export/exporter.js +277 -0
  75. package/core/export/index.js +24 -0
  76. package/core/flags/evaluator.js +252 -0
  77. package/core/flags/hasher.js +37 -0
  78. package/core/flags/index.js +21 -0
  79. package/core/flags/manager.js +263 -0
  80. package/core/flags/store.js +126 -0
  81. package/core/health/index.js +41 -0
  82. package/core/health/middleware.js +213 -0
  83. package/core/health/normalize.js +140 -0
  84. package/core/health/probes.js +203 -0
  85. package/core/http/adapter.js +74 -0
  86. package/core/http/express-adapter.js +46 -0
  87. package/core/http/hono-adapter.js +531 -0
  88. package/core/http/index.js +41 -0
  89. package/core/http/pipeline.js +485 -0
  90. package/core/index.js +336 -0
  91. package/core/limits/index.js +34 -0
  92. package/core/limits/middleware.js +325 -0
  93. package/core/limits/normalize.js +222 -0
  94. package/core/logger/formatters.js +264 -0
  95. package/core/logger/index.js +260 -0
  96. package/core/logger/trace.js +137 -0
  97. package/core/metrics/collectors.js +125 -0
  98. package/core/metrics/index.js +45 -0
  99. package/core/metrics/middleware.js +230 -0
  100. package/core/metrics/registry.js +366 -0
  101. package/core/orm/batch.js +70 -0
  102. package/core/orm/cache/fingerprint.js +2 -2
  103. package/core/orm/cache/memory-provider.js +27 -110
  104. package/core/orm/d1.js +265 -0
  105. package/core/orm/index.js +176 -13
  106. package/core/orm/json-fields.js +22 -8
  107. package/core/orm/migrate-cloud.js +194 -0
  108. package/core/orm/model.js +10 -0
  109. package/core/orm/pool.js +97 -0
  110. package/core/orm/query-builder.js +72 -9
  111. package/core/orm/repository.js +318 -19
  112. package/core/orm/schema-helpers.js +8 -10
  113. package/core/orm/scopes.js +321 -1
  114. package/core/orm/transaction.js +10 -2
  115. package/core/orm/utils.js +4 -86
  116. package/core/queue/adapters/cloudflare.js +131 -0
  117. package/core/queue/adapters/database.js +4 -8
  118. package/core/queue/adapters/pubsub.js +400 -0
  119. package/core/queue/adapters/sqs.js +419 -0
  120. package/core/queue/adapters/wait-until.js +77 -0
  121. package/core/queue/index.js +8 -0
  122. package/core/queue/manager.js +66 -41
  123. package/core/rate-limit/index.js +22 -0
  124. package/core/rate-limit/limiter.js +219 -0
  125. package/core/rate-limit/stores/memory.js +129 -0
  126. package/core/rate-limit/stores/redis.js +151 -0
  127. package/core/rate-limit/utils.js +112 -0
  128. package/core/resilience/circuit-breaker.js +422 -0
  129. package/core/resilience/errors.js +63 -0
  130. package/core/resilience/index.js +53 -0
  131. package/core/resilience/registry.js +97 -0
  132. package/core/resilience/retry.js +203 -0
  133. package/core/schema-cache.js +9 -2
  134. package/core/secrets/index.js +113 -0
  135. package/core/secrets/manager.js +308 -0
  136. package/core/secrets/providers/aws.js +288 -0
  137. package/core/secrets/providers/env.js +44 -0
  138. package/core/secrets/providers/gcp.js +307 -0
  139. package/core/secrets/providers/memory.js +76 -0
  140. package/core/shutdown/http-adapter.js +4 -1
  141. package/core/shutdown/shutdown-manager.js +129 -19
  142. package/core/stream/index.js +19 -0
  143. package/core/stream/text-stream.js +326 -0
  144. package/core/studio/index.js +43 -0
  145. package/core/studio/inspector.js +258 -0
  146. package/core/studio/server.js +325 -0
  147. package/core/studio/ui.js +681 -0
  148. package/core/utils/array.js +12 -0
  149. package/core/utils/base64url.js +8 -0
  150. package/core/utils/crypto.js +118 -0
  151. package/core/utils/ensure-leading-slash.js +6 -0
  152. package/core/utils/escape-regexp.js +7 -0
  153. package/core/utils/fetch.js +6 -5
  154. package/core/utils/fs.js +144 -0
  155. package/core/utils/hmac.js +6 -0
  156. package/core/utils/json.js +98 -0
  157. package/core/utils/object.js +106 -0
  158. package/core/utils/random.js +9 -0
  159. package/core/utils/regex.js +77 -0
  160. package/core/utils/sha256.js +6 -0
  161. package/core/utils/string.js +87 -0
  162. package/core/utils/strip-trailing-slash.js +6 -0
  163. package/core/utils/time.js +96 -0
  164. package/core/utils/timeout.js +348 -0
  165. package/core/utils/url.js +106 -0
  166. package/core/utils/walk.js +7 -0
  167. package/index.d.ts +1549 -2
  168. package/index.js +272 -2
  169. package/package.json +3 -2
  170. package/plugins/admin-panel/core/api-extensions.js +2 -5
  171. package/plugins/admin-panel/index.js +13 -6
  172. package/plugins/admin-panel/modules/menu.js +1 -1
  173. package/plugins/api-key/crypto.js +3 -3
  174. package/plugins/api-key/index.js +3 -2
  175. package/plugins/api-key/scopes.js +5 -7
  176. package/plugins/audit-log/api-handlers.js +6 -15
  177. package/plugins/audit-log/index.js +3 -1
  178. package/plugins/audit-log/parse.js +3 -3
  179. package/plugins/basic-auth/index.js +3 -2
  180. package/plugins/cors.js +3 -2
  181. package/plugins/csrf/index.js +9 -12
  182. package/plugins/csv/index.js +8 -5
  183. package/plugins/dashboard/app.js +2 -2
  184. package/plugins/dashboard/index.js +5 -5
  185. package/plugins/data-exchange/record-selection.js +2 -5
  186. package/plugins/email/api-handlers.js +5 -18
  187. package/plugins/email/auth-bridge.js +3 -2
  188. package/plugins/email/index.js +11 -9
  189. package/plugins/health-check.js +2 -1
  190. package/plugins/index.js +5 -0
  191. package/plugins/lazy.js +5 -6
  192. package/plugins/mcp/discovery.js +18 -17
  193. package/plugins/polar/src/api.js +2 -1
  194. package/plugins/polar/src/webhooks.js +5 -6
  195. package/plugins/queue/index.js +18 -2
  196. package/plugins/rate-limit/index.js +3 -1
  197. package/plugins/redirect/index.js +16 -9
  198. package/plugins/rls/index.js +170 -0
  199. package/plugins/seo-checker/index.js +2 -2
  200. package/plugins/site-analytics/index.js +3 -1
  201. package/plugins/site-analytics/tracking.js +2 -2
  202. package/plugins/sitemap.js +3 -2
  203. package/plugins/swagger.js +12 -5
  204. package/plugins/upload/gcs-provider.js +148 -0
  205. package/plugins/upload/index.js +136 -77
  206. package/plugins/upload/orphan-pruner.js +4 -3
  207. package/plugins/upload/s3-provider.js +257 -0
  208. package/plugins/webhooks/crypto.js +6 -11
  209. package/plugins/webhooks/dispatcher.js +8 -8
  210. package/plugins/webhooks/index.js +33 -23
  211. package/plugins/webhooks/matcher.js +7 -11
  212. package/plugins/webhooks/sender.js +8 -11
  213. package/plugins/xlsx/index.js +7 -5
  214. package/src/api/api-loader.js +12 -95
  215. package/src/api/define-api.js +1 -0
  216. package/src/app-context.js +41 -5
  217. package/src/client-runtime/constants.js +10 -0
  218. package/src/client-runtime/mount.js +2 -3
  219. package/src/dev/banner.js +6 -2
  220. package/src/dev/client-gen.js +458 -0
  221. package/src/discovery/scan-routes.js +5 -2
  222. package/src/file-router.js +3 -3
  223. package/src/helpers.js +212 -24
  224. package/src/modules/module-discovery.js +1 -9
  225. package/src/pages/page-loader.js +13 -154
  226. package/src/plugin-manager.js +99 -18
  227. package/src/server.js +335 -133
  228. package/src/services/discovery.js +19 -40
  229. package/src/services/executor.js +95 -25
  230. package/src/services/memoize.js +3 -25
  231. package/src/services/registry.js +15 -1
  232. package/src/services/validator.js +38 -20
  233. package/src/template/precompile.js +8 -19
@@ -66,6 +66,7 @@ class NodeHttpAdapter {
66
66
  return new Promise((resolve) => {
67
67
  if (!this.server || !this.server.listening) {
68
68
  this._closed = true;
69
+ this.destroy();
69
70
  return resolve();
70
71
  }
71
72
 
@@ -73,6 +74,7 @@ class NodeHttpAdapter {
73
74
 
74
75
  this.server.close(() => {
75
76
  this._closed = true;
77
+ this.destroy();
76
78
  resolve();
77
79
  });
78
80
  });
@@ -115,13 +117,14 @@ class NodeHttpAdapter {
115
117
  }
116
118
  }
117
119
  this.sockets.clear();
120
+ this.destroy();
118
121
  }
119
122
 
120
123
  /**
121
124
  * Detach all listeners from the server
122
125
  */
123
126
  destroy() {
124
- if (this.server) {
127
+ if (this.server && typeof this.server.removeListener === 'function') {
125
128
  this.server.removeListener('connection', this._onConnection);
126
129
  this.server.removeListener('secureConnection', this._onSecureConnection);
127
130
  }
@@ -5,6 +5,8 @@
5
5
  * @module core/shutdown/shutdown-manager
6
6
  */
7
7
 
8
+ const { parseDurationMs } = require('../utils/time');
9
+
8
10
  class ShutdownManager {
9
11
  /**
10
12
  * @param {Object} [options]
@@ -19,7 +21,7 @@ class ShutdownManager {
19
21
  this.options = {
20
22
  enabled: options.enabled !== false,
21
23
  mode: options.mode === 'force' ? 'force' : 'graceful',
22
- timeout: typeof options.timeout === 'number' && options.timeout >= 0 ? options.timeout : 10_000,
24
+ timeout: options.timeout !== undefined ? parseDurationMs(options.timeout, 10_000) : 10_000,
23
25
  signals: Array.isArray(options.signals) ? options.signals : ['SIGINT', 'SIGTERM'],
24
26
  logger: options.logger === null ? null : (options.logger || console),
25
27
  exitOnSignal: options.exitOnSignal !== false,
@@ -57,8 +59,8 @@ class ShutdownManager {
57
59
  }
58
60
 
59
61
  set timeout(value) {
60
- if (typeof value === 'number' && value >= 0) {
61
- this.options.timeout = value;
62
+ if (value !== undefined && value !== null) {
63
+ this.options.timeout = parseDurationMs(value, this.options.timeout);
62
64
  }
63
65
  }
64
66
 
@@ -100,6 +102,15 @@ class ShutdownManager {
100
102
  return this;
101
103
  }
102
104
 
105
+ /**
106
+ * Register a shutdown hook (alias for onShutdown)
107
+ * @param {Function} fn
108
+ * @returns {this}
109
+ */
110
+ register(fn) {
111
+ return this.onShutdown(fn);
112
+ }
113
+
103
114
  /**
104
115
  * Register a plugin disposer / cleanup function
105
116
  * @param {string|Function} nameOrFn - Plugin name or disposer function
@@ -206,16 +217,65 @@ class ShutdownManager {
206
217
 
207
218
  this._log('info', `Starting ${modeLabel} shutdown (reason: ${reason})`);
208
219
 
220
+ const totalTimeout = isForce ? 0 : Math.max(0, this.options.timeout);
221
+ const startTime = Date.now();
222
+ const deadline = totalTimeout > 0 ? startTime + totalTimeout : 0;
223
+
224
+ const getRemainingTime = () => {
225
+ if (deadline === 0) return 0;
226
+ return Math.max(0, deadline - Date.now());
227
+ };
228
+
209
229
  // 1. Run plugin disposers in reverse registration order (terminates SSE streams, WebSockets, devReload clients, and workers)
210
230
  if (this._disposers.length > 0) {
211
231
  this._log('info', `Disposing ${this._disposers.length} plugins`);
212
- // Reverse array to tear down dependencies in reverse order
213
232
  const reverseDisposers = this._disposers.slice().reverse();
214
- for (const { name, fn } of reverseDisposers) {
233
+ for (let i = 0; i < reverseDisposers.length; i++) {
234
+ const { name, fn } = reverseDisposers[i];
235
+ const remainingDisposers = reverseDisposers.length - i;
236
+ const remainingMs = getRemainingTime();
237
+
238
+ if (isForce || (deadline > 0 && remainingMs <= 0)) {
239
+ try {
240
+ const res = fn();
241
+ if (res && typeof res.then === 'function') {
242
+ await Promise.race([
243
+ Promise.resolve(res),
244
+ new Promise(r => {
245
+ const t = setTimeout(r, 50);
246
+ if (typeof t.unref === 'function') t.unref();
247
+ })
248
+ ]);
249
+ }
250
+ } catch (err) {
251
+ this._log('error', `Error in plugin disposer "${name}":`, err);
252
+ }
253
+ continue;
254
+ }
255
+
256
+ const perDisposerTimeout = Math.min(
257
+ remainingMs,
258
+ Math.max(100, Math.floor(remainingMs / (remainingDisposers + 1)))
259
+ );
260
+
261
+ let timer = null;
262
+ const timeoutPromise = new Promise((resolve) => {
263
+ timer = setTimeout(() => {
264
+ this._log('warn', `Plugin disposer "${name}" timed out after ${perDisposerTimeout}ms`);
265
+ resolve();
266
+ }, perDisposerTimeout);
267
+ if (typeof timer.unref === 'function') timer.unref();
268
+ });
269
+
215
270
  try {
216
- await fn();
271
+ await Promise.race([
272
+ Promise.resolve().then(() => fn()),
273
+ timeoutPromise
274
+ ]);
217
275
  } catch (err) {
218
276
  this._log('error', `Error in plugin disposer "${name}":`, err);
277
+ } finally {
278
+ if (timer) clearTimeout(timer);
219
279
  }
220
280
  }
221
281
  }
@@ -225,13 +285,24 @@ class ShutdownManager {
225
285
  this._log('info', 'Closing HTTP server');
226
286
 
227
287
  for (const adapter of this._adapters) {
228
- if (isForce) {
229
- // Force mode: immediately close listener & force terminate connections
288
+ const remainingMs = getRemainingTime();
289
+
290
+ if (isForce || (deadline > 0 && remainingMs <= 0)) {
291
+ // Force mode or deadline expired: immediately forceClose
230
292
  try {
231
293
  if (typeof adapter.forceClose === 'function') {
232
294
  adapter.forceClose();
233
295
  }
234
- await adapter.close();
296
+ const closeRes = adapter.close();
297
+ if (closeRes && typeof closeRes.then === 'function') {
298
+ await Promise.race([
299
+ Promise.resolve(closeRes),
300
+ new Promise(r => {
301
+ const t = setTimeout(r, 100);
302
+ if (typeof t.unref === 'function') t.unref();
303
+ })
304
+ ]);
305
+ }
235
306
  } catch (err) {
236
307
  this._log('error', 'Error force closing adapter:', err);
237
308
  }
@@ -244,15 +315,13 @@ class ShutdownManager {
244
315
  } catch (e) {}
245
316
 
246
317
  let timer = null;
247
- let timedOut = false;
248
-
249
318
  const closePromise = adapter.close();
250
319
 
251
- if (this.options.timeout > 0) {
320
+ if (deadline > 0) {
321
+ const adapterTimeout = getRemainingTime();
252
322
  const timeoutPromise = new Promise((resolve) => {
253
323
  timer = setTimeout(() => {
254
- timedOut = true;
255
- this._log('warn', `Graceful shutdown timed out after ${this.options.timeout}ms`);
324
+ this._log('warn', `Graceful shutdown timed out with ${adapterTimeout}ms remaining budget`);
256
325
  this._log('info', 'Force closing active connections');
257
326
  try {
258
327
  if (typeof adapter.forceClose === 'function') {
@@ -262,7 +331,7 @@ class ShutdownManager {
262
331
  this._log('error', 'Error force closing connections after timeout:', err);
263
332
  }
264
333
  resolve();
265
- }, this.options.timeout);
334
+ }, adapterTimeout);
266
335
 
267
336
  if (typeof timer.unref === 'function') {
268
337
  timer.unref();
@@ -278,8 +347,8 @@ class ShutdownManager {
278
347
  clearTimeout(timer);
279
348
  }
280
349
 
281
- // Ensure closePromise has resolved
282
- await closePromise.catch(() => {});
350
+ // Prevent unhandled rejection without blocking shutdown if timeout won
351
+ closePromise.catch(() => {});
283
352
  }
284
353
  }
285
354
  }
@@ -287,11 +356,52 @@ class ShutdownManager {
287
356
  // 3. Run application shutdown hooks (app.onShutdown)
288
357
  if (this._hooks.length > 0) {
289
358
  this._log('info', `Running ${this._hooks.length} shutdown hooks`);
290
- for (const hook of this._hooks) {
359
+ for (let i = 0; i < this._hooks.length; i++) {
360
+ const hook = this._hooks[i];
361
+ const remainingHooks = this._hooks.length - i;
362
+ const remainingMs = getRemainingTime();
363
+
364
+ if (isForce || (deadline > 0 && remainingMs <= 0)) {
365
+ try {
366
+ const res = hook();
367
+ if (res && typeof res.then === 'function') {
368
+ await Promise.race([
369
+ Promise.resolve(res),
370
+ new Promise(r => {
371
+ const t = setTimeout(r, 50);
372
+ if (typeof t.unref === 'function') t.unref();
373
+ })
374
+ ]);
375
+ }
376
+ } catch (err) {
377
+ this._log('error', 'Error in shutdown hook:', err);
378
+ }
379
+ continue;
380
+ }
381
+
382
+ const perHookTimeout = Math.min(
383
+ remainingMs,
384
+ Math.max(100, Math.floor(remainingMs / (remainingHooks + 1)))
385
+ );
386
+
387
+ let timer = null;
388
+ const timeoutPromise = new Promise((resolve) => {
389
+ timer = setTimeout(() => {
390
+ this._log('warn', `Shutdown hook timed out after ${perHookTimeout}ms`);
391
+ resolve();
392
+ }, perHookTimeout);
393
+ if (typeof timer.unref === 'function') timer.unref();
394
+ });
395
+
291
396
  try {
292
- await hook();
397
+ await Promise.race([
398
+ Promise.resolve().then(() => hook()),
399
+ timeoutPromise
400
+ ]);
293
401
  } catch (err) {
294
402
  this._log('error', 'Error in shutdown hook:', err);
403
+ } finally {
404
+ if (timer) clearTimeout(timer);
295
405
  }
296
406
  }
297
407
  }
@@ -0,0 +1,19 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * Webspresso Streaming Subsystem
5
+ * Text, NDJSON, and real-time AI/LLM streaming utilities
6
+ * @module core/stream
7
+ */
8
+
9
+ const {
10
+ TextStreamController,
11
+ streamText,
12
+ streamJson,
13
+ } = require('./text-stream');
14
+
15
+ module.exports = {
16
+ TextStreamController,
17
+ streamText,
18
+ streamJson,
19
+ };
@@ -0,0 +1,326 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * High-performance, zero-dependency Text and NDJSON streaming engine for Webspresso
5
+ * Designed for LLM, AI tokens, and real-time chunked HTTP responses
6
+ * @module core/stream/text-stream
7
+ */
8
+
9
+ const EventEmitter = require('events');
10
+
11
+ /**
12
+ * Controller for an active chunked text or JSON stream
13
+ * @extends EventEmitter
14
+ */
15
+ class TextStreamController extends EventEmitter {
16
+ /**
17
+ * @param {import('http').IncomingMessage} req
18
+ * @param {import('http').ServerResponse} res
19
+ * @param {Object} [options]
20
+ * @param {number} [options.status=200]
21
+ * @param {string} [options.contentType='text/plain; charset=utf-8']
22
+ * @param {Record<string, string>} [options.headers]
23
+ * @param {boolean} [options.ndjson=false]
24
+ */
25
+ constructor(req, res, options = {}) {
26
+ super();
27
+
28
+ this.req = req;
29
+ this.res = res;
30
+ this.options = options;
31
+ this.ndjson = options.ndjson === true;
32
+
33
+ this.isOpen = true;
34
+ this.isClosed = false;
35
+ this._cleanupBound = this._handleClose.bind(this);
36
+
37
+ this._init();
38
+ }
39
+
40
+ /**
41
+ * Initialize socket settings and HTTP response headers
42
+ * @private
43
+ */
44
+ _init() {
45
+ // 1. Opt out of compression (zlib buffers chunks and breaks LLM real-time streaming)
46
+ if (typeof this.res.compress === 'function') {
47
+ this.res.compress(false);
48
+ }
49
+
50
+ // 2. Optimize socket for streaming
51
+ const socket = this.req ? this.req.socket : null;
52
+ if (socket) {
53
+ if (typeof socket.setTimeout === 'function') socket.setTimeout(0);
54
+ if (typeof socket.setNoDelay === 'function') socket.setNoDelay(true);
55
+ if (typeof socket.setKeepAlive === 'function') socket.setKeepAlive(true);
56
+ }
57
+
58
+ // 3. Write chunked streaming headers
59
+ if (!this.res.headersSent) {
60
+ const status = this.options.status || 200;
61
+ const contentType = this.ndjson
62
+ ? (this.options.contentType || 'application/x-ndjson; charset=utf-8')
63
+ : (this.options.contentType || 'text/plain; charset=utf-8');
64
+
65
+ const customHeaders = this.options.headers || {};
66
+ const headers = {
67
+ 'Content-Type': contentType,
68
+ 'Cache-Control': 'no-cache, no-transform',
69
+ 'Connection': 'keep-alive',
70
+ 'X-Content-Type-Options': 'nosniff',
71
+ ...customHeaders,
72
+ };
73
+
74
+ if (typeof this.res.writeHead === 'function') {
75
+ this.res.writeHead(status, headers);
76
+ } else {
77
+ for (const [key, value] of Object.entries(headers)) {
78
+ this.res.setHeader(key, value);
79
+ }
80
+ this.res.statusCode = status;
81
+ }
82
+ }
83
+
84
+ if (typeof this.res.flushHeaders === 'function') {
85
+ this.res.flushHeaders();
86
+ }
87
+
88
+ // 4. Listen for disconnect / termination
89
+ if (this.req) {
90
+ this.req.on('close', this._cleanupBound);
91
+ }
92
+ this.res.on('close', this._cleanupBound);
93
+ this.res.on('finish', this._cleanupBound);
94
+ this.res.on('error', this._cleanupBound);
95
+ }
96
+
97
+ /**
98
+ * Internal termination handler
99
+ * @private
100
+ */
101
+ _handleClose() {
102
+ if (this.isClosed) return;
103
+ this.isOpen = false;
104
+ this.isClosed = true;
105
+
106
+ if (this.req) {
107
+ this.req.removeListener('close', this._cleanupBound);
108
+ }
109
+ this.res.removeListener('close', this._cleanupBound);
110
+ this.res.removeListener('finish', this._cleanupBound);
111
+ this.res.removeListener('error', this._cleanupBound);
112
+
113
+ this.emit('close');
114
+ }
115
+
116
+ /**
117
+ * Flush response buffer if supported by platform/adapter
118
+ * @private
119
+ */
120
+ _flush() {
121
+ if (typeof this.res.flush === 'function') {
122
+ try {
123
+ this.res.flush();
124
+ } catch (_) {}
125
+ }
126
+ }
127
+
128
+ /**
129
+ * Write a text chunk or JSON object to the client
130
+ * Handles backpressure if buffer fills
131
+ * @param {string|Buffer|Object} chunk
132
+ * @returns {Promise<boolean>} True when flushed or queued
133
+ */
134
+ async write(chunk) {
135
+ if (!this.isOpen || this.isClosed || this.res.destroyed || this.res.writableEnded) {
136
+ return false;
137
+ }
138
+
139
+ let payload;
140
+ if (this.ndjson) {
141
+ if (typeof chunk === 'string') {
142
+ payload = chunk.endsWith('\n') ? chunk : `${chunk}\n`;
143
+ } else {
144
+ payload = `${JSON.stringify(chunk)}\n`;
145
+ }
146
+ } else {
147
+ if (typeof chunk === 'object' && !Buffer.isBuffer(chunk)) {
148
+ payload = JSON.stringify(chunk);
149
+ } else {
150
+ payload = String(chunk);
151
+ }
152
+ }
153
+
154
+ return new Promise((resolve) => {
155
+ try {
156
+ const canContinue = this.res.write(payload);
157
+ this._flush();
158
+
159
+ if (!canContinue && !this.res.destroyed && !this.res.writableEnded) {
160
+ this.res.once('drain', () => resolve(true));
161
+ } else {
162
+ resolve(true);
163
+ }
164
+ } catch (_) {
165
+ this._handleClose();
166
+ resolve(false);
167
+ }
168
+ });
169
+ }
170
+
171
+ /**
172
+ * Pipes an async iterable, generator, or stream into this HTTP response
173
+ * @param {AsyncIterable<any>|Iterable<any>|import('stream').Readable} source
174
+ * @param {Function} [transform] - Optional transformer function
175
+ * @returns {Promise<void>}
176
+ */
177
+ async pipe(source, transform) {
178
+ if (!source) return;
179
+
180
+ try {
181
+ for await (const rawChunk of source) {
182
+ if (!this.isOpen || this.isClosed) break;
183
+
184
+ const chunk = typeof transform === 'function' ? transform(rawChunk) : rawChunk;
185
+ if (chunk === undefined || chunk === null) continue;
186
+
187
+ await this.write(chunk);
188
+ }
189
+ } catch (err) {
190
+ this.emit('error', err);
191
+ throw err;
192
+ }
193
+ }
194
+
195
+ /**
196
+ * Streams output from a generator or runner callback and closes the response on finish
197
+ * @param {Function} runnerFn
198
+ * @returns {Promise<void>}
199
+ */
200
+ async stream(runnerFn) {
201
+ if (typeof runnerFn !== 'function') {
202
+ throw new TypeError('stream() expects a function or generator');
203
+ }
204
+
205
+ try {
206
+ const res = runnerFn(this);
207
+ if (res && typeof res[Symbol.asyncIterator] === 'function') {
208
+ await this.pipe(res);
209
+ } else if (res && typeof res[Symbol.iterator] === 'function') {
210
+ await this.pipe(res);
211
+ } else if (res && typeof res.then === 'function') {
212
+ await res;
213
+ }
214
+ } finally {
215
+ this.close();
216
+ }
217
+ }
218
+
219
+ /**
220
+ * Close the stream and terminate the HTTP response
221
+ */
222
+ close() {
223
+ if (this.isClosed) return;
224
+ this.isOpen = false;
225
+ this.isClosed = true;
226
+
227
+ try {
228
+ if (!this.res.writableEnded && !this.res.destroyed) {
229
+ this.res.end();
230
+ }
231
+ } catch (_) {}
232
+
233
+ this._handleClose();
234
+ }
235
+
236
+ /**
237
+ * Alias for close()
238
+ */
239
+ end() {
240
+ this.close();
241
+ }
242
+ }
243
+
244
+ /**
245
+ * Streams plain text (e.g. LLM / AI tokens, markdown) to the HTTP response
246
+ * @param {import('http').IncomingMessage} req
247
+ * @param {import('http').ServerResponse} res
248
+ * @param {AsyncIterable<any>|Function|Object} sourceOrCallback
249
+ * @param {Object} [maybeOptions]
250
+ * @returns {TextStreamController|Promise<void>}
251
+ */
252
+ function streamText(req, res, sourceOrCallback, maybeOptions = {}) {
253
+ let source = null;
254
+ let options = {};
255
+
256
+ const isSource =
257
+ typeof sourceOrCallback === 'function' ||
258
+ (sourceOrCallback && (
259
+ typeof sourceOrCallback[Symbol.asyncIterator] === 'function' ||
260
+ typeof sourceOrCallback[Symbol.iterator] === 'function' ||
261
+ typeof sourceOrCallback.pipe === 'function'
262
+ ));
263
+
264
+ if (isSource) {
265
+ source = sourceOrCallback;
266
+ options = maybeOptions || {};
267
+ } else if (sourceOrCallback && typeof sourceOrCallback === 'object') {
268
+ options = sourceOrCallback;
269
+ }
270
+
271
+ const controller = new TextStreamController(req, res, { ...options, ndjson: false });
272
+
273
+ if (source) {
274
+ if (typeof source === 'function') {
275
+ return controller.stream(source);
276
+ }
277
+ return controller.pipe(source, options.map).finally(() => controller.close());
278
+ }
279
+
280
+ return controller;
281
+ }
282
+
283
+ /**
284
+ * Streams newline-delimited JSON (NDJSON) objects to the HTTP response
285
+ * @param {import('http').IncomingMessage} req
286
+ * @param {import('http').ServerResponse} res
287
+ * @param {AsyncIterable<any>|Function|Object} sourceOrCallback
288
+ * @param {Object} [maybeOptions]
289
+ * @returns {TextStreamController|Promise<void>}
290
+ */
291
+ function streamJson(req, res, sourceOrCallback, maybeOptions = {}) {
292
+ let source = null;
293
+ let options = {};
294
+
295
+ const isSource =
296
+ typeof sourceOrCallback === 'function' ||
297
+ (sourceOrCallback && (
298
+ typeof sourceOrCallback[Symbol.asyncIterator] === 'function' ||
299
+ typeof sourceOrCallback[Symbol.iterator] === 'function' ||
300
+ typeof sourceOrCallback.pipe === 'function'
301
+ ));
302
+
303
+ if (isSource) {
304
+ source = sourceOrCallback;
305
+ options = maybeOptions || {};
306
+ } else if (sourceOrCallback && typeof sourceOrCallback === 'object') {
307
+ options = sourceOrCallback;
308
+ }
309
+
310
+ const controller = new TextStreamController(req, res, { ...options, ndjson: true });
311
+
312
+ if (source) {
313
+ if (typeof source === 'function') {
314
+ return controller.stream(source);
315
+ }
316
+ return controller.pipe(source, options.map).finally(() => controller.close());
317
+ }
318
+
319
+ return controller;
320
+ }
321
+
322
+ module.exports = {
323
+ TextStreamController,
324
+ streamText,
325
+ streamJson,
326
+ };
@@ -0,0 +1,43 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * Webspresso DB Studio Subsystem
5
+ * Interactive visual database browser and SQL query runner
6
+ * @module core/studio
7
+ */
8
+
9
+ const {
10
+ listTables,
11
+ getTableSchema,
12
+ getTableRows,
13
+ insertRow,
14
+ updateRow,
15
+ deleteRow,
16
+ executeRawQuery,
17
+ getDialect,
18
+ } = require('./inspector');
19
+
20
+ const {
21
+ createStudioApp,
22
+ startStudio,
23
+ openBrowser,
24
+ getTelemetrySnapshot,
25
+ } = require('./server');
26
+
27
+ const { renderStudioHtml } = require('./ui');
28
+
29
+ module.exports = {
30
+ listTables,
31
+ getTableSchema,
32
+ getTableRows,
33
+ insertRow,
34
+ updateRow,
35
+ deleteRow,
36
+ executeRawQuery,
37
+ getDialect,
38
+ createStudioApp,
39
+ startStudio,
40
+ openBrowser,
41
+ getTelemetrySnapshot,
42
+ renderStudioHtml,
43
+ };