alepha 0.15.2 → 0.15.4

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

@@ -32,6 +32,13 @@ export class SSRManifestProvider {
     );
   }
 
+  /**
+   * Get the full manifest object.
+   */
+  public getManifest(): Static<SsrManifestAtomSchema> {
+    return this.manifest;
+  }
+
   /**
    * Get the base path for assets (from Vite's base config).
    * Returns empty string if base is "/" (default), otherwise returns the base path.

package/src/react/router/services/ReactRouter.ts

@@ -7,7 +7,7 @@ import {
   type ReactRouterState,
 } from "../providers/ReactPageProvider.ts";
 
-export interface RouterGoOptions {
+export interface RouterPushOptions {
   replace?: boolean;
   params?: Record<string, string>;
   query?: Record<string, string>;
@@ -114,7 +114,7 @@ export class ReactRouter<T extends object> {
       return;
     }
 
-    await this.go(this.location.pathname + this.location.search, {
+    await this.push(this.location.pathname + this.location.search, {
       replace: true,
       force: true,
     });
@@ -168,18 +168,18 @@ export class ReactRouter<T extends object> {
     await this.browser?.invalidate(props);
   }
 
-  public async go(path: string, options?: RouterGoOptions): Promise<void>;
-  public async go(
+  public async push(path: string, options?: RouterPushOptions): Promise<void>;
+  public async push(
     path: keyof VirtualRouter<T>,
-    options?: RouterGoOptions,
+    options?: RouterPushOptions,
   ): Promise<void>;
-  public async go(
+  public async push(
     path: string | keyof VirtualRouter<T>,
-    options?: RouterGoOptions,
+    options?: RouterPushOptions,
   ): Promise<void> {
     for (const page of this.pages) {
       if (page.name === path) {
-        await this.browser?.go(
+        await this.browser?.push(
           this.path(path as keyof VirtualRouter<T>, options),
           options,
         );
@@ -187,17 +187,17 @@ export class ReactRouter<T extends object> {
       }
     }
 
-    await this.browser?.go(path as string, options);
+    await this.browser?.push(path as string, options);
   }
 
-  public anchor(path: string, options?: RouterGoOptions): AnchorProps;
+  public anchor(path: string, options?: RouterPushOptions): AnchorProps;
   public anchor(
     path: keyof VirtualRouter<T>,
-    options?: RouterGoOptions,
+    options?: RouterPushOptions,
   ): AnchorProps;
   public anchor(
     path: string | keyof VirtualRouter<T>,
-    options: RouterGoOptions = {},
+    options: RouterPushOptions = {},
   ): AnchorProps {
     let href = path as string;
 
@@ -214,7 +214,7 @@ export class ReactRouter<T extends object> {
         ev.stopPropagation();
         ev.preventDefault();
 
-        this.go(href, options).catch(console.error);
+        this.push(href, options).catch(console.error);
       },
     };
   }

package/src/scheduler/index.workerd.ts

@@ -0,0 +1,43 @@
+import { $module } from "alepha";
+import { AlephaLock } from "alepha/lock";
+import { $scheduler } from "./primitives/$scheduler.ts";
+import { CronProvider } from "./providers/CronProvider.ts";
+import { WorkerdCronProvider } from "./providers/WorkerdCronProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./constants/CRON.ts";
+export * from "./primitives/$scheduler.ts";
+export * from "./providers/CronProvider.ts";
+export * from "./providers/WorkerdCronProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+declare module "alepha" {
+  interface Hooks {
+    /**
+     * Cloudflare Workers scheduled event.
+     *
+     * Emitted when a cron trigger fires in Cloudflare Workers.
+     */
+    "cloudflare:scheduled": {
+      cron: string;
+      scheduledTime: number;
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export const AlephaScheduler = $module({
+  name: "alepha.scheduler",
+  primitives: [$scheduler],
+  services: [AlephaLock, CronProvider, WorkerdCronProvider],
+  register: (alepha) => {
+    // Replace CronProvider with WorkerdCronProvider for Cloudflare Workers
+    alepha.with({
+      provide: CronProvider,
+      use: WorkerdCronProvider,
+    });
+  },
+});

package/src/scheduler/providers/CronProvider.ts

@@ -16,6 +16,11 @@ export class CronProvider {
   protected readonly start = $hook({
     on: "start",
     handler: () => {
+      if (this.alepha.isServerless()) {
+        this.log.info("Ignoring cron jobs in serverless environment");
+        return;
+      }
+
       for (const cron of this.cronJobs) {
         if (!cron.running) {
           cron.running = true;
@@ -62,12 +67,12 @@ export class CronProvider {
         ? this.cronJobs.find((c) => c.name === name)
         : name;
 
-    if (!cron) {
+    if (!cron || !cron.running) {
       return;
     }
 
     cron.running = false;
-    cron.abort.abort();
+    cron.abort?.abort();
     this.log.debug(`Cron task '${cron.name}' stopped`);
   }
 
@@ -109,13 +114,13 @@ export class CronProvider {
     }
 
     const duration = next.getTime() - now.toDate().getTime();
-
-    task.abort = new AbortController();
+    const abort = new AbortController();
+    task.abort = abort;
 
     this.dt
       .wait(duration, {
         now: now.valueOf(),
-        signal: task.abort.signal,
+        signal: abort.signal,
       })
       .then(() => {
         if (!task.running) {
@@ -141,6 +146,48 @@ export class CronProvider {
         this.log.warn("Issue during cron waiting timer", err as Error);
       });
   }
+
+  /**
+   * Trigger a specific cron job by name.
+   */
+  public async trigger(name: string): Promise<void> {
+    const job = this.cronJobs.find((j) => j.name === name);
+    if (!job) {
+      this.log.warn(`Cron job '${name}' not found`);
+      return;
+    }
+    await this.runJobs([job], this.dt.now());
+  }
+
+  /**
+   * Trigger all registered cron jobs.
+   */
+  public async triggerAll(): Promise<void> {
+    await this.runJobs(this.cronJobs, this.dt.now());
+  }
+
+  /**
+   * Run multiple cron jobs in parallel.
+   */
+  protected async runJobs(jobs: CronJob[], now: DateTime): Promise<void> {
+    const results = await Promise.allSettled(
+      jobs.map(async (job) => {
+        this.log.debug(`Running cron job '${job.name}'`);
+        try {
+          await job.handler({ now });
+          this.log.debug(`Cron job '${job.name}' completed`);
+        } catch (error) {
+          this.log.error(`Cron job '${job.name}' failed`, error);
+          throw error;
+        }
+      }),
+    );
+
+    const failures = results.filter((r) => r.status === "rejected");
+    if (failures.length > 0) {
+      this.log.error(`${failures.length}/${jobs.length} cron jobs failed`);
+    }
+  }
 }
 
 export interface CronJob {
@@ -151,5 +198,5 @@ export interface CronJob {
   loop: boolean;
   running?: boolean;
   onError?: (error: Error) => void;
-  abort: AbortController;
+  abort?: AbortController;
 }

package/src/scheduler/providers/WorkerdCronProvider.ts

@@ -0,0 +1,102 @@
+import { $hook } from "alepha";
+import type { DateTime } from "alepha/datetime";
+import { parseCronExpression } from "cron-schedule";
+import { CronProvider } from "./CronProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+declare module "alepha" {
+  interface Hooks {
+    /**
+     * Cloudflare Workers scheduled event.
+     *
+     * Emitted when a cron trigger fires in Cloudflare Workers.
+     */
+    "cloudflare:scheduled": {
+      cron: string;
+      scheduledTime: number;
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Cloudflare Workers cron provider.
+ *
+ * This provider handles scheduled events from Cloudflare Workers Cron Triggers.
+ * Unlike the Node.js CronProvider, this doesn't use intervals/timeouts - instead,
+ * it reacts to scheduled events triggered by Cloudflare.
+ *
+ * **Usage:**
+ * 1. Define schedulers with `$scheduler({ cron: "0 * * * *", handler: ... })`
+ * 2. Build your app with `alepha build` - cron triggers are automatically added to `wrangler.jsonc`
+ * 3. Deploy to Cloudflare Workers
+ *
+ * **How it works:**
+ * - During build, all registered `$scheduler` cron expressions are collected
+ * - The build generates `wrangler.jsonc` with `triggers.crons` automatically filled
+ * - When Cloudflare fires a cron trigger, the `scheduled` handler emits `cloudflare:scheduled`
+ * - This provider listens to that event and runs matching schedulers
+ *
+ * @see https://developers.cloudflare.com/workers/configuration/cron-triggers/
+ */
+export class WorkerdCronProvider extends CronProvider {
+  /**
+   * Override to avoid creating AbortController in global scope.
+   * Cloudflare Workers doesn't allow this during initialization.
+   */
+  public override createCronJob(
+    name: string,
+    expression: string,
+    handler: (context: { now: DateTime }) => Promise<void>,
+  ): void {
+    this.cronJobs.push({
+      name,
+      cron: parseCronExpression(expression),
+      expression,
+      handler,
+      loop: false,
+    });
+  }
+
+  /**
+   * Handle a scheduled event from Cloudflare Workers.
+   */
+  protected readonly onScheduledEvent = $hook({
+    on: "cloudflare:scheduled",
+    handler: async (event) => {
+      const now = this.dt.of(event.scheduledTime);
+
+      this.log.info("Received scheduled event", {
+        cron: event.cron,
+        scheduledTime: now.format(),
+      });
+
+      // Find jobs that match this cron expression
+      const matchingJobs = this.cronJobs.filter(
+        (job) => job.expression === event.cron,
+      );
+
+      if (matchingJobs.length === 0) {
+        // No exact match - try to find jobs that would fire at this time
+        const matchingByTime = this.cronJobs.filter((job) =>
+          job.cron.matchDate(now.toDate()),
+        );
+
+        if (matchingByTime.length > 0) {
+          this.log.debug(
+            `No exact cron match for '${event.cron}', found ${matchingByTime.length} jobs matching by time`,
+          );
+          await this.runJobs(matchingByTime, now);
+          return;
+        }
+
+        this.log.warn(`No cron jobs found for expression '${event.cron}'`);
+        return;
+      }
+
+      await this.runJobs(matchingJobs, now);
+    },
+  });
+}

package/src/security/__tests__/ServerSecurityProvider.spec.ts

@@ -15,6 +15,7 @@ describe("ServerSecurityProvider", () => {
   it("should protect action from unauthorized users", async () => {
     class TestApp {
       ok = $action({
+        secure: true,
         handler: () => "OK",
       });
     }
@@ -63,10 +64,12 @@ describe("ServerSecurityProvider", () => {
   it("should guard by permission", async () => {
     class TestApp {
       admin = $action({
+        secure: true,
         group: "read",
         handler: () => "ADMIN",
       });
       user = $action({
+        secure: true,
         group: "read",
         handler: () => "USER",
       });
@@ -128,4 +131,78 @@ describe("ServerSecurityProvider", () => {
       await app.admin.fetch({}, { user: admin }).then((it) => it.data),
     ).toBe("ADMIN");
   });
+
+  it("should allow public actions by default (no secure option)", async () => {
+    class TestApp {
+      public = $action({
+        handler: () => "PUBLIC",
+      });
+      issuer = $issuer({
+        secret: "test",
+        roles: [{ name: "user", permissions: [{ name: "*" }] }],
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaServer).with(AlephaSecurity);
+    const app = alepha.inject(TestApp);
+    await alepha.start();
+
+    // Should work without authentication via .run()
+    expect(await app.public.run({})).toBe("PUBLIC");
+
+    // Should work without authentication via .fetch()
+    expect(await app.public.fetch({}).then((it) => it.data)).toBe("PUBLIC");
+
+    // Should work via HTTP without token
+    const response = await fetch(
+      `${alepha.inject(ServerProvider).hostname}${app.public.route.path}`,
+    );
+    expect(response.status).toBe(200);
+    expect(await response.text()).toBe("PUBLIC");
+  });
+
+  it("should allow explicit secure: false", async () => {
+    class TestApp {
+      public = $action({
+        secure: false,
+        handler: () => "PUBLIC",
+      });
+      issuer = $issuer({
+        secret: "test",
+        roles: [{ name: "user", permissions: [{ name: "*" }] }],
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaServer).with(AlephaSecurity);
+    const app = alepha.inject(TestApp);
+    await alepha.start();
+
+    // Should work without authentication
+    expect(await app.public.run({})).toBe("PUBLIC");
+    expect(await app.public.fetch({}).then((it) => it.data)).toBe("PUBLIC");
+  });
+
+  it("should require auth when secure: true is explicit", async () => {
+    class TestApp {
+      protected = $action({
+        secure: true,
+        handler: () => "PROTECTED",
+      });
+      issuer = $issuer({
+        secret: "test",
+        roles: [{ name: "user", permissions: [{ name: "*" }] }],
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaServer).with(AlephaSecurity);
+    const app = alepha.inject(TestApp);
+    await alepha.start();
+
+    // Should fail without user
+    await expect(app.protected.run({})).rejects.toThrowError(UnauthorizedError);
+
+    // Should succeed with user
+    const user = { id: randomUUID(), roles: ["user"] };
+    expect(await app.protected.run({}, { user })).toBe("PROTECTED");
+  });
 });

package/src/security/providers/ServerSecurityProvider.ts

@@ -31,25 +31,23 @@ export class ServerSecurityProvider {
     handler: async () => {
       for (const action of this.alepha.primitives($action)) {
         // -------------------------------------------------------------------------------------------------------------
-        // if the action is disabled or not secure, we do NOT create a permission for it
+        // Only create permission when secure is explicitly set to true
+        // Actions are public by default (like $route)
         // -------------------------------------------------------------------------------------------------------------
         if (
           action.options.disabled ||
-          action.options.secure === false ||
+          action.options.secure !== true ||
           this.securityProvider.getRealms().length === 0
         ) {
           continue;
         }
 
-        const secure = action.options.secure;
-        if (typeof secure !== "object") {
-          this.securityProvider.createPermission({
-            name: action.name,
-            group: action.group,
-            method: action.route.method,
-            path: action.route.path,
-          });
-        }
+        this.securityProvider.createPermission({
+          name: action.name,
+          group: action.group,
+          method: action.route.method,
+          path: action.route.path,
+        });
       }
     },
   });
@@ -59,10 +57,12 @@ export class ServerSecurityProvider {
   protected readonly onActionRequest = $hook({
     on: "action:onRequest",
     handler: async ({ action, request, options }) => {
-      // if you set explicitly secure: false, we assume you don't want any security check
-      // but only if no user is provided in options
-      if (action.options.secure === false && !options.user) {
-        this.log.trace("Skipping security check for route");
+      const secure = action.options.secure;
+
+      // Skip security if not explicitly enabled (secure: true or secure: { realm: ... })
+      // Actions are public by default (like $route)
+      if (secure !== true && typeof secure !== "object" && !options.user) {
+        this.log.trace("Skipping security check for action - not secured");
         return;
       }
 
@@ -93,7 +93,7 @@ export class ServerSecurityProvider {
           this.alepha.codec.decode(userAccountInfoSchema, request.user),
         );
       } catch (error) {
-        if (action.options.secure || permission) {
+        if (secure === true || typeof secure === "object" || permission) {
           throw error;
         }
         // else, we skip the security check
@@ -106,7 +106,7 @@ export class ServerSecurityProvider {
     on: "server:onRequest",
     priority: "last",
     handler: async ({ request, route }) => {
-      // if you set explicitly secure: false, we assume you don't want any security check
+      // Skip entirely only if explicitly disabled
       if (route.secure === false) {
         this.log.trace(
           "Skipping security check for route - explicitly disabled",
@@ -126,7 +126,7 @@ export class ServerSecurityProvider {
         typeof route.secure === "object" ? route.secure.realm : undefined;
 
       try {
-        // Try to resolve user (JWT, API key, etc.)
+        // Try to resolve user (JWT, API key, etc.) - even for public routes (optional auth)
         request.user = await this.securityProvider.resolveUserFromServerRequest(
           request,
           { permission, realm },
@@ -135,7 +135,11 @@ export class ServerSecurityProvider {
         // No user resolved?
         if (!request.user) {
           // Route requires auth → throw
-          if (route.secure || permission) {
+          if (
+            route.secure === true ||
+            typeof route.secure === "object" ||
+            permission
+          ) {
             // Provide a more specific error message when no auth header was provided
             if (!request.headers.authorization) {
               throw new InvalidTokenError(
@@ -144,7 +148,7 @@ export class ServerSecurityProvider {
             }
             throw new UnauthorizedError("Authentication required");
           }
-          // Route is public → skip
+          // Route is public → skip (but we tried to resolve user for optional auth)
           this.log.trace(
             "Skipping security check for route - no auth provided and not required",
           );
@@ -166,11 +170,15 @@ export class ServerSecurityProvider {
           permission,
         });
       } catch (error) {
-        if (route.secure || permission) {
+        if (
+          route.secure === true ||
+          typeof route.secure === "object" ||
+          permission
+        ) {
           throw error;
         }
 
-        // else, we skip the security check
+        // else, we skip the security check (route is public)
         this.log.trace(
           "Skipping security check for route - error occurred",
           error,

package/src/server/compress/providers/ServerCompressProvider.ts

@@ -62,6 +62,12 @@ export class ServerCompressProvider {
   public readonly onResponse = $hook({
     on: "server:onResponse",
     handler: async ({ request, response }) => {
+      // In serverless (Cloudflare Workers), skip compression entirely:
+      // Cloudflare's edge network automatically compresses responses
+      if (this.alepha.isServerless()) {
+        return;
+      }
+
       // skip if already compressed
       if (response.headers["content-encoding"]) {
         return;

package/src/server/core/providers/NodeHttpServerProvider.spec.ts

@@ -31,7 +31,9 @@ describe("NodeHttpServerProvider", () => {
     });
 
     test("production mode: waits for connections then closes", async () => {
-      alepha = Alepha.create({ env: { NODE_ENV: "production" } });
+      alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      });
       alepha.with(NodeHttpServerProvider);
 
       await alepha.start();
@@ -52,7 +54,9 @@ describe("NodeHttpServerProvider", () => {
     });
 
     test("production mode: forces close after timeout", async () => {
-      alepha = Alepha.create({ env: { NODE_ENV: "production" } });
+      alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      });
       alepha.with(NodeHttpServerProvider);
 
       await alepha.start();
@@ -89,7 +93,9 @@ describe("NodeHttpServerProvider", () => {
     });
 
     test("rejects new requests during shutdown", async () => {
-      alepha = Alepha.create({ env: { NODE_ENV: "production" } });
+      alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      });
       alepha.with(NodeHttpServerProvider);
 
       await alepha.start();