webspresso 0.0.90 → 0.0.91

package/README.md

@@ -1244,6 +1244,82 @@ The SEO Checker panel appears as a floating widget and can be opened via:
 - Dev toolbar "SEO Check" button
 - Floating toggle button (🔍) in bottom-right corner
 
+**Basic Auth Plugin:**
+- Zero-dependency HTTP Basic Authentication (RFC 7617) with timing-safe password verification (`crypto.timingSafeEqual`).
+- Can protect the entire application globally or expose named route middleware (`middleware: ['basicAuth']`).
+
+```javascript
+const { basicAuthPlugin } = require('webspresso/plugins');
+
+const { app } = createApp({
+  pagesDir: './pages',
+  plugins: [
+    basicAuthPlugin({
+      global: false, // Set to true to protect the whole app
+      users: {
+        admin: 'supersecret',
+      },
+      realm: 'Protected Area',
+    }),
+  ],
+});
+```
+
+**Realtime Layer & Plugin:**
+- Framework-agnostic, plugin-based, and adapter-supported realtime layer (`core/realtime` and `plugins/realtime`).
+- Adapters for **Generic WebSocket**, **SSE (Server-Sent Events)**, and **Socket.IO**.
+- Universal API for browsers and SSR safety (never initializes network connections during server-side rendering).
+- Built-in exponential backoff reconnection with jitter, multi-strategy authentication (token, cookie, custom), auto-recovery of subscriptions on reconnect, and token sanitization.
+
+```javascript
+const { createApp } = require('webspresso');
+const { realtimePlugin, websocket } = require('webspresso/plugins');
+
+// 1. App Plugin Setup
+const { app } = createApp({
+  plugins: [
+    realtimePlugin({
+      adapter: websocket({ url: '/realtime' }),
+      auth: { strategy: 'cookie' },
+      autoConnect: true,
+    }),
+  ],
+});
+
+// 2. Subscription & RPC
+const sub = app.realtime.subscribe('project:123', { role: 'editor' }, {
+  connected() {
+    console.log('Connected to project:123');
+  },
+  received(data) {
+    console.log('Live message:', data);
+  },
+});
+
+sub.perform('user_typing', { userId: 42, isTyping: true });
+sub.send({ text: 'Hello team!' });
+
+// 3. Standalone Client Usage (with Token Auth & Refresh)
+const { realtime, websocket } = require('webspresso');
+
+const client = realtime({
+  adapter: websocket({ url: 'wss://api.example.com/realtime' }),
+  auth: {
+    strategy: 'token',
+    getToken: async () => localStorage.getItem('token'),
+    refreshToken: async () => {
+      const res = await fetch('/api/auth/refresh', { method: 'POST' });
+      const { token } = await res.json();
+      localStorage.setItem('token', token);
+      return token;
+    },
+    onUnauthorized: (err) => {
+      window.location.href = '/login';
+    },
+  },
+});
+```
+
 ### Creating Custom Plugins
 
 ```javascript
@@ -1584,31 +1660,87 @@ module.exports = {
 };
 ```
 
-## i18n
+## i18n & Localization
 
-### Global Translations
+Webspresso features a zero-dependency, ultra-fast internationalization engine built directly on native Node.js `Intl` APIs (`Intl.PluralRules`, `Intl.NumberFormat`, `Intl.DateTimeFormat`, `Intl.RelativeTimeFormat`).
 
-Add JSON files to `pages/locales/`:
+### 1. Global & Route-Specific Translations
+
+Add JSON files to `pages/locales/` for global dictionary entries, or inside any route directory `pages/catalog/locales/` for route-specific overrides:
 
 ```json
+// pages/locales/en.json
 {
   "nav": {
     "home": "Home",
     "about": "About"
+  },
+  "cart": {
+    "zero": "Your cart is empty",
+    "one": "You have 1 item in your cart",
+    "other": "You have {{count}} items in your cart"
   }
 }
 ```
 
