alepha 0.15.1 → 0.15.3

package/src/react/websocket/hooks/useRoom.tsx

@@ -0,0 +1,242 @@
+import type { Static } from "alepha";
+import { useAlepha, useInject } from "alepha/react";
+import type { ChannelPrimitive, TWSObject } from "alepha/websocket";
+import { WebSocketClient } from "alepha/websocket";
+import { useEffect, useRef, useState } from "react";
+
+/**
+ * UseRoom options
+ */
+export interface UseRoomOptions<
+  TClient extends TWSObject,
+  TServer extends TWSObject,
+> {
+  /**
+   * Room ID to connect to
+   */
+  roomId: string;
+
+  /**
+   * Channel primitive defining the schemas
+   */
+  channel: ChannelPrimitive<TClient, TServer>;
+
+  /**
+   * Handler for incoming messages from the server
+   */
+  handler: (message: Static<TClient>) => void;
+
+  /**
+   * Optional WebSocket URL override
+   * Defaults to auto-detected URL based on window.location
+   */
+  url?: string;
+
+  /**
+   * Enable automatic reconnection on disconnect
+   * @default true
+   */
+  autoReconnect?: boolean;
+
+  /**
+   * Reconnection interval in milliseconds
+   * @default 3000
+   */
+  reconnectInterval?: number;
+
+  /**
+   * Maximum reconnection attempts (-1 for infinite)
+   * @default 10
+   */
+  maxReconnectAttempts?: number;
+
+  /**
+   * Called when connection is established
+   */
+  onConnect?: () => void;
+
+  /**
+   * Called when connection is closed
+   */
+  onDisconnect?: () => void;
+
+  /**
+   * Called on connection error
+   */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * UseRoom return value
+ */
+export interface UseRoomReturn<TServer extends TWSObject> {
+  /**
+   * Send a message to the server
+   */
+  send: (message: Static<TServer>) => Promise<void>;
+
+  /**
+   * Whether the connection is established
+   */
+  isConnected: boolean;
+
+  /**
+   * Whether the connection is in progress
+   */
+  isConnecting: boolean;
+
+  /**
+   * Whether there was an error
+   */
+  isError: boolean;
+
+  /**
+   * The error object if any
+   */
+  error?: Error;
+
+  /**
+   * Manually reconnect
+   */
+  reconnect: () => void;
+
+  /**
+   * Manually disconnect
+   */
+  disconnect: () => void;
+}
+
+/**
+ * React hook for WebSocket room communication
+ *
+ * Provides automatic connection management, reconnection, and type-safe messaging
+ * for WebSocket rooms using the injected WebSocketClient service.
+ *
+ * Multiple useRoom hooks on the same channel will share a single WebSocket connection.
+ *
+ * @example
+ * ```tsx
+ * const chat = useRoom({
+ *   roomId: "room-123",
+ *   channel: chatChannel,
+ *   handler: (message) => {
+ *     if (message.type === "append") {
+ *       setMessages(prev => [...prev, message]);
+ *     }
+ *   }
+ * }, [roomId]);
+ *
+ * const sendMessage = async () => {
+ *   await chat.send({
+ *     content: "Hello, world!"
+ *   });
+ * };
+ * ```
+ */
+export const useRoom = <TClient extends TWSObject, TServer extends TWSObject>(
+  options: UseRoomOptions<TClient, TServer>,
+  deps: unknown[],
+): UseRoomReturn<TServer> => {
+  const webSocketClient = useInject(WebSocketClient);
+  const unsubscribeRef = useRef<(() => void) | null>(null);
+
+  const [isConnected, setIsConnected] = useState(false);
+  const [isConnecting, setIsConnecting] = useState(false);
+  const [isError, setIsError] = useState(false);
+  const [error, setError] = useState<Error | undefined>(undefined);
+
+  const {
+    roomId,
+    channel,
+    handler,
+    url,
+    autoReconnect,
+    reconnectInterval,
+    maxReconnectAttempts,
+    onConnect,
+    onDisconnect,
+    onError,
+  } = options;
+
+  useEffect(() => {
+    // Subscribe to room
+    const unsubscribe = webSocketClient.subscribe(roomId, channel, handler, {
+      url,
+      autoReconnect,
+      reconnectInterval,
+      maxReconnectAttempts,
+      onConnect: () => {
+        setIsConnected(true);
+        setIsConnecting(false);
+        setIsError(false);
+        setError(undefined);
+        onConnect?.();
+      },
+      onDisconnect: () => {
+        setIsConnected(false);
+        setIsConnecting(false);
+        onDisconnect?.();
+      },
+      onError: (err) => {
+        setIsError(true);
+        setError(err);
+        setIsConnecting(false);
+        onError?.(err);
+      },
+    });
+
+    unsubscribeRef.current = unsubscribe;
+
+    // Get initial state from connection
+    const connection = webSocketClient.getConnection(channel);
+    if (connection) {
+      setIsConnected(connection.isConnected);
+      setIsConnecting(connection.isConnecting);
+      setIsError(connection.isError);
+      setError(connection.error);
+    }
+
+    // Cleanup on unmount or deps change
+    return () => {
+      unsubscribe();
+      unsubscribeRef.current = null;
+    };
+  }, deps);
+
+  const alepha = useAlepha();
+
+  if (!alepha.isBrowser()) {
+    return {
+      send: async (_message: Static<TServer>) => {
+        // No-op on server
+      },
+      isConnected: false,
+      isConnecting: false,
+      isError: false,
+      error: undefined,
+      reconnect: () => {
+        // No-op on server
+      },
+      disconnect: () => {
+        // No-op on server
+      },
+    };
+  }
+
+  return {
+    send: async (message: Static<TServer>) => {
+      await webSocketClient.send(roomId, channel, message);
+    },
+    isConnected,
+    isConnecting,
+    isError,
+    error,
+    reconnect: () => {
+      const connection = webSocketClient.getConnection(channel);
+      connection?.reconnect();
+    },
+    disconnect: () => {
+      unsubscribeRef.current?.();
+    },
+  };
+};

package/src/react/websocket/index.ts

@@ -0,0 +1,7 @@
+/**
+ * alepha/react/websocket
+ *
+ * React hooks for real-time WebSocket communication
+ */
+
+export * from "./hooks/useRoom.tsx";

package/src/redis/__tests__/redis.spec.ts

@@ -55,4 +55,17 @@ describe("Redis", () => {
     await redis.lpush("test:b", "b");
     await alepha.stop();
   });
+
+  it("should increment values atomically", async ({ expect }) => {
+    const key = `test:incr:${randomUUID()}`;
+
+    const val1 = await redis.incr(key, 1);
+    expect(val1).toBe(1);
+
+    const val2 = await redis.incr(key, 5);
+    expect(val2).toBe(6);
+
+    const val3 = await redis.incr(key, -2);
+    expect(val3).toBe(4);
+  });
 });

