jiren 1.4.5 → 1.5.0

package/components/index.ts

@@ -26,6 +26,9 @@ export type {
   ErrorInterceptor,
   InterceptorRequestContext,
   InterceptorResponseContext,
+  EndpointMetrics,
+  GlobalMetrics,
+  MetricsAPI,
 } from "./types";
 
 // Remove broken exports

package/components/metrics.ts

@@ -0,0 +1,420 @@
+/**
+ * Metrics & Observability System for Jiren HTTP Client
+ * Tracks performance, cache efficiency, errors, and request statistics
+ */
+
+export interface EndpointMetrics {
+  endpoint: string;
+  requests: {
+    total: number;
+    success: number;
+    failed: number;
+  };
+  statusCodes: Record<number, number>;
+  timing: {
+    avgMs: number;
+    minMs: number;
+    maxMs: number;
+    p50Ms: number;
+    p95Ms: number;
+    p99Ms: number;
+  };
+  cache: {
+    l1Hits: number;
+    l1Misses: number;
+    l2Hits: number;
+    l2Misses: number;
+    hitRate: string; // e.g., "75.5%"
+  };
+  deduplication: {
+    hits: number;
+    misses: number;
+    hitRate: string;
+  };
+  bytes: {
+    sent: number;
+    received: number;
+  };
+  errors: Record<string, number>;
+  lastRequestAt: number | null;
+}
+
+export interface GlobalMetrics {
+  totalRequests: number;
+  totalSuccess: number;
+  totalFailed: number;
+  avgResponseTimeMs: number;
+  totalBytesSent: number;
+  totalBytesReceived: number;
+  overallCacheHitRate: string;
+  overallDeduplicationRate: string;
+  endpoints: number;
+  uptime: number; // milliseconds since client creation
+}
+
+export interface MetricsAPI {
+  get(endpoint: string): EndpointMetrics | null;
+  getAll(): Record<string, EndpointMetrics>;
+  getGlobal(): GlobalMetrics;
+  reset(endpoint?: string): void;
+  export(): string; // JSON string
+}
+
+interface RequestMetric {
+  startTime: number;
+  responseTimeMs: number;
+  status: number;
+  success: boolean;
+  bytesSent: number;
+  bytesReceived: number;
+  cacheHit: boolean;
+  cacheLayer?: "l1" | "l2"; // Which cache layer hit
+  dedupeHit: boolean;
+  error?: string;
+}
+
+class EndpointMetricsCollector {
+  private endpoint: string;
+  private requestHistory: RequestMetric[] = [];
+  private maxHistorySize = 10000; // Keep last 10k requests for percentile calculations
+
+  // Aggregated counters
+  private totalRequests = 0;
+  private successCount = 0;
+  private failedCount = 0;
+  private statusCodeCounts: Record<number, number> = {};
+  private l1CacheHits = 0;
+  private l1CacheMisses = 0;
+  private l2CacheHits = 0;
+  private l2CacheMisses = 0;
+  private dedupeHits = 0;
+  private dedupeMisses = 0;
+  private totalBytesSent = 0;
+  private totalBytesReceived = 0;
+  private errorCounts: Record<string, number> = {};
+  private lastRequestTimestamp: number | null = null;
+
+  // Response time tracking
+  private totalResponseTime = 0;
+  private minResponseTime = Infinity;
+  private maxResponseTime = 0;
+
+  constructor(endpoint: string) {
+    this.endpoint = endpoint;
+  }
+
+  /**
+   * Record a request metric
+   */
+  recordRequest(metric: RequestMetric): void {
+    this.totalRequests++;
+    this.lastRequestTimestamp = Date.now();
+
+    // Success/failure
+    if (metric.success) {
+      this.successCount++;
+    } else {
+      this.failedCount++;
+    }
+
+    // Status codes
+    this.statusCodeCounts[metric.status] =
+      (this.statusCodeCounts[metric.status] || 0) + 1;
+
+    // Cache tracking
+    if (metric.cacheHit) {
+      if (metric.cacheLayer === "l1") {
+        this.l1CacheHits++;
+      } else if (metric.cacheLayer === "l2") {
+        this.l2CacheHits++;
+      }
+    } else {
+      // Only count as miss if cache was checked (not deduped)
+      if (!metric.dedupeHit) {
+        this.l1CacheMisses++;
+        this.l2CacheMisses++;
+      }
+    }
+
+    // Deduplication
+    if (metric.dedupeHit) {
+      this.dedupeHits++;
+    } else {
+      this.dedupeMisses++;
+    }
+
+    // Bytes
+    this.totalBytesSent += metric.bytesSent;
+    this.totalBytesReceived += metric.bytesReceived;
+
+    // Errors
+    if (metric.error) {
+      this.errorCounts[metric.error] =
+        (this.errorCounts[metric.error] || 0) + 1;
+    }
+
+    // Response time
+    this.totalResponseTime += metric.responseTimeMs;
+    this.minResponseTime = Math.min(
+      this.minResponseTime,
+      metric.responseTimeMs
+    );
+    this.maxResponseTime = Math.max(
+      this.maxResponseTime,
+      metric.responseTimeMs
+    );
+
+    // Store in history for percentile calculations
+    this.requestHistory.push(metric);
+    if (this.requestHistory.length > this.maxHistorySize) {
+      this.requestHistory.shift(); // Remove oldest
+    }
+  }
+
+  /**
+   * Calculate percentiles from request history
+   */
+  private calculatePercentile(percentile: number): number {
+    if (this.requestHistory.length === 0) return 0;
+
+    const sorted = this.requestHistory
+      .map((m) => m.responseTimeMs)
+      .sort((a, b) => a - b);
+
+    const index = Math.ceil((percentile / 100) * sorted.length) - 1;
+    return sorted[Math.max(0, index)] || 0;
+  }
+
+  /**
+   * Get current metrics snapshot
+   */
+  getMetrics(): EndpointMetrics {
+    const totalCacheAttempts = this.l1CacheHits + this.l1CacheMisses;
+    const totalCacheHits = this.l1CacheHits + this.l2CacheHits;
+    const cacheHitRate =
+      totalCacheAttempts > 0
+        ? ((totalCacheHits / totalCacheAttempts) * 100).toFixed(2) + "%"
+        : "0%";
+
+    const totalDedupeAttempts = this.dedupeHits + this.dedupeMisses;
+    const dedupeHitRate =
+      totalDedupeAttempts > 0
+        ? ((this.dedupeHits / totalDedupeAttempts) * 100).toFixed(2) + "%"
+        : "0%";
+
+    return {
+      endpoint: this.endpoint,
+      requests: {
+        total: this.totalRequests,
+        success: this.successCount,
+        failed: this.failedCount,
+      },
+      statusCodes: { ...this.statusCodeCounts },
+      timing: {
+        avgMs:
+          this.totalRequests > 0
+            ? parseFloat(
+                (this.totalResponseTime / this.totalRequests).toFixed(2)
+              )
+            : 0,
+        minMs:
+          this.minResponseTime === Infinity
+            ? 0
+            : parseFloat(this.minResponseTime.toFixed(2)),
+        maxMs: parseFloat(this.maxResponseTime.toFixed(2)),
+        p50Ms: parseFloat(this.calculatePercentile(50).toFixed(2)),
+        p95Ms: parseFloat(this.calculatePercentile(95).toFixed(2)),
+        p99Ms: parseFloat(this.calculatePercentile(99).toFixed(2)),
+      },
+      cache: {
+        l1Hits: this.l1CacheHits,
+        l1Misses: this.l1CacheMisses,
+        l2Hits: this.l2CacheHits,
+        l2Misses: this.l2CacheMisses,
+        hitRate: cacheHitRate,
+      },
+      deduplication: {
+        hits: this.dedupeHits,
+        misses: this.dedupeMisses,
+        hitRate: dedupeHitRate,
+      },
+      bytes: {
+        sent: this.totalBytesSent,
+        received: this.totalBytesReceived,
+      },
+      errors: { ...this.errorCounts },
+      lastRequestAt: this.lastRequestTimestamp,
+    };
+  }
+
+  /**
+   * Reset all metrics
+   */
+  reset(): void {
+    this.requestHistory = [];
+    this.totalRequests = 0;
+    this.successCount = 0;
+    this.failedCount = 0;
+    this.statusCodeCounts = {};
+    this.l1CacheHits = 0;
+    this.l1CacheMisses = 0;
+    this.l2CacheHits = 0;
+    this.l2CacheMisses = 0;
+    this.dedupeHits = 0;
+    this.dedupeMisses = 0;
+    this.totalBytesSent = 0;
+    this.totalBytesReceived = 0;
+    this.errorCounts = {};
+    this.lastRequestTimestamp = null;
+    this.totalResponseTime = 0;
+    this.minResponseTime = Infinity;
+    this.maxResponseTime = 0;
+  }
+}
+
+/**
+ * Main Metrics Collector - manages metrics for all endpoints
+ */
+export class MetricsCollector implements MetricsAPI {
+  private endpoints: Map<string, EndpointMetricsCollector> = new Map();
+  private startTime: number;
+
+  constructor() {
+    this.startTime = Date.now();
+  }
+
+  /**
+   * Get or create endpoint collector
+   */
+  private getEndpointCollector(endpoint: string): EndpointMetricsCollector {
+    if (!this.endpoints.has(endpoint)) {
+      this.endpoints.set(endpoint, new EndpointMetricsCollector(endpoint));
+    }
+    return this.endpoints.get(endpoint)!;
+  }
+
+  /**
+   * Record a request event
+   */
+  recordRequest(endpoint: string, metric: RequestMetric): void {
+    this.getEndpointCollector(endpoint).recordRequest(metric);
+  }
+
+  /**
+   * Get metrics for a specific endpoint
+   */
+  get(endpoint: string): EndpointMetrics | null {
+    const collector = this.endpoints.get(endpoint);
+    return collector ? collector.getMetrics() : null;
+  }
+
+  /**
+   * Get metrics for all endpoints
+   */
+  getAll(): Record<string, EndpointMetrics> {
+    const result: Record<string, EndpointMetrics> = {};
+    for (const [endpoint, collector] of this.endpoints) {
+      result[endpoint] = collector.getMetrics();
+    }
+    return result;
+  }
+
+  /**
+   * Get global aggregated metrics
+   */
+  getGlobal(): GlobalMetrics {
+    let totalRequests = 0;
+    let totalSuccess = 0;
+    let totalFailed = 0;
+    let totalResponseTime = 0;
+    let totalBytesSent = 0;
+    let totalBytesReceived = 0;
+    let totalCacheHits = 0;
+    let totalCacheAttempts = 0;
+    let totalDedupeHits = 0;
+    let totalDedupeAttempts = 0;
+
+    for (const collector of this.endpoints.values()) {
+      const metrics = collector.getMetrics();
+      totalRequests += metrics.requests.total;
+      totalSuccess += metrics.requests.success;
+      totalFailed += metrics.requests.failed;
+      totalResponseTime += metrics.timing.avgMs * metrics.requests.total;
+      totalBytesSent += metrics.bytes.sent;
+      totalBytesReceived += metrics.bytes.received;
+
+      totalCacheHits += metrics.cache.l1Hits + metrics.cache.l2Hits;
+      totalCacheAttempts +=
+        metrics.cache.l1Hits +
+        metrics.cache.l1Misses +
+        metrics.cache.l2Hits +
+        metrics.cache.l2Misses;
+
+      totalDedupeHits += metrics.deduplication.hits;
+      totalDedupeAttempts +=
+        metrics.deduplication.hits + metrics.deduplication.misses;
+    }
+
+    const avgResponseTimeMs =
+      totalRequests > 0 ? totalResponseTime / totalRequests : 0;
+
+    const overallCacheHitRate =
+      totalCacheAttempts > 0
+        ? ((totalCacheHits / totalCacheAttempts) * 100).toFixed(2) + "%"
+        : "0%";
+
+    const overallDeduplicationRate =
+      totalDedupeAttempts > 0
+        ? ((totalDedupeHits / totalDedupeAttempts) * 100).toFixed(2) + "%"
+        : "0%";
+
+    return {
+      totalRequests,
+      totalSuccess,
+      totalFailed,
+      avgResponseTimeMs: parseFloat(avgResponseTimeMs.toFixed(2)),
+      totalBytesSent,
+      totalBytesReceived,
+      overallCacheHitRate,
+      overallDeduplicationRate,
+      endpoints: this.endpoints.size,
+      uptime: Date.now() - this.startTime,
+    };
+  }
+
+  /**
+   * Reset metrics for specific endpoint or all
+   */
+  reset(endpoint?: string): void {
+    if (endpoint) {
+      const collector = this.endpoints.get(endpoint);
+      if (collector) {
+        collector.reset();
+      }
+    } else {
+      // Reset all
+      for (const collector of this.endpoints.values()) {
+        collector.reset();
+      }
+      this.startTime = Date.now();
+    }
+  }
+
+  /**
+   * Export all metrics as JSON string
+   */
+  export(): string {
+    return JSON.stringify(
+      {
+        global: this.getGlobal(),
+        endpoints: this.getAll(),
+        exportedAt: new Date().toISOString(),
+      },
+      null,
+      2
+    );
+  }
+}
+
+// Export for use in client.ts
+export type { RequestMetric };