-### Route-Specific Translations
+### 2. Basic Translation & Interpolation
+
+```nunjucks
+{# Direct function call #}
+<h1>{{ t('nav.home') }}</h1>
+
+{# With parameter interpolation #}
+<p>{{ t('welcome', { name: currentUser.username }) }}</p>
 
-Add a `locales/` folder inside any route directory to override global translations.
+{# With Nunjucks filter #}
+<h1>{{ 'nav.home' | t }}</h1>
+<p>{{ 'welcome' | t({ name: currentUser.username }) }}</p>
+```
 
-### Using Translations
+### 3. Native Pluralization (`Intl.PluralRules`)
 
-In templates:
+Pass `count` (or `n`, `cardinal`) to automatically select the correct CLDR plural category (`zero`, `one`, `two`, `few`, `many`, `other`) or exact number (`0`, `1`):
 
 ```nunjucks
-<h1>{{ t('nav.home') }}</h1>
+<p>{{ t('cart', { count: cart.items.length }) }}</p>
+```
+
+You can also use the inline `t.plural()` helper:
+```nunjucks
+<p>{{ t.plural(items.length, { one: '1 item', other: '{{count}} items' }) }}</p>
+```
+
+### 4. Fallback Locales Chain
+
+If a translation key is missing in the requested locale (e.g. `tr`), Webspresso automatically falls back to `DEFAULT_LOCALE` (default: `en`) before returning the key name or default fallback value. Check key existence with `t.has('key')` or `t.exists('key')`.
+
+### 5. Built-in `Intl` Formatters on `t`
+
+Format numbers, currencies, dates, and relative times according to the active locale without external date/number libraries:
+
+```nunjucks
+{# Numbers #}
+<span>{{ t.number(1234567.89) }}</span> {# TR: 1.234.567,89 | EN: 1,234,567.89 #}
+
+{# Currencies #}
+<span>{{ t.currency(199.99, 'TRY') }}</span> {# ₺199,99 #}
+<span>{{ t.currency(49.99, 'USD') }}</span>  {# $49.99 #}
+
+{# Dates #}
+<span>{{ t.date(post.created_at, { dateStyle: 'long' }) }}</span>
+
+{# Relative Time #}
+<span>{{ t.relativeTime(-2, 'day') }}</span> {# "2 days ago" or "2 gün önce" #}
+```
+
+### 6. Language Switcher Helpers
+
+Use `fsy.localeUrl(targetLocale)` to generate a URL with the current page path and query parameters preserved:
+
+```nunjucks
+<a href="{{ fsy.localeUrl('en') }}">English</a>
+<a href="{{ fsy.localeUrl('tr') }}">Türkçe</a>
+<a href="{{ fsy.localeUrl('de') }}">Deutsch</a>
 ```
 
 ## Template Helpers
