alepha 0.15.1 → 0.15.3

package/src/server/rate-limit/providers/ServerRateLimitProvider.spec.ts

@@ -83,29 +83,53 @@ describe("ServerRateLimitProvider", () => {
     expect(result2.allowed).toBe(true);
   });
 
-  it("should extract IP from x-forwarded-for header", async () => {
+  it("should use req.ip for rate limiting (trust proxy handled by ServerRequestParser)", async () => {
     const options = { max: 1, windowMs: 60000 };
 
-    // First request with x-forwarded-for: 203.0.113.1
-    const req1 = createMockRequest("127.0.0.1");
-    req1.headers["x-forwarded-for"] = "203.0.113.1, 192.168.1.1";
-
+    // Rate limit uses req.ip which is resolved by ServerRequestParser
+    // Trust proxy configuration is at server level via TRUST_PROXY env var
+    const req1 = createMockRequest("192.168.1.100");
     const result1 = await provider.checkLimit(req1, options);
     expect(result1.allowed).toBe(true);
 
-    // Second request with same x-forwarded-for should be blocked
-    const req2 = createMockRequest("127.0.0.1");
-    req2.headers["x-forwarded-for"] = "203.0.113.1, 192.168.1.1";
-
+    // Same IP should be blocked
+    const req2 = createMockRequest("192.168.1.100");
     const result2 = await provider.checkLimit(req2, options);
     expect(result2.allowed).toBe(false);
+  });
+
+  it("should handle truly concurrent requests atomically", async () => {
+    const options = { max: 3, windowMs: 60000 };
+
+    // Fire 5 requests concurrently from the same IP
+    const requests = Array.from({ length: 5 }, () =>
+      createMockRequest("10.0.0.1"),
+    );
+    const results = await Promise.all(
+      requests.map((req) => provider.checkLimit(req, options)),
+    );
+
+    // Exactly 3 should be allowed, 2 should be blocked
+    const allowed = results.filter((r) => r.allowed).length;
+    const blocked = results.filter((r) => !r.allowed).length;
+
+    expect(allowed).toBe(3);
+    expect(blocked).toBe(2);
+  });
+
+  it("should return correct resetTime within the fixed window", async () => {
+    const windowMs = 60000;
+    const options = { max: 10, windowMs };
+    const req = createMockRequest();
+
+    const result = await provider.checkLimit(req, options);
 
-    // Request with different x-forwarded-for should be allowed
-    const req3 = createMockRequest("127.0.0.1");
-    req3.headers["x-forwarded-for"] = "198.51.100.1, 192.168.1.1";
+    // resetTime should be at the end of the current window
+    const now = Date.now();
+    const windowStart = Math.floor(now / windowMs) * windowMs;
+    const expectedResetTime = windowStart + windowMs;
 
-    const result3 = await provider.checkLimit(req3, options);
-    expect(result3.allowed).toBe(true);
+    expect(result.resetTime).toBe(expectedResetTime);
   });
 });
 

package/src/server/rate-limit/providers/ServerRateLimitProvider.ts

@@ -1,5 +1,5 @@
 import { $atom, $env, $hook, $inject, $use, type Static, t } from "alepha";
