millas 0.2.11 → 0.2.12-beta-1

package/src/http/UrlGenerator.js

@@ -0,0 +1,375 @@
+'use strict';
+
+/**
+ * UrlGenerator
+ *
+ * Laravel-like URL generation service.
+ * Registered in the container as 'url' by the framework after boot.
+ *
+ * Handles:
+ *   - Absolute and relative URL generation
+ *   - Named route URLs with parameter substitution
+ *   - Asset URLs
+ *   - Secure (HTTPS) URL forcing
+ *   - Query string appending
+ *   - Current / previous URL tracking (set by middleware)
+ *   - Signed URLs with expiry
+ */
+class UrlGenerator {
+  /**
+   * @param {object} options
+   * @param {string}          options.baseUrl        — e.g. 'http://localhost:3000'
+   * @param {RouteRegistry}   options.routeRegistry  — registered named routes
+   */
+  constructor(options = {}) {
+    this._baseUrl       = (options.baseUrl || '').replace(/\/$/, '');
+    this._routeRegistry = options.routeRegistry || null;
+    this._forcedScheme  = null;   // 'https' when forceHttps() is called
+    this._assetUrl      = null;   // separate CDN / asset origin
+    this._appKey        = options.appKey || process.env.APP_KEY || '';
+
+    // Set by RequestUrlMiddleware on each request
+    this._currentUrl    = null;
+    this._previousUrl   = null;
+  }
+
+  // ── Base URL ───────────────────────────────────────────────────────────────
+
+  /**
+   * The configured base URL of the application.
+   *   URL.base()  → 'https://myapp.com'
+   */
+  base() {
+    return this._resolveBase();
+  }
+
+  // ── URL generation ─────────────────────────────────────────────────────────
+
+  /**
+   * Generate an absolute URL for a path.
+   *
+   *   URL.to('/users')           → 'https://myapp.com/users'
+   *   URL.to('/users', { id: 1 })→ 'https://myapp.com/users?id=1'
+   *   URL.to('https://other.com')→ 'https://other.com'  (already absolute)
+   */
+  to(path, query = {}) {
+    if (this._isAbsolute(path)) return this._appendQuery(path, query);
+    const base = this._resolveBase();
+    const url  = base + '/' + path.replace(/^\//, '');
+    return this._appendQuery(url, query);
+  }
+
+  /**
+   * Generate a secure (HTTPS) URL for a path.
+   *
+   *   URL.secure('/login')  → 'https://myapp.com/login'
+   */
+  secure(path, query = {}) {
+    const url = this.to(path, query);
+    return url.replace(/^http:\/\//, 'https://');
+  }
+
+  /**
+   * Generate a relative URL (path only, no origin).
+   *
+   *   URL.relative('/users')    → '/users'
+   *   URL.relative('/users', { page: 2 }) → '/users?page=2'
+   */
+  relative(path, query = {}) {
+    const normalized = '/' + path.replace(/^\//, '');
+    return this._appendQuery(normalized, query);
+  }
+
+  // ── Named routes ───────────────────────────────────────────────────────────
+
+  /**
+   * Generate a URL for a named route, substituting parameters.
+   *
+   *   // Route: Route.get('/users/:id/posts/:postId', ...).name('users.posts.show')
+   *   URL.route('users.posts.show', { id: 1, postId: 42 })
+   *   → 'https://myapp.com/users/1/posts/42'
+   *
+   *   // Extra params become query string
+   *   URL.route('users.index', { page: 2, search: 'alice' })
+   *   → 'https://myapp.com/users?page=2&search=alice'
+   *
+   *   // Relative
+   *   URL.route('users.show', { id: 5 }, { absolute: false })
+   *   → '/users/5'
+   */
+  route(name, params = {}, options = {}) {
+    if (!this._routeRegistry) {
+      throw new Error('[URL] Route registry not available. Make sure the app is booted.');
+    }
+
+    const entry = this._routeRegistry.findByName(name);
+    if (!entry) {
+      throw new Error(`[URL] No route named "${name}".`);
+    }
+
+    const { path, query } = this._substituteParams(entry.path, params);
+    const absolute = options.absolute !== false;
+
+    if (!absolute) return this._appendQuery(path, query);
+    return this._appendQuery(this._resolveBase() + path, query);
+  }
+
+  // ── Assets ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Generate an asset URL (uses asset origin if configured, else base URL).
+   *
+   *   URL.asset('css/app.css')          → 'https://myapp.com/css/app.css'
+   *   URL.asset('images/logo.png')      → 'https://cdn.myapp.com/images/logo.png'
+   */
+  asset(path) {
+    const origin = this._assetUrl || this._resolveBase();
+    return origin.replace(/\/$/, '') + '/' + path.replace(/^\//, '');
+  }
+
+  /**
+   * Generate a secure asset URL.
+   */
+  secureAsset(path) {
+    return this.asset(path).replace(/^http:\/\//, 'https://');
+  }
+
+  // ── Current / previous ────────────────────────────────────────────────────
+
+  /**
+   * The full URL of the current request.
+   * Populated by the request context — null outside of a request.
+   */
+  current() {
+    return this._currentUrl;
+  }
+
+  /**
+   * The full URL of the previous request (from Referer header).
+   * Returns fallback if unavailable.
+   *
+   *   URL.previous()           → 'https://myapp.com/dashboard'
+   *   URL.previous('/')        → '/' if no previous URL
+   */
+  previous(fallback = '/') {
+    return this._previousUrl || this.to(fallback);
+  }
+
+  /**
+   * The path portion of the current URL (no origin).
+   */
+  currentPath() {
+    if (!this._currentUrl) return null;
+    try {
+      // If it's a full URL, extract pathname; otherwise treat as path directly
+      if (this._isAbsolute(this._currentUrl)) {
+        return new globalThis.URL(this._currentUrl).pathname;
+      }
+      return this._currentUrl.split('?')[0];
+    } catch {
+      return this._currentUrl;
+    }
+  }
+
+  // ── Signed URLs ────────────────────────────────────────────────────────────
+
+  /**
+   * Generate a signed URL that cannot be tampered with.
+   * Optionally expires after a given number of seconds.
+   *
+   *   URL.signedRoute('password.reset', { token }, 3600)
+   *   → 'https://myapp.com/password/reset?token=...&expires=...&signature=...'
+   */
+  signedRoute(name, params = {}, expiresIn = null) {
+    const base = this.route(name, params);
+    return this._sign(base, expiresIn);
+  }
+
+  /**
+   * Generate a signed URL for an arbitrary path.
+   *
+   *   URL.signedUrl('/download/file.pdf', 300)
+   */
+  signedUrl(path, expiresIn = null) {
+    const url = this.to(path);
+    return this._sign(url, expiresIn);
+  }
+
+  /**
+   * Verify that a signed URL is valid and has not expired.
+   * Returns true if valid, false otherwise.
+   *
+   *   URL.hasValidSignature(req)
+   */
+  hasValidSignature(req) {
+    const rawUrl = this.to(req.path || req.url || '', req.query || {});
+    return this._verifySignature(rawUrl);
+  }
+
+  // ── Scheme control ────────────────────────────────────────────────────────
+
+  /**
+   * Force all generated URLs to use HTTPS.
+   *   URL.forceHttps()
+   */
+  forceHttps(force = true) {
+    this._forcedScheme = force ? 'https' : null;
+    return this;
+  }
+
+  /**
+   * Force all generated URLs to use a specific scheme.
+   *   URL.forceScheme('https')
+   */
+  forceScheme(scheme) {
+    this._forcedScheme = scheme || null;
+    return this;
+  }
+
+  /**
+   * Set a separate origin for asset URLs (CDN, S3, etc.).
+   *   URL.useAssetOrigin('https://cdn.myapp.com')
+   */
+  useAssetOrigin(origin) {
+    this._assetUrl = origin ? origin.replace(/\/$/, '') : null;
+    return this;
+  }
+
+  // ── Introspection ──────────────────────────────────────────────────────────
+
+  /**
+   * Check whether a string is a valid absolute URL.
+   *   URL.isValid('https://example.com')  → true
+   *   URL.isValid('/relative/path')       → false
+   */
+  isValid(url) {
+    try { new URL(url); return true; } catch { return false; }
+  }
+
+  /**
+   * Check whether the current request URL matches a pattern.
+   * Supports * wildcards.
+   *
+   *   URL.is('/users/*')     → true on /users/1, /users/edit
+   *   URL.is('/users')       → true only on /users
+   */
+  is(...patterns) {
+    const path = this.currentPath() || '';
+    return patterns.some(pattern => {
+      const regex = new RegExp(
+        '^' + pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') + '$'
+      );
+      return regex.test(path);
+    });
+  }
+
+  // ── Internal: called by framework ─────────────────────────────────────────
+
+  /** Set by AppInitialiser / request middleware. @internal */
+  _setCurrentUrl(url)  { this._currentUrl  = url; }
+  _setPreviousUrl(url) { this._previousUrl = url; }
+
+  // ── Private ────────────────────────────────────────────────────────────────
+
+  _resolveBase() {
+    let base = process.env.APP_URL || this._baseUrl;
+
+    if (!base) {
+      const host   = process.env.MILLAS_HOST || 'localhost';
+      const port   = process.env.APP_PORT    || process.env.MILLAS_PORT || '3000';
+      const scheme = this._forcedScheme || 'http';
+      base = `${scheme}://${host}:${port}`;
+    }
+
+    if (this._forcedScheme) {
+      base = base.replace(/^https?:\/\//, `${this._forcedScheme}://`);
+    }
+
+    return base.replace(/\/$/, '');
+  }
+
+  _isAbsolute(url) {
+    return /^https?:\/\//.test(url);
+  }
+
+  _appendQuery(url, query = {}) {
+    const pairs = Object.entries(query).filter(([, v]) => v !== undefined && v !== null);
+    if (!pairs.length) return url;
+    const qs = new URLSearchParams(pairs).toString();
+    return url + (url.includes('?') ? '&' : '?') + qs;
+  }
+
+  /**
+   * Replace :param and {param} placeholders in a route path.
+   * Returns { path, query } where query holds leftover params.
+   */
+  _substituteParams(routePath, params) {
+    const remaining = { ...params };
+    let   path      = routePath;
+
+    // Replace :param and {param} style placeholders
+    path = path.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)\??|\{([a-zA-Z_][a-zA-Z0-9_]*)\??}/g, (_, p1, p2) => {
+      const key = p1 || p2;
+      if (key in remaining) {
+        const val = remaining[key];
+        delete remaining[key];
+        return encodeURIComponent(val);
+      }
+      return '';
+    });
+
+    // Remove any trailing slash left by optional segments
+    path = path.replace(/\/+$/, '') || '/';
+
+    return { path, query: remaining };
+  }
+
+  _sign(url, expiresIn) {
+    const crypto = require('crypto');
+    let   target = url;
+
+    if (expiresIn) {
+      const expires = Math.floor(Date.now() / 1000) + expiresIn;
+      target = this._appendQuery(url, { expires });
+    }
+
+    const signature = crypto
+      .createHmac('sha256', this._appKey)
+      .update(target)
+      .digest('hex')
+      .slice(0, 40);
+
+    return this._appendQuery(target, { signature });
+  }
+
+  _verifySignature(url) {
+    const crypto = require('crypto');
+    try {
+      const parsed    = new URL(url);
+      const signature = parsed.searchParams.get('signature');
+      const expires   = parsed.searchParams.get('expires');
+
+      if (!signature) return false;
+
+      if (expires && Math.floor(Date.now() / 1000) > Number(expires)) {
+        return false; // expired
+      }
+
+      // Reconstruct the URL without the signature param to re-sign
+      parsed.searchParams.delete('signature');
+      const unsigned = parsed.toString();
+
+      const expected = require('crypto')
+        .createHmac('sha256', this._appKey)
+        .update(unsigned)
+        .digest('hex')
+        .slice(0, 40);
+
+      return signature === expected;
+    } catch {
+      return false;
+    }
+  }
+}
+
+module.exports = UrlGenerator;

package/src/http/WelcomePage.js

@@ -0,0 +1,273 @@
+'use strict';
+
+/**
+ * WelcomePage
+ *
+ * Renders a branded welcome page when no GET / route is defined.
+ * Automatically removed once the developer registers their own / route.
+ *
+ * Only shown to browser requests (Accept: text/html).
+ * API clients always receive JSON.
+ */
+class WelcomePage {
+
+  /**
+   * Returns an Express middleware that serves the welcome page for GET /
+   * only when no user-defined route has been registered for that path.
+   *
+   * @param {string} version  — package version shown in the page
+   */
+  static handler(version = '') {
+    return function millaWelcome(req, res) {
+      const accept = req.headers?.accept || '';
+      const wantsHtml = accept.includes('text/html') && !accept.startsWith('application/json');
+
+      if (!wantsHtml) {
+        return res.json({
+          framework: 'Millas',
+          version,
+          message:   'Welcome to your Millas app. Define your routes in routes/api.js.',
+          docs:      'https://millas.dev/docs',
+        });
+      }
+
+      res.setHeader('Content-Type', 'text/html; charset=utf-8');
+      res.send(WelcomePage._render(version));
+    };
+  }
+
+  static _render(version) {
+    const ver = version ? `v${version}` : '';
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Welcome — Millas</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+    :root {
+      --orange:      #f97316;
+      --orange-dark: #ea580c;
+      --orange-dim:  #fff7ed;
+      --orange-mid:  #fed7aa;
+      --bg:          #fafafa;
+      --surface:     #ffffff;
+      --border:      #e5e7eb;
+      --text:        #111827;
+      --muted:       #6b7280;
+      --code-bg:     #fff7ed;
+      --code-fg:     #c2410c;
+    }
+
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --orange:      #fb923c;
+        --orange-dark: #f97316;
+        --orange-dim:  #1c0f00;
+        --orange-mid:  #7c2d12;
+        --bg:          #0c0c0c;
+        --surface:     #141414;
+        --border:      #262626;
+        --text:        #f5f5f5;
+        --muted:       #737373;
+        --code-bg:     #1a0e00;
+        --code-fg:     #fb923c;
+      }
+    }
+
+    body {
+      font-family: 'Segoe UI', system-ui, -apple-system, sans-serif;
+      background: var(--bg);
+      color: var(--text);
+      min-height: 100vh;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      padding: 40px 20px;
+    }
+
+    /* ── Logo mark ── */
+    .logo {
+      width: 64px;
+      height: 64px;
+      background: linear-gradient(135deg, var(--orange), var(--orange-dark));
+      border-radius: 18px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      margin-bottom: 28px;
+      box-shadow: 0 8px 32px color-mix(in srgb, var(--orange) 35%, transparent);
+    }
+    .logo svg { width: 34px; height: 34px; }
+
+    /* ── Card ── */
+    .card {
+      padding: 48px 52px;
+      max-width: 560px;
+      width: 100%;
+      text-align: center;
+    }
+
+    h1 {
+      font-size: 28px;
+      font-weight: 800;
+      letter-spacing: -.5px;
+      color: var(--text);
+      line-height: 1.2;
+    }
+    h1 span { color: var(--orange); }
+
+    .version {
+      display: inline-block;
+      margin-top: 10px;
+      background: var(--orange-dim);
+      color: var(--orange-dark);
+      border: 1px solid var(--orange-mid);
+      border-radius: 99px;
+      font-size: 12px;
+      font-weight: 600;
+      padding: 3px 12px;
+      font-family: 'Cascadia Code', 'Fira Code', monospace;
+    }
+
+    .tagline {
+      margin-top: 16px;
+      font-size: 15px;
+      color: var(--muted);
+      line-height: 1.6;
+    }
+
+    /* ── Divider ── */
+    .divider {
+      height: 1px;
+      background: var(--border);
+      margin: 32px 0;
+    }
+
+    /* ── Quickstart block ── */
+    .qs-label {
+      font-size: 11px;
+      font-weight: 700;
+      text-transform: uppercase;
+      letter-spacing: .8px;
+      color: var(--muted);
+      margin-bottom: 12px;
+    }
+
+    .code-block {
+      background: var(--code-bg);
+      border: 1px solid var(--orange-mid);
+      border-radius: 12px;
+      padding: 18px 20px;
+      text-align: left;
+      font-family: 'Cascadia Code', 'Fira Code', 'SF Mono', monospace;
+      font-size: 13px;
+      line-height: 1.9;
+      color: var(--code-fg);
+    }
+    .code-block .comment { color: var(--muted); font-style: italic; }
+    .code-block .kw      { color: var(--orange-dark); font-weight: 700; }
+    .code-block .str     { color: #16a34a; }
+
+    /* ── Links row ── */
+    .links {
+      margin-top: 28px;
+      display: flex;
+      justify-content: center;
+      gap: 12px;
+      flex-wrap: wrap;
+    }
+    .link {
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+      padding: 8px 18px;
+      border-radius: 99px;
+      font-size: 13px;
+      font-weight: 600;
+      text-decoration: none;
+      transition: opacity .15s;
+    }
+    .link:hover { opacity: .8; }
+    .link-primary {
+      background: linear-gradient(135deg, var(--orange), var(--orange-dark));
+      color: #fff;
+    }
+    .link-ghost {
+      background: var(--surface);
+      color: var(--text);
+      border: 1px solid var(--border);
+    }
+
+    /* ── Footer note ── */
+    .note {
+      margin-top: 36px;
+      font-size: 12px;
+      color: var(--muted);
+      line-height: 1.6;
+    }
+    .note strong { color: var(--orange); font-family: monospace; font-weight: 600; }
+  </style>
+</head>
+<body>
+
+  <div class="logo">
+    <!-- M lettermark -->
+    <svg viewBox="0 0 34 34" fill="none" xmlns="http://www.w3.org/2000/svg">
+      <path d="M4 27V7l13 13L30 7v20" stroke="#fff" stroke-width="3.5" stroke-linecap="round" stroke-linejoin="round"/>
+    </svg>
+  </div>
+
+  <div class="card">
+    <h1>Welcome to <span>Millas</span></h1>
+    ${ver ? `<div class="version">${_esc(ver)}</div>` : ''}
+
+    <p class="tagline">
+      Your app is running. Define your first route and this page will disappear.
+    </p>
+
+    <div class="divider"></div>
+
+    <div class="qs-label">Get started</div>
+    <div class="code-block">
+<span class="comment">// routes/api.js</span>
+<span class="kw">module</span>.exports = <span class="kw">function</span> (Route) {
+  Route.get(<span class="str">'/'</span>, () => ({
+    message: <span class="str">'Hello from Millas!'</span>
+  }));
+};
+    </div>
+
+    <div class="links">
+      <a class="link link-primary" href="https://id-preview--ae4ed87b-a9d5-434d-8559-1e8c30972a28.lovable.app" target="_blank">
+        📖 Documentation
+      </a>
+      <a class="link link-ghost" href="https://github.com/millas-framework/millas" target="_blank">
+        GitHub
+      </a>
+    </div>
+  </div>
+
+  <p class="note">
+    This page is shown because no route is registered for <strong>GET /</strong>.<br>
+    It will never appear in production to end users.
+  </p>
+
+</body>
+</html>`;
+  }
+}
+
+function _esc(str) {
+  return String(str ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+module.exports = WelcomePage;