webspresso 0.0.108 → 0.0.110

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 (184) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +3 -3
  3. package/bin/commands/add-esbuild.js +7 -3
  4. package/bin/commands/add-tailwind.js +9 -5
  5. package/bin/commands/build.js +20 -4
  6. package/bin/commands/dev.js +57 -7
  7. package/bin/commands/doctor.js +42 -1
  8. package/bin/commands/favicon-generate.js +10 -3
  9. package/bin/commands/new.js +8 -3
  10. package/bin/commands/start.js +3 -1
  11. package/bin/utils/add-command.js +16 -0
  12. package/core/app.js +45 -3
  13. package/core/auth/authenticate.js +3 -3
  14. package/core/auth/hash.js +167 -43
  15. package/core/auth/index.js +13 -1
  16. package/core/auth/jwt.js +21 -2
  17. package/core/auth/manager.js +63 -14
  18. package/core/auth/middleware.js +4 -2
  19. package/core/auth/oauth.js +5 -1
  20. package/core/auth/tokens.js +7 -2
  21. package/core/auth/totp.js +42 -6
  22. package/core/auth/user-agent.js +2 -0
  23. package/core/client/adapter/datastar.js +1401 -0
  24. package/core/client/api.js +1337 -0
  25. package/core/client/controller.js +1706 -0
  26. package/core/client/debug.js +367 -0
  27. package/core/client/devtool.js +1134 -0
  28. package/core/client/forms.js +1164 -0
  29. package/core/client/fragments.js +894 -0
  30. package/core/client/index.d.ts +59 -0
  31. package/core/client/index.js +391 -0
  32. package/core/client/lite.js +175 -0
  33. package/core/client/server-fragments.js +868 -0
  34. package/core/client/storage.js +339 -0
  35. package/core/client/utils.js +281 -0
  36. package/core/compression/middleware.js +277 -26
  37. package/core/context/app-context.js +25 -3
  38. package/core/context/request.js +32 -4
  39. package/core/errors/middleware.js +14 -0
  40. package/core/events/dispatcher.js +33 -0
  41. package/core/forms/flash.js +136 -102
  42. package/core/health/middleware.js +36 -6
  43. package/core/http/pipeline.js +45 -6
  44. package/core/index.js +25 -7
  45. package/core/kernel/view.js +41 -10
  46. package/core/metrics/middleware.js +30 -6
  47. package/core/metrics/registry.js +13 -5
  48. package/core/orm/cache/fingerprint.js +32 -11
  49. package/core/orm/cache/layer.js +19 -2
  50. package/core/orm/hidden.js +145 -0
  51. package/core/orm/model.js +48 -2
  52. package/core/orm/query-builder.js +343 -6
  53. package/core/orm/query-filters.js +14 -2
  54. package/core/orm/repository.js +64 -13
  55. package/core/orm/schema-helpers.js +9 -6
  56. package/core/orm/transaction.js +50 -6
  57. package/core/orm/types.js +4 -0
  58. package/core/queue/adapters/database.js +184 -2
  59. package/core/queue/adapters/memory.js +153 -5
  60. package/core/queue/adapters/redis.js +59 -4
  61. package/core/queue/job.js +14 -1
  62. package/core/queue/manager.js +115 -0
  63. package/core/resilience/circuit-breaker.js +27 -8
  64. package/core/services/builtins/exchange.js +174 -7
  65. package/core/services/builtins/file-manager.js +36 -0
  66. package/core/services/builtins/mail.js +27 -0
  67. package/core/services/builtins/queue.js +144 -0
  68. package/core/services/builtins/security.js +118 -0
  69. package/core/services/builtins/webhook.js +110 -0
  70. package/core/services/executor.js +38 -16
  71. package/core/services/index.js +4 -1
  72. package/core/sse/stream.js +28 -5
  73. package/core/utils/timeout.js +8 -1
  74. package/core/validation/compiler.js +10 -7
  75. package/index.d.ts +1320 -74
  76. package/index.js +128 -8
  77. package/package.json +75 -27
  78. package/plugins/admin-panel/client/parts/08-record-list.js +717 -70
  79. package/plugins/admin-panel/index.js +19 -8
  80. package/plugins/csrf/index.js +3 -3
  81. package/plugins/data-exchange/export.js +214 -0
  82. package/plugins/data-exchange/import.js +48 -5
  83. package/plugins/data-exchange/index.js +70 -28
  84. package/plugins/data-exchange/preview.js +266 -0
  85. package/plugins/data-exchange/template.js +242 -0
  86. package/plugins/email/admin-component.js +783 -141
  87. package/plugins/email/api-handlers.js +51 -1
  88. package/plugins/email/index.js +5 -0
  89. package/plugins/email/service.js +48 -0
  90. package/plugins/file-manager/admin-component.js +1546 -70
  91. package/plugins/file-manager/api-handlers.js +166 -1
  92. package/plugins/file-manager/core.js +598 -8
  93. package/plugins/file-manager/index.js +8 -0
  94. package/plugins/index.js +7 -0
  95. package/plugins/mcp/auth.js +3 -3
  96. package/plugins/oauth/index.js +36 -3
  97. package/plugins/queue/admin-component.js +1092 -0
  98. package/plugins/queue/api-handlers.js +248 -0
  99. package/plugins/queue/index.js +69 -0
  100. package/plugins/rest-resources/index.js +7 -2
  101. package/plugins/security/admin-component.js +689 -0
  102. package/plugins/security/api-handlers.js +169 -0
  103. package/plugins/security/audit.js +153 -0
  104. package/plugins/security/bruteforce.js +244 -0
  105. package/plugins/security/firewall.js +459 -0
  106. package/plugins/security/headers.js +214 -0
  107. package/plugins/security/honeypot.js +234 -0
  108. package/plugins/security/incident-recorder.js +137 -0
  109. package/plugins/security/index.js +211 -0
  110. package/plugins/seo-checker/analyzer.js +20 -7
  111. package/plugins/upload/index.js +36 -0
  112. package/plugins/webhooks/admin-component.js +702 -175
  113. package/plugins/webhooks/api-handlers.js +75 -1
  114. package/plugins/webhooks/dispatcher.js +290 -11
  115. package/plugins/webhooks/index.js +37 -2
  116. package/plugins/webhooks/sender.js +56 -0
  117. package/plugins/xlsx/engine.js +19 -4
  118. package/src/api/api-loader.js +19 -1
  119. package/src/bundle/index.js +443 -17
  120. package/src/client-runtime/bootstrap-swup.js +9 -0
  121. package/src/client-runtime/mount.js +15 -20
  122. package/src/client-runtime/resolve.js +3 -2
  123. package/src/dev/api-typegen.js +1300 -0
  124. package/src/dev/banner.js +10 -1
  125. package/src/dev/colors.js +1 -1
  126. package/src/dev/index.js +7 -1
  127. package/src/dev/typegen.js +173 -17
  128. package/src/dev-reload/index.js +1 -1
  129. package/src/discovery/file-route-parser.js +17 -3
  130. package/src/discovery/scan-routes.js +4 -1
  131. package/src/file-router.js +253 -69
  132. package/src/helpers.js +46 -26
  133. package/src/njk-frontmatter.js +30 -4
  134. package/src/routing/cascading.js +26 -8
  135. package/src/routing/mount-discovered-routes.js +76 -0
  136. package/src/server.js +231 -70
  137. package/views/partials/webspresso-client-runtime.njk +1 -9
  138. package/.agents/ADMIN.md +0 -426
  139. package/.agents/AGENTS.md +0 -96
  140. package/.agents/ARCHITECTURE.md +0 -163
  141. package/.agents/AUTH.md +0 -581
  142. package/.agents/CACHE.md +0 -148
  143. package/.agents/CLI.md +0 -649
  144. package/.agents/COMPRESSION.md +0 -59
  145. package/.agents/CONTEXT.md +0 -152
  146. package/.agents/CONVENTIONS.md +0 -50
  147. package/.agents/EARLY_HINTS.md +0 -120
  148. package/.agents/EMAIL.md +0 -223
  149. package/.agents/ERRORS.md +0 -260
  150. package/.agents/EVENTS.md +0 -179
  151. package/.agents/FLAGS.md +0 -118
  152. package/.agents/HEALTH.md +0 -118
  153. package/.agents/LIMITS.md +0 -109
  154. package/.agents/LOGGING.md +0 -93
  155. package/.agents/MCP.md +0 -103
  156. package/.agents/METRICS.md +0 -127
  157. package/.agents/MIGRATION_JOBS.md +0 -95
  158. package/.agents/ORM.md +0 -700
  159. package/.agents/PLUGINS.md +0 -729
  160. package/.agents/QUEUE.md +0 -290
  161. package/.agents/RATE_LIMIT.md +0 -147
  162. package/.agents/REALTIME.md +0 -213
  163. package/.agents/RESILIENCE.md +0 -235
  164. package/.agents/ROUTING.md +0 -605
  165. package/.agents/SCALE_OUT.md +0 -109
  166. package/.agents/SECRETS.md +0 -117
  167. package/.agents/SERVICES.md +0 -341
  168. package/.agents/SHUTDOWN.md +0 -74
  169. package/.agents/STREAMING.md +0 -108
  170. package/.agents/WORKFLOW.md +0 -27
  171. package/.agents/internal/DOCUMENTATION_REVIEW.md +0 -485
  172. package/.agents/internal/TECHNICAL_REVIEW.md +0 -428
  173. package/.agents/skills/webspresso-admin-and-plugins/SKILL.md +0 -122
  174. package/.agents/skills/webspresso-framework/SKILL.md +0 -89
  175. package/.agents/skills/webspresso-orm-and-database/SKILL.md +0 -127
  176. package/.agents/skills/webspresso-routing-and-api/SKILL.md +0 -130
  177. package/.agents/skills/webspresso-services/SKILL.md +0 -134
  178. package/.cursorrules +0 -14
  179. package/AGENTS.md +0 -203
  180. package/CLAUDE.md +0 -54
  181. package/core/kernel/run-demo.js +0 -58
  182. package/plugins/admin-panel/styles.js +0 -9
  183. package/plugins/data-exchange/export-xlsx.js +0 -119
  184. package/src/client-runtime/bootstrap-alpine-swup.js +0 -34
