PodFetch

PodFetch is a self‑hosted podcast manager written in Rust on the backend and powered by React for its single‑page web interface. The core of the application is a lightweight HTTP API that orchestrates feed discovery, episode downloading, and metadata management. It exposes a RESTful endpoint set for CRUD operations on subscriptions, episodes, and user preferences, while also providing an RSS‑compatible feed that can be consumed by any GPodder‑compatible client. The Rust service leverages async runtimes (Tokio) and the actix‑web framework for high throughput, while the React front end communicates via JSON over HTTPS, providing a responsive experience on desktop and mobile browsers.

Architecture

• Backend: Rust + Actix‑web, async I/O with Tokio. Core logic is split into modules for feed parsing (feed-rs), download scheduling, and media storage. The application uses a PostgreSQL database (via sqlx) for persistence of subscriptions, episode metadata, and user settings. Media files are stored on the local filesystem or an S3‑compatible object store, with paths tracked in the database.
• Frontend: React (Create‑React‑App) with hooks and Context API for state management. The UI consumes the backend’s JSON endpoints and uses react-router for navigation between subscriptions, episode lists, and playback screens.
• Containerization: The repo contains a Dockerfile that builds a minimal Alpine‑based image. CI/CD pipelines on GitHub Actions automatically build and push new images to Docker Hub whenever commits land on main. The image exposes port 8080 and expects environment variables for database credentials, storage paths, and optional GPodder feed configuration.

Core Capabilities

• Feed Discovery & Sync: Pulls RSS feeds, parses <item> entries, and schedules downloads via a background worker. Duplicate detection uses episode GUIDs or media URLs.
• Download Engine: Uses reqwest for HTTP(S) downloads, supports resume via HTTP Range headers, and writes files atomically to avoid corruption.
• Playback: The React player streams local media through a /media/:id endpoint, supporting progressive download and basic controls (seek, volume).
• API Extensibility: Developers can extend functionality by adding custom middleware to Actix, exposing new endpoints for analytics or integration with other services (e.g., OAuth providers).
• GPodder Feed: Publishes a /gpodder endpoint that mimics the GPodder server, allowing existing clients to sync subscriptions without modification.

Deployment & Infrastructure

• Self‑Hosting: Requires a PostgreSQL instance and optional S3 credentials. The Docker image is lightweight (~200 MB) and can run on any platform that supports Docker or Podman.
• Scalability: The stateless API can be horizontally scaled behind a reverse proxy (NGINX, Traefik). Media files are served directly from the container or a dedicated storage service; thus, read traffic can be offloaded to CDN edge nodes if needed.
• Observability: Actix offers built‑in request logging; the project ships with Prometheus metrics endpoints (/metrics) and integrates with OpenTelemetry for distributed tracing. Health checks (/healthz) are exposed for orchestration tools.

Integration & Extensibility

• Webhooks: Users can register callbacks that fire on episode download or feed update events, enabling automated workflows (e.g., sending notifications to Slack).
• Plugin System: While no formal plugin API exists yet, the modular Rust codebase allows developers to fork and add custom logic—such as transcoding audio or applying DRM—by extending the download worker.
• Custom Frontends: Since the backend is purely RESTful, third‑party developers can build native mobile apps or command‑line clients that consume the same endpoints.

Developer Experience

• Configuration: All settings are injected via environment variables (DATABASE_URL, STORAGE_PATH, GPOUNDER_FEED). The documentation includes a detailed reference of each variable and default values.
• Documentation: The project hosts auto‑generated Rust docs (via cargo doc) and a UI preview on GitHub Pages. API routes are documented with examples in the README, making onboarding quick.
• Community & Licensing: Released under an MIT license, PodFetch has a small but active GitHub community. Issues and pull requests are reviewed promptly, and the CI pipeline ensures code quality through tests and static analysis.

Use Cases

• Personal Podcast Server: Run PodFetch on a NAS or Raspberry Pi to sync subscriptions across devices, ensuring privacy and offline access.
• Enterprise Knowledge Base: Host internal podcast feeds for training or announcements, exposing the GPodder feed to existing corporate clients.
• Developer Tooling: Integrate PodFetch into CI pipelines to fetch and archive podcast episodes for automated QA or archival purposes.

Advantages

• Performance: Rust’s zero‑cost abstractions and async I/O give fast feed polling and concurrent downloads with minimal CPU overhead.
• Flexibility: The clear separation between API, storage, and frontend allows developers to swap components (e.g., replace PostgreSQL with SQLite for lightweight setups).
• Licensing: MIT license permits commercial use without copyleft obligations, unlike some open‑source media managers.
• Self‑Hosting Control: No reliance on third‑party services; all data remains on your infrastructure, addressing privacy concerns common in cloud‑based podcast apps.

PodFetch combines a modern Rust backend with a responsive React UI, delivering a