@ti-engine/web-framework 1.19.0 → 1.20.0

package/README.md

@@ -1,74 +1,74 @@
-# ti-engine web framework
-
-![Logo](https://raw.githubusercontent.com/Belleal/ti-engine/master/packages/core/docs/ti-engine-icon.ico)
-
-Flexible framework for the creation of microservices with node.js.
-
-## Information
-
-This is a customizable web framework based on the **ti-engine** framework. Currently under development.
-
-## Environment variables
-
-The web server configuration (host, port, TLS, cookies, etc.) is normally provided via the service configuration file merged in the `TiWebServer` constructor. The following environment variables can override individual values at runtime — useful for container/12-factor deployments where the same image is configured per environment:
-
-* `TI_WEB_HOST` overrides the bind address (e.g. `0.0.0.0` in a container). Defaults to the value in the web server config.
-* `TI_WEB_PORT` overrides the listen port.
-* `TI_WEB_USE_TLS` (`true`/`false`) toggles in-app TLS. Set `false` when a reverse proxy / ingress terminates TLS.
-* `TI_WEB_TLS_CERT_PATH` / `TI_WEB_TLS_KEY_PATH` override the TLS certificate/key paths (only used when TLS is enabled).
-* `TI_WEB_COOKIE_SECRET` sets the session cookie signing secret. Set a stable, private value for durable sessions and multi-replica deployments (otherwise a random per-process value is used).
-* `TI_WEB_AUTH_METHODS` (comma-separated) **replaces** the enabled authentication methods (`auth.enabledMethods`), e.g. `openid-google` or `local,openid-google`.
-* `TI_WEB_AUTH_ADMINS` (comma-separated) **replaces** the admin allowlist (`auth.admins`). Entries are matched against the session user's user ID, username or email, so an OpenID deployment lists emails. An explicitly empty value means *no admins*.
-* `TI_WEB_TRUSTED_ORIGINS` (comma-separated) **replaces** the trusted request origins (`trustedOrigins`) — needed behind proxies that do not present the real external origin.
-* `TI_WEB_STATIC_MAX_AGE` (whole seconds) overrides `staticCache.maxAge`. See [Static asset caching](#static-asset-caching).
-* `TI_WEB_STATIC_IMMUTABLE` (`true`/`false`) overrides `staticCache.immutable`.
-* `TI_WEB_STATIC_IMMUTABLE_PATHS` (comma-separated) **replaces** `staticCache.immutablePaths`. An explicitly empty value means *no long-lived paths*.
-
-OpenID Connect providers are configured with their own variables — `TI_AZURE_AUTH_CLIENT_ID` / `TI_AZURE_AUTH_CLIENT_SECRET` / `TI_AZURE_AUTH_CALLBACK_URL` / `TI_AZURE_AUTH_DISCOVERY_URL`, and the `TI_GCLOUD_AUTH_*` equivalents. A callback URL may be given either as the full absolute URL registered with the provider (`https://your-host/login/azure-callback`) or as a path (`/login/azure-callback`): the server always listens on the path, while the `redirect_uri` sent to the provider is the absolute value verbatim if one was configured, and otherwise assembled from the request's forwarded protocol/host.
-
-## Static asset caching
-
-Everything under `/static` is served with a `Cache-Control` policy configured by the `staticCache` block:
-
-```json
-{
-  "staticCache": {
-    "maxAge": 0,
-    "immutable": false,
-    "immutablePaths": [ "/fonts/" ]
-  }
-}
-```
-
-* `maxAge` — the `max-age` in **whole seconds** (not an express-style `"1y"` duration string; one is rejected with a warning rather than reinterpreted as milliseconds). `0`, the default, emits `public, max-age=0, must-revalidate`.
-* `immutable` — adds the `immutable` directive. Defaults to `false`, and is **ignored with a warning when `maxAge` is 0**, since a response that is stale on arrival cannot also promise never to change.
-* `immutablePaths` — path prefixes under `/static` (matched case-sensitively, on a path-segment boundary) served `public, max-age=31536000, immutable` regardless of the two settings above. Defaults to `[ "/fonts/" ]`. This **replaces** rather than merges, so `[]` means no long-lived paths.
-
-**The default revalidates, and that is deliberate.** `immutable` tells a browser the bytes behind a URL will never change, and browsers honour it so completely that not even a manual reload revalidates. On a stable filename — which is what the framework's own assets use (`/static/scripts/ti-framework.js`, the theme sheets) — the promise is false, and a deployed CSS or JS fix simply never reaches anyone who has already visited, for up to a year, with no way to tell them otherwise. Revalidating costs a conditional request per asset, answered with a `304` from the `ETag`/`Last-Modified` that `express.static` still attaches — headers, no body.
-
-**Opt back into `immutable` once your filenames are content-addressed.** If your build emits `app.a1b2c3.css`, or your application appends a content hash to each asset URL, the promise becomes true and there is real value in making it:
-
-```json
-{
-  "staticCache": { "maxAge": 31536000, "immutable": true }
-}
-```
-
-Fonts are the default exception because a released `.woff2` is an artifact rather than something edited in place, and its filename already carries the family, weight and style. If that is not how a given deployment manages its fonts, clear the list.
-
-## Configure HTTPS for development
-
-Use the `mkcert` tool to create a certificate for development.
-
-Step 1: Install the tool:
-```text
-choco install mkcert
-```
-Step 2: Install certificate authority:
-```text
-mkcert -install
-```
-Step 3: Generate certificate files for localhost:
-```text
-mkcert localhost 127.0.0.1 ::1
+# ti-engine web framework
+
+![Logo](https://raw.githubusercontent.com/Belleal/ti-engine/master/packages/core/docs/ti-engine-icon.ico)
+
+Flexible framework for the creation of microservices with node.js.
+
+## Information
+
+This is a customizable web framework based on the **ti-engine** framework. Currently under development.
+
+## Environment variables
+
+The web server configuration (host, port, TLS, cookies, etc.) is normally provided via the service configuration file merged in the `TiWebServer` constructor. The following environment variables can override individual values at runtime — useful for container/12-factor deployments where the same image is configured per environment:
+
+* `TI_WEB_HOST` overrides the bind address (e.g. `0.0.0.0` in a container). Defaults to the value in the web server config.
+* `TI_WEB_PORT` overrides the listen port.
+* `TI_WEB_USE_TLS` (`true`/`false`) toggles in-app TLS. Set `false` when a reverse proxy / ingress terminates TLS.
+* `TI_WEB_TLS_CERT_PATH` / `TI_WEB_TLS_KEY_PATH` override the TLS certificate/key paths (only used when TLS is enabled).
+* `TI_WEB_COOKIE_SECRET` sets the session cookie signing secret. Set a stable, private value for durable sessions and multi-replica deployments (otherwise a random per-process value is used).
+* `TI_WEB_AUTH_METHODS` (comma-separated) **replaces** the enabled authentication methods (`auth.enabledMethods`), e.g. `openid-google` or `local,openid-google`.
+* `TI_WEB_AUTH_ADMINS` (comma-separated) **replaces** the admin allowlist (`auth.admins`). Entries are matched against the session user's user ID, username or email, so an OpenID deployment lists emails. An explicitly empty value means *no admins*.
+* `TI_WEB_TRUSTED_ORIGINS` (comma-separated) **replaces** the trusted request origins (`trustedOrigins`) — needed behind proxies that do not present the real external origin.
+* `TI_WEB_STATIC_MAX_AGE` (whole seconds) overrides `staticCache.maxAge`. See [Static asset caching](#static-asset-caching).
+* `TI_WEB_STATIC_IMMUTABLE` (`true`/`false`) overrides `staticCache.immutable`.
+* `TI_WEB_STATIC_IMMUTABLE_PATHS` (comma-separated) **replaces** `staticCache.immutablePaths`. An explicitly empty value means *no long-lived paths*.
+
+OpenID Connect providers are configured with their own variables — `TI_AZURE_AUTH_CLIENT_ID` / `TI_AZURE_AUTH_CLIENT_SECRET` / `TI_AZURE_AUTH_CALLBACK_URL` / `TI_AZURE_AUTH_DISCOVERY_URL`, and the `TI_GCLOUD_AUTH_*` equivalents. A callback URL may be given either as the full absolute URL registered with the provider (`https://your-host/login/azure-callback`) or as a path (`/login/azure-callback`): the server always listens on the path, while the `redirect_uri` sent to the provider is the absolute value verbatim if one was configured, and otherwise assembled from the request's forwarded protocol/host.
+
+## Static asset caching
+
+Everything under `/static` is served with a `Cache-Control` policy configured by the `staticCache` block:
+
+```json
+{
+  "staticCache": {
+    "maxAge": 0,
+    "immutable": false,
+    "immutablePaths": [ "/fonts/" ]
+  }
+}
+```
+
+* `maxAge` — the `max-age` in **whole seconds** (not an express-style `"1y"` duration string; one is rejected with a warning rather than reinterpreted as milliseconds). `0`, the default, emits `public, max-age=0, must-revalidate`.
+* `immutable` — adds the `immutable` directive. Defaults to `false`, and is **ignored with a warning when `maxAge` is 0**, since a response that is stale on arrival cannot also promise never to change.
+* `immutablePaths` — path prefixes under `/static` (matched case-sensitively, on a path-segment boundary) served `public, max-age=31536000, immutable` regardless of the two settings above. Defaults to `[ "/fonts/" ]`. This **replaces** rather than merges, so `[]` means no long-lived paths.
+
+**The default revalidates, and that is deliberate.** `immutable` tells a browser the bytes behind a URL will never change, and browsers honour it so completely that not even a manual reload revalidates. On a stable filename — which is what the framework's own assets use (`/static/scripts/ti-framework.js`, the theme sheets) — the promise is false, and a deployed CSS or JS fix simply never reaches anyone who has already visited, for up to a year, with no way to tell them otherwise. Revalidating costs a conditional request per asset, answered with a `304` from the `ETag`/`Last-Modified` that `express.static` still attaches — headers, no body.
+
+**Opt back into `immutable` once your filenames are content-addressed.** If your build emits `app.a1b2c3.css`, or your application appends a content hash to each asset URL, the promise becomes true and there is real value in making it:
+
+```json
+{
+  "staticCache": { "maxAge": 31536000, "immutable": true }
+}
+```
+
+Fonts are the default exception because a released `.woff2` is an artifact rather than something edited in place, and its filename already carries the family, weight and style. If that is not how a given deployment manages its fonts, clear the list.
+
+## Configure HTTPS for development
+
+Use the `mkcert` tool to create a certificate for development.
+
+Step 1: Install the tool:
+```text
+choco install mkcert
+```
+Step 2: Install certificate authority:
+```text
+mkcert -install
+```
+Step 3: Generate certificate files for localhost:
+```text
+mkcert localhost 127.0.0.1 ::1
 ```

package/bin/build/post-install.js

@@ -1,18 +1,18 @@
-const fs = require( "node:fs" );
-const path = require( "node:path" );
-
-function copyLibrary( source, destination ) {
-    try {
-        fs.mkdirSync( path.dirname( destination ), { recursive: true } );
-        fs.copyFileSync( source, destination );
-        console.log( `Copied ${ source } -> ${ destination }` );
-    } catch ( error ) {
-        console.error( `Failed to copy ${ source } -> ${ destination }:`, error.message );
-        process.exit( 1 );
-    }
-}
-
-const staticDir = path.join( __dirname, "..", "static", "scripts", "lib" );
-
-copyLibrary( require.resolve( "htmx.org/dist/htmx.min.js" ), path.join( staticDir, "htmx.min.js" ) );
-copyLibrary( require.resolve( "@alpinejs/csp/dist/cdn.min.js" ), path.join( staticDir, "alpinejs-csp.min.js" ) );
+const fs = require( "node:fs" );
+const path = require( "node:path" );
+
+function copyLibrary( source, destination ) {
+    try {
+        fs.mkdirSync( path.dirname( destination ), { recursive: true } );
+        fs.copyFileSync( source, destination );
+        console.log( `Copied ${ source } -> ${ destination }` );
+    } catch ( error ) {
+        console.error( `Failed to copy ${ source } -> ${ destination }:`, error.message );
+        process.exit( 1 );
+    }
+}
+
+const staticDir = path.join( __dirname, "..", "static", "scripts", "lib" );
+
+copyLibrary( require.resolve( "htmx.org/dist/htmx.min.js" ), path.join( staticDir, "htmx.min.js" ) );
+copyLibrary( require.resolve( "@alpinejs/csp/dist/cdn.min.js" ), path.join( staticDir, "alpinejs-csp.min.js" ) );

package/bin/localization/web-server-labels.json

@@ -1,28 +1,28 @@
-{
-  "interface": {
-    "default": {
-      "login": {
-        "password": {
-          "en": "Password",
-          "bg": "Парола"
-        },
-        "sign-in": {
-          "en": "Sign In",
-          "bg": "Вход"
-        },
-        "sign-in-azure": {
-          "en": "Sign In - Azure",
-          "bg": "Вход с Azure"
-        },
-        "sign-in-google": {
-          "en": "Sign In - Google",
-          "bg": "Вход с Google"
-        },
-        "username": {
-          "en": "Username",
-          "bg": "Потребител"
-        }
-      }
-    }
-  }
+{
+  "interface": {
+    "default": {
+      "login": {
+        "password": {
+          "en": "Password",
+          "bg": "Парола"
+        },
+        "sign-in": {
+          "en": "Sign In",
+          "bg": "Вход"
+        },
+        "sign-in-azure": {
+          "en": "Sign In - Azure",
+          "bg": "Вход с Azure"
+        },
+        "sign-in-google": {
+          "en": "Sign In - Google",
+          "bg": "Вход с Google"
+        },
+        "username": {
+          "en": "Username",
+          "bg": "Потребител"
+        }
+      }
+    }
+  }
 }

package/bin/static/.well-known/appspecific/com.chrome.devtools.json

@@ -1,6 +1,6 @@
-{
-  "workspace": {
-    "root": "packages/web-framework",
-    "uuid": "a6c9b71a-41c3-448d-a680-7c1f6c5b42b0"
-  }
+{
+  "workspace": {
+    "root": "packages/web-framework",
+    "uuid": "a6c9b71a-41c3-448d-a680-7c1f6c5b42b0"
+  }
 }

package/bin/static/fragments/components/component-notification-bar.html

@@ -1,21 +1,21 @@
-<div id="ti-notifications" x-data="tiComponentNotificationBar" class="ti-toast-stack" aria-live="polite" aria-atomic="false">
-    <template x-for="n in notifications" x-bind:key="n.id">
-        <div class="ti-toast" x-bind:class="n.tone || 'info'" role="alert">
-            <div class="ti-toast-bar" aria-hidden="true"></div>
-            <div class="ti-toast-icon" aria-hidden="true">
-                <span class="ti-icon check md" aria-hidden="true" x-show="n.tone === 'success'"></span>
-                <span class="ti-icon close md" aria-hidden="true" x-show="n.tone === 'danger'"></span>
-                <span class="ti-icon warning-triangle md" aria-hidden="true" x-show="n.tone === 'warn'"></span>
-                <span class="ti-icon info-circle md" aria-hidden="true" x-show="!n.tone || n.tone === 'info'"></span>
-            </div>
-            <div class="ti-toast-body">
-                <div class="ti-toast-title" x-text="n.title || ''"></div>
-                <div class="ti-toast-msg" x-text="n.message || ''"></div>
-                <div class="ti-toast-details" x-show="n.details" x-text="n.details || ''"></div>
-            </div>
-            <button class="ti-toast-close" @click="remove(n.id)" aria-label="Dismiss notification" type="button">
-                <span class="ti-icon close sm" aria-hidden="true"></span>
-            </button>
-        </div>
-    </template>
-</div>
+<div id="ti-notifications" x-data="tiComponentNotificationBar" class="ti-toast-stack" aria-live="polite" aria-atomic="false">
+    <template x-for="n in notifications" x-bind:key="n.id">
+        <div class="ti-toast" x-bind:class="n.tone || 'info'" role="alert">
+            <div class="ti-toast-bar" aria-hidden="true"></div>
+            <div class="ti-toast-icon" aria-hidden="true">
+                <span class="ti-icon check md" aria-hidden="true" x-show="n.tone === 'success'"></span>
+                <span class="ti-icon close md" aria-hidden="true" x-show="n.tone === 'danger'"></span>
+                <span class="ti-icon warning-triangle md" aria-hidden="true" x-show="n.tone === 'warn'"></span>
+                <span class="ti-icon info-circle md" aria-hidden="true" x-show="!n.tone || n.tone === 'info'"></span>
+            </div>
+            <div class="ti-toast-body">
+                <div class="ti-toast-title" x-text="n.title || ''"></div>
+                <div class="ti-toast-msg" x-text="n.message || ''"></div>
+                <div class="ti-toast-details" x-show="n.details" x-text="n.details || ''"></div>
+            </div>
+            <button class="ti-toast-close" @click="remove(n.id)" aria-label="Dismiss notification" type="button">
+                <span class="ti-icon close sm" aria-hidden="true"></span>
+            </button>
+        </div>
+    </template>
+</div>

package/bin/static/fragments/components/component-sidebar.html

@@ -1,33 +1,33 @@
-<nav class="ti-sidebar" x-data="tiComponentSidebarNav" aria-label="Main navigation">
-    <button class="ti-sidebar-collapse-btn" @click="toggleCollapse()" x-bind:aria-label="collapsed ? 'Expand sidebar' : 'Collapse sidebar'" type="button">
-        <span class="ti-icon chevron-left xs" aria-hidden="true"></span>
-    </button>
-
-    <!-- Brand slot — override in app-specific frame -->
-    <div class="ti-sidebar-brand">
-        <div class="ti-sidebar-brand-mark">T</div>
-        <div class="ti-sidebar-brand-text-block">
-            <span class="ti-sidebar-brand-text">ti-engine</span>
-        </div>
-    </div>
-
-    <!-- Navigation slot — override in app-specific frame -->
-    <div class="ti-sidebar-nav">
-        <a href="/" class="ti-sidebar-item" data-tip="Dashboard" aria-label="Dashboard">
-            <span class="ti-sidebar-item-icon">
-                <span class="ti-icon dashboard md" aria-hidden="true"></span>
-            </span>
-            <span class="ti-sidebar-item-label">Dashboard</span>
-        </a>
-    </div>
-
-    <!-- Footer -->
-    <div class="ti-sidebar-foot">
-        <button class="ti-sidebar-item" @click="toggleTheme()" data-tip="Toggle theme" aria-label="Toggle theme" type="button">
-            <span class="ti-sidebar-item-icon">
-                <span class="ti-icon sun md" aria-hidden="true"></span>
-            </span>
-            <span class="ti-sidebar-item-label" x-text="theme === 'daylight' ? 'Glass Theme' : 'Daylight Theme'">Toggle Theme</span>
-        </button>
-    </div>
-</nav>
+<nav class="ti-sidebar" x-data="tiComponentSidebarNav" aria-label="Main navigation">
+    <button class="ti-sidebar-collapse-btn" @click="toggleCollapse()" x-bind:aria-label="collapsed ? 'Expand sidebar' : 'Collapse sidebar'" type="button">
+        <span class="ti-icon chevron-left xs" aria-hidden="true"></span>
+    </button>
+
+    <!-- Brand slot — override in app-specific frame -->
+    <div class="ti-sidebar-brand">
+        <div class="ti-sidebar-brand-mark">T</div>
+        <div class="ti-sidebar-brand-text-block">
+            <span class="ti-sidebar-brand-text">ti-engine</span>
+        </div>
+    </div>
+
+    <!-- Navigation slot — override in app-specific frame -->
+    <div class="ti-sidebar-nav">
+        <a href="/" class="ti-sidebar-item" data-tip="Dashboard" aria-label="Dashboard">
+            <span class="ti-sidebar-item-icon">
+                <span class="ti-icon dashboard md" aria-hidden="true"></span>
+            </span>
+            <span class="ti-sidebar-item-label">Dashboard</span>
+        </a>
+    </div>
+
+    <!-- Footer -->
+    <div class="ti-sidebar-foot">
+        <button class="ti-sidebar-item" @click="toggleTheme()" data-tip="Toggle theme" aria-label="Toggle theme" type="button">
+            <span class="ti-sidebar-item-icon">
+                <span class="ti-icon sun md" aria-hidden="true"></span>
+            </span>
+            <span class="ti-sidebar-item-label" x-text="theme === 'daylight' ? 'Glass Theme' : 'Daylight Theme'">Toggle Theme</span>
+        </button>
+    </div>
+</nav>

package/bin/static/fragments/components/component-tooltip.html

@@ -1,11 +1,11 @@
-<div x-data="tiComponentTooltip()"
-     x-on:mouseover="handleEnter($event)"
-     x-on:mouseout="handleLeave($event)"
-     x-on:focusin="handleEnter($event)"
-     x-on:focusout="handleLeave($event)"
-     class="ti-tooltip">
-    <div x-show="isVisible"
-         x-text="text"
-         x-transition
-         class="ti-tooltip-bubble"></div>
+<div x-data="tiComponentTooltip()"
+     x-on:mouseover="handleEnter($event)"
+     x-on:mouseout="handleLeave($event)"
+     x-on:focusin="handleEnter($event)"
+     x-on:focusout="handleLeave($event)"
+     class="ti-tooltip">
+    <div x-show="isVisible"
+         x-text="text"
+         x-transition
+         class="ti-tooltip-bubble"></div>
 </div>

package/bin/static/fragments/components/component-topbar.html

@@ -1,6 +1,6 @@
-<header id="ti-topbar" class="ti-topbar" x-data="tiComponentTopbar">
-    <div id="ti-topbar-info">
-        <div class="ti-topbar-title" x-text="screenTitle"></div>
-        <div class="ti-topbar-sub" x-show="$store.tiApplication.topbarSubtitle" x-text="$store.tiApplication.topbarSubtitle"></div>
-    </div>
+<header id="ti-topbar" class="ti-topbar" x-data="tiComponentTopbar">
+    <div id="ti-topbar-info">
+        <div class="ti-topbar-title" x-text="screenTitle"></div>
+        <div class="ti-topbar-sub" x-show="$store.tiApplication.topbarSubtitle" x-text="$store.tiApplication.topbarSubtitle"></div>
+    </div>
 </header>

package/bin/static/fragments/frame-administration.html

@@ -1,3 +1,3 @@
-<div>
-    <span>Administration</span>
+<div>
+    <span>Administration</span>
 </div>

package/bin/static/fragments/frame-application.html

@@ -1,19 +1,19 @@
-<div class="ti-application" x-data="tiApplication" x-bind:class="{ collapsed: collapsed }">
-    <!-- Sidebar -->
-    <ti-component-sidebar-placeholder></ti-component-sidebar-placeholder>
-
-    <!-- Content -->
-    <div id="ti-content-wrapper" class="ti-content">
-        <!-- Topbar -->
-        <ti-component-topbar-placeholder></ti-component-topbar-placeholder>
-
-        <!-- Application Screen -->
-        <div id="ti-content" class="ti-page-scrollable">
-            <ti-nested-frame-placeholder hx-get="/app/dashboard" hx-trigger="load" hx-target="this" hx-swap="outerHTML"
-                                         hx-push-url="true"></ti-nested-frame-placeholder>
-        </div>
-    </div>
-
-    <!-- Toast notification stack -->
-    <ti-component-notification-bar-placeholder></ti-component-notification-bar-placeholder>
+<div class="ti-application" x-data="tiApplication" x-bind:class="{ collapsed: collapsed }">
+    <!-- Sidebar -->
+    <ti-component-sidebar-placeholder></ti-component-sidebar-placeholder>
+
+    <!-- Content -->
+    <div id="ti-content-wrapper" class="ti-content">
+        <!-- Topbar -->
+        <ti-component-topbar-placeholder></ti-component-topbar-placeholder>
+
+        <!-- Application Screen -->
+        <div id="ti-content" class="ti-page-scrollable">
+            <ti-nested-frame-placeholder hx-get="/app/dashboard" hx-trigger="load" hx-target="this" hx-swap="outerHTML"
+                                         hx-push-url="true"></ti-nested-frame-placeholder>
+        </div>
+    </div>
+
+    <!-- Toast notification stack -->
+    <ti-component-notification-bar-placeholder></ti-component-notification-bar-placeholder>
 </div>

package/bin/static/fragments/frame-dashboard.html

@@ -1,3 +1,3 @@
-<div>
-    <span>Dashboard</span>
+<div>
+    <span>Dashboard</span>
 </div>