package/components/native.ts

@@ -82,6 +82,48 @@ export const ffiDef = {
     returns: FFIType.void,
   },
 
+  // =========================================================================
+  // OPTIMIZED SINGLE-CALL API
+  // =========================================================================
+
+  zclient_request_full: {
+    args: [
+      FFIType.ptr, // client
+      FFIType.cstring, // method
+      FFIType.cstring, // url
+      FFIType.cstring, // headers (nullable)
+      FFIType.cstring, // body (nullable)
+      FFIType.u8, // max_redirects
+      FFIType.bool, // antibot
+    ],
+    returns: FFIType.ptr, // ZFullResponse*
+  },
+  zclient_response_full_free: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
+  // Accessor functions for ZFullResponse
+  zfull_response_status: {
+    args: [FFIType.ptr],
+    returns: FFIType.u16,
+  },
+  zfull_response_body: {
+    args: [FFIType.ptr],
+    returns: FFIType.ptr,
+  },
+  zfull_response_body_len: {
+    args: [FFIType.ptr],
+    returns: FFIType.u64,
+  },
+  zfull_response_headers: {
+    args: [FFIType.ptr],
+    returns: FFIType.ptr,
+  },
+  zfull_response_headers_len: {
+    args: [FFIType.ptr],
+    returns: FFIType.u64,
+  },
+
   // =========================================================================
   // CACHE FFI
   // =========================================================================

