feat: upgrade to v2.0.0 with multi-mirror fallback, new endpoints, and LRU cache

- Add multi-mirror fallback system with 5 mirror domains - Add LRU cache with configurable TTL per endpoint - Add response compression (gzip) - Add Seasons endpoint (/api/seasons/:id) - Add Watch Order endpoint (/api/watch-order/:id) - Add Latest Updated endpoint (/api/latest-updated) - Add Download endpoint (/api/download) - Add cache stats endpoint (/api/cache/stats) - Add mirror status/reset endpoints (/api/mirrors, /api/mirrors/reset) - Add configurable rate limiting with X-RateLimit headers - Add request timeouts and entity too large handling - Update documentation with all new endpoints - Update CHANGELOG.md with v2.0.0 entry - Update package.json version to 2.0.0 - Add 6 AI agent prompts for development
2026-10-22 10:55:10 +00:00 · 2026-07-04 15:07:07 +05:30
parent 30feda703a
commit fe51275db0
51 changed files with 5151 additions and 342 deletions
@@ -4,111 +4,117 @@
 * Repository: https://github.com/Shineii86/AniKotoAPI
 *
 * @description
- *   In-memory caching utility for storing and retrieving API responses.
- *   Implements TTL-based cache invalidation to prevent stale data
- *   while reducing unnecessary requests to the source site.
+ *   In-memory LRU cache with configurable TTL per endpoint.
+ *   Evicts least recently used entries when max size reached.
+ *   Supports cache statistics and manual invalidation.
 *
 * @exports
- *   getCache, setCache, clearCache
+ *   getCache, setCache, clearCache, getCacheStats, LRUCache
 *
 * @author  Shinei Nouzen
 * @license MIT
 * ======= • ======= • ======= • ======= • =======• =======
 */

-// ══════════════════════════════════════════════════════════════
-// CACHE STORAGE & CONFIGURATION
-// ══════════════════════════════════════════════════════════════
-
-// ---- FEATURE: In-memory Map-based cache storage ----
-/**
- * Internal cache storage using JavaScript Map object.
- * Stores data with timestamps for TTL-based expiration.
- *
- * @type {Map<string, {data: any, timestamp: number}>}
- */
-const cache = new Map();
-
-// ---- FEATURE: Cache time-to-live configuration (5 minutes) ----
-/**
- * Cache TTL (Time-To-Live) in milliseconds.
- * Default: 5 minutes (300,000 ms).
- * After this duration, cached items are considered stale
- * and will be removed on next access.
- *
- * @type {number}
- * @default 300000
- */
-const CACHE_TTL = 5 * 60 * 1000;
-// ---- FEATURE: Maximum cache size ----
-const MAX_CACHE_SIZE = 100;
-
-// ══════════════════════════════════════════════════════════════
-// CACHE OPERATIONS
-// ══════════════════════════════════════════════════════════════
-
-// ---- FEATURE: Retrieve cached data by key with TTL validation ----
-/**
- * Retrieves data from cache if it exists and hasn't expired.
- * Automatically removes stale entries on access.
- *
- * @param {string} key - The cache key to lookup
- * @returns {any|null} Cached data if valid, null if expired or missing
- *
- * @example
- *   // Get cached anime list
- *   const data = getCache("anime-list-action");
- *   if (data) {
- *     // Use cached data
- *   }
- */
-const getCache = (key) => {
-  const item = cache.get(key);
-  if (item && Date.now() - item.timestamp < CACHE_TTL) {
-    return item.data;
+class LRUCache {
+  constructor(maxSize = 100, defaultTTL = 300000) {
+    this.cache = new Map();
+    this.maxSize = maxSize;
+    this.defaultTTL = defaultTTL;
+    this.stats = { hits: 0, misses: 0, sets: 0, deletes: 0 };
  }
-  cache.delete(key);
-  return null;
-};

-// ---- FEATURE: Store data in cache with current timestamp ----
-/**
- * Stores data in cache with current timestamp for TTL tracking.
- * Overwrites any existing data for the same key.
- *
- * @param {string} key - The cache key to store under
- * @param {any} data - The data to cache (any serializable type)
- * @returns {void}
- *
- * @example
- *   // Cache anime search results
- *   setCache("search-one-piece", animeResults);
- */
-const setCache = (key, data) => {
-  // Evict oldest entries if cache is full
-  if (cache.size >= MAX_CACHE_SIZE) {
-    const oldestKey = cache.keys().next().value;
-    cache.delete(oldestKey);
+  get(key) {
+    if (!this.cache.has(key)) {
+      this.stats.misses++;
+      return undefined;
+    }
+
+    const entry = this.cache.get(key);
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      this.stats.misses++;
+      return undefined;
+    }
+
+    this.stats.hits++;
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    return entry.value;
  }
-  cache.set(key, { data, timestamp: Date.now() });
+
+  set(key, value, ttl) {
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    }
+
+    if (this.cache.size >= this.maxSize) {
+      const firstKey = this.cache.keys().next().value;
+      this.cache.delete(firstKey);
+    }
+
+    this.cache.set(key, {
+      value,
+      expiresAt: Date.now() + (ttl || this.defaultTTL)
+    });
+    this.stats.sets++;
+  }
+
+  delete(key) {
+    const existed = this.cache.delete(key);
+    if (existed) this.stats.deletes++;
+    return existed;
+  }
+
+  clear() {
+    const size = this.cache.size;
+    this.cache.clear();
+    return size;
+  }
+
+  getStats() {
+    const total = this.stats.hits + this.stats.misses;
+    return {
+      ...this.stats,
+      size: this.cache.size,
+      hitRate: total > 0 ? ((this.stats.hits / total) * 100).toFixed(2) + '%' : '0%'
+    };
+  }
+
+  has(key) {
+    if (!this.cache.has(key)) return false;
+    const entry = this.cache.get(key);
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return false;
+    }
+    return true;
+  }
+}
+
+const TTL = {
+  home: 600000,
+  search: 300000,
+  info: 600000,
+  episodes: 300000,
+  servers: 600000,
+  stream: 180000,
+  spotlight: 600000,
+  trending: 600000,
+  schedule: 1800000,
+  genres: 3600000,
+  suggestions: 300000,
+  default: 300000
 };

