alepha 0.18.2 → 0.18.3

package/src/react/router/providers/ReactPageProvider.ts

@@ -8,6 +8,7 @@ import {
   type TSchema,
   t,
 } from "alepha";
+import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
 import { AlephaContext, ClientOnly } from "alepha/react";
 import type { Head } from "alepha/react/head";
@@ -24,6 +25,8 @@ import {
   type PagePrimitiveOptions,
 } from "../primitives/$page.ts";
 
+// -------------------------------------------------------------------------------------------------------------------
+
 export const reactPageOptions = $atom({
   name: "alepha.react.page.options",
   description: "Configuration options for the React page provider.",
@@ -32,20 +35,87 @@ export const reactPageOptions = $atom({
      * Enable React StrictMode wrapper.
      */
     strictMode: t.boolean({ default: true }),
+    /**
+     * RegExp pattern (as string) to detect file-like URLs (e.g. /hello.txt, /wp-login.php).
+     * When a request hits the catch-all wildcard route and matches this pattern,
+     * SSR is skipped and a plain 404 response is returned instead.
+     *
+     * Set to empty string to disable this behavior.
+     *
+     * @default "\\.[a-zA-Z0-9]{1,10}$"
+     */
+    staticFilePattern: t.string(),
   }),
   default: {
     strictMode: true,
+    staticFilePattern: "\\.[a-zA-Z0-9]{1,10}$",
   },
 });
 