-import { $cache } from "alepha/cache";
+import { CacheProvider } from "alepha/cache";
 import { $logger } from "alepha/logger";
 import {
   HttpError,
@@ -74,14 +74,11 @@ export class ServerRateLimitProvider {
   protected readonly log = $logger();
   protected readonly serverRouterProvider = $inject(ServerRouterProvider);
   protected readonly env = $env(envSchema);
-
-  protected readonly cache = $cache<RateLimitData>({
-    name: "server-rate-limit",
-    ttl: [this.env.RATE_LIMIT_WINDOW_MS, "milliseconds"],
-  });
-
+  protected readonly cacheProvider = $inject(CacheProvider);
   protected readonly globalOptions = $use(rateLimitOptions);
 
+  protected static readonly CACHE_NAME = "rate-limit";
+
   /**
    * Registered rate limit configurations with their path patterns
    */
@@ -210,42 +207,30 @@ export class ServerRateLimitProvider {
   ): Promise<RateLimitResult> {
     const windowMs = options.windowMs ?? this.env.RATE_LIMIT_WINDOW_MS;
     const max = options.max ?? this.env.RATE_LIMIT_MAX_REQUESTS;
-    const key = this.generateKey(req);
+    const baseKey = this.generateKey(req);
 
     const now = Date.now();
-    const windowStart = now - windowMs;
-
-    // Get current rate limit data
-    const currentData = (await this.cache.get(key)) || {
-      count: 0,
-      windowStart: now,
-      hits: [],
-    };
-
-    // Clean old hits outside the current window
-    const validHits = currentData.hits.filter(
-      (hit: number) => hit >= windowStart,
+    // Fixed window: round down to nearest window boundary
+    const windowStart = Math.floor(now / windowMs) * windowMs;
+    const resetTime = windowStart + windowMs;
+
+    // Include window timestamp in key for automatic expiration of old windows
+    const key = `${baseKey}:${windowStart}`;
+
+    // Atomic increment - returns the new count after incrementing
+    const count = await this.cacheProvider.incr(
+      ServerRateLimitProvider.CACHE_NAME,
+      key,
+      1,
     );
 
-    // Check if limit exceeded
-    const allowed = validHits.length < max;
-    const remaining = Math.max(0, max - validHits.length);
-    const resetTime = Math.max(...validHits, windowStart) + windowMs;
-
-    // If allowed, record this request
-    if (allowed) {
-      validHits.push(now);
-      await this.cache.set(key, {
-        count: validHits.length,
-        windowStart: Math.min(currentData.windowStart, windowStart),
-        hits: validHits,
-      });
-    }
+    const allowed = count <= max;
+    const remaining = Math.max(0, max - count);
 
     const result: RateLimitResult = {
       allowed,
       limit: max,
-      remaining: allowed ? remaining - 1 : remaining,
+      remaining,
       resetTime,
     };
 
@@ -257,26 +242,7 @@ export class ServerRateLimitProvider {
   }
 
   protected generateKey(req: ServerRequest): string {
-    // Default to IP-based rate limiting
-    const ip = this.getClientIP(req);
-    return `ip:${ip}`;
+    // Use req.ip which is resolved by ServerRequestParser with proper trust proxy handling
+    return `ip:${req.ip || "unknown"}`;
   }
-
-  protected getClientIP(req: ServerRequest): string {
-    // Check x-forwarded-for header first (for proxies/load balancers)
-    const forwarded = req.headers?.["x-forwarded-for"];
-    if (forwarded) {
-      // x-forwarded-for can contain multiple IPs, get the first one (original client)
-      const firstIp = forwarded.split(",")[0].trim();
-      if (firstIp) return firstIp;
-    }
-
-    return req.ip || "unknown";
-  }
-}
-
-interface RateLimitData {
-  count: number;
-  windowStart: number;
-  hits: number[];
 }

package/src/server/static/index.ts

@@ -11,9 +11,15 @@ export * from "./providers/ServerStaticProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Create static file server with `$static()`.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
+ *
+ * Static file serving.
+ *
+ * **Features:**
+ * - Serve static files from directory
  *
- * @see {@link ServerStaticProvider}
  * @module alepha.server.static
  */
 export const AlephaServerStatic = $module({

package/src/server/static/providers/ServerStaticProvider.ts

@@ -4,9 +4,9 @@ import { basename, isAbsolute, join } from "node:path";
 import type { Readable as NodeStream } from "node:stream";
 import { $hook, $inject, Alepha } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
-import { FileDetector } from "alepha/file";
 import { $logger } from "alepha/logger";
 import { type ServerHandler, ServerRouterProvider } from "alepha/server";
+import { FileDetector } from "alepha/system";
 import { $serve, type ServePrimitiveOptions } from "../primitives/$serve.ts";
 
 export class ServerStaticProvider {

package/src/server/swagger/index.ts

@@ -30,11 +30,16 @@ declare module "alepha/server" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Plugin for Alepha Server that provides Swagger documentation capabilities.
- * It generates OpenAPI v3 documentation for the server's endpoints ($action).
- * It also provides a Swagger UI for interactive API documentation.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
+ *
+ * Automatic API documentation generation.
+ *
+ * **Features:**
+ * - Swagger/OpenAPI configuration
+ * - Routes: `GET /swagger/ui`, `GET /swagger.json`
  *
- * @see {@link ServerSwaggerProvider}
  * @module alepha.server.swagger
  */
 export const AlephaServerSwagger = $module({

package/src/server/swagger/providers/ServerSwaggerProvider.ts

@@ -12,7 +12,6 @@ import {
   type TSchema,
   t,
 } from "alepha";
-import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
 import { AlephaSecurity } from "alepha/security";
 import {
@@ -23,6 +22,7 @@ import {
   ServerRouterProvider,
 } from "alepha/server";
 import { ServerStaticProvider } from "alepha/server/static";
+import { FileSystemProvider } from "alepha/system";
 import {
   $swagger,
   type OpenApiDocument,

package/src/sms/index.ts

@@ -34,13 +34,17 @@ declare module "alepha" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides SMS sending capabilities for Alepha applications with multiple provider backends.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | rare | stable |
  *
- * The SMS module enables declarative SMS sending through the `$sms` primitive, allowing you to send
- * text messages through different providers: memory (for testing) or local file system.
- * It supports automatic provider selection based on environment configuration.
+ * SMS delivery with multiple provider support.
+ *
+ * **Features:**
+ * - Send SMS with templates
+ * - Multiple recipients
+ * - Provider abstraction
  *
- * @see {@link SmsProvider}
  * @module alepha.sms
  */
 export const AlephaSms = $module({

package/src/sms/providers/LocalSmsProvider.spec.ts

@@ -1,5 +1,5 @@
 import { Alepha } from "alepha";
-import { FileSystemProvider, MemoryFileSystemProvider } from "alepha/file";
+import { FileSystemProvider, MemoryFileSystemProvider } from "alepha/system";
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import { SmsError } from "../errors/SmsError.ts";
 import { LocalSmsProvider } from "./LocalSmsProvider.ts";

package/src/sms/providers/LocalSmsProvider.ts

@@ -1,6 +1,6 @@
 import { $inject } from "alepha";
-import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
+import { FileSystemProvider } from "alepha/system";
 import { SmsError } from "../errors/SmsError.ts";
 import type { SmsProvider, SmsSendOptions } from "./SmsProvider.ts";
 

package/src/system/index.browser.ts

@@ -0,0 +1,36 @@
+import { $module } from "alepha";
+import { FileSystemProvider } from "./providers/FileSystemProvider.ts";
+import { MemoryFileSystemProvider } from "./providers/MemoryFileSystemProvider.ts";
+import { MemoryShellProvider } from "./providers/MemoryShellProvider.ts";
+import { ShellProvider } from "./providers/ShellProvider.ts";
+import { FileDetector } from "./services/FileDetector.ts";
+
+export * from "./errors/FileError.ts";
+export * from "./providers/FileSystemProvider.ts";
+export * from "./providers/MemoryFileSystemProvider.ts";
+export * from "./providers/MemoryShellProvider.ts";
+export * from "./providers/ShellProvider.ts";
+export * from "./services/FileDetector.ts";
+
+export const AlephaSystem = $module({
+  name: "alepha.system",
+  services: [
+    FileDetector,
+    FileSystemProvider,
+    MemoryFileSystemProvider,
+    ShellProvider,
+    MemoryShellProvider,
+  ],
+  register: (alepha) =>
+    alepha
+      .with({
+        optional: true,
+        provide: FileSystemProvider,
+        use: MemoryFileSystemProvider,
+      })
+      .with({
+        optional: true,
+        provide: ShellProvider,
+        use: MemoryShellProvider,
+      }),
+});

package/src/system/index.ts

@@ -0,0 +1,62 @@
+import { $module } from "alepha";
+import { FileSystemProvider } from "./providers/FileSystemProvider.ts";
+import { MemoryFileSystemProvider } from "./providers/MemoryFileSystemProvider.ts";
+import { MemoryShellProvider } from "./providers/MemoryShellProvider.ts";
+import { NodeFileSystemProvider } from "./providers/NodeFileSystemProvider.ts";
+import { NodeShellProvider } from "./providers/NodeShellProvider.ts";
+import { ShellProvider } from "./providers/ShellProvider.ts";
+import { FileDetector } from "./services/FileDetector.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./errors/FileError.ts";
+export * from "./providers/FileSystemProvider.ts";
+export * from "./providers/MemoryFileSystemProvider.ts";
+export * from "./providers/MemoryShellProvider.ts";
+export * from "./providers/NodeFileSystemProvider.ts";
+export * from "./providers/NodeShellProvider.ts";
+export * from "./providers/ShellProvider.ts";
+export * from "./services/FileDetector.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | tooling | standard | stable |
+ *
+ * System-level abstractions for portable code across runtimes.
+ *
+ * **Features:**
+ * - File system operations (read, write, exists, etc.)
+ * - Shell command execution
+ * - File type detection and MIME utilities
+ * - Memory implementations for testing
+ *
+ * @module alepha.system
+ */
+export const AlephaSystem = $module({
+  name: "alepha.system",
+  primitives: [],
+  services: [
+    FileDetector,
+    FileSystemProvider,
+    MemoryFileSystemProvider,
+    NodeFileSystemProvider,
+    ShellProvider,
+    MemoryShellProvider,
+    NodeShellProvider,
+  ],
+  register: (alepha) =>
+    alepha
+      .with({
+        optional: true,
+        provide: FileSystemProvider,
+        use: NodeFileSystemProvider,
+      })
+      .with({
+        optional: true,
+        provide: ShellProvider,
+        use: alepha.isTest() ? MemoryShellProvider : NodeShellProvider,
+      }),
+});

package/src/system/index.workerd.ts

@@ -0,0 +1 @@
+export * from "./index.browser.ts";

package/src/{file → system}/providers/FileSystemProvider.ts

@@ -196,8 +196,16 @@ export interface CpOptions {
 export interface MkdirOptions {
   /**
    * If true, creates parent directories as needed
+   *
+   * @default true
    */
   recursive?: boolean;
+  /**
+   * If true, does not throw an error if the directory already exists
+   *
+   * @default true
+   */
+  force?: boolean;
   /**
    * File mode (permission and sticky bits)
    */
@@ -306,4 +314,20 @@ export abstract class FileSystemProvider {
     path: string,
     data: Uint8Array | Buffer | string | FileLike,
   ): Promise<void>;
+
+  /**
+   * Reads the content of a file as a string.
+   *
+   * @param path - The file path to read
+   * @returns The file content as a string
+   */
+  abstract readTextFile(path: string): Promise<string>;
+
+  /**
+   * Reads the content of a file as JSON.
+   *
+   * @param path - The file path to read
+   * @returns The parsed JSON content
+   */
+  abstract readJsonFile<T = unknown>(path: string): Promise<T>;
 }

package/src/{file → system}/providers/MemoryFileSystemProvider.ts

@@ -1,4 +1,5 @@
-import type { FileLike } from "alepha";
+import { join as nodeJoin } from "node:path";
+import { $inject, type FileLike, Json } from "alepha";
 import type {
   CpOptions,
   CreateFileOptions,
@@ -51,6 +52,8 @@ export interface MemoryFileSystemProviderOptions {
  * ```
  */
 export class MemoryFileSystemProvider implements FileSystemProvider {
+  protected json = $inject(Json);
+
   /**
    * In-memory storage for files (path -> content)
    */
@@ -71,6 +74,16 @@ export class MemoryFileSystemProvider implements FileSystemProvider {
    */
   public writeFileCalls: Array<{ path: string; data: string }> = [];
 
+  /**
+   * Track readFile calls for test assertions
+   */
+  public readFileCalls: Array<string> = [];
+
+  /**
+   * Track rm calls for test assertions
+   */
+  public rmCalls: Array<{ path: string; options?: RmOptions }> = [];
+
   /**
    * Track join calls for test assertions
    */
@@ -99,17 +112,42 @@ export class MemoryFileSystemProvider implements FileSystemProvider {
 
   /**
    * Join path segments using forward slashes.
+   * Uses Node's path.join for proper normalization (handles .. and .)
    */
   public join(...paths: string[]): string {
     this.joinCalls.push(paths);
-    // Simple path join - normalize and join with /
-    return paths.filter(Boolean).join("/").replace(/\/+/g, "/");
+    return nodeJoin(...paths);
   }
 
   /**
    * Create a FileLike object from various sources.
    */
   public createFile(options: CreateFileOptions): FileLike {
+    if ("path" in options) {
+      const filePath = options.path;
+      const buffer = this.files.get(filePath);
+      if (buffer === undefined) {
+        throw new Error(
+          `ENOENT: no such file or directory, open '${filePath}'`,
+        );
+      }
+      return {
+        name: options.name ?? filePath.split("/").pop() ?? "file",
+        type: options.type ?? "application/octet-stream",
+        size: buffer.byteLength,
+        lastModified: Date.now(),
+        stream: () => {
+          throw new Error("Stream not implemented in MemoryFileSystemProvider");
+        },
+        arrayBuffer: async (): Promise<ArrayBuffer> =>
+          buffer.buffer.slice(
+            buffer.byteOffset,
+            buffer.byteOffset + buffer.byteLength,
+          ) as ArrayBuffer,
+        text: async () => buffer.toString("utf-8"),
+      };
+    }
+
     if ("buffer" in options) {
       const buffer = options.buffer;
       return {
@@ -157,6 +195,8 @@ export class MemoryFileSystemProvider implements FileSystemProvider {
    * Remove a file or directory from memory.
    */
   public async rm(path: string, options?: RmOptions): Promise<void> {
+    this.rmCalls.push({ path, options });
+
     const exists = this.files.has(path) || this.directories.has(path);
 
     if (!exists && !options?.force) {
@@ -327,6 +367,8 @@ export class MemoryFileSystemProvider implements FileSystemProvider {
    * Read a file from memory.
    */
   public async readFile(path: string): Promise<Buffer> {
+    this.readFileCalls.push(path);
+
     if (this.readFileError) {
       throw this.readFileError;
     }
@@ -338,6 +380,22 @@ export class MemoryFileSystemProvider implements FileSystemProvider {
     return content;
   }
 
+  /**
+   * Read a file from memory as text.
+   */
+  public async readTextFile(path: string): Promise<string> {
+    const buffer = await this.readFile(path);
+    return buffer.toString("utf-8");
+  }
+
+  /**
+   * Read a file from memory as JSON.
+   */
+  public async readJsonFile<T = unknown>(path: string): Promise<T> {
+    const text = await this.readTextFile(path);
+    return this.json.parse(text) as T;
+  }
+
   /**
    * Write a file to memory.
    */
@@ -378,12 +436,67 @@ export class MemoryFileSystemProvider implements FileSystemProvider {
     this.directories.clear();
     this.mkdirCalls = [];
     this.writeFileCalls = [];
+    this.readFileCalls = [];
+    this.rmCalls = [];
     this.joinCalls = [];
     this.mkdirError = null;
     this.writeFileError = null;
     this.readFileError = null;
   }
 
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Test assertion helpers
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Check if a file was written during the test.
+   *
+   * @example
+   * ```typescript
+   * expect(fs.wasWritten("/project/tsconfig.json")).toBe(true);
+   * ```
+   */
+  public wasWritten(path: string): boolean {
+    return this.writeFileCalls.some((call) => call.path === path);
+  }
+
+  /**
+   * Check if a file was written with content matching a pattern.
+   *
+   * @example
+   * ```typescript
+   * expect(fs.wasWrittenMatching("/project/tsconfig.json", /extends/)).toBe(true);
+   * ```
+   */
+  public wasWrittenMatching(path: string, pattern: RegExp): boolean {
+    const call = this.writeFileCalls.find((c) => c.path === path);
+    return call ? pattern.test(call.data) : false;
+  }
+
+  /**
+   * Check if a file was read during the test.
+   *
+   * @example
+   * ```typescript
+   * expect(fs.wasRead("/project/package.json")).toBe(true);
+   * ```
+   */
+  public wasRead(path: string): boolean {
+    return this.readFileCalls.includes(path);
+  }
+
+  /**
+   * Check if a file was deleted during the test.
+   *
+   * @example
+   * ```typescript
+   * expect(fs.wasDeleted("/project/old-file.txt")).toBe(true);
+   * ```
+   */
+  public wasDeleted(path: string): boolean {
+    return this.rmCalls.some((call) => call.path === path);
+  }
+
   /**
    * Get the content of a file as a string (convenience method for testing).
    */