From 2e0ef33b92692036519c5cc4d5f44fca59c2f4df Mon Sep 17 00:00:00 2001 From: Shinei Nouzen <157171073+Shineii86@users.noreply.github.com> Date: Thu, 2 Jul 2026 07:48:51 +0530 Subject: [PATCH] docs: add streaming status, Cloudflare fix guide, and troubleshooting - Add Streaming Status section explaining why pipe endpoints fail (500) - Add 'How to Fix Streaming Issues' with 3 solutions: - ScraperAPI (free 1K req/month, easiest) - FlareSolverr (self-hosted, unlimited) - Self-host entire API on VPS - Update Configuration table with SCRAPER_API_KEY and FLARESOLVERR_URL - Add FAQ entries for streaming 500 errors and /api/pipe-health - Add troubleshooting row for streaming 500 errors - Add verification steps with example responses --- README.md | 139 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 138 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index fa709e6..7e6b0e8 100644 --- a/README.md +++ b/README.md @@ -101,12 +101,38 @@ ### πŸ”„ Self-Healing System (v2.3.0) When Cloudflare blocks streaming requests, the API automatically tries fallback methods: -- **Direct** β†’ Mirror rotation across 4 domains +- **Direct** β†’ Mirror rotation across 4 domains (miruro.to, miruro.ru, miruro.bz, miruro.tv) - **ScraperAPI** β†’ Free proxy bypass (1K req/month) - **FlareSolverr** β†’ Self-hosted browser proxy Zero-config: works out of the box. Add `SCRAPER_API_KEY` env var for automatic Cloudflare bypass. +### ⚠️ Streaming Status + +> **Streaming endpoints (`/api/episodes`, `/api/watch`, `/api/sources`, `/api/stream`) return 500 errors when Cloudflare blocks pipe requests.** +> +> This is expected behavior on Vercel's free tier. Cloudflare's bot protection blocks requests from datacenter IPs (including Vercel's). Metadata endpoints (search, info, trending, etc.) work perfectly β€” only streaming is affected. + +| What Works | What's Blocked | +|:---|:---| +| Search, suggestions, filter | Episodes, sources, stream | +| Info, characters, relations | Watch, download | +| Trending, popular, schedule | All pipe-dependent endpoints | +| Genres, tags, calendar | Streaming provider data | +| All AniList-backed endpoints | | + +**To fix streaming**, set one of these environment variables in Vercel: + +```bash +# Option 1: ScraperAPI (free 1K requests/month) +SCRAPER_API_KEY=your_scraperapi_key + +# Option 2: FlareSolverr (self-hosted, unlimited) +FLARESOLVERR_URL=http://your-flaresolverr-host:8191 +``` + +See [How to Fix Streaming](#-how-to-fix-streaming-issues) in Troubleshooting below. + ### How It Works ```mermaid @@ -410,8 +436,12 @@ bun dev | `ALLOWED_ORIGINS` | `*` | Comma-separated allowed origins (restricts CORS in production) | | `PIPE_OBF_KEY` | `71951034...` | Pipe response XOR obfuscation key (hex, 32 chars) | | `PRU_PROXY_KEY` | `a54d389c...` | PRU proxy URL XOR key (hex, 32 chars) | +| `SCRAPER_API_KEY` | β€” | ScraperAPI key for Cloudflare bypass (free 1K req/month) | +| `FLARESOLVERR_URL` | β€” | FlareSolverr URL for browser-based bypass (e.g., `http://127.0.0.1:8191`) | > ⚠️ **Required for production:** Set `ALLOWED_ORIGINS` to restrict CORS. Set `PIPE_OBF_KEY` and `PRU_PROXY_KEY` for pipe decoding. +> +> πŸ“Ί **For streaming:** Set `SCRAPER_API_KEY` or `FLARESOLVERR_URL` to bypass Cloudflare bot protection. See [How to Fix Streaming Issues](#-how-to-fix-streaming-issues). ### Vercel Configuration @@ -1445,6 +1475,95 @@ docker run -p 3000:3000 miruroapi | ❌ Deploy fails on Vercel | Build error | Check `node server.js` locally first | | ❌ Slow first request | Serverless cold start | Normal β€” first request after idle takes ~500ms | | ❌ Rate limited | Too many requests | Cache reduces this β€” wait for TTL expiry | +| ❌ **Streaming 500 errors** | **Cloudflare blocks pipe requests** | **Set `SCRAPER_API_KEY` or `FLARESOLVERR_URL`** (see below) | + +### 🎬 How to Fix Streaming Issues + +Streaming endpoints fail because Cloudflare's bot protection blocks requests from Vercel's datacenter IPs. The pipe endpoint (`miruro.to/api/secure/pipe`) returns HTTP 403 to any request that doesn't come from a residential IP or real browser. + +#### Why Does This Happen? + +``` +Your App (Vercel) β†’ Cloudflare WAF β†’ miruro.to/api/secure/pipe β†’ 403 Blocked +``` + +Cloudflare detects: +- Datacenter IP ranges (Vercel, AWS, GCP, etc.) +- Missing browser fingerprint headers +- Non-residential traffic patterns + +#### Fix 1: ScraperAPI (Easiest β€” Free Tier) + +ScraperAPI proxies your requests through residential IPs, bypassing Cloudflare. + +```bash +# 1. Sign up at https://www.scraperapi.com/ (free 1,000 requests/month) +# 2. Get your API key from the dashboard +# 3. Add to Vercel environment variables: +SCRAPER_API_KEY=your_api_key_here +``` + +**Cost:** Free for 1K requests/month. Paid plans from $49/month for 250K requests. + +#### Fix 2: FlareSolverr (Self-Hosted β€” Unlimited) + +FlareSolverr runs a headless browser that bypasses Cloudflare automatically. + +```bash +# 1. Run FlareSolverr on your own server +docker run -d --name flaresolverr -p 8191:8191 ghcr.io/flaresolverr/flaresolverr:latest + +# 2. Add to Vercel environment variables: +FLARESOLVERR_URL=http://your-server-ip:8191 +``` + +**Cost:** Free (self-hosted). Requires a VPS with Docker. + +**Requirements:** +- 1GB+ RAM +- Public IP address +- Docker installed + +#### Fix 3: Self-Host the Entire API + +If you run the API on your own VPS (not Vercel), requests come from your residential/datacenter IP which may not be blocked. + +```bash +# Clone and install +git clone https://github.com/Shineii86/MiruroAPI.git +cd MiruroAPI && npm install + +# Start on your own server +npm start +# β†’ http://your-server:3000 +``` + +#### Verifying the Fix + +After setting an environment variable, check if streaming works: + +```bash +# Check pipe health +curl "https://mirurotvapi.vercel.app/api/pipe-health" + +# Test episodes +curl "https://mirurotvapi.vercel.app/api/episodes/20" +``` + +Expected response when streaming works: +```json +{ + "success": true, + "results": { + "methods": { + "direct": { "status": "failed" }, + "scraperapi": { "status": "working", "latency": "1200ms" } + }, + "working": 1, + "recommendation": "ScraperAPI is working. Streaming endpoints are functional." + } +} +``` ### πŸ› Debug Mode @@ -1504,6 +1623,24 @@ Yes! Use npm start to run the Express server on any VPS, Docker con 12 providers: kiwi, pewe, bee, bonk, bun, ally, nun, twin, cog, moo, hop, telli. Not all anime are available on every provider. +
+❌ Why are streaming endpoints returning 500 errors? +
+Cloudflare's bot protection blocks requests from Vercel's datacenter IPs. The pipe endpoint (miruro.to/api/secure/pipe) returns HTTP 403. To fix this, set SCRAPER_API_KEY (free 1K req/month from ScraperAPI) or FLARESOLVERR_URL (self-hosted browser proxy) in your Vercel environment variables. See How to Fix Streaming Issues above. +
+ +
+πŸ” Why does /api/staff/:id return 404? +
+Some AniList staff IDs don't exist or have limited data. Try searching with /api/staff?query=name instead. This is an AniList API limitation, not a bug. +
+ +
+πŸ“Š How do I check if streaming is working? +
+Use /api/pipe-health to check which pipe methods are working. It shows the status of Direct, ScraperAPI, and FlareSolverr fallback methods with latency and error details. +
+ --- ## πŸ—ΊοΈ Roadmap