# RSSPipe 🚀

> **Modern, High-Performance RSS Information Gateway & Distraction-Free Reader**

RSSPipe is a single-user, self-hosted RSS information gateway designed to replace traditional feeds readers with an elegant, ultra-fast, and distraction-free reading experience. Built with a robust Go backend and a modern React PWA interface.

---

## ✨ Key Features

- 🖥️ **Reeder 4 Minimal 3-Pane View**: Designed for desktop power users with collapsible navigation sidebar, dense article list, and distraction-free reading canvas.
- 📱 **Xiaohongshu-Style Masonry Waterfall**: Designed for mobile and media-rich browsing with adaptive masonry columns, category filter chips, and full-screen post reader.
- ⚡ **High-Speed Crawler & Engine**: Concurrent worker pool crawler in Go with per-feed polling intervals, custom timeouts, and HTTP conditional caching (ETag / Last-Modified 304).
- 🔒 **Single-User Security & Auth**: JWT-based session security and bcrypt hashing to secure access over the public internet.
- 📁 **OPML 2.0 Import & Export**: Effortless migration from Miniflux, Feedly, Inoreader, NetNewsWire, or Reeder.
- 🔗 **Standalone Article Sharing**: Instant public HTML snapshot sharing (`/share/{uuid}.html`) for individual articles.
- ⌨️ **Keyboard Navigation**: Complete single-key shortcut navigation (`j`/`k` next/previous, `m` mark read, `s` star, `e` archive, `v` view original, `[` sidebar toggle).
- 💾 **Local State & Reading Persistence**: Restores exact view modes, filter selections, active feeds, and reading positions upon page refresh.

---

## 🛠️ Architecture & Tech Stack

```
   ┌─────────────────────────────────────────────────────────┐
   │                  React 18 PWA Frontend                  │
   │      (Vite + TypeScript + Lucide + Modern CSS)          │
   └──────────────────────────┬──────────────────────────────┘
                              │ REST API + Static Asset Serving
   ┌──────────────────────────▼──────────────────────────────┐
   │                   Go 1.22 HTTP Server                   │
   │               (Chi Router + JWT Auth)                   │
   ├──────────────────────────┬──────────────────────────────┤
   │    Background Crawler    │      SQLite Engine (WAL)     │
   │ (Worker Pool + Parser)   │  (modernc.org/sqlite Driver) │
   └──────────────────────────┴──────────────────────────────┘
```

- **Backend**: Go 1.22+, `go-chi/chi`, `gofeed` parser, `golang-jwt/jwt`.
- **Database**: Embedded SQLite with WAL mode (`modernc.org/sqlite` pure Go driver, no CGO required).
- **Frontend**: React 18, TypeScript, Vite, CSS custom properties.

---

## 🚀 Quickstart

### Option 1: Run with Docker Compose

```bash
# Clone the repository
git clone https://git.pengzhan.dev/haopengzhan/rsspipe.git
cd rsspipe

# Start RSSPipe
docker compose up -d
```

Visit **`http://localhost:8080`**.
Default credentials:

- **Username**: `admin`
- **Password**: `admin123456` *(configurable via environment variables)*

---

### Option 2: Local Development Setup

#### Prerequisites

- **Go 1.22+**
- **Node.js 18+ & npm**

```bash
# Clone the repository
git clone https://git.pengzhan.dev/haopengzhan/rsspipe.git
cd rsspipe

# Build and start server using Makefile
make dev
```

Or build separately:
```bash
make build          # Compiles frontend bundle + backend binary into bin/rsspipe
./bin/rsspipe       # Runs production binary
```

The server binds to `http://localhost:8080` and serves both the API endpoints and static frontend assets.

---

## ⚙️ Configuration & Environment Variables

| Variable | Default | Description |
| :--- | :--- | :--- |
| `PORT` | `8080` | Server HTTP port |
| `DB_PATH` | `./data/rsspipe.db` | Path to SQLite database file |
| `JWT_SECRET` | *(auto-generated)* | 32-byte secret key for signing JWT tokens |
| `ADMIN_USERNAME` | `admin` | Initial default administrator username |
| `ADMIN_PASSWORD` | `admin123456` | Initial default administrator password |
| `CRAWLER_WORKERS` | `10` | Number of concurrent fetch worker threads |
| `CRAWLER_INTERVAL` | `15` | Default background crawler interval (minutes) |

---

## ⌨️ Keyboard Shortcuts

| Shortcut | Action |
| :--- | :--- |
| `j` / `k` | Navigate to Next / Previous article |
| `m` | Toggle Read / Unread status |
| `s` | Toggle Starred status |
| `e` | Mark as read and advance to next |
| `v` | Open original article URL in new tab |
| `[` | Toggle left navigation sidebar |
| `r` | Trigger immediate refresh of feeds |
| `a` | Open "Add Subscription" modal |
| `1` | Switch to Desktop 3-Split View |
| `2` | Switch to Xiaohongshu Waterfall View |
| `3` | Switch to Settings & Management View |
| `Shift + A` | Mark all items in active view as read |
| `?` | Open keyboard shortcuts cheatsheet |
| `Esc` | Close any active modal dialog |

---

## 🧪 Testing & Quality Automation

```bash
make check          # Run all quality checks (gofmt, go vet, tests, tsc, gitleaks)
make test           # Run backend Go unit tests
make lint           # Check formatting and run go vet
make format         # Auto-format all Go files
```

---

## 📄 License

MIT License. Free for personal and commercial self-hosted use.