-// ---- FEATURE: Clear all cached entries from memory ----
-/**
- * Clears all entries from the cache. Use when:
- * - Memory cleanup is needed
- * - Force-refreshing all data
- * - Application restart/reset
- *
- * @returns {void}
- *
- * @example
- *   // Force refresh all cached data
- *   clearCache();
- */
-const clearCache = () => {
-  cache.clear();
-};
+const cache = new LRUCache(
+  parseInt(process.env.CACHE_MAX_SIZE) || 200,
+  parseInt(process.env.CACHE_DEFAULT_TTL) || 300000
+);

-export { getCache, setCache, clearCache };
-// ══════════════════════════════════════════════════════════════ END: cache.helper.js
+const getCache = (key) => cache.get(key);
+const setCache = (key, data, ttl) => cache.set(key, data, ttl);
+const clearCache = () => cache.clear();
+const getCacheStats = () => cache.getStats();
+
+export { getCache, setCache, clearCache, getCacheStats, LRUCache, TTL };
@@ -5,8 +5,8 @@
 *
 * @description
 *   HTTP client utility for fetching and parsing HTML content from
- *   paginated URLs. Uses axios for HTTP requests and Cheerio for
- *   DOM parsing, with support for page-based pagination.
+ *   paginated URLs. Uses mirror fallback for resilience and Cheerio
+ *   for DOM parsing, with support for page-based pagination.
 *
 * @exports
 *   extractPages
@@ -16,73 +16,26 @@
 * ======= • ======= • ======= • ======= • =======• =======
 */

-// ══════════════════════════════════════════════════════════════
-// DEPENDENCIES
-// ══════════════════════════════════════════════════════════════
-
-// ---- FEATURE: Cheerio HTML parser import ----
-/**
- * Cheerio library for server-side DOM manipulation.
- * Used to parse and query HTML content from fetched pages.
- *
- * @type {module:cheerio}
- */
 import * as cheerio from "cheerio";
+import { fetchWithMirror } from "./mirror.helper.js";

