alepha 0.15.3 → 0.15.4

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/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/links/providers/ServerLinksProvider.spec.ts

@@ -0,0 +1,332 @@
+import { randomUUID } from "node:crypto";
+import { Alepha, t } from "alepha";
+import { $issuer, AlephaSecurity } from "alepha/security";
+import { $action, ServerProvider } from "alepha/server";
+import { describe, it } from "vitest";
+import { LinkProvider, ServerLinksProvider } from "../index.ts";
+
+describe("ServerLinksProvider", () => {
+  describe("secured field in links", () => {
+    it("should set secured=undefined for public actions (no secure option)", async ({
+      expect,
+    }) => {
+      class App {
+        publicAction = $action({
+          handler: () => "PUBLIC",
+        });
+      }
+
+      const alepha = Alepha.create().with(App).with(ServerLinksProvider);
+      await alepha.start();
+
+      const links = alepha.inject(LinkProvider).getServerLinks();
+      const link = links.find((l) => l.name === "publicAction");
+
+      expect(link).toBeDefined();
+      expect(link?.secured).toBeUndefined();
+    });
+
+    it("should set secured=false for explicitly public actions", async ({
+      expect,
+    }) => {
+      class App {
+        publicAction = $action({
+          secure: false,
+          handler: () => "PUBLIC",
+        });
+      }
+
+      const alepha = Alepha.create().with(App).with(ServerLinksProvider);
+      await alepha.start();
+
+      const links = alepha.inject(LinkProvider).getServerLinks();
+      const link = links.find((l) => l.name === "publicAction");
+
+      expect(link).toBeDefined();
+      expect(link?.secured).toBe(false);
+    });
+
+    it("should set secured=true for secured actions", async ({ expect }) => {
+      class App {
+        securedAction = $action({
+          secure: true,
+          handler: () => "SECURED",
+        });
+      }
+
+      const alepha = Alepha.create().with(App).with(ServerLinksProvider);
+      await alepha.start();
+
+      const links = alepha.inject(LinkProvider).getServerLinks();
+      const link = links.find((l) => l.name === "securedAction");
+
+      expect(link).toBeDefined();
+      expect(link?.secured).toBe(true);
+    });
+
+    it("should set secured to object for realm-secured actions", async ({
+      expect,
+    }) => {
+      class App {
+        realmAction = $action({
+          secure: { realm: "admin" },
+          handler: () => "REALM",
+        });
+      }
+
+      const alepha = Alepha.create().with(App).with(ServerLinksProvider);
+      await alepha.start();
+
+      const links = alepha.inject(LinkProvider).getServerLinks();
+      const link = links.find((l) => l.name === "realmAction");
+
+      expect(link).toBeDefined();
+      expect(link?.secured).toEqual({ realm: "admin" });
+    });
+  });
+
+  describe("/_links endpoint with security", () => {
+    it("should return public actions to unauthenticated users", async ({
+      expect,
+    }) => {
+      class App {
+        publicAction = $action({
+          schema: { response: t.text() },
+          handler: () => "PUBLIC",
+        });
+        issuer = $issuer({
+          secret: "test",
+          roles: [{ name: "user", permissions: [{ name: "*" }] }],
+        });
+      }
+
+      const alepha = Alepha.create()
+        .with(App)
+        .with(ServerLinksProvider)
+        .with(AlephaSecurity);
+      await alepha.start();
+
+      const res = await fetch(
+        `${alepha.inject(ServerProvider).hostname}/api/_links`,
+      );
+      const data = await res.json();
+
+      expect(data.links).toContainEqual(
+        expect.objectContaining({
+          name: "publicAction",
+          path: "/publicAction",
+        }),
+      );
+    });
+
+    it("should NOT return secured actions to unauthenticated users", async ({
+      expect,
+    }) => {
+      class App {
+        securedAction = $action({
+          secure: true,
+          schema: { response: t.text() },
+          handler: () => "SECURED",
+        });
+        issuer = $issuer({
+          secret: "test",
+          roles: [{ name: "user", permissions: [{ name: "*" }] }],
+        });
+      }
+
+      const alepha = Alepha.create()
+        .with(App)
+        .with(ServerLinksProvider)
+        .with(AlephaSecurity);
+      await alepha.start();
+
+      const res = await fetch(
+        `${alepha.inject(ServerProvider).hostname}/api/_links`,
+      );
+      const data = await res.json();
+
+      expect(data.links).not.toContainEqual(
+        expect.objectContaining({
+          name: "securedAction",
+        }),
+      );
+    });
+
+    it("should return secured actions to authenticated users with permissions", async ({
+      expect,
+    }) => {
+      class App {
+        securedAction = $action({
+          secure: true,
+          schema: { response: t.text() },
+          handler: () => "SECURED",
+        });
+        issuer = $issuer({
+          secret: "test",
+          roles: [{ name: "user", permissions: [{ name: "*" }] }],
+        });
+      }
+
+      const alepha = Alepha.create()
+        .with(App)
+        .with(ServerLinksProvider)
+        .with(AlephaSecurity);
+      await alepha.start();
+
+      // Use HttpClient to get a token automatically in test mode
+      const app = alepha.inject(App);
+      const { data } = await app.securedAction.fetch(
+        {},
+        {
+          user: { id: randomUUID(), roles: ["user"] },
+        },
+      );
+      expect(data).toBe("SECURED");
+    });
+
+    it("should return both public and secured actions when user is authenticated", async ({
+      expect,
+    }) => {
+      class App {
+        publicAction = $action({
+          schema: { response: t.text() },
+          handler: () => "PUBLIC",
+        });
+        securedAction = $action({
+          secure: true,
+          schema: { response: t.text() },
+          handler: () => "SECURED",
+        });
+        issuer = $issuer({
+          secret: "test",
+          roles: [{ name: "user", permissions: [{ name: "*" }] }],
+        });
+      }
+
+      const alepha = Alepha.create()
+        .with(App)
+        .with(ServerLinksProvider)
+        .with(AlephaSecurity);
+      await alepha.start();
+
+      const linksProvider = alepha.inject(ServerLinksProvider);
+      const user = { id: randomUUID(), roles: ["user"] };
+
+      const { links } = await linksProvider.getUserApiLinks({ user });
+
+      expect(links).toContainEqual(
+        expect.objectContaining({ name: "publicAction" }),
+      );
+      expect(links).toContainEqual(
+        expect.objectContaining({ name: "securedAction" }),
+      );
+    });
+
+    it("should filter secured actions based on user permissions", async ({
+      expect,
+    }) => {
+      class App {
+        adminOnly = $action({
+          secure: true,
+          group: "admin",
+          schema: { response: t.text() },
+          handler: () => "ADMIN",
+        });
+        userAction = $action({
+          secure: true,
+          group: "user",
+          schema: { response: t.text() },
+          handler: () => "USER",
+        });
+        issuer = $issuer({
+          secret: "test",
+          roles: [
+            { name: "admin", permissions: [{ name: "*" }] },
+            { name: "user", permissions: [{ name: "user:*" }] },
+          ],
+        });
+      }
+
+      const alepha = Alepha.create()
+        .with(App)
+        .with(ServerLinksProvider)
+        .with(AlephaSecurity);
+      await alepha.start();
+
+      const linksProvider = alepha.inject(ServerLinksProvider);
+
+      // User with "user" role should only see userAction
+      const userLinks = await linksProvider.getUserApiLinks({
+        user: { id: randomUUID(), roles: ["user"] },
+      });
+
+      expect(userLinks.links).toContainEqual(
+        expect.objectContaining({ name: "userAction" }),
+      );
+      expect(userLinks.links).not.toContainEqual(
+        expect.objectContaining({ name: "adminOnly" }),
+      );
+
+      // User with "admin" role should see both
+      const adminLinks = await linksProvider.getUserApiLinks({
+        user: { id: randomUUID(), roles: ["admin"] },
+      });
+
+      expect(adminLinks.links).toContainEqual(
+        expect.objectContaining({ name: "userAction" }),
+      );
+      expect(adminLinks.links).toContainEqual(
+        expect.objectContaining({ name: "adminOnly" }),
+      );
+    });
+  });
+
+  describe("mixed public and secured actions", () => {
+    it("should correctly differentiate public from secured in server links", async ({
+      expect,
+    }) => {
+      class App {
+        getUsers = $action({
+          path: "/users",
+          schema: { response: t.array(t.text()) },
+          handler: () => ["user1", "user2"],
+        });
+        createUser = $action({
+          path: "/users",
+          secure: true,
+          schema: {
+            body: t.object({ name: t.text() }),
+            response: t.text(),
+          },
+          handler: ({ body }) => body.name,
+        });
+        deleteUser = $action({
+          method: "DELETE",
+          path: "/users/:id",
+          secure: true,
+          schema: {
+            params: t.object({ id: t.text() }),
+            response: t.void(),
+          },
+          handler: () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(App).with(ServerLinksProvider);
+      await alepha.start();
+
+      const links = alepha.inject(LinkProvider).getServerLinks();
+
+      const getUsers = links.find((l) => l.name === "getUsers");
+      const createUser = links.find((l) => l.name === "createUser");
+      const deleteUser = links.find((l) => l.name === "deleteUser");
+
+      // getUsers is public (no secure option)
+      expect(getUsers?.secured).toBeUndefined();
+
+      // createUser and deleteUser are secured
+      expect(createUser?.secured).toBe(true);
+      expect(deleteUser?.secured).toBe(true);
+    });
+  });
+});

package/src/server/links/providers/ServerLinksProvider.ts

@@ -48,7 +48,7 @@ export class ServerLinksProvider {
           group: action.group,
           schema: action.options.schema,
           requestBodyType: action.getBodyContentType(),
-          secured: action.options.secure ?? true,
+          secured: action.options.secure,
           method: action.method === "GET" ? undefined : action.method,
           prefix: action.prefix,
           path: action.path,

package/src/vite/tasks/generateCloudflare.ts

@@ -1,5 +1,8 @@
 import { access, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
+import type { Alepha } from "alepha";
+import type { CronProvider } from "alepha/scheduler";
+import type { WorkerdCronProvider } from "../../scheduler/providers/WorkerdCronProvider.ts";
 
 export interface GenerateCloudflareOptions {
   /**
@@ -13,6 +16,8 @@ export interface GenerateCloudflareOptions {
    * Additional Wrangler configuration options to merge into wrangler.jsonc.
    */
   config?: WranglerConfig;
+
+  alepha: Alepha;
 }
 
 export interface WranglerConfig {
@@ -31,7 +36,7 @@ const WARNING_COMMENT =
  * - worker.js entry point for Cloudflare Workers
  */
 export async function generateCloudflare(
-  opts: GenerateCloudflareOptions = {},
+  opts: GenerateCloudflareOptions,
 ): Promise<void> {
   const distDir = opts.distDir ?? "dist";
   const root = process.cwd();
@@ -40,6 +45,15 @@ export async function generateCloudflare(
     .then(() => true)
     .catch(() => false);
 
+  let workerdCronProvider: CronProvider | undefined;
+  try {
+    workerdCronProvider = opts.alepha.inject(
+      "CronProvider",
+    ) as WorkerdCronProvider;
+  } catch {}
+
+  const crons = workerdCronProvider?.getCronJobs();
+
   const wrangler: WranglerConfig = {
     name,
     main: "./main.cloudflare.js",
@@ -62,6 +76,12 @@ export async function generateCloudflare(
     };
   }
 
+  if (crons && crons.length > 0) {
+    const cronExpressions = [...new Set(crons.map((c) => c.expression))];
+    wrangler.triggers ??= {};
+    wrangler.triggers.crons = cronExpressions;
+  }
+
   const url = process.env.DATABASE_URL;
   if (url?.startsWith("d1:")) {
     const [name, id] = url.replace("d1://", "").replace("d1:", "").split(":");
@@ -102,7 +122,7 @@ export default {
     try {
       await __alepha.start();
     } catch (err) {
-      console.error(err);
+      console.error("Failed to start Alepha for fetch event", err);
       return new Response("Internal Server Error", { status: 500 });
     }
 
@@ -110,6 +130,22 @@ export default {
 
     return ctx.res;
   },
+
+  scheduled: async (event, env, ctx) => {
+    __alepha.set("cloudflare.env", env);
+
+    try {
+      await __alepha.start();
+    } catch (err) {
+      console.error("Failed to start Alepha for scheduled event", err);
+      throw err;
+    }
+
+    await __alepha.events.emit("cloudflare:scheduled", {
+      cron: event.cron,
+      scheduledTime: event.scheduledTime,
+    });
+  },
 };
 `.trim();