alepha 0.15.0 → 0.15.2

package/src/server/core/services/ServerRequestParser.ts

@@ -1,14 +1,32 @@
-import { $inject, Alepha } from "alepha";
+import { $env, $inject, Alepha, t } from "alepha";
 import { ServerReply } from "../helpers/ServerReply.ts";
 import type {
+  RequestGeo,
+  RequestReferer,
   ServerRequest,
   ServerRequestData,
 } from "../interfaces/ServerRequest.ts";
 import { UserAgentParser } from "./UserAgentParser.ts";
 
+const envSchema = t.object({
+  /**
+   * Trust proxy headers (X-Forwarded-For, X-Real-IP) for client IP resolution.
+   *
+   * Default: true (modern deployments are typically behind a reverse proxy)
+   *
+   * Set to false only if your server accepts direct connections without a proxy
+   * and you want to use the raw connection IP.
+   */
+  TRUST_PROXY: t.boolean({
+    default: true,
+    description: "Trust proxy headers for client IP",
+  }),
+});
+
 export class ServerRequestParser {
   protected readonly alepha = $inject(Alepha);
   protected readonly userAgentParser = $inject(UserAgentParser);
+  protected readonly env = $env(envSchema);
 
   public createServerRequest(rawRequest: ServerRequestData): ServerRequest {
     const self = this;
@@ -30,6 +48,24 @@ export class ServerRequestParser {
       get userAgent() {
         return self.getRequestUserAgent(rawRequest);
       },
+      get geo() {
+        return self.getRequestGeo(rawRequest);
+      },
+      get isBot() {
+        return self.getIsBot(rawRequest);
+      },
+      get isMobile() {
+        return self.getIsMobile(rawRequest);
+      },
+      get protocol() {
+        return self.getProtocol(rawRequest);
+      },
+      get language() {
+        return self.getLanguage(rawRequest);
+      },
+      get referer() {
+        return self.getReferer(rawRequest);
+      },
     } as ServerRequest;
   }
 
@@ -42,22 +78,279 @@ export class ServerRequestParser {
   }
 
   public getRequestIp(request: ServerRequestData): string | undefined {
-    // check for the 'x-forwarded-for' header first, which is commonly used
-    // in proxy setups to forward the original client's IP address.
+    // Only trust proxy headers when explicitly configured
+    if (this.env.TRUST_PROXY) {
+      const headers = request.headers;
+
+      // X-Forwarded-For: standard proxy header (Cloudflare, Vercel, Nginx, etc.)
+      const forwardedFor = headers["x-forwarded-for"];
+      if (forwardedFor) {
+        return Array.isArray(forwardedFor)
+          ? forwardedFor[0]
+          : forwardedFor.split(",")[0].trim();
+      }
+
+      // X-Real-IP: alternative proxy header
+      const xRealIP = headers["x-real-ip"];
+      if (xRealIP) {
+        return Array.isArray(xRealIP) ? xRealIP[0] : xRealIP;
+      }
+    }
 
-    // https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-For
+    // Default: use raw connection IP
+    return this.getConnectionIp(request);
+  }
 
-    const forwardedFor = request.headers["x-forwarded-for"];
-    if (forwardedFor) {
-      // The 'x-forwarded-for' header can contain multiple IPs, so we take the first one.
-      return Array.isArray(forwardedFor)
-        ? forwardedFor[0]
-        : forwardedFor.split(",")[0].trim();
+  protected getConnectionIp(request: ServerRequestData): string | undefined {
+    // Get IP from raw connection (Node.js socket)
+    const nodeReq = request.raw.node?.req;
+    if (nodeReq) {
+      return nodeReq.socket?.remoteAddress;
     }
+    return undefined;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Geolocation
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  public getRequestGeo(request: ServerRequestData): RequestGeo {
+    const headers = request.headers;
+
+    return {
+      // Country: Cloudflare, Vercel, AWS CloudFront
+      country:
+        headers["cf-ipcountry"] ||
+        headers["x-vercel-ip-country"] ||
+        headers["cloudfront-viewer-country"],
+
+      // City: Cloudflare, Vercel
+      city: headers["cf-ipcity"] || headers["x-vercel-ip-city"],
+
+      // Region: Cloudflare, Vercel
+      region:
+        headers["cf-region"] ||
+        headers["cf-region-code"] ||
+        headers["x-vercel-ip-country-region"],
+
+      // Coordinates: Cloudflare, Vercel
+      latitude: headers["cf-iplatitude"] || headers["x-vercel-ip-latitude"],
+      longitude: headers["cf-iplongitude"] || headers["x-vercel-ip-longitude"],
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Bot detection
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  protected static readonly BOT_PATTERNS = [
+    /bot/i,
+    /crawl/i,
+    /spider/i,
+    /slurp/i,
+    /googlebot/i,
+    /bingbot/i,
+    /yandex/i,
+    /baiduspider/i,
+    /facebookexternalhit/i,
+    /twitterbot/i,
+    /linkedinbot/i,
+    /whatsapp/i,
+    /telegrambot/i,
+    /discordbot/i,
+    /slackbot/i,
+    /applebot/i,
+    /duckduckbot/i,
+    /semrush/i,
+    /ahrefsbot/i,
+    /mj12bot/i,
+    /dotbot/i,
+    /petalbot/i,
+    /bytespider/i,
+    /gptbot/i,
+    /claudebot/i,
+    /anthropic/i,
+    /curl/i,
+    /wget/i,
+    /python-requests/i,
+    /axios/i,
+    /node-fetch/i,
+    /go-http-client/i,
+    /java\//i,
+    /libwww/i,
+    /httpunit/i,
+    /nutch/i,
+    /phpcrawl/i,
+    /biglotron/i,
+    /teoma/i,
+    /convera/i,
+    /gigablast/i,
+    /ia_archiver/i,
+    /webmon/i,
+    /httrack/i,
+    /grub\.org/i,
+    /netresearchserver/i,
+    /speedy/i,
+    /fluffy/i,
+    /findlink/i,
+    /panscient/i,
+    /ips-agent/i,
+    /yanga/i,
+    /cyberpatrol/i,
+    /postrank/i,
+    /page2rss/i,
+    /linkdex/i,
+    /ezooms/i,
+    /heritrix/i,
+    /findthatfile/i,
+    /europarchive\.org/i,
+    /mappydata/i,
+    /eright/i,
+    /apercite/i,
+    /aboundex/i,
+    /domaincrawler/i,
+    /wbsearchbot/i,
+    /summify/i,
+    /ccbot/i,
+    /edisterbot/i,
+    /seznambot/i,
+    /ec2linkfinder/i,
+    /gslfbot/i,
+    /aihitbot/i,
+    /intelium_bot/i,
+    /yeti/i,
+    /retrevopageanalyzer/i,
+    /lb-spider/i,
+    /sogou/i,
+    /lssbot/i,
+    /careerbot/i,
+    /wotbox/i,
+    /wocbot/i,
+    /ichiro/i,
+    /duckduckgo/i,
+    /lssrocketcrawler/i,
+    /drupact/i,
+    /webcompanycrawler/i,
+    /acoonbot/i,
+    /openindexspider/i,
+    /screaming frog/i,
+    /pingdom/i,
+    /uptimerobot/i,
+    /headlesschrome/i,
+    /phantomjs/i,
+    /prerender/i,
+    /lighthouse/i,
+    /pagespeed/i,
+  ];
+
+  public getIsBot(request: ServerRequestData): boolean {
+    const ua = request.headers["user-agent"];
+    if (!ua) return false;
+
+    return ServerRequestParser.BOT_PATTERNS.some((pattern) => pattern.test(ua));
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Mobile detection
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  protected static readonly MOBILE_PATTERNS = [
+    /android/i,
+    /webos/i,
+    /iphone/i,
+    /ipad/i,
+    /ipod/i,
+    /blackberry/i,
+    /iemobile/i,
+    /opera mini/i,
+    /mobile/i,
+    /tablet/i,
+    /kindle/i,
+    /silk/i,
+    /fennec/i,
+    /windows phone/i,
+    /windows ce/i,
+    /symbian/i,
+    /palm/i,
+    /webmate/i,
+  ];
+
+  public getIsMobile(request: ServerRequestData): boolean {
+    const ua = request.headers["user-agent"];
+    if (!ua) return false;
+
+    return ServerRequestParser.MOBILE_PATTERNS.some((pattern) =>
+      pattern.test(ua),
+    );
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Protocol detection
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  public getProtocol(request: ServerRequestData): "http" | "https" {
+    // Check proxy headers first
+    const forwardedProto = request.headers["x-forwarded-proto"];
+    if (forwardedProto) {
+      return forwardedProto.toLowerCase() === "https" ? "https" : "http";
+    }
+
+    // Cloudflare-specific header
+    const cfVisitorHeader = request.headers["cf-visitor"];
+    if (cfVisitorHeader) {
+      try {
+        const parsed = JSON.parse(cfVisitorHeader);
+        if (parsed.scheme === "https") return "https";
+      } catch {
+        // Ignore parse errors
+      }
+    }
+
+    // Check URL scheme
+    if (request.url.protocol === "https:") {
+      return "https";
+    }
+
+    return "http";
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Language detection
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  public getLanguage(request: ServerRequestData): string | undefined {
+    const acceptLanguage = request.headers["accept-language"];
+    if (!acceptLanguage) return undefined;
+
+    // Parse Accept-Language header
+    // Format: "en-US,en;q=0.9,fr;q=0.8"
+    const firstLang = acceptLanguage.split(",")[0];
+    if (!firstLang) return undefined;
+
+    // Remove quality value if present (e.g., "en;q=0.9" -> "en")
+    const lang = firstLang.split(";")[0].trim();
+
+    return lang || undefined;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Referer parsing
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  public getReferer(request: ServerRequestData): RequestReferer | undefined {
+    const referer = request.headers.referer || request.headers.referrer;
+    if (!referer) return undefined;
 
-    const xRealIP = request.headers["x-real-ip"];
-    if (xRealIP) {
-      return Array.isArray(xRealIP) ? xRealIP[0] : xRealIP;
+    try {
+      const url = new URL(referer);
+      return {
+        url: referer,
+        hostname: url.hostname,
+        pathname: url.pathname,
+      };
+    } catch {
+      // Invalid URL
+      return undefined;
     }
   }
 }

package/src/server/cors/index.ts

@@ -25,30 +25,16 @@ declare module "alepha/server" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Plugin for configuring CORS on the Alepha server.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * @example
- * ```ts
- * import { Alepha, $route } from "alepha";
- * import { AlephaServerCors, $cors } from "alepha/server-cors";
+ * Cross-Origin Resource Sharing configuration.
  *
- * class ApiService {
- *   // Global CORS is applied via corsOptions atom
+ * **Features:**
+ * - CORS policy definition
  *
- *   // Path-specific CORS for API routes
- *   apiCors = $cors({
- *     paths: ["/api/*"],
- *     origin: "https://app.example.com",
- *     credentials: true,
- *   });
- *
- *   route = $route({
- *     path: "/api/data",
- *     method: "POST",
- *     handler: () => ({ data: "hello" }),
- *   });
- * }
- * ```
+ * @module alepha.server.cors
  */
 export const AlephaServerCors = $module({
   name: "alepha.server.cors",

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

@@ -25,9 +25,13 @@ export const $cors = (options: CorsPrimitiveConfig): AbstractCorsPrimitive => {
 // ---------------------------------------------------------------------------------------------------------------------
 
 export interface CorsPrimitiveConfig extends Partial<CorsOptions> {
-  /** Name identifier for this CORS config (default: property key) */
+  /**
+   * Name identifier for this CORS config (default: property key).
+   */
   name?: string;
-  /** Path patterns to match (supports wildcards like /api/*) */
+  /**
+   * Path patterns to match (supports wildcards like /api/*).
+   */
   paths?: string[];
 }
 

package/src/server/health/index.ts

@@ -10,9 +10,15 @@ export * from "./schemas/healthSchema.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Plugin for Alepha Server that provides health-check endpoints.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | devops | standard | stable |
+ *
+ * Application health monitoring endpoints.
+ *
+ * **Features:**
+ * - `GET /health` endpoint
  *
- * @see {@link ServerHealthProvider}
  * @module alepha.server.health
  */
 export const AlephaServerHealth = $module({

package/src/server/helmet/index.ts

@@ -9,10 +9,18 @@ export * from "./providers/ServerHelmetProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Automatically adds important HTTP security headers to every response
- * to help protect your application from common web vulnerabilities.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
+ *
+ * HTTP security headers.
+ *
+ * **Features:**
+ * - X-Frame-Options
+ * - X-Content-Type-Options
+ * - Content-Security-Policy
+ * - Other security headers
  *
- * @see {@link ServerHelmetProvider}
  * @module alepha.server.helmet
  */
 export const AlephaServerHelmet = $module({

package/src/server/links/atoms/apiLinksAtom.ts

@@ -0,0 +1,7 @@
+import { $atom, t } from "alepha";
+import { apiLinksResponseSchema } from "../schemas/apiLinksResponseSchema.ts";
+
+export const apiLinksAtom = $atom({
+  name: "alepha.server.request.apiLinks",
+  schema: t.optional(apiLinksResponseSchema),
+});

package/src/server/links/index.browser.ts

@@ -1,4 +1,5 @@
 import { $module } from "alepha";
+import { apiLinksAtom } from "./atoms/apiLinksAtom.ts";
 import { $client } from "./primitives/$client.ts";
 import { $remote } from "./primitives/$remote.ts";
 import { LinkProvider } from "./providers/LinkProvider.ts";
@@ -14,6 +15,7 @@ export * from "./schemas/apiLinksResponseSchema.ts";
 
 export const AlephaServerLinks = $module({
   name: "alepha.server.links",
+  atoms: [apiLinksAtom],
   primitives: [$remote, $client],
   services: [LinkProvider],
 });

package/src/server/links/index.ts

@@ -1,6 +1,7 @@
 import "alepha/security";
 import { $module } from "alepha";
 import { AlephaServer } from "alepha/server";
+import { apiLinksAtom } from "./atoms/apiLinksAtom.ts";
 import { $client } from "./primitives/$client.ts";
 import { $remote } from "./primitives/$remote.ts";
 import { LinkProvider } from "./providers/LinkProvider.ts";
@@ -34,18 +35,24 @@ declare module "alepha" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides server-side link management and remote capabilities for client-server interactions.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * The server-links module enables declarative link definitions using `$remote` and `$client` primitives,
- * facilitating seamless API endpoint management and client-server communication. It integrates with server
- * security features to ensure safe and controlled access to resources.
+ * Type-safe API client with request deduplication.
+ *
+ * **Features:**
+ * - Virtual HTTP client for type-safe API calls
+ * - Remote action definitions
+ * - Type inference from action schemas
+ * - Request deduplication
+ * - Automatic error handling
  *
- * @see {@link $remote}
- * @see {@link $client}
  * @module alepha.server.links
  */
 export const AlephaServerLinks = $module({
   name: "alepha.server.links",
+  atoms: [apiLinksAtom],
   primitives: [$remote, $client],
   services: [
     AlephaServer,

package/src/server/metrics/index.ts

@@ -9,10 +9,17 @@ export * from "./providers/ServerMetricsProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * This module provides prometheus metrics for the Alepha server.
- * Metrics are exposed at the `/metrics` endpoint.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | devops | standard | stable |
+ *
+ * Prometheus-style metrics collection.
+ *
+ * **Features:**
+ * - Prometheus-style metrics
+ * - Custom metric registration
+ * - Metric exposition endpoint
  *
- * @see {@link ServerMetricsProvider}
  * @module alepha.server.metrics
  */
 export const AlephaServerMetrics = $module({

package/src/server/multipart/index.ts

@@ -9,10 +9,16 @@ export * from "./providers/ServerMultipartProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * This module provides support for handling multipart/form-data requests.
- * It allows to parse body data containing t.file().
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
+ *
+ * Multipart form data handling for file uploads.
+ *
+ * **Features:**
+ * - File upload parsing
+ * - Form field extraction
  *
- * @see {@link ServerMultipartProvider}
  * @module alepha.server.multipart
  */
 export const AlephaServerMultipart = $module({

package/src/server/proxy/index.ts

@@ -11,9 +11,15 @@ export * from "./providers/ServerProxyProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Plugin for Alepha that provides a proxy server functionality.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
+ *
+ * Reverse proxy routing.
+ *
+ * **Features:**
+ * - Proxy configuration and routing
  *
- * @see {@link $proxy}
  * @module alepha.server.proxy
  */
 export const AlephaServerProxy = $module({

package/src/server/rate-limit/index.ts

@@ -31,42 +31,38 @@ declare module "alepha/server" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 export interface RateLimitOptions {
-  /** Maximum number of requests per window (default: 100) */
+  /**
+   * Maximum number of requests per window (default: 100).
+   */
   max?: number;
-  /** Window duration in milliseconds (default: 15 minutes) */
+  /**
+   * Window duration in milliseconds (default: 15 minutes).
+   */
   windowMs?: number;
-  /** Custom key generator function */
+  /**
+   * Custom key generator function.
+   */
   keyGenerator?: (req: any) => string;
-  /** Skip rate limiting for failed requests */
+  /**
+   * Skip rate limiting for failed requests.
+   */
   skipFailedRequests?: boolean;
-  /** Skip rate limiting for successful requests */
+  /**
+   * Skip rate limiting for successful requests.
+   */
   skipSuccessfulRequests?: boolean;
 }
 
 /**
- * Provides rate limiting capabilities for server routes and actions with configurable limits and windows.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * The server-rate-limit module enables per-route and per-action rate limiting using either:
- * - The `$rateLimit` primitive with `paths` option for path-based rate limiting
- * - The `rateLimit` option in action primitives for action-specific limiting
+ * Request rate limiting on actions.
  *
- * It offers sliding window rate limiting, custom key generation, and seamless integration with server routes.
+ * **Features:**
+ * - Rate limit configuration per action
  *
- * @example
- * ```ts
- * import { $rateLimit, AlephaServerRateLimit } from "alepha/server/rate-limit";
- *
- * class ApiService {
- *   // Path-specific rate limiting
- *   apiRateLimit = $rateLimit({
- *     paths: ["/api/*"],
- *     max: 100,
- *     windowMs: 15 * 60 * 1000, // 15 minutes
- *   });
- * }
- * ```
- *
- * @see {@link $rateLimit}
  * @module alepha.server.rate-limit
  */
 export const AlephaServerRateLimit = $module({

package/src/server/rate-limit/primitives/$rateLimit.ts

@@ -41,9 +41,13 @@ export const $rateLimit = (
 // ---------------------------------------------------------------------------------------------------------------------
 
 export interface RateLimitPrimitiveOptions extends RateLimitOptions {
-  /** Name identifier for this rate limit (default: property key) */
+  /**
+   * Name identifier for this rate limit (default: property key).
+   */
   name?: string;
-  /** Path patterns to match (supports wildcards like /api/*) */
+  /**
+   * Path patterns to match (supports wildcards like /api/*).
+   */
   paths?: string[];
 }