-// ---- FEATURE: Axios HTTP client import ----
 /**
- * Axios HTTP client for making requests to the source site.
- * Handles redirects, timeouts, and response parsing.
+ * Fetches HTML content from a URL with pagination and mirror fallback.
+ * Automatically tries alternative domains if primary fails.
 *
- * @type {module:axios}
- */
-import axios from "axios";
-
-// ---- FEATURE: Browser-mimicking headers import ----
-/**
- * Pre-configured HTTP headers to mimic browser requests.
- * Imported from header.config.js for consistent usage.
- *
- * @type {Object}
- */
-import { headers } from "../configs/header.config.js";
-
-// ══════════════════════════════════════════════════════════════
-// PAGE EXTRACTION FUNCTION
-// ══════════════════════════════════════════════════════════════
-
-// ---- FEATURE: Fetch and parse paginated URL content ----
-/**
- * Fetches HTML content from a URL with optional pagination support.
- * Appends page query parameter for pages > 1 and returns parsed
- * Cheerio instance for DOM querying.
- *
- * @param {string} url - Base URL to fetch (without page parameter)
+ * @param {string} url - Base URL path to fetch (e.g., "/filter?keyword=naruto")
 * @param {number} [page=1] - Page number to fetch (1-indexed)
 * @returns {Promise<CheerioAPI>} Parsed Cheerio instance of the page
- * @throws {Error} If HTTP request fails or returns non-2xx status
 *
 * @example
- *   // Fetch first page of search results
- *   const $ = await extractPages("https://anikototv.to/filter?keyword=one-piece");
- *
- * @example
- *   // Fetch second page of genre listing
- *   const $ = await extractPages(genreUrl, 2);
- *
- * @note
- *   WARNING: The site may block requests without proper headers.
- *   Always use the imported headers configuration.
- *
- * @note
- *   TIP: Consider implementing retry logic for failed requests
- *   in production environments.
+ *   const $ = await extractPages("/filter?keyword=one-piece");
+ *   const $page2 = await extractPages("/filter?keyword=one-piece", 2);
 */
 const extractPages = async (url, page = 1) => {
  try {
    const separator = url.includes("?") ? "&" : "?";
-    const finalUrl = page > 1 ? `${url}${separator}page=${page}` : url;
-    const { data } = await axios.get(finalUrl, { headers });
+    const path = page > 1 ? `${url}${separator}page=${page}` : url;
+    const { data } = await fetchWithMirror(path);
    const $ = cheerio.load(data);
    return $;
  } catch (error) {
@@ -91,4 +44,3 @@ const extractPages = async (url, page = 1) => {
 };

 export { extractPages };
-// ══════════════════════════════════════════════════════════════ END: extractPages.helper.js
@@ -0,0 +1,251 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKotoAPI — mirror.helper.js
+ * Repository: https://github.com/Shineii86/AniKotoAPI
+ *
+ * @description
+ *   Multi-mirror fallback helper for resilient scraping.
+ *   Automatically tries alternative domains if primary is blocked/down.
+ *   Caches working mirror per session for faster subsequent requests.
+ *
+ * @exports
+ *   fetchWithMirror, getWorkingMirror, resetMirrorCache
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
+import axios from "axios";
+import { headers } from "../configs/header.config.js";
+import { getCache, setCache } from "./cache.helper.js";
+
+// ══════════════════════════════════════════════════════════════
+// MIRROR CONFIGURATION
+// ══════════════════════════════════════════════════════════════
+
+// Default mirrors with names and priority
+const DEFAULT_MIRRORS = [
+  { url: "https://anikototv.to", name: "Primary", priority: 1 },
+  { url: "https://anikoto.cz", name: "Regional CZ", priority: 2 },
+  { url: "https://anikoto.me", name: "Short TLD", priority: 3 },
+  { url: "https://anikoto.net", name: "Network", priority: 4 },
+  { url: "https://anikototv.se", name: "Nordic .se", priority: 5 },
+];
+
+// Parse custom mirrors from env or use defaults
+function parseMirrors() {
+  const envMirrors = process.env.MIRROR_DOMAINS;
+  if (!envMirrors) return DEFAULT_MIRRORS;
+  
+  return envMirrors.split(",").map((url, index) => ({
+    url: url.trim(),
+    name: `Mirror ${index + 1}`,
+    priority: index + 1
+  }));
+}
+
+const ALL_MIRRORS = parseMirrors();
+ALL_MIRRORS.sort((a, b) => a.priority - b.priority);
+
+// Cache key for working mirror
+const MIRROR_CACHE_KEY = "working_mirror";
+const MIRROR_CACHE_TTL = parseInt(process.env.MIRROR_CACHE_TTL) || 3600000;
+
+// ══════════════════════════════════════════════════════════════
+// MIRROR STATE
+// ══════════════════════════════════════════════════════════════
+
+let workingMirror = null;
+let failedMirrors = new Set();
+
+// ══════════════════════════════════════════════════════════════
+// HELPER FUNCTIONS
+// ══════════════════════════════════════════════════════════════
+
+/**
+ * Check if a mirror is accessible
+ * @param {string} baseUrl - Mirror base URL
+ * @returns {Promise<boolean>}
+ */
+async function checkMirror(baseUrl) {
+  try {
+    const response = await axios.get(`${baseUrl}/home`, {
+      headers,
+      timeout: 10000,
+      maxRedirects: 5,
+    });
+    return response.status === 200;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Get the best available mirror
+ * @returns {Promise<string>} Working mirror base URL
+ */
+async function getWorkingMirror() {
+  // Check cache first
+  const cached = getCache(MIRROR_CACHE_KEY);
+  if (cached && !failedMirrors.has(cached)) {
+    workingMirror = cached;
+    return workingMirror;
+  }
+
+  // Try mirrors in priority order
+  for (const mirror of ALL_MIRRORS) {
+    if (failedMirrors.has(mirror.url)) continue;
+
+    const isWorking = await checkMirror(mirror.url);
+    if (isWorking) {
+      workingMirror = mirror.url;
+      setCache(MIRROR_CACHE_KEY, mirror.url, MIRROR_CACHE_TTL);
+      console.log(`[MIRROR] Using: ${mirror.name} (${mirror.url})`);
+      return mirror.url;
+    } else {
+      failedMirrors.add(mirror.url);
+      console.log(`[MIRROR] Failed: ${mirror.name} (${mirror.url})`);
+    }
+  }
+
+  // All mirrors failed, reset and try again
+  failedMirrors.clear();
+  workingMirror = ALL_MIRRORS[0].url;
+  console.log(`[MIRROR] All failed, resetting to primary: ${workingMirror}`);
+  return workingMirror;
+}
+
+/**
+ * Reset mirror cache and failed state
+ */
+function resetMirrorCache() {
+  workingMirror = null;
+  failedMirrors.clear();
+  setCache(MIRROR_CACHE_KEY, null, 0);
+  console.log("[MIRROR] Cache reset");
+}
+
+/**
+ * Build URL with current mirror
+ * @param {string} path - URL path
+ * @param {string} baseUrl - Optional custom base URL
+ * @returns {string} Full URL
+ */
+function buildUrl(path, baseUrl = workingMirror) {
+  const base = baseUrl || ALL_MIRRORS[0].url;
+  return `${base}${path}`;
+}
+
+/**
+ * Fetch with automatic mirror fallback
+ * @param {string} path - URL path to fetch
+ * @param {object} options - Additional options
+ * @returns {Promise<{data: string, mirror: string}>}
+ */
+async function fetchWithMirror(path, options = {}) {
+  const { 
+    timeout = 15000, 
+    retries = 2,
+    returnType = "text",
+    headers: customHeaders = {}
+  } = options;
+
+  // Merge default headers with custom headers
+  const requestHeaders = { ...headers, ...customHeaders };
+
+  let lastError = null;
+
+  // Try cached working mirror first
+  const mirrorsToTry = [];
+  
+  if (workingMirror && !failedMirrors.has(workingMirror)) {
+    mirrorsToTry.push(workingMirror);
+  }
+
+  // Add remaining mirrors
+  for (const mirror of ALL_MIRRORS) {
+    if (!mirrorsToTry.includes(mirror.url) && !failedMirrors.has(mirror.url)) {
+      mirrorsToTry.push(mirror.url);
+    }
+  }
+
+  // If all failed, reset and try all
+  if (mirrorsToTry.length === 0) {
+    failedMirrors.clear();
+    mirrorsToTry.push(...ALL_MIRRORS.map(m => m.url));
+  }
+
+  for (const mirror of mirrorsToTry) {
+    const url = buildUrl(path, mirror);
+    
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        const response = await axios.get(url, {
+          headers: requestHeaders,
+          timeout,
+          responseType: returnType === "text" ? "text" : "json",
+        });
+
+        if (response.status === 200) {
+          // Update working mirror
+          if (mirror !== workingMirror) {
+            workingMirror = mirror;
+            setCache(MIRROR_CACHE_KEY, mirror, MIRROR_CACHE_TTL);
+            console.log(`[MIRROR] Switched to: ${mirror}`);
+          }
+          return { 
+            data: returnType === "text" ? response.data : response.data,
+            mirror 
+          };
+        }
+      } catch (error) {
+        lastError = error;
+        if (attempt < retries) {
+          // Wait before retry
+          await new Promise(r => setTimeout(r, 500 * (attempt + 1)));
+        }
+      }
+    }
+
+    // Mark mirror as failed after all retries
+    failedMirrors.add(mirror);
+    console.log(`[MIRROR] Marked as failed: ${mirror}`);
+  }
+
+  throw new Error(`All mirrors failed. Last error: ${lastError?.message}`);
+}
+
+/**
+ * Get mirror status for all domains
+ * @returns {Promise<Array>}
+ */
+async function getMirrorStatus() {
+  const status = [];
+  
+  for (const mirror of ALL_MIRRORS) {
+    const start = Date.now();
+    const isWorking = await checkMirror(mirror.url);
+    const latency = Date.now() - start;
+    
+    status.push({
+      name: mirror.name,
+      url: mirror.url,
+      priority: mirror.priority,
+      status: isWorking ? "online" : "offline",
+      latency: `${latency}ms`,
+      isCurrent: mirror.url === workingMirror,
+    });
+  }
+  
+  return status;
+}
+
+export { 
+  fetchWithMirror, 
+  getWorkingMirror, 
+  resetMirrorCache, 
+  buildUrl,
+  getMirrorStatus,
+  ALL_MIRRORS
+};