package/src/redis/index.ts

@@ -18,34 +18,18 @@ export * from "./providers/RedisSubscriberProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Redis client provider for Alepha applications.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * Automatically selects the appropriate provider based on runtime:
- * - Bun: Uses `BunRedisProvider` with Bun's native Redis client (7.9x faster than ioredis)
- * - Node.js: Uses `NodeRedisProvider` with `@redis/client`
+ * Redis client wrapper.
  *
- * @example
- * ```ts
- * // Inject the abstract provider - runtime selects the implementation
- * const redis = alepha.inject(RedisProvider);
+ * **Features:**
+ * - Connection pooling
+ * - Automatic reconnection
+ * - Command pipelining
+ * - Pub/sub support
  *
- * // Use common operations
- * await redis.set("key", "value");
- * const value = await redis.get("key");
- *
- * // For pub/sub
- * const subscriber = alepha.inject(RedisSubscriberProvider);
- * await subscriber.subscribe("channel", (message, channel) => {
- *   console.log(`Received: ${message} on ${channel}`);
- * });
- * ```
- *
- * @see {@link RedisProvider} - Abstract base class
- * @see {@link NodeRedisProvider} - Node.js implementation
- * @see {@link BunRedisProvider} - Bun implementation
- * @see {@link RedisSubscriberProvider} - Abstract subscriber base class
- * @see {@link NodeRedisSubscriberProvider} - Node.js subscriber implementation
- * @see {@link BunRedisSubscriberProvider} - Bun subscriber implementation
  * @module alepha.redis
  */
 export const AlephaRedis = $module({

package/src/redis/providers/BunRedisProvider.ts

@@ -264,6 +264,15 @@ export class BunRedisProvider extends RedisProvider {
     await this.publisher.publish(channel, message);
   }
 
+  // ---------------------------------------------------------
+  // Counter operations
+  // ---------------------------------------------------------
+
+  public override async incr(key: string, amount: number): Promise<number> {
+    const result = await this.publisher.send("INCRBY", [key, String(amount)]);
+    return Number(result);
+  }
+
   /**
    * Get the Redis connection URL.
    */

package/src/redis/providers/NodeRedisProvider.ts

@@ -233,6 +233,14 @@ export class NodeRedisProvider extends RedisProvider {
     await this.publisher.publish(channel, message);
   }
 
+  // ---------------------------------------------------------
+  // Counter operations
+  // ---------------------------------------------------------
+
+  public override async incr(key: string, amount: number): Promise<number> {
+    return this.publisher.INCRBY(key, amount);
+  }
+
   /**
    * Get the Redis connection URL.
    */

package/src/redis/providers/RedisProvider.ts

@@ -108,6 +108,22 @@ export abstract class RedisProvider {
    * @param message The message to publish.
    */
   public abstract publish(channel: string, message: string): Promise<void>;
+
+  // ---------------------------------------------------------
+  // Counter operations
+  // ---------------------------------------------------------
+
+  /**
+   * Increment the integer value of a key by the given amount.
+   *
+   * If the key does not exist, it is set to 0 before performing the operation.
+   * This operation is atomic.
+   *
+   * @param key The key to increment.
+   * @param amount The amount to increment by.
+   * @returns The new value after incrementing.
+   */
+  public abstract incr(key: string, amount: number): Promise<number>;
 }
 
 /**

package/src/retry/index.ts

@@ -12,9 +12,18 @@ export * from "./providers/RetryProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Retry mechanism provider for Alepha applications.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
+ *
+ * Automatic retry with backoff.
+ *
+ * **Features:**
+ * - Retry configuration
+ * - Exponential backoff
+ * - Max retry limits
+ * - Custom retry predicates
  *
- * @see {@link RetryProvider}
  * @module alepha.retry
  */
 export const AlephaRetry = $module({

package/src/router/index.ts

@@ -1 +1,16 @@
+/**
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | frontend | standard | stable |
+ *
+ * Frontend routing infrastructure.
+ *
+ * **Features:**
+ * - Route state management
+ * - Navigation methods
+ * - Route matching
+ *
+ * @module alepha.router
+ */
+
 export * from "./providers/RouterProvider.ts";

package/src/scheduler/index.ts

@@ -35,9 +35,18 @@ declare module "alepha" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Generic interface for scheduling tasks.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | rare | stable |
+ *
+ * Cron and interval-based task execution.
+ *
+ * **Features:**
+ * - Scheduled tasks with cron expressions (e.g., `0 0 * * *`)
+ * - Interval-based scheduling
+ * - Distributed locking to prevent duplicate execution
+ * - Lifecycle hooks: `begin`, `success`, `error`, `end`
  *
- * @see {@link $scheduler}
  * @module alepha.scheduler
  */
 export const AlephaScheduler = $module({

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

@@ -24,6 +24,7 @@ describe("Basic Authentication", () => {
 
     // Action without basic auth
     publicAction = $action({
+      secure: false,
       handler: () => "public success",
     });
 
@@ -48,6 +49,7 @@ describe("Basic Authentication", () => {
     });
 
     customAuthAction = $action({
+      secure: false,
       handler: async (request) => {
         this.customAuth.check(request);
         return "custom auth success";

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",
       });
     }
@@ -23,16 +24,24 @@ describe("ServerSecurityProvider", () => {
     const app = alepha.inject(TestApp);
     await alepha.start();
 
-    // in testing environment, .run() a dummy user is created
-    expect(await app.ok.run({})).toBe("OK");
-
-    // but you can force empty user
+    await expect(app.ok.run({})).rejects.toThrowError(UnauthorizedError);
     await expect(app.ok.run({}, { user: undefined })).rejects.toThrowError(
       UnauthorizedError,
     );
 
     // .fetch() will also generates a dummy user in testing environment
-    expect(await app.ok.fetch({}).then((it) => it.data)).toBe("OK");
+    expect(
+      await app.ok
+        .fetch(
+          {},
+          {
+            user: {
+              id: randomUUID(),
+            },
+          },
+        )
+        .then((it) => it.data),
+    ).toBe("OK");
 
     // but you can also force empty user
     await expect(app.ok.fetch({}, { user: undefined })).rejects.toThrowError(
@@ -55,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",
       });
@@ -120,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/index.ts

@@ -15,6 +15,7 @@ import type { UserAccount } from "./schemas/userAccountInfoSchema.ts";
 export * from "./errors/InvalidCredentialsError.ts";
 export * from "./errors/InvalidPermissionError.ts";
 export * from "./errors/SecurityError.ts";
+export * from "./interfaces/IssuerResolver.ts";
 export * from "./interfaces/UserAccountToken.ts";
 export * from "./primitives/$basicAuth.ts";
 export * from "./primitives/$issuer.ts";
@@ -88,19 +89,23 @@ declare module "alepha/server" {
 }
 
 /**
- * Provides comprehensive authentication and authorization capabilities with JWT tokens, role-based access control, and user management.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | epic | stable |
  *
- * The security module enables building secure applications using primitives like `$issuer`, `$role`, and `$permission`
- * on class properties. It offers JWT-based authentication, fine-grained permissions, service accounts, and seamless
- * integration with various authentication providers and user management systems.
+ * Complete authentication and authorization system with JWT, RBAC, and multi-issuer support.
  *
- * When used with `AlephaServer`, this module automatically registers `ServerSecurityProvider` and `ServerBasicAuthProvider`
- * to protect HTTP routes and actions with JWT and Basic Auth.
+ * **Features:**
+ * - JWT token issuer with role definitions
+ * - Role-based access control (RBAC)
+ * - Fine-grained permissions
+ * - HTTP Basic Authentication
+ * - Service-to-service authentication
+ * - Multi-issuer support for federated auth
+ * - JWKS (JSON Web Key Set) for external issuers
+ * - Token refresh logic
+ * - User profile extraction from JWT
  *
- * @see {@link $issuer}
- * @see {@link $role}
- * @see {@link $permission}
- * @see {@link $basicAuth}
  * @module alepha.security
  */
 export const AlephaSecurity = $module({

package/src/security/interfaces/IssuerResolver.ts

@@ -0,0 +1,27 @@
+import type { ServerRequest } from "alepha/server";
+import type { UserAccount } from "../schemas/userAccountInfoSchema.ts";
+
+/**
+ * User info that a resolver returns.
+ * This is the input to `SecurityProvider.createUser()`.
+ */
+export type UserInfo = Omit<UserAccount, "sessionId"> & {
+  sessionId?: string;
+};
+
+/**
+ * Resolver definition for authenticating users from requests.
+ */
+export interface IssuerResolver {
+  /**
+   * Priority (lower = first). Default: 100
+   */
+  priority?: number;
+
+  /**
+   * Resolve user from HTTP request.
+   * Return UserInfo if authenticated, null to try next resolver.
+   * Throw UnauthorizedError to stop chain.
+   */
+  onRequest: (req: ServerRequest) => Promise<UserInfo | null>;
+}