@@ -1682,6 +1814,224 @@ module.exports = {
 10. Nunjucks render
 11. Route `afterRender`
 
+## Services Layer
+
+Webspresso includes a lightweight, framework-agnostic **Services Layer** to organize reusable business logic, query flows, and multi-step mutations under `services/`.
+
+Services are automatically discovered from the filesystem and can be invoked from SSR data loaders (`ctx.service()`), API routes (`req.service()`), background jobs, cron, CLI tasks, or other services.
+
+### 1. File Structure & Service Names
+
+Files inside `services/` map directly to dot-separated service names:
+
+```text
+services/
+  user/
+    get.js           → user.get
+    create.js        → user.create
+    profile/
+      get.js         → user.profile.get
+  post/
+    publish.js       → post.publish
+    listByUser.js    → post.listByUser
+  payment/
+    refund.js        → payment.refund
+```
+
+### 2. Service Definition
+
+Services export a handler and an optional input validation schema:
+
+```javascript
+// services/user/get.js
+module.exports = {
+  schema: {
+    id: 'number',
+  },
+
+  async handler({ id }, ctx) {
+    return ctx.db.users.findById(id);
+  },
+};
+```
+
+You can also use the `defineService` helper:
+
+```javascript
+// services/payment/refund.js
+const { defineService } = require('webspresso');
+
+module.exports = defineService({
+  // Zod functional schema syntax ({ z }) with built-in nanoid support
+  schema: ({ z }) => z.object({
+    transactionId: z.string().min(3),
+    amount: z.number().positive(),
+    reason: z.string().optional(),
+  }),
+
+  async handler({ transactionId, amount, reason }, ctx) {
+    // Process refund logic...
+    return { refundId: 'ref_123', transactionId, amount, status: 'succeeded' };
+  },
+});
+```
+
+### 3. Service-to-Service Composition
+
+Services can seamlessly call other services via `ctx.service()` while sharing the exact same request context (`ctx.db`, `ctx.auth`, `ctx.session`, `ctx.user`):
+
+```javascript
+// services/post/publish.js
+module.exports = {
+  schema: ({ z }) => z.object({
+    title: z.string(),
+    authorId: z.number(),
+  }),
+
+  async handler({ title, authorId }, ctx) {
+    const author = await ctx.service('user.get', { id: authorId });
+
+    return ctx.db.posts.create({
+      title,
+      author_id: author.id,
+      published_at: new Date(),
+    });
+  },
+};
+```
+
+> **Circular Call Protection**: Webspresso automatically tracks service call stacks and detects recursive/circular dependencies (e.g. `user.get -> profile.get -> user.get`), throwing an informative `Circular service call detected` error.
+
+### 4. Invoking from SSR & API Routes
+
+In SSR page data loaders (`pages/users/[id].njk`):
+
+```javascript
+// pages/users/[id].js
+module.exports = {
+  async load(req, ctx) {
+    const user = await ctx.service('user.get', { id: Number(req.params.id) });
+    return { user };
+  },
+};
+```
+
+In API routes or Express middleware:
+
+```javascript
+// pages/api/users.post.js
+module.exports = async function(req, res) {
+  const user = await req.service('user.create', req.body);
+  res.status(201).json(user);
+};
+```
+
+### 5. Service Caching & Memoization (`cache: '5m'`)
+
+Services can be cached in-memory with automatic TTL expiration and deterministic key serialization:
+
+```javascript
+// services/product/stats.js
+module.exports = {
+  // Cache result for 5 minutes based on input arguments
+  cache: '5m', // supports '30s', '5m', '1h', '1d', ms numbers, or { ttl: '5m', key: (input) => input.id }
+
+  async handler({ productId }, ctx) {
+    return ctx.db.stats.getProductStats(productId);
+  },
+};
+```
+
+You can invalidate cache keys explicitly on mutations:
+
+```javascript
+// From any service or route:
+ctx.service.invalidate('product.stats', { productId: 42 });
+
+// Or clear all cached entries for a service:
+ctx.service.clearCache('product.stats');
+```
+
+You can also use `memoize` as a standalone utility for any async function:
+
+```javascript
+const { memoize } = require('webspresso');
+
+const fetchRemoteRates = memoize(async () => {
+  return fetchExchangeRates();
+}, { ttl: '10m', maxSize: 100 });
+```
+
+### 6. Timeouts & Database Transactions (`timeout`, `transaction`)
+
+You can protect services against hanging handlers and ensure automatic ACID transaction rollbacks:
+
+```javascript
+// services/order/checkout.js
+module.exports = {
+  // Abort with 504 Gateway Timeout if execution exceeds 5 seconds
+  timeout: '5s',
+
+  // Wrap execution in an automatic Knex transaction (rolls back on any error)
+  transaction: true,
+
+  async handler({ orderId, items }, ctx) {
+    // ctx.trx and ctx.db are automatically bound to the active transaction
+    await ctx.db('orders').where({ id: orderId }).update({ status: 'paid' });
+    await ctx.service('inventory.deduct', { items }); // Nested services reuse the exact same transaction!
+
+    return { orderId, success: true };
+  },
+};
+```
+
+### 7. Authorization & Role Guards (`auth`)
+
+Services can enforce authentication and role-based access control (RBAC) automatically:
+
+```javascript
+// services/admin/billing.js
+module.exports = {
+  // Requires authenticated user with 'admin' or 'finance' role
+  auth: ['admin', 'finance'], // or auth: true (any logged in user) or auth: (user, ctx) => boolean
+
+  async handler(input, ctx) {
+    // Guaranteed to have authorized ctx.user
+    return ctx.db('billing_records').select();
+  },
+};
+```
+
+Throws `UnauthorizedError` (401) when unauthenticated or `ForbiddenError` (403) when role permissions are insufficient.
+
+### 8. Interactive CLI Runner (`webspresso service`)
+
+You can test and run any service directly from the command line without starting the HTTP server:
+
+```bash
+# Interactive selection & prompt mode
+npx webspresso service
+
+# Run a specific service with JSON payload
+npx webspresso service user.get -i '{"id": 42}'
+
+# Run with key=value query string
+npx webspresso service payment.refund -i 'transactionId=tx_123 amount=49.99'
+```
+
+### 7. Programmatic Usage & Testing
+
+You can execute services directly in unit tests or background scripts:
+
+```javascript
+const { createServiceRegistry } = require('webspresso');
+
+const services = createServiceRegistry({ servicesDir: './services' });
+const user = await services.call('user.get', { id: 42 }, { db: mockDb });
+```
+
+---
+
 ## Environment Variables
 
 | Variable | Default | Description |

package/bin/commands/service.js

@@ -0,0 +1,193 @@
+/**
+ * Webspresso CLI: Service Command
+ * Run and test services interactively without starting the HTTP server
+ * @module bin/commands/service
+ */
+
+const path = require('path');
+const inquirer = require('inquirer');
+const { createServiceRegistry } = require('../../src/services');
+const { resolveDbConfigIfExists, createDbInstance } = require('../utils/db');
+
+/**
+ * Parse input string into an object
+ * @param {string} inputStr
+ * @returns {*}
+ */
+function parseInputPayload(inputStr) {
+  if (!inputStr || typeof inputStr !== 'string') {
+    return {};
+  }
+
+  const trimmed = inputStr.trim();
+  if (!trimmed) return {};
+
+  // Try JSON first
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+    try {
+      return JSON.parse(trimmed);
+    } catch (e) {
+      throw new Error(`Invalid JSON input: ${e.message}`);
+    }
+  }
+
+  // Try key=value pairs (e.g. "id=42 name=Alice" or "id=42&name=Alice")
+  const result = {};
+  const pairs = trimmed.includes('&') ? trimmed.split('&') : trimmed.split(/\s+/);
+
+  for (const pair of pairs) {
+    if (!pair.includes('=')) continue;
+    const [rawKey, ...valParts] = pair.split('=');
+    const key = rawKey.trim();
+    const val = valParts.join('=').trim();
+
+    // Auto coerce simple types
+    if (val === 'true') result[key] = true;
+    else if (val === 'false') result[key] = false;
+    else if (val === 'null') result[key] = null;
+    else if (!Number.isNaN(Number(val)) && val !== '') result[key] = Number(val);
+    else result[key] = val;
+  }
+
+  return Object.keys(result).length > 0 ? result : trimmed;
+}
+
+function registerCommand(program) {
+  program
+    .command('service [name]')
+    .alias('service:run')
+    .alias('service:call')
+    .description('Run and test services interactively without starting the HTTP server')
+    .option('-i, --input <payload>', 'Input payload as JSON string or key=val pairs')
+    .option('-d, --dir <path>', 'Path to services directory (default: ./services)')
+    .option('-c, --config <path>', 'Path to database config file (optional)')
+    .option('-E, --env <environment>', 'Environment (development, production)', 'development')
+    .action(async (nameArg, options) => {
+      let db = null;
+      try {
+        const servicesDir = options.dir
+          ? path.resolve(process.cwd(), options.dir)
+          : path.resolve(process.cwd(), 'services');
+
+        const registry = createServiceRegistry({
+          servicesDir,
+          isDev: true,
+        });
+
+        const serviceNames = registry.list();
+
+        if (serviceNames.length === 0) {
+          console.log(`\n⚠️  No services found in "${path.relative(process.cwd(), servicesDir) || '.'}".`);
+          console.log('   Create your first service file in services/user/get.js\n');
+          return;
+        }
+
+        let serviceName = nameArg;
+
+        // Interactive Service Selection if not provided
+        if (!serviceName) {
+          console.log(`\n⚡ Discovered ${serviceNames.length} service(s) in ${path.relative(process.cwd(), servicesDir) || 'services/'}:\n`);
+
+          const answer = await inquirer.prompt([
+            {
+              type: 'list',
+              name: 'selectedService',
+              message: 'Select a service to execute:',
+              choices: serviceNames.map((name) => {
+                const def = registry.get(name);
+                const hasSchema = !!def?.schema;
+                return {
+                  name: `${name.padEnd(25)} ${hasSchema ? '📋 (has schema)' : ''}`,
+                  value: name,
+                };
+              }),
+            },
+          ]);
+
+          serviceName = answer.selectedService;
+        }
+
+        if (!registry.has(serviceName)) {
+          console.error(`\n❌ Error: Service "${serviceName}" not found.`);
+          console.log(`   Available services: ${serviceNames.join(', ')}\n`);
+          process.exit(1);
+        }
+
+        const serviceDef = registry.get(serviceName);
+
+        // Input gathering
+        let input = {};
+        if (options.input) {
+          input = parseInputPayload(options.input);
+        } else {
+          console.log(`\n⚙️  Target: \x1b[36m${serviceName}\x1b[0m (${serviceDef.filePath ? path.relative(process.cwd(), serviceDef.filePath) : 'in-memory'})`);
+
+          const inputAnswer = await inquirer.prompt([
+            {
+              type: 'input',
+              name: 'rawInput',
+              message: 'Enter input (JSON or key=val pairs, leave empty for {}):',
+              default: '{}',
+            },
+          ]);
+
+          input = parseInputPayload(inputAnswer.rawInput);
+        }
+
+        // Initialize DB if config exists
+        const dbConfigResult = resolveDbConfigIfExists(options.config);
+        if (dbConfigResult) {
+          try {
+            db = await createDbInstance(dbConfigResult.config, options.env);
+          } catch (dbErr) {
+            console.warn(`\n⚠️  Could not connect to database: ${dbErr.message}`);
+          }
+        }
+
+        const ctx = {
+          db,
+          user: { id: 1, role: 'admin', email: 'cli-admin@webspresso.local' },
+          logger: console,
+        };
+
+        console.log(`\n🚀 Executing \x1b[36m${serviceName}\x1b[0m with input:`, JSON.stringify(input));
+        const startTime = Date.now();
+
+        try {
+          const result = await registry.call(serviceName, input, ctx);
+          const duration = Date.now() - startTime;
+
+          console.log(`\n✅ \x1b[32mExecution succeeded (${duration}ms)\x1b[0m\n`);
+          console.log(JSON.stringify(result, null, 2));
+          console.log('');
+        } catch (execErr) {
+          const duration = Date.now() - startTime;
+          console.error(`\n❌ \x1b[31mExecution failed (${duration}ms): ${execErr.message}\x1b[0m\n`);
+
+          if (execErr.fields) {
+            console.error('Validation Details:');
+            for (const [f, msg] of Object.entries(execErr.fields)) {
+              console.error(`  - ${f}: ${msg}`);
+            }
+            console.error('');
+          } else if (execErr.stack) {
+            console.error(execErr.stack);
+            console.error('');
+          }
+          process.exitCode = 1;
+        }
+      } catch (err) {
+        console.error(`\n❌ CLI Error: ${err.message}\n`);
+        process.exitCode = 1;
+      } finally {
+        if (db && typeof db.destroy === 'function') {
+          await db.destroy();
+        }
+      }
+    });
+}
+
+module.exports = {
+  registerCommand,
+  parseInputPayload,
+};

