playbooks

home / skills / dbobkov245-source / pwa-torserve / resilience-core

resilience-core skill

/skills/resilience-core

This skill ensures 100% poster and description availability by routing TMDB requests through a multi-layer resilience cascade for reliable metadata.

npx playbooks add skill dbobkov245-source/pwa-torserve --skill resilience-core

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.9 KB
---
name: resilience-core
description: Specialist in network resilience, anti-censorship, and TMDB access in restricted regions.
---

# Resilience Core Skill

This skill ensures 100% uptime for metadata fetching by using a multi-layer fallback strategy.
**Metric:** The user must NEVER see a blank poster or missing description due to a network error.

## 🌐 The Multi-Level Resilience Cascade
Every external request (especially to TMDB) MUST go through `tmdbClient.js`.
NEVER use `fetch()` directly for metadata.

**Cascade Order:**
1.  **Custom Cloudflare Worker:** First line of defense.
2.  **Lampa Proxy:** Public mirror (apn-latest.onrender.com).
3.  **Server Proxy:** Self-hosted proxy (`/api/proxy?url=...`).
4.  **CapacitorHttp + Client DoH (Native Only):**
    *   Uses `dns.google` API to resolve IP, bypassing ISP DNS Poisoning.
    *   Sends direct HTTPS requests to IP with `Host` header.
5.  **Corsproxy.io:** Browser-based fallback.
6.  **Kinopoisk (Out-of-band Fallback):**
    *   Used ONLY for text data (titles, descriptions).
    *   Triggered ONLY if TMDB is completely unreachable via all above levels.

### 🚦 Traffic Isolation Rule
**RULE:** DoH (DNS-over-HTTPS) and IP-direct requests are used **TOKYO for API data (JSON)**.
*   **NEVER** use DoH mechanisms for loading images/posters.
*   Images have their own resilience logic (Mirrors -> WSRV.NL).

## 🛡️ Image Resilience
Images use a separate logic:
*   **Mirrors:** `imagetmdb.com`, `nl.imagetmdb.com`, etc.
*   **Auto-Ban:** If a mirror fails 20 times in 10s, it's banned.
*   **WSRV.NL:** If all mirrors fail, we switch to `wsrv.nl` proxying.

## 💻 Usage Example
```javascript
import tmdbClient from '../utils/tmdbClient';

// BAD ❌
// const res = await fetch('https://api.themoviedb.org/3/movie/550');

// GOOD ✅
const data = await tmdbClient('/movie/550');
if (data.source === 'kinopoisk') {
    // Handle specific KP logic if needed
}
```

Overview

This skill provides a hardened metadata and image fetching layer for apps that must remain available in restrictive or unreliable networks. It enforces a multi-level fallback cascade for TMDB calls and a separate, mirror-based strategy for images so users never see blank posters or missing descriptions. The design prioritizes API data integrity and safe DNS/IP workarounds for native clients.

How this skill works

All external metadata requests are routed through a single client (tmdbClient) that attempts a defined cascade of proxies and fallbacks. For native environments it can use DNS-over-HTTPS plus direct-IP requests with Host headers to evade DNS poisoning; browser flows rely on public proxies and cors fallbacks. Images follow an independent mirror list with auto-banning and final proxying via wsrv.nl if mirrors fail.

When to use it

  • When metadata or posters must be displayed despite ISP censorship or DNS tampering.
  • For Android TV or NAS apps that stream torrents and need reliable TMDB access.
  • When building a client that must avoid exposing API keys or direct TMDB calls in the UI.
  • When you need a deterministic, testable fallback order for external requests.

Best practices

  • Channel all TMDB calls through a single client module (do NOT use fetch() directly).
  • Preserve source metadata (e.g., record when Kinopoisk is used) so downstream logic can adapt to format differences.
  • Use DoH + direct-IP only for JSON API requests; never use it for image loading.
  • Implement mirror health checks and auto-ban mirrors that fail repeatedly within short windows.
  • Keep the cascade order and timeouts conservative to avoid long UI stalls.

Example use cases

  • Android TV torrent app that must show posters/descriptions in censored regions.
  • Home NAS media server that fetches metadata reliably for large libraries.
  • Mobile native app using Capacitor that needs to bypass ISP DNS poisoning for API access.
  • Web client that uses cloud worker and public proxy fallbacks to avoid exposing TMDB keys to the browser.

FAQ

What happens if all TMDB paths fail?

If every level in the cascade fails, a text-only fallback to Kinopoisk is used for titles and descriptions; images remain handled via image mirrors or wsrv.nl.

Can I use DoH for images to improve reliability?

No. DoH and direct-IP techniques are restricted to API/JSON requests only. Images must use the mirror/proxy image flow to avoid mixed-host and header issues.

How do I integrate this with my client code?

Import and use the centralized tmdbClient for all metadata calls. Check response.source when special handling is required (for example, Kinopoisk fallbacks).