+// -------------------------------------------------------------------------------------------------------------------
+
 /**
  * Handle page routes for React applications. (Browser and Server)
  */
 export class ReactPageProvider {
+  protected readonly dateTimeProvider = $inject(DateTimeProvider);
   protected readonly log = $logger();
   protected readonly options = $use(reactPageOptions);
   protected readonly alepha = $inject(Alepha);
   protected readonly pages: PageRoute[] = [];
+  protected nextIdCursor = 0;
+
+  protected readonly configure = $hook({
+    on: "configure",
+    handler: () => {
+      let hasNotFoundHandler = false;
+      const pages = this.alepha.primitives($page);
+
+      const hasParent = (it: PagePrimitive) => {
+        if (it.options.parent) {
+          return true;
+        }
+
+        for (const page of pages) {
+          const children = page.options.children
+            ? Array.isArray(page.options.children)
+              ? page.options.children
+              : page.options.children()
+            : [];
+          if (children.includes(it)) {
+            return true;
+          }
+        }
+      };
+
+      for (const page of pages) {
+        if (page.options.path === "/*") {
+          hasNotFoundHandler = true;
+        }
+
+        // skip children, we only want root pages
+        if (hasParent(page)) {
+          continue;
+        }
+
+        this.add(this.map(pages, page));
+      }
+
+      if (!hasNotFoundHandler && pages.length > 0) {
+        // add a default 404 page if not already defined
+        this.add({
+          path: "/*",
+          name: "notFound",
+          component: NotFoundPage,
+          onServerResponse: ({ reply }) => {
+            reply.status = 404;
+          },
+        });
+      }
+    },
+  });
+
+  // -------------------------------------------------------------------------------------------------------------------
 
   public getPages(): PageRoute[] {
     return this.pages;
@@ -210,7 +280,7 @@ export class ReactPageProvider {
           ? this.alepha.codec.decode(route.schema.query, state.query)
           : {};
       } catch (e) {
-        it.error = e as Error;
+        it.error = e instanceof Error ? e : new Error(String(e));
         break;
       }
 
@@ -219,7 +289,7 @@ export class ReactPageProvider {
           ? this.alepha.codec.decode(route.schema.params, state.params)
           : {};
       } catch (e) {
-        it.error = e as Error;
+        it.error = e instanceof Error ? e : new Error(String(e));
         break;
       }
 
@@ -258,6 +328,11 @@ export class ReactPageProvider {
         forceRefresh = true;
       }
 
+      // redirect shorthand
+      if (route.redirect) {
+        return { redirect: route.redirect };
+      }
+
       // no loader, render a basic view by default
       if (!route.loader) {
         continue;
@@ -288,7 +363,7 @@ export class ReactPageProvider {
 
         this.log.error("Page loader has failed", e);
 
-        it.error = e as Error;
+        it.error = e instanceof Error ? e : new Error(String(e));
         break;
       }
     }
@@ -322,14 +397,18 @@ export class ReactPageProvider {
       // normal use case
       if (!it.error) {
         try {
-          const element = await this.createElement(it.route, {
-            // default props attached to page
-            ...(it.route.props ? it.route.props() : {}),
-            // resolved props
-            ...props,
-            // context props (from previous layers)
-            ...context,
-          });
+          const element = await this.createElement(
+            it.route,
+            {
+              // default props attached to page
+              ...(it.route.props ? it.route.props() : {}),
+              // resolved props
+              ...props,
+              // context props (from previous layers)
+              ...context,
+            },
+            state.url,
+          );
 
           state.layers.push({
             name: it.route.name,
@@ -343,7 +422,7 @@ export class ReactPageProvider {
             cache: it.cache,
           });
         } catch (e) {
-          it.error = e as Error;
+          it.error = e instanceof Error ? e : new Error(String(e));
         }
       }
 
@@ -377,6 +456,7 @@ export class ReactPageProvider {
             index: i + 1,
             path,
             route: it.route,
+            cache: it.cache,
           });
           break;
         } catch (e) {
@@ -405,6 +485,7 @@ export class ReactPageProvider {
   protected async createElement(
     page: PageRoute,
     props: Record<string, any>,
+    targetUrl?: URL,
   ): Promise<ReactNode> {
     if (page.lazy && page.component) {
       this.log.warn(
@@ -413,8 +494,17 @@ export class ReactPageProvider {
     }
 
     if (page.lazy) {
-      const component = await page.lazy(); // load component
-      return createElement(component.default, props);
+      try {
+        const component = await page.lazy();
+        return createElement(component.default, props);
+      } catch (error) {
+        if (this.alepha.isBrowser() && this.isChunkLoadError(error)) {
+          if (this.reloadAfterChunkError(targetUrl)) {
+            return undefined;
+          }
+        }
+        throw error;
+      }
     }
 
     if (page.component) {
@@ -424,6 +514,46 @@ export class ReactPageProvider {
     return undefined;
   }
 
+  /**
+   * Detect chunk load errors caused by stale dynamic imports after a deployment.
+   * When new assets are deployed with different hashes, old chunk URLs return 404.
+   */
+  protected isChunkLoadError(error: unknown): boolean {
+    if (!(error instanceof Error)) return false;
+    const msg = error.message;
+    return (
+      /Failed to fetch dynamically imported module/.test(msg) ||
+      /error loading dynamically imported module/i.test(msg) ||
+      /Unable to preload CSS/.test(msg) ||
+      /Importing a module script failed/.test(msg)
+    );
+  }
+
+  /**
+   * Navigate to the target URL to fetch updated assets after a chunk load failure.
+   * Uses sessionStorage to prevent infinite reload loops.
+   * Returns true if navigation was initiated.
+   */
+  protected reloadAfterChunkError(url?: URL): boolean {
+    const key = "alepha:chunk-reload";
+    const lastReload = sessionStorage.getItem(key);
+    const now = this.dateTimeProvider.nowMillis();
+
+    if (lastReload && now - Number(lastReload) < 10_000) {
+      this.log.error(
+        "Chunk load failed after recent reload, not retrying to avoid loop",
+      );
+      return false;
+    }
+
+    this.log.warn("Chunk load failed after deployment, reloading page");
+    sessionStorage.setItem(key, String(now));
+    window.location.assign(
+      url ? url.pathname + url.search : window.location.href,
+    );
+    return true;
+  }
+
   public renderError(error: Error): ReactNode {
     return createElement(ErrorViewer, { error, alepha: this.alepha });
   }
@@ -490,56 +620,6 @@ export class ReactPageProvider {
     );
   }
 
-  protected readonly configure = $hook({
-    on: "configure",
-    handler: () => {
-      let hasNotFoundHandler = false;
-      const pages = this.alepha.primitives($page);
-
-      const hasParent = (it: PagePrimitive) => {
-        if (it.options.parent) {
-          return true;
-        }
-
-        for (const page of pages) {
-          const children = page.options.children
-            ? Array.isArray(page.options.children)
-              ? page.options.children
-              : page.options.children()
-            : [];
-          if (children.includes(it)) {
-            return true;
-          }
-        }
-      };
-
-      for (const page of pages) {
-        if (page.options.path === "/*") {
-          hasNotFoundHandler = true;
-        }
-
-        // skip children, we only want root pages
-        if (hasParent(page)) {
-          continue;
-        }
-
-        this.add(this.map(pages, page));
-      }
-
-      if (!hasNotFoundHandler && pages.length > 0) {
-        // add a default 404 page if not already defined
-        this.add({
-          path: "/*",
-          name: "notFound",
-          component: NotFoundPage,
-          onServerResponse: ({ reply }) => {
-            reply.status = 404;
-          },
-        });
-      }
-    },
-  });
-
   protected map(
     pages: Array<PagePrimitive>,
     target: PagePrimitive,
@@ -607,14 +687,14 @@ export class ReactPageProvider {
     return path;
   }
 
-  protected _next = 0;
-
   protected nextId(): string {
-    this._next += 1;
-    return `P${this._next}`;
+    this.nextIdCursor += 1;
+    return `P${this.nextIdCursor}`;
   }
 }
 
+// ---------------------------------------------------------------------------------------------------------------------
+
 export const isPageRoute = (it: any): it is PageRoute => {
   return (
     it &&
@@ -644,6 +724,11 @@ export interface PageRoute extends PageRouteEntry {
   name: string;
   parent?: PageRoute;
   match: string;
+
+  /**
+   * Optional meta information associated with the page route, can be used for any purpose (e.g. menu label, icon, etc.).
+   */
+  label?: string;
 }
 
 export interface Layer {
@@ -709,7 +794,9 @@ export interface ReactRouterState {
    */
   head: Head;
 
-  //
+  /**
+   * Optional name of the current page route
+   */
   name?: string;
 }
 
@@ -721,10 +808,6 @@ export interface RouterStackItem {
   cache?: boolean;
 }
 
-export interface TransitionOptions {
-  previous?: PreviousLayerData[];
-}
-
 export interface CreateLayersResult {
   redirect?: string;
   state?: ReactRouterState;

package/src/react/router/providers/ReactServerProvider.ts

@@ -29,6 +29,7 @@ import {
   type PageRoute,
   ReactPageProvider,
   type ReactRouterState,
+  reactPageOptions,
 } from "./ReactPageProvider.ts";
 import { ReactServerTemplateProvider } from "./ReactServerTemplateProvider.ts";
 import { SSRManifestProvider } from "./SSRManifestProvider.ts";
@@ -72,6 +73,7 @@ export class ReactServerProvider {
   protected hasServerLinksProvider = false;
 
   protected readonly options = $use(reactServerOptions);
+  protected readonly pageOptions = $use(reactPageOptions);
 
   /**
    * Configure the React server provider.
@@ -124,7 +126,7 @@ export class ReactServerProvider {
     this.hasServerLinksProvider = this.alepha.has(ServerLinksProvider);
 
     for (const page of this.pageApi.getPages()) {
-      if (page.component || page.lazy) {
+      if (page.component || page.lazy || page.redirect) {
         this.log.debug(`+ ${page.match} -> ${page.name}`);
 
         // Separate $cache from server-level middleware.
@@ -250,6 +252,16 @@ export class ReactServerProvider {
     });
   }
 
+  /**
+   * Resolve the static file pattern from page options.
+   * Returns a compiled RegExp, or `false` if disabled (empty string).
+   */
+  protected resolveStaticFilePattern(): RegExp | false {
+    const pattern = this.pageOptions.staticFilePattern;
+    if (!pattern) return false;
+    return new RegExp(pattern);
+  }
+
   /**
    * Create the request handler for a page route.
    *
@@ -261,10 +273,23 @@ export class ReactServerProvider {
     cacheMiddleware: Middleware[] = [],
   ): ServerHandler {
     const hasCache = cacheMiddleware.length > 0;
+    const isCatchAll = route.match === "/*";
+    const staticFilePattern = isCatchAll
+      ? this.resolveStaticFilePattern()
+      : false;
 
     return async (serverRequest) => {
       const { url, reply, query, params } = serverRequest;
 
+      // Skip SSR for file-like URLs hitting the catch-all wildcard.
+      // Bots and crawlers often probe paths like /hello.txt, /wp-login.php, etc.
+      // Rendering a full React page for these is wasteful — return a plain 404 instead.
+      if (staticFilePattern && staticFilePattern.test(url.pathname)) {
+        reply.status = 404;
+        reply.headers["content-type"] = "text/plain";
+        return "Not Found";
+      }
+
       this.log.trace("Rendering page", { name: route.name });
 
       // Initialize router state
@@ -366,6 +391,7 @@ export class ReactServerProvider {
         },
         {
           hydration: true,
+          state,
           onError: (error) => {
             if (error instanceof Redirection) {
               this.log.debug("Streaming resulted in redirection", {
@@ -382,7 +408,13 @@ export class ReactServerProvider {
 
       this.log.trace("Page streaming started (early head optimization)");
       route.onServerResponse?.(serverRequest);
-      reply.body = htmlStream;
+      reply.body = htmlStream.pipeThrough(
+        new TransformStream({
+          flush: () => {
+            this.log.info("Page streaming completed", { name: route.name });
+          },
+        }),
+      );
     };
   }
 
@@ -567,6 +599,12 @@ declare module "alepha" {
 /**
  * React server provider configuration atom
  */
+/**
+ * Default pattern matching file-like URLs (e.g. /hello.txt, /wp-login.php).
+ * Matches paths whose last segment contains a dot followed by 1-10 alphanumeric characters.
+ */
+export const DEFAULT_STATIC_FILE_PATTERN = "\\.[a-zA-Z0-9]{1,10}$";
+
 export const reactServerOptions = $atom({
   name: "alepha.react.server.options",
   schema: t.object({

package/src/react/router/providers/ReactServerTemplateProvider.ts

@@ -300,6 +300,7 @@ export class ReactServerTemplateProvider {
     >,
     options: {
       hydration?: boolean;
+      state?: ReactRouterState;
       onError?: (error: unknown) => void;
     } = {},
   ): ReadableStream<Uint8Array> {
@@ -308,7 +309,7 @@ export class ReactServerTemplateProvider {
 
     let headClosed = false;
     let bodyStarted = false;
-    let routerState: ReactRouterState | undefined;
+    let routerState: ReactRouterState | undefined = options.state;
 
     return new ReadableStream<Uint8Array>({
       start: async (controller) => {
@@ -469,6 +470,17 @@ export class ReactServerTemplateProvider {
     );
 
     controller.enqueue(slots.ROOT_CLOSE);
+
+    if (routerState) {
+      controller.enqueue(slots.HYDRATION_PREFIX);
+      controller.enqueue(
+        encoder.encode(
+          this.safeJsonSerialize(this.buildHydrationData(routerState)),
+        ),
+      );
+      controller.enqueue(slots.HYDRATION_SUFFIX);
+    }
+
     controller.enqueue(slots.BODY_HTML_CLOSE);
   }
 

package/src/security/providers/SecurityProvider.ts

@@ -1,13 +1,11 @@
 import {
-  $env,
   $hook,
   $inject,
   Alepha,
   AppNotStartedError,
   ContainerLockedError,
-  type Static,
-  t,
 } from "alepha";
+import { SecretProvider } from "alepha/crypto";
 import { $logger } from "alepha/logger";
 import { ForbiddenError } from "alepha/server";
 import type { JSONWebKeySet, JWTPayload } from "jose";
@@ -27,20 +25,6 @@ import {
 } from "../schemas/userAccountInfoSchema.ts";
 import { JwtProvider } from "./JwtProvider.ts";
 
-export const DEFAULT_APP_SECRET = "05759934015388327323179852515731"; // (32)
-
-export const alephaSecurityEnvSchema = t.object({
-  APP_SECRET: t.text({
-    description:
-      "The secret key used for signing JWTs and other security features. It should be a strong, random string of at least 32 characters for HS256. Do not use the default value in production.",
-    default: DEFAULT_APP_SECRET,
-  }),
-});
-
-declare module "alepha" {
-  interface Env extends Partial<Static<typeof alephaSecurityEnvSchema>> {}
-}
-
 export class SecurityProvider {
   protected readonly UNKNOWN_USER_NAME = "Anonymous User";
   protected readonly PERMISSION_REGEXP = /^[\w-]+((:[\w-]+)+)?$/;
@@ -49,11 +33,11 @@ export class SecurityProvider {
 
   protected readonly log = $logger();
   protected readonly jwt = $inject(JwtProvider);
-  protected readonly env = $env(alephaSecurityEnvSchema);
   protected readonly alepha = $inject(Alepha);
+  protected readonly secretProvider = $inject(SecretProvider);
 
-  public get secretKey() {
-    return this.env.APP_SECRET;
+  public get secretKey(): string {
+    return this.secretProvider.secretKey;
   }
 
   /**
@@ -68,7 +52,7 @@ export class SecurityProvider {
     ? [
         {
           name: "default",
-          secret: this.env.APP_SECRET,
+          secret: this.secretKey,
           roles: [
             {
               name: "admin",
@@ -86,12 +70,6 @@ export class SecurityProvider {
   protected start = $hook({
     on: "start",
     handler: async () => {
-      if (this.alepha.isProduction() && this.secretKey === DEFAULT_APP_SECRET) {
-        this.log.warn(
-          "Using default APP_SECRET in production is not recommended. Please set a strong APP_SECRET value.",
-        );
-      }
-
       for (const realm of this.realms) {
         if (realm.secret) {
           const secret =

package/src/server/auth/primitives/$auth.ts

@@ -255,7 +255,29 @@ export class AuthPrimitive extends Primitive<AuthPrimitiveOptions> {
   protected readonly securityProvider = $inject(SecurityProvider);
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
 
-  public oauth?: Configuration;
+  protected oauthConfig?: Configuration;
+  protected oauthInitializer?: () => Promise<Configuration>;
+
+  public get oauth(): Configuration | undefined {
+    return this.oauthConfig;
+  }
+
+  /**
+   * Get the OAuth2/OIDC configuration, initializing lazily if needed (serverless mode).
+   */
+  public async getOAuth(): Promise<Configuration | undefined> {
+    if (this.oauthConfig) {
+      return this.oauthConfig;
+    }
+
+    if (this.oauthInitializer) {
+      this.oauthConfig = await this.oauthInitializer();
+      this.oauthInitializer = undefined;
+      return this.oauthConfig;
+    }
+
+    return undefined;
+  }
 
   public get name() {
     return this.options.name ?? this.config.propertyKey;
@@ -320,10 +342,13 @@ export class AuthPrimitive extends Primitive<AuthPrimitiveOptions> {
             },
           );
         });
-    } else if (this.oauth) {
+    }
+
+    const oauth = await this.getOAuth();
+    if (oauth) {
       try {
         return {
-          ...(await refreshTokenGrant(this.oauth, refreshToken)),
+          ...(await refreshTokenGrant(oauth, refreshToken)),
           issued_at: this.dateTimeProvider.now().unix(),
         };
       } catch (error) {
@@ -399,30 +424,38 @@ export class AuthPrimitive extends Primitive<AuthPrimitiveOptions> {
   }
 
   public async prepare() {
-    const addons: Array<(config: Configuration) => void> = [];
-
-    addons.push(allowInsecureRequests);
-
     if ("oidc" in this.options) {
       const { oidc } = this.options;
 
-      this.oauth = await discovery(
-        new URL(oidc.issuer),
-        oidc.clientId,
-        {
-          client_secret: oidc.clientSecret,
-        },
-        undefined,
-        {
-          execute: addons,
-        },
-      );
+      const discoverOidc = async () => {
+        const execute: Array<(config: Configuration) => void> = [];
+        execute.push(allowInsecureRequests);
+
+        return discovery(
+          new URL(oidc.issuer),
+          oidc.clientId,
+          {
+            client_secret: oidc.clientSecret,
+          },
+          undefined,
+          {
+            execute,
+          },
+        );
+      };
+
+      // Defer OIDC discovery in serverless/dev to avoid cold start penalty
+      if (this.alepha.isServerless() || !this.alepha.isProduction()) {
+        this.oauthInitializer = discoverOidc;
+      } else {
+        this.oauthConfig = await discoverOidc();
+      }
     }
 
     if ("oauth" in this.options) {
       const { oauth } = this.options;
 
-      this.oauth = new Configuration(
+      this.oauthConfig = new Configuration(
         {
           authorization_endpoint: oauth.authorization,
           token_endpoint: oauth.token,