diff --git a/README.md b/README.md index 5c26985..9bae03b 100644 --- a/README.md +++ b/README.md @@ -1,85 +1,119 @@ -# Edge Relay +# ๐Ÿš€ Edge Relay (Proxy Bun) -HTTP proxy untuk Vercel Edge Runtime. +High-performance HTTP Proxy & Relay handler optimized for Vercel Edge Runtime, Cloudflare Workers, and Bun. -## Live Deployment +## ๐ŸŒ Live Deployment -- **Docs/Tester**: `https://proxy-bun.vercel.app/docs` -- **Utama**: `https://proxy-bun.vercel.app` -- **Alternatif**: `https://vercel-relay-alpha-umber.vercel.app` -- **Alternatif**: `https://proxy-bun-mytheclipse8647-orfq73fe.apn.leapcell.dev` -- **Alternatif**: `https://opennext-app.superaseph.workers.dev` +| Provider | Endpoint | +|----------|----------| +| **Primary (Vercel)** | `https://proxy-bun.vercel.app` | +| **Secondary (CF Workers)** | `https://opennext-app.superaseph.workers.dev` | +| **Leapcell** | `https://proxy-bun-mytheclipse8647-orfq73fe.apn.leapcell.dev` | +| **Interactive Docs** | `https://proxy-bun.vercel.app/docs` | -## Cara Pakai +--- -### Header yang Dibutuhkan +## ๐Ÿ›  Cara Pakai + +Proxy ini bekerja dengan menangkap request ke endpoint relay dan meneruskannya ke target yang ditentukan via headers. + +### Required Headers | Header | Required | Default | Deskripsi | |--------|----------|---------|-----------| -| `x-relay-target` | Yes | - | URL target yang ingin di-proxy | -| `x-relay-path` | No | `/` | Path yang ditambahkan ke target | +| `x-relay-target` | **Yes** | - | Base URL target (e.g. `https://api.openai.com`) | +| `x-relay-path` | No | `/` | Path tambahan (e.g. `/v1/chat/completions`) | -### Contoh +--- +## ๐Ÿ“– Contoh Penggunaan + +### 1. Simple GET Request +Mengambil data dari JSONPlaceholder. ```bash -curl -H "x-relay-target: https://jsonplaceholder.typicode.com/posts/1" https://proxy-bun.vercel.app/ -``` -```bash -curl -H "x-relay-target: https://api.example.com" \ - -H "x-relay-path: /v1/users" \ +curl -H "x-relay-target: https://jsonplaceholder.typicode.com/posts/1" \ https://proxy-bun.vercel.app/ ``` -### HTTP Methods +### 2. POST with Body & Headers +Meneruskan API Key dan data JSON ke target. +```bash +curl -X POST \ + -H "x-relay-target: https://api.example.com" \ + -H "x-relay-path: /v1/data" \ + -H "Authorization: Bearer YOUR_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"key": "value"}' \ + https://proxy-bun.vercel.app/ +``` -Mendukung semua HTTP methods: -- `GET`, `HEAD` - tanpa body -- `POST`, `PUT`, `PATCH`, `DELETE` - dengan body +### 3. Binary Data / Upload +Mendukung upload file via `POST`/`PUT` (streaming). +```bash +curl -X PUT \ + -H "x-relay-target: https://storage.com" \ + -H "x-relay-path: /upload/image.png" \ + --data-binary "@/path/to/image.png" \ + https://proxy-bun.vercel.app/ +``` -### Header Handling +--- -Relay headers yang di-strip sebelum forwarded: +## โš™๏ธ Fitur & Spesifikasi + +### โšก Protocol Support +- **HTTP/1.1 & HTTP/2** - Full support. +- **Methods** - `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`. +- **Streaming** - Mendukung response streaming (Server-Sent Events / SSE) secara native. +- **CORS** - Otomatis menambahkan header `Access-Control-Allow-*` agar bisa diakses dari browser. + +### ๐Ÿ›ก๏ธ Security & Header Handling +Relay ini bersifat transparan kecuali untuk header berikut yang di-**strip** sebelum diteruskan ke target: +- `host` (diganti dengan host target) - `x-relay-target` - `x-relay-path` -- `host` -Headers lain tetap di-pass. +Semua header lain (seperti `Authorization`, `User-Agent`, `Cookie`, dsb) akan diteruskan apa adanya. -### Error Handling +### ๐Ÿงช Error Codes +| Status | Deskripsi | +|--------|-----------| +| `400` | Missing `x-relay-target` header. | +| `403` | Target domain tidak valid (jika whitelist aktif). | +| `502` | Target gagal dihubungi / Bad Gateway. | -```json -{ - "error": "Missing x-relay-target header" -} -``` -HTTP 400 jika `x-relay-target` tidak ada. +--- -## Struktur Kode +## ๐Ÿ“‚ Struktur Project -``` -proxy-bun/ -โ”œโ”€โ”€ src/ -โ”‚ โ”œโ”€โ”€ app/ -โ”‚ โ”‚ โ”œโ”€โ”€ docs/page.tsx # UI / Documentation -โ”‚ โ”‚ โ””โ”€โ”€ route.ts # Edge API handler -โ”‚ โ””โ”€โ”€ lib/ -โ”‚ โ”œโ”€โ”€ relay-utils.ts # Pure functions untuk relay logic -โ”‚ โ””โ”€โ”€ relay-utils.test.ts # Unit tests +```text +src/ +โ”œโ”€โ”€ app/ +โ”‚ โ”œโ”€โ”€ route.ts # Entry point proxy (Edge Handler) +โ”‚ โ””โ”€โ”€ docs/ # UI Interactive Docs & Tester +โ””โ”€โ”€ lib/ + โ”œโ”€โ”€ relay-utils.ts # Logic filter header & request builder + โ””โ”€โ”€ utils.ts # Helper UI ``` -### relay-utils.ts +## ๐Ÿ— Development -| Function | Deskripsi | -|----------|-----------| -| `normalizeTargetUrl(target, path)` | Gabung target + path, hapus trailing slash | -| `filterHeaders(headers)` | Filter relay & security headers | -| `shouldSendBody(method)` | Cek apakah method butuh body | -| `buildRelayRequest(req, url, headers)` | Bangun RequestInit untuk fetch | -| `createRelayResponse(response)` | Buat Response dari fetch result | - -## Development +Gunakan [Bun](https://bun.sh) untuk performa terbaik. ```bash -bun test # Run tests -bun run dev # Start local Next.js server +# Install dependencies +bun install + +# Run dev server +bun dev + +# Run unit tests +bun test ``` + +## ๐Ÿš€ Deployment (GitHub Actions) +Project ini otomatis dideploy ke Cloudflare Workers setiap ada push ke `master`. +Konfigurasi workflow ada di `.github/workflows/deploy.yml`. + +--- +๐Ÿค– **Powered by Bun + Next.js Edge Runtime**