package/bin/webspresso.js

@@ -33,6 +33,7 @@ const { registerCommand: registerDoctor } = require('./commands/doctor');
 const { registerCommand: registerSkill } = require('./commands/skill');
 const { registerCommand: registerUpgrade } = require('./commands/upgrade');
 const { registerCommand: registerOrmMap } = require('./commands/orm-map');
+const { registerCommand: registerService } = require('./commands/service');
 
 registerNew(program);
 registerPage(program);
@@ -54,6 +55,7 @@ registerDoctor(program);
 registerSkill(program);
 registerUpgrade(program);
 registerOrmMap(program);
+registerService(program);
 
 // Parse arguments
 program.parse();

package/core/auth/middleware.js

@@ -17,6 +17,15 @@ function createAuthMiddleware(authManager) {
 
   const sessionConfig = authManager.getSessionConfig();
 
+  if (!sessionConfig.store && process.env.NODE_ENV === 'production') {
+    const warnMsg = '[webspresso:auth] Warning: Default MemoryStore is being used in production. It is not designed for production environments and will leak memory under high load. Please configure a persistent session store (e.g. Knex or Redis).';
+    if (typeof process !== 'undefined' && typeof process.emitWarning === 'function') {
+      process.emitWarning(warnMsg, 'SecurityWarning');
+    } else {
+      console.warn(warnMsg);
+    }
+  }
+
   /**
    * Session middleware
    * Sets up express-session with secure cookie enforcement

package/core/compression/compressible.js

@@ -0,0 +1,51 @@
+/**
+ * Content-Type Compressibility Filter
+ * Determines if a given MIME type benefits from HTTP compression.
+ * @module core/compression/compressible
+ */
+
+// Regex patterns for MIME types that benefit from compression
+const COMPRESSIBLE_TYPE_REGEX = /^(?:text\/[a-z0-9.+_-]+|application\/(?:javascript|x-javascript|json|ld\+json|manifest\+json|graphql\+json|geo\+json|xml|atom\+xml|rss\+xml|xhtml\+xml|x-yaml|yaml|vnd\.api\+json|schema\+json|hal\+json)|image\/svg\+xml)$/i;
+
+// Regex patterns for already-compressed or non-compressible types
+const INCOMPRESSIBLE_TYPE_REGEX = /^(?:image\/(?:jpeg|png|gif|webp|avif|heic|heif)|video\/[a-z0-9.+_-]+|audio\/[a-z0-9.+_-]+|application\/(?:zip|gzip|x-gzip|x-bzip2|x-compress|x-7z-compressed|x-rar-compressed|pdf|wasm|octet-stream))$/i;
+
+/**
+ * Determine if a Content-Type is compressible
+ * @param {string|undefined|null} contentType - Raw Content-Type header (e.g. 'text/html; charset=utf-8')
+ * @returns {boolean}
+ */
+function isCompressible(contentType) {
+  if (!contentType || typeof contentType !== 'string') {
+    return false;
+  }
+
+  // Extract base MIME type (strip parameters like ; charset=utf-8)
+  const semiIndex = contentType.indexOf(';');
+  const mime = (semiIndex !== -1 ? contentType.slice(0, semiIndex) : contentType).trim().toLowerCase();
+
+  if (!mime) {
+    return false;
+  }
+
+  // Fast negative check
+  if (INCOMPRESSIBLE_TYPE_REGEX.test(mime)) {
+    return false;
+  }
+
+  // Check compressible match
+  if (COMPRESSIBLE_TYPE_REGEX.test(mime)) {
+    return true;
+  }
+
+  // General text or suffix match (+json, +xml, +yaml)
+  if (mime.startsWith('text/') || mime.endsWith('+json') || mime.endsWith('+xml') || mime.endsWith('+yaml')) {
+    return true;
+  }
+
+  return false;
+}
+
+module.exports = {
+  isCompressible,
+};