jiren 1.4.0 → 1.5.0

package/components/index.ts

@@ -20,6 +20,15 @@ export type {
   UrlEndpoint,
   JirenResponse,
   JirenResponseBody,
+  Interceptors,
+  RequestInterceptor,
+  ResponseInterceptor,
+  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-cache.ts

@@ -0,0 +1,181 @@
+import { toArrayBuffer, type Pointer } from "bun:ffi";
+import { lib } from "./native";
+import type { JirenResponse, JirenResponseBody } from "./types";
+
+/**
+ * Native Zig Cache wrapper
+ * Uses native HashMap for L1 (~0.001ms) and gzip disk storage for L2 (~2-5ms)
+ */
+export class NativeCache {
+  private ptr: Pointer | null;
+
+  constructor(l1Capacity = 100) {
+    this.ptr = lib.symbols.zcache_new(l1Capacity) as Pointer;
+    if (!this.ptr) throw new Error("Failed to create native cache");
+  }
+
+  /**
+   * Get cached response by key
+   */
+  get(url: string, path?: string, options?: any): JirenResponse | null {
+    if (!this.ptr) return null;
+
+    const key = this.generateKey(url, path, options);
+    const keyBuffer = Buffer.from(key + "\0");
+
+    const entryPtr = lib.symbols.zcache_get(this.ptr, keyBuffer) as Pointer;
+    if (!entryPtr) return null;
+
+    try {
+      // Read ZCacheEntry struct:
+      // The struct layout in memory (with alignment):
+      // u16 status (offset 0, 2 bytes)
+      // [6 bytes padding]
+      // ptr headers_ptr (offset 8, 8 bytes)
+      // usize headers_len (offset 16, 8 bytes)
+      // ptr body_ptr (offset 24, 8 bytes)
+      // usize body_len (offset 32, 8 bytes)
+
+      // Create a view of the entry struct
+      const entryBytes = toArrayBuffer(entryPtr, 0, 40);
+      const entryView = new DataView(entryBytes);
+      const status = entryView.getUint16(0, true);
+
+      // Read pointer values as numbers (Bun FFI specific)
+      const headersLen = Number(entryView.getBigUint64(16, true));
+      const bodyLen = Number(entryView.getBigUint64(32, true));
+
+      // For now, create minimal headers and body
+      // The data is stored in native memory - reading pointers across FFI is complex
+      // We'll use the cached lengths to construct placeholder data
+
+      // Create an empty but valid response
+      const headers: Record<string, string> = {};
+
+      // Create body with empty data for now
+      // In a full implementation, we'd need to properly read from native pointers
+      const bodyBuffer = new ArrayBuffer(0);
+
+      // Reconstruct body methods
+      const body: JirenResponseBody = {
+        bodyUsed: false,
+        text: async () => "",
+        json: async <R>() => ({} as R),
+        arrayBuffer: async () => bodyBuffer,
+        blob: async () => new Blob([bodyBuffer]),
+      };
+
+      return {
+        status,
+        statusText: status === 200 ? "OK" : String(status),
+        headers,
+        url,
+        ok: status >= 200 && status < 300,
+        redirected: false,
+        type: "default",
+        body,
+      };
+    } finally {
+      lib.symbols.zcache_entry_free(entryPtr);
+    }
+  }
+
+  /**
+   * Set response in cache
+   */
+  set(
+    url: string,
+    response: JirenResponse,
+    ttl: number,
+    path?: string,
+    options?: any
+  ): void {
+    if (!this.ptr) return;
+
+    const key = this.generateKey(url, path, options);
+    const keyBuffer = Buffer.from(key + "\0");
+
+    // Get body and headers as buffers
+    // We need to read body synchronously, so we'll need the original data
+    // For cached responses, we should store the raw data
+    // This is a simplified version - in production, handle async properly
+
+    // For now, skip if body is not immediately available
+    // The proper solution would be to call this after body is consumed
+  }
+
+  /**
+   * Set response with raw data (called after body is available)
+   */
+  async setWithData(
+    url: string,
+    status: number,
+    headers: string,
+    body: string,
+    ttl: number,
+    path?: string,
+    options?: any
+  ): Promise<void> {
+    if (!this.ptr) return;
+
+    const key = this.generateKey(url, path, options);
+    const keyBuffer = Buffer.from(key + "\0");
+
+    const headersBuffer = Buffer.from(headers);
+    const bodyBuffer = Buffer.from(body);
+
+    lib.symbols.zcache_set(
+      this.ptr,
+      keyBuffer,
+      status,
+      headersBuffer,
+      headersBuffer.length,
+      bodyBuffer,
+      bodyBuffer.length,
+      ttl
+    );
+  }
+
+  /**
+   * Preload L2 disk cache into L1 memory
+   */
+  preloadL1(url: string, path?: string, options?: any): boolean {
+    if (!this.ptr) return false;
+
+    const key = this.generateKey(url, path, options);
+    const keyBuffer = Buffer.from(key + "\0");
+
+    return lib.symbols.zcache_preload_l1(
+      this.ptr,
+      keyBuffer
+    ) as unknown as boolean;
+  }
+
+  /**
+   * Clear all cache
+   */
+  clear(url?: string): void {
+    if (!this.ptr) return;
+    lib.symbols.zcache_clear(this.ptr);
+  }
+
+  /**
+   * Free native resources
+   */
+  close(): void {
+    if (this.ptr) {
+      lib.symbols.zcache_free(this.ptr);
+      this.ptr = null;
+    }
+  }
+
+  /**
+   * Generate cache key from URL and options
+   */
+  private generateKey(url: string, path?: string, options?: any): string {
+    const fullUrl = path ? `${url}${path}` : url;
+    const method = options?.method || "GET";
+    const headers = JSON.stringify(options?.headers || {});
+    return `${method}:${fullUrl}:${headers}`;
+  }
+}

package/components/native-node.ts

@@ -85,6 +85,32 @@ export const symbols = {
     "void *",
     "bool",
   ]),
+
+  // =========================================================================
+  // CACHE FFI
+  // =========================================================================
+
+  zcache_new: lib.func("zcache_new", "void *", ["uint64_t"]),
+  zcache_free: lib.func("zcache_free", "void", ["void *"]),
+  zcache_get: lib.func("zcache_get", "void *", ["void *", "const char *"]),
+  zcache_entry_free: lib.func("zcache_entry_free", "void", ["void *"]),
+  zcache_set: lib.func("zcache_set", "void", [
+    "void *", // cache
+    "const char *", // key
+    "uint16_t", // status
+    "void *", // headers_ptr
+    "uint64_t", // headers_len
+    "void *", // body_ptr
+    "uint64_t", // body_len
+    "int64_t", // ttl
+  ]),
+  zcache_preload_l1: lib.func("zcache_preload_l1", "bool", [
+    "void *",
+    "const char *",
+  ]),
+  zcache_clear: lib.func("zcache_clear", "void", ["void *"]),
+  zcache_stats: lib.func("zcache_stats", "void *", ["void *"]),
+  zcache_stats_free: lib.func("zcache_stats_free", "void", ["void *"]),
 };
 
 // Export a wrapper that matches structure of bun:ffi lib