package/.agents/LIMITS.md DELETED
@@ -1,109 +0,0 @@
1
- # Configurable Payload Size Limits & DoS Protection (`core/limits`)
2
-
3
- Webspresso provides a zero-dependency, configurable request body size limiter and Denial of Service (DoS) protection layer. It safeguards Node.js memory against payload exhaustion attacks while supporting per-route overrides, streaming bypass, and native raw body capture for HMAC webhook verification.
4
-
5
- ---
6
-
7
- ## 🎯 Key Capabilities
8
-
9
- 1. **Multi-Parser Configuration**:
10
- - `json`: Size limit for `application/json` (default: `'1mb'`).
11
- - `urlencoded`: Size limit for `application/x-www-form-urlencoded` (default: `'1mb'`).
12
- - `parameterLimit`: Maximum number of URL-encoded form parameters (default: `1000`).
13
- - `raw`: Size limit for `application/octet-stream` (default: `false` / disabled).
14
- - `text`: Size limit for `text/plain` (default: `false` / disabled).
15
- 2. **Standard Exception Mapping**:
16
- - Limit exceeded -> Throws `PayloadTooLargeError` (HTTP 413) with `{ limit, length, expected }` details and `code: 'PAYLOAD_TOO_LARGE'`.
17
- - Parameter exhaustion -> Throws `PayloadTooLargeError` (HTTP 413) with `code: 'PARAMETERS_TOO_MANY'`.
18
- - Malformed JSON -> Throws `BadRequestError` (HTTP 400) with `code: 'INVALID_JSON_PAYLOAD'`.
19
- 3. **Webhook & HMAC Signature Verification**:
20
- - `captureRawBody: true` stores incoming unparsed `Buffer` on `req.rawBody` for zero-overhead cryptographic signatures (Polar, Stripe, LemonSqueezy, GitHub).
21
- 4. **Route Overrides & Streaming Bypass**:
22
- - `limits.routes`: Generous limits for specific paths (e.g. `/api/upload` -> 25MB) without loosening server-wide protection.
23
- - `limits.exclude`: Completely skips global body parsers for streaming and custom multipart endpoints.
24
-
25
- ---
26
-
27
- ## 🚀 Configuration Examples
28
-
29
- ### 1. Global Configuration
30
-
31
- ```javascript
32
- const { createApp } = require('webspresso');
33
-
34
- const app = createApp({
35
- pagesDir: 'pages',
36
- limits: {
37
- json: '2mb', // 2 Megabytes for JSON
38
- urlencoded: '1mb', // 1 Megabyte for Forms
39
- parameterLimit: 2000, // Up to 2000 parameters
40
- raw: '10mb', // Enable raw buffer parsing for binary data
41
- captureRawBody: true, // Automatically populate req.rawBody
42
- },
43
- });
44
- ```
45
-
46
- Shorthand (applies to both JSON and URL-encoded):
47
- ```javascript
48
- const app = createApp({
49
- pagesDir: 'pages',
50
- limits: '5mb', // Both json and urlencoded set to 5 MB
51
- });
52
- ```
53
-
54
- ### 2. Route Overrides & Exclusions
55
-
56
- ```javascript
57
- const app = createApp({
58
- pagesDir: 'pages',
59
- limits: {
60
- json: '500kb', // Tight global limit for standard APIs
61
- routes: {
62
- '/api/import/json': { json: '25mb' }, // Relaxed limit for batch import
63
- '/api/webhooks/*': { raw: '5mb', captureRawBody: true },
64
- },
65
- exclude: [
66
- '/api/stream/upload', // Skip global body parser entirely for socket streaming
67
- ],
68
- },
69
- });
70
- ```
71
-
72
- ### 3. Webhook Signature Verification with `req.rawBody`
73
-
74
- ```javascript
75
- // pages/api/webhooks/polar.post.js
76
- const crypto = require('crypto');
77
- const { defineApi, UnauthorizedError } = require('webspresso');
78
-
79
- module.exports = defineApi({
80
- handler: async (req, res) => {
81
- const signature = req.headers['webhook-signature'];
82
- const expected = crypto
83
- .createHmac('sha256', process.env.POLAR_WEBHOOK_SECRET)
84
- .update(req.rawBody) // Native Buffer captured via captureRawBody
85
- .digest('hex');
86
-
87
- if (signature !== expected) {
88
- throw new UnauthorizedError('Invalid signature');
89
- }
90
-
91
- return res.json({ received: true });
92
- },
93
- });
94
- ```
95
-
96
- ---
97
-
98
- ## 🛡️ Standalone Middleware Usage
99
-
100
- For manual route mounting or custom Express routers:
101
-
102
- ```javascript
103
- const { createLimitsMiddleware } = require('webspresso');
104
-
105
- // Mount on custom router or endpoint
106
- app.post('/custom-endpoint', createLimitsMiddleware({ json: '50mb' }), (req, res) => {
107
- res.json({ size: req.body.length });
108
- });
109
- ```
@@ -1,93 +0,0 @@
1
- # Structured Cloud Logging & Distributed Tracing Guide
2
-
3
- Webspresso features an enterprise, zero-dependency Structured Cloud Logger (`core/logger`) designed specifically for serverless and containerized cloud platforms (Google Cloud Run, AWS App Runner, ECS Fargate, Lambda, Kubernetes).
4
-
5
- ---
6
-
7
- ## 🎯 Key Capabilities
8
-
9
- 1. **Native Cloud Platform Detection & Formatting**:
10
- - **Google Cloud Platform (`format: 'gcp'`)**: Automatically emits JSON payloads with Google Cloud Logging `severity` levels (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`), `logging.googleapis.com/trace`, `logging.googleapis.com/spanId`, and RFC `httpRequest` metadata.
11
- - **Amazon Web Services (`format: 'aws'`)**: Formats logs with `level`, `requestId`, `xrayTraceId`, and `http` metrics compatible with AWS CloudWatch and AWS X-Ray.
12
- - **Standard JSON (`format: 'json'`)**: Compact, structured single-line JSON stream for Docker, Kubernetes, and Datadog.
13
- - **Development Pretty (`format: 'pretty'`)**: Fast, ANSI color-coded console logs for local developer happiness.
14
- 2. **Distributed Tracing Context Propagation**:
15
- - Parses incoming request trace headers automatically:
16
- - `x-cloud-trace-context` (Google Cloud Trace)
17
- - `x-amzn-trace-id` (AWS X-Ray)
18
- - `traceparent` (W3C standard)
19
- - `x-request-id` / `x-correlation-id`
20
- - Injects trace ID and span ID into every log statement emitted during the request lifecycle.
21
- 3. **Automatic Child Logger on Requests (`req.logger`)**:
22
- - In API route handlers and SSR page loaders, `req.logger` is pre-bound to the request's trace ID and contextual metadata.
23
- - Automatically logs HTTP access on request finish (`res.on('finish')`) with latency, status code, remote IP, and user-agent.
24
- 4. **Deep Sensitive Key Redaction**:
25
- - Recursively masks sensitive fields (`password`, `token`, `secret`, `authorization`, `cookie`, `apiKey`) to prevent accidental credential leakage in cloud log aggregation systems.
26
-
27
- ---
28
-
29
- ## 🚀 Usage in Application Code
30
-
31
- ### In API Route Handlers
32
-
33
- ```javascript
34
- // pages/api/orders.post.js
35
- const { defineApi } = require('webspresso');
36
-
37
- module.exports = defineApi({
38
- schema: ({ z }) => ({
39
- body: z.object({ amount: z.number().positive(), customerId: z.string() }),
40
- }),
41
- handler: async (req, res) => {
42
- // req.logger is automatically bound to the request's trace ID
43
- req.logger.info('Processing order checkout', {
44
- customerId: req.input.body.customerId,
45
- amount: req.input.body.amount,
46
- });
47
-
48
- try {
49
- const order = await req.service('order.create', req.input.body);
50
- req.logger.info('Order processed successfully', { orderId: order.id });
51
- return res.status(201).json(order);
52
- } catch (err) {
53
- req.logger.error('Failed to process order', { error: err.message });
54
- throw err;
55
- }
56
- },
57
- });
58
- ```
59
-
60
- ### Standalone Logger & Child Context
61
-
62
- ```javascript
63
- const { createLogger } = require('webspresso');
64
-
65
- const logger = createLogger({
66
- format: 'auto', // 'gcp' | 'aws' | 'json' | 'pretty'
67
- level: 'info',
68
- defaultMeta: { service: 'payment-worker' },
69
- project: 'my-gcp-project', // optional GCP project ID
70
- });
71
-
72
- logger.info('Worker started');
73
-
74
- // Create contextual child logger
75
- const jobLogger = logger.child({ jobId: 'job_42' });
76
- jobLogger.info('Task execution started');
77
- ```
78
-
79
- ### Configuration in `createApp`
80
-
81
- ```javascript
82
- const { createApp } = require('webspresso');
83
-
84
- const app = createApp({
85
- pagesDir: './pages',
86
- logger: {
87
- format: 'auto', // Auto-detected from K_SERVICE, AWS_EXECUTION_ENV, or NODE_ENV
88
- level: 'info',
89
- exclude: ['/healthz', '/readyz', '/favicon.ico'],
90
- redact: ['password', 'secret', 'token'],
91
- },
92
- });
93
- ```
package/.agents/MCP.md DELETED
@@ -1,103 +0,0 @@
1
- # Webspresso Model Context Protocol (MCP) Guide
2
-
3
- The **Model Context Protocol (MCP)** plugin (`plugins/mcp`) connects Webspresso applications directly to AI agents, IDE assistants (Antigravity, Claude Desktop, Cursor, Zed, Windsurf), and autonomous coding tools.
4
-
5
- ---
6
-
7
- ## 1. Overview & Architecture
8
-
9
- Webspresso's architecture seamlessly bridges to MCP:
10
- - **Services (`services/`) → MCP Tools**: Every service defined in `services/` is automatically converted into an MCP tool with full JSON Schema input validation derived from its Zod `schema`.
11
- - **ORM Models (`models/`) → MCP Tools & Resources**: Models defined with `defineModel` provide query tools (`orm_find`, `orm_findById`), mutation tools (`orm_create`, `orm_update`, `orm_delete`), metadata tools (`orm_describe_model`), and resources (`webspresso://models`, `webspresso://models/{model}`, `webspresso://schema`).
12
- - **System Context → MCP Resources**: `webspresso://routes` (file routes, API routes, HTTP methods), `webspresso://services` (catalog of services), and `webspresso://health` (system metrics).
13
- - **Dual Transport**:
14
- - **Stdio (`webspresso mcp`)**: Standard input/output JSON-RPC 2.0 lines for local IDEs and CLI.
15
- - **HTTP & SSE (`/_mcp/sse`, `/_mcp/messages`, `/_mcp`)**: Server-Sent Events stream and Streamable HTTP for remote or web-accessible agents.
16
-
17
- ---
18
-
19
- ## 2. Using the Plugin in Webspresso App
20
-
21
- ```javascript
22
- const { createApp, mcpPlugin } = require('webspresso');
23
- const db = require('./models');
24
-
25
- const { app } = createApp({
26
- db,
27
- plugins: [
28
- mcpPlugin({
29
- path: '/_mcp', // default: '/_mcp'
30
- auth: {
31
- token: process.env.MCP_SECRET_TOKEN, // Bearer token validation
32
- localhostOnly: true, // Only allow connections from localhost
33
- },
34
- services: {
35
- include: ['user.*', 'catalog.*'], // optional filter
36
- readOnly: false, // set true to disable mutation services
37
- },
38
- orm: {
39
- readOnly: false, // set true to allow only find/describe queries
40
- },
41
- discovery: true, // auto-discover custom mcp/ folder
42
- }),
43
- ],
44
- });
45
- ```
46
-
47
- ---
48
-
49
- ## 3. CLI Command: `webspresso mcp`
50
-
51
- Start the MCP server over Stdio without starting the web server:
52
-
53
- ```bash
54
- # Start MCP server over stdio
55
- npx webspresso mcp
56
-
57
- # Restrict to read-only mode (prevent mutations)
58
- npx webspresso mcp --read-only
59
-
60
- # Print configuration snippet for Claude Desktop / Cursor
61
- npx webspresso mcp --print-config
62
- ```
63
-
64
- ### IDE Configuration
65
-
66
- Add to `claude_desktop_config.json` or `.cursor/mcp.json` or Antigravity IDE `mcp_config.json`:
67
-
68
- ```json
69
- {
70
- "mcpServers": {
71
- "my-webspresso-app": {
72
- "command": "npx",
73
- "args": ["webspresso", "mcp"]
74
- }
75
- }
76
- }
77
- ```
78
-
79
- ---
80
-
81
- ## 4. Custom Tools, Resources, and Prompts (`mcp/` folder)
82
-
83
- When `discovery: true` (default), Webspresso scans the project's `mcp/` directory:
84
-
85
- ```
86
- mcp/
87
- ├── tools/
88
- │ └── deploy_preview.js # exports { name, description, inputSchema, handler }
89
- ├── resources/
90
- │ └── docs.js # exports { uri, name, description, handler }
91
- └── prompts/
92
- └── review_code.js # exports { name, description, arguments, handler }
93
- ```
94
-
95
- ### Programmatic Registration via Runtime API
96
- ```javascript
97
- const mcp = app.usePlugin('mcp'); // or ctx.mcp inside plugins
98
- mcp.registerTool({
99
- name: 'custom_action',
100
- description: 'Does something custom',
101
- handler: async (args, ctx) => { ... },
102
- });
103
- ```
@@ -1,127 +0,0 @@
1
- # Cloud Metrics & Distributed Tracing Guide
2
-
3
- Webspresso provides an enterprise-grade, zero-dependency Cloud Metrics & Distributed Tracing engine (`core/metrics`) delivering Prometheus exposition format (`/metrics`), JSON telemetry (`/metrics.json`), HTTP latency histograms, and W3C/GCP/AWS distributed tracing header propagation.
4
-
5
- ---
6
-
7
- ## 🎯 Key Capabilities
8
-
9
- 1. **Prometheus-Compatible Exposition Format**:
10
- - Zero external dependencies (no `prom-client` or OpenTelemetry npm packages required).
11
- - Generates compliant `text/plain; version=0.0.4; charset=utf-8` output directly consumable by Prometheus, Grafana Agent, Google Cloud Managed Service for Prometheus, AWS CloudWatch Container Insights, and Datadog.
12
- - Dual-format exposition: `/metrics` for Prometheus scraping and `/metrics.json` (or `Accept: application/json`) for programmatic inspection or lightweight dashboards.
13
- 2. **Distributed Tracing & W3C Propagation**:
14
- - Parses incoming tracing headers automatically (`traceparent`, `x-cloud-trace-context`, `x-amzn-trace-id`, `x-request-id`).
15
- - Automatically injects `x-trace-id` and W3C `traceparent` (`00-${traceId}-${spanId}-01`) onto outgoing HTTP response headers.
16
- - Attaches `req.traceId` and `req.spanId` to the incoming request object for seamless correlation with `req.logger`.
17
- 3. **Core HTTP Request Telemetry**:
18
- - `webspresso_http_requests_total{method, route, status}`: Counter for all processed HTTP requests.
19
- - `webspresso_http_request_duration_seconds{method, route}`: Latency histogram with cumulative buckets, `_sum`, and `_count`.
20
- - `webspresso_http_active_requests`: Gauge tracking in-flight concurrent requests.
21
- - **Noise-free scraping**: Internal scrape calls to `/metrics`, `/metrics.json`, and `/healthz` are excluded from HTTP latency counters to prevent self-polluting metrics graphs.
22
- 4. **Automated Node.js & Framework Collectors**:
23
- - **Process & Memory**: `process_uptime_seconds`, `nodejs_heap_size_used_bytes`, `nodejs_heap_size_total_bytes`, `process_resident_memory_bytes`, `nodejs_external_memory_bytes`.
24
- - **CPU**: `process_cpu_user_seconds_total`, `process_cpu_system_seconds_total`.
25
- - **Event Loop Lag**: `nodejs_eventloop_lag_seconds{quantile="0.50|0.99|max"}` via native `perf_hooks.monitorEventLoopDelay`.
26
- - **Database Connection Pool**: `webspresso_db_pool_size`, `webspresso_db_pool_used`, `webspresso_db_pool_available` (Knex pool).
27
- - **In-Memory Cache**: `webspresso_cache_entries`, `webspresso_cache_bytes` (LRU cache).
28
- - **Circuit Breakers**: `webspresso_circuit_breaker_state{name}` (0=closed, 1=half-open, 2=open), `webspresso_circuit_breaker_failures_total{name}`.
29
- 5. **Security & Gating**:
30
- - Protect metrics endpoints with bearer token authentication (`auth: 'secret-token'`).
31
-
32
- ---
33
-
34
- ## 🚀 Configuration & Enabling Metrics
35
-
36
- ### 1. Enabling via `createApp`
37
-
38
- ```javascript
39
- const { createApp } = require('webspresso');
40
-
41
- const { app } = createApp({
42
- pagesDir: './pages',
43
- metrics: {
44
- enabled: true, // default: true if metrics option is passed
45
- path: '/metrics', // default: '/metrics'
46
- collectDefault: true, // default: true (system, memory, pool, cache, lag)
47
- traceHeader: true, // default: true (x-trace-id, traceparent)
48
- auth: process.env.METRICS_TOKEN || null, // Optional Bearer token protection
49
- buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
50
- },
51
- });
52
- ```
53
-
54
- Or enable with shorthand:
55
-
56
- ```javascript
57
- createApp({
58
- metrics: true, // mounts /metrics and /metrics.json with defaults
59
- });
60
- ```
61
-
62
- ---
63
-
64
- ## 📊 Custom Application Metrics
65
-
66
- Application routes, services, and plugins can register and record custom domain metrics via `app.metrics` or `req.metrics`:
67
-
68
- ```javascript
69
- // Register a custom counter
70
- const orderCounter = app.metrics.counter(
71
- 'shop_orders_placed_total',
72
- 'Total number of completed customer orders'
73
- );
74
-
75
- // Register a custom gauge
76
- const activeUsersGauge = app.metrics.gauge(
77
- 'shop_active_cart_sessions',
78
- 'Number of carts currently active'
79
- );
80
-
81
- // In an API handler
82
- // pages/api/checkout.post.js
83
- module.exports = defineApi({
84
- handler: async (req, res) => {
85
- const order = await req.service('order.create', req.body);
86
-
87
- // Increment domain metric
88
- orderCounter.inc({ plan: order.plan, currency: order.currency }, 1);
89
-
90
- return res.status(201).json(order);
91
- },
92
- });
93
- ```
94
-
95
- ---
96
-
97
- ## 🛡️ Standalone Registry Usage
98
-
99
- ```javascript
100
- const { createMetricsRegistry } = require('webspresso');
101
-
102
- const registry = createMetricsRegistry();
103
-
104
- const counter = registry.counter('jobs_processed_total', 'Jobs processed by worker');
105
- counter.inc({ queue: 'email', status: 'success' }, 1);
106
-
107
- const histogram = registry.histogram('job_execution_duration_seconds', 'Job execution duration', [0.1, 0.5, 1, 5]);
108
- histogram.observe({ queue: 'email' }, 0.24);
109
-
110
- // Format output
111
- console.log(registry.formatPrometheus());
112
- console.log(JSON.stringify(registry.formatJson(), null, 2));
113
- ```
114
-
115
- ---
116
-
117
- ## 📈 Prometheus Scrape Configuration (`prometheus.yml`)
118
-
119
- ```yaml
120
- scrape_configs:
121
- - job_name: 'webspresso-app'
122
- scrape_interval: 15s
123
- metrics_path: '/metrics'
124
- bearer_token: 'YOUR_METRICS_TOKEN' # if auth is enabled
125
- static_configs:
126
- - targets: ['localhost:3000']
127
- ```
@@ -1,95 +0,0 @@
1
- # Cloud Migration Jobs & Zero-Downtime Database Deploy Guide
2
-
3
- Webspresso provides an enterprise, zero-downtime database migration architecture designed specifically for Google Cloud Run, AWS ECS Fargate, AWS App Runner, and Kubernetes.
4
-
5
- ---
6
-
7
- ## 🎯 The Cloud Migration Challenge
8
-
9
- In containerized, autoscaling cloud platforms (such as Google Cloud Run or AWS ECS), running migrations inside the web application container startup command (`CMD ["node", "server.js"]`) causes severe production risks:
10
-
11
- 1. **Concurrent Migration Race Conditions**: If a new revision autoscales to multiple container instances, multiple containers attempt to run migrations simultaneously, causing deadlock or corrupt schema states.
12
- 2. **Crash Loops & Downtime**: If a migration script fails, web containers fail health checks and crash-loop, but HTTP traffic might already hit partially-migrated schemas.
13
- 3. **Stale Lock Hangs**: If a container is forcefully terminated by Cloud Run or ECS during migration, Knex's `knex_migrations_lock` table is left locked (`Migration table is already locked`), breaking all subsequent CI/CD deployments.
14
-
15
- ### The Webspresso Solution: Dedicated Pre-Deploy Cloud Migration Jobs
16
-
17
- Webspresso solves this by separating database schema migrations into a single, isolated pre-deploy job that runs to completion before new web service revisions receive traffic:
18
-
19
- ```
20
- [ Git Push / CI/CD ]
21
- │
22
- ▼
23
- [ Build Container Image ]
24
- │
25
- ▼
26
- [ Run Cloud Migration Job ] ──── (Fails? Stop deployment, keep old web version running)
27
- │ (Success)
28
- ▼
29
- [ Deploy Web Service Revision ] ─── (Safely route 100% traffic to new code)
30
- ```
31
-
32
- ---
33
-
34
- ## 🚀 CLI Commands
35
-
36
- ### 1. Scaffold Migration Jobs (`add:migration-job`)
37
-
38
- ```bash
39
- # For Google Cloud Run (cloudrun-job.yaml + deploy-cloudrun-migration.sh)
40
- npx webspresso add:migration-job --platform cloudrun --app my-app --cloudsql "project:region:instance"
41
-
42
- # For AWS ECS Fargate & App Runner (ecs-migration-task.json + deploy-aws-migration.sh)
43
- npx webspresso add:migration-job --platform aws --app my-app --region us-east-1
44
-
45
- # For Kubernetes / Helm (k8s/migration-job.yaml with pre-upgrade hooks)
46
- npx webspresso add:migration-job --platform k8s --app my-app
47
-
48
- # For all platforms
49
- npx webspresso add:migration-job --platform all
50
- ```
51
-
52
- ---
53
-
54
- ## ⚡ Cloud-Safe Migration Options (`db:migrate`)
55
-
56
- Webspresso's `db:migrate` command features cloud resilience flags powered by `core/orm/migrate-cloud.js`:
57
-
58
- ```bash
59
- # Cloud-Safe mode: exponential backoff connection retries + automatic stale lock auto-healing
60
- npx webspresso db:migrate --safe --env production
61
-
62
- # Dry-run: preview pending migrations without altering the database
63
- npx webspresso db:migrate --dry-run --env production
64
-
65
- # Auto-heal hanging locks left by aborted serverless jobs
66
- npx webspresso db:migrate --unlock-if-stale
67
-
68
- # Force unlock migration table immediately
69
- npx webspresso db:migrate --force-unlock
70
- ```
71
-
72
- ---
73
-
74
- ## 🛡️ Zero-Downtime Migration Rules for Schema Evolution
75
-
76
- When modifying production schemas under zero-downtime requirements, follow the **Expand and Contract (Parallel Run)** pattern:
77
-
78
- | Goal | ❌ Risky (Breaks running old version) | ✅ Zero-Downtime Pattern |
79
- | :--- | :--- | :--- |
80
- | **Rename Column** | `table.renameColumn('old', 'new')` | 1. Add `new` column<br>2. Dual-write in application<br>3. Backfill data<br>4. Drop `old` column in subsequent deploy |
81
- | **Drop Column** | `table.dropColumn('field')` | Remove column references in application code first, deploy code, then drop column in the next deployment. |
82
- | **Add NOT NULL** | `table.string('col').notNullable()` | 1. Add nullable column or column with default value<br>2. Backfill existing rows<br>3. Alter to `notNullable` |
83
- | **Add Index** | Raw `CREATE INDEX` (locks table) | In Postgres: use `CREATE INDEX CONCURRENTLY` |
84
-
85
- ---
86
-
87
- ## 🔍 Preflight Verification (`deploy:check`)
88
-
89
- Webspresso's preflight scanner automatically audits migration strategies:
90
-
91
- ```bash
92
- npx webspresso deploy:check --platform cloudrun --strict
93
- ```
94
-
95
- If migrations exist and no cloud migration job is detected, it emits an actionable warning to prevent production container race conditions.