package/components/types.ts

@@ -90,11 +90,11 @@ export interface ParsedUrl {
   path: string;
 }
 
-/** Warmup URL with a key for type-safe access */
-export interface WarmupUrlConfig {
+/** Target URL with a key for type-safe access */
+export interface TargetUrlConfig {
   /** Unique key to access this URL via client.url[key] */
   key: string;
-  /** The URL to warmup */
+  /** The target URL */
   url: string;
   /** Enable response caching for this URL (default: false) */
   cache?: boolean | CacheConfig;
@@ -183,8 +183,8 @@ export interface UrlEndpoint {
   prefetch(options?: UrlRequestOptions): Promise<void>;
 }
 
-/** Type helper to extract keys from warmup config array */
-export type ExtractWarmupKeys<T extends readonly WarmupUrlConfig[]> =
+/** Type helper to extract keys from target config array */
+export type ExtractTargetKeys<T extends readonly TargetUrlConfig[]> =
   T[number]["key"];
 
 /** Context passed to request interceptors */
@@ -224,3 +224,63 @@ export interface Interceptors {
   response?: ResponseInterceptor[];
   error?: ErrorInterceptor[];
 }
+
+/** Metrics for a single endpoint */
+export interface EndpointMetrics {
+  endpoint: string;
+  requests: {
+    total: number;
+    success: number;
+    failed: number;
+  };
+  statusCodes: Record<number, number>;
+  timing: {
+    avgMs: number;
+    minMs: number;
+    maxMs: number;
+    p50Ms: number;
+    p95Ms: number;
+    p99Ms: number;
+  };
+  cache: {
+    l1Hits: number;
+    l1Misses: number;
+    l2Hits: number;
+    l2Misses: number;
+    hitRate: string;
+  };
+  deduplication: {
+    hits: number;
+    misses: number;
+    hitRate: string;
+  };
+  bytes: {
+    sent: number;
+    received: number;
+  };
+  errors: Record<string, number>;
+  lastRequestAt: number | null;
+}
+
+/** Global aggregated metrics across all endpoints */
+export interface GlobalMetrics {
+  totalRequests: number;
+  totalSuccess: number;
+  totalFailed: number;
+  avgResponseTimeMs: number;
+  totalBytesSent: number;
+  totalBytesReceived: number;
+  overallCacheHitRate: string;
+  overallDeduplicationRate: string;
+  endpoints: number;
+  uptime: number;
+}
+
+/** Public API for accessing metrics */
+export interface MetricsAPI {
+  get(endpoint: string): EndpointMetrics | null;
+  getAll(): Record<string, EndpointMetrics>;
+  getGlobal(): GlobalMetrics;
+  reset(endpoint?: string): void;
+  export(): string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jiren",
-  "version": "1.4.5",
+  "version": "1.5.0",
   "author": "",
   "main": "index.ts",
   "module": "index.ts",