Gator - RSS Feed Aggregator

A command-line RSS feed aggregator written in Go that allows users to manage and aggregate RSS feeds, follow feeds of interest, and browse posts from subscribed feeds.

Features

• User Management: Register and manage multiple users with login switching
• Feed Management: Add and track RSS feeds from various sources
• RSS Aggregation: Automatically fetch and parse RSS feeds at configurable intervals
• Feed Subscription: Follow and unfollow RSS feeds
• Post Browsing: Browse aggregated posts from followed feeds
• Database Persistence: Store users, feeds, posts, and subscriptions in PostgreSQL

Prerequisites

• Go 1.26.2 or later
• PostgreSQL database
• Command-line interface

Installation

1. Clone the repository:

git clone https://github.com/itsankitpatel/gator.git
cd gator

2. Install dependencies:

go mod download

NOTE: You can skip the above two steps if you install the project via go install:

go install github.com/itsankitpatel/gator@latest

and then you can run the commands with gator instead of go run ..

3. Set up your PostgreSQL database

   1. Download postgresql
   2. Check the postgresql version

   psql --version

   • Update postgres password:

   sudo passwd postgres

   Enter a password, and be sure you won't forget it. You can just use something easy like postgres.

   • Start the postgres server in background
     For Linux:

     sudo service postgresql start

     For macOS:

     brew services start postgresql

   • Enter the psql shell
     For Linux:

     sudo -u postgres psql

     For macOS:

       psql postgres

     You should see something like this:

     postgres=#

   • Create a new database named gator:

   CREATE DATABASE gator;

   • Connect to the gator database:

   \c gator;

   • Set the user password(Linux/WSL only):

   ALTER USER postgres WITH PASSWORD 'postgres';

   For simplicity, I used postgres as the password. Before, we altered the system user's password, now we're altering the database user's password.

4. Create a .gatorconfig.json file in your home directory:

{
  "db_url": "postgres://username:password@localhost/gator?sslmode=disable",
  "current_user_name": ""
}

Usage

User Management

Register a new user:

go run . register <username>

Login as a user:

go run . login <username>

List all users:

go run . users

Feed Management

Add a new RSS feed:

go run . addfeed <feed_name> <feed_url>

Requires user to be logged in. Automatically follows the feed for the current user.

List all feeds:

go run . feeds

Feed Subscription

Follow a feed by URL:

go run . follow <feed_url>

Requires user to be logged in. Adds an existing feed to the current user's subscriptions.

List feeds you're following:

go run . following

Requires user to be logged in.

Unfollow a feed:

go run . unfollow <feed_url>

Requires user to be logged in. Removes the feed from your subscriptions.

RSS Aggregation

Start automatic feed aggregation:

go run . agg <interval>

Fetches all RSS feeds at the specified interval (e.g., 10s, 1m, 5m).

Example:

go run . agg 30s

This fetches all feeds every 30 seconds and saves new posts to the database.

Browse Posts

View posts from followed feeds:

go run . browse [limit]

Requires user to be logged in. Displays posts from feeds you follow. Optionally specify the number of posts to display (default: 2).

Example:

go run . browse 5

Database Management

Reset the entire gator database:

go run . reset

Clears all data from users, feeds, posts, and feed follows tables.

Architecture

Project Structure

gator/
├── main.go                          # Application entry point
├── commands.go                      # Command registration and routing
├── handler_*.go                     # HTTP handlers for each command
├── rss_feed.go                      # RSS parsing logic
├── internal/
│   ├── config/
│   │   └── config.go               # Configuration management
│   └── database/
│       ├── db.go                   # Database initialization
│       ├── models.go               # Data models
│       └── *.sql.go                # Auto-generated SQL queries
└── sql/
    ├── schema/                     # Database schema migrations
    └── queries/                    # SQL queries

Database Schema

• users: Stores user accounts
• feeds: Stores RSS feed URLs and metadata
• feed_follows: Tracks which users follow which feeds
• posts: Stores individual blog posts from feeds

Configuration

The application uses a .gatorconfig.json file in your home directory to store:

• db_url: PostgreSQL connection string
• current_user_name: Currently logged-in user

Dependencies

• github.com/google/uuid - UUID generation for database records
• github.com/lib/pq - PostgreSQL driver for Go

How It Works

1. User Registration: Create user accounts that are stored in the database
2. Feed Management: Add RSS feed URLs to track
3. Aggregation: The agg command fetches feeds on an interval:
   • Fetches the next unfetched feed
   • Marks the feed as fetched
   • Parses the RSS XML
   • Saves new posts to the database (skips duplicates)
4. Browsing: Users can browse posts from feeds they follow, filtered by user

Development Notes

• The application uses context-based database queries for proper timeout handling
• RSS parsing handles both RFC1123Z and RFC1123 date formats
• HTML entities in RSS content are properly unescaped
• Duplicate posts are automatically skipped during aggregation
• Authentication is handled through config file user switching (middleware)