gator

Gator

Gator is a command-line RSS feed aggregator and reader written in Go. It allows users to register, follow/unfollow feeds, fetch and browse posts, and manage their subscriptions, all backed by a PostgreSQL database.

Features

• User registration and login
• Add, follow, and unfollow RSS feeds
• Fetch and store posts from feeds
• Browse posts from followed feeds
• Periodic feed aggregation
• Command-based interface
• Persistent configuration and session management

Requirements

• Go 1.24.4 or later
• PostgreSQL database
• sqlc for generating database access code

Setup

1. Install with Go:

   go install github.com/kevvarlar/gator@latest
   

2. Configure the database:

   • Create a new PostgreSQL database called gator by running: (Linux/WSL)

     sudo -u postgres psql -c "CREATE DATABASE gator;"
     

   (Mac)

   psql postgres -c "CREATE DATABASE gator;"
   

   • Set the db_url in your config (see below).

3. Get the migration files:

   • Download or clone the migration files from the repository:

     git clone https://github.com/kevvarlar/gator.git
     # Or download just the sql/schema directory from the repo
     

4. Run database migrations:

   • Use goose or your preferred migration tool:

     goose -dir sql/schema postgres "$DB_URL" up
     

5. Generate Go database code (for development only):

   sqlc generate
   

Usage

After installation, you can run Gator from anywhere:

gator <command> [arguments...]

Configuration

Gator uses a JSON config file stored at ~/.gatorconfig.json:

{
  "db_url": "postgres://user:password@localhost:5432/gatordb?sslmode=disable",
  "current_user_name": "yourusername"
}

You can set the current user with the login command.

Commands

• register <username>: Register a new user
• login <username>: Set the current user
• addfeed <feed_name> <feed_url>: Add a new feed and follow it
• feeds: List all feeds
• follow <feed_url>: Follow an existing feed
• unfollow <feed_url>: Unfollow a feed
• following: List feeds you are following
• browse [limit]: Show recent posts from followed feeds (default limit: 2)
• agg <duration>: Periodically fetch new posts (e.g., agg 10m)
• reset: Delete all users (admin/dev only)
• users: List all users

Database Schema

• users: Stores user accounts
• feeds: Stores RSS feeds
• feed_follows: Many-to-many relationship between users and feeds
• posts: Stores posts fetched from feeds

See sql/schema/ for full schema definitions.

Code Structure (for contributors)

• main.go: Entry point, command registration, and app startup
• command.go: Command handlers and business logic
• scrape.go: Feed fetching and post creation
• rss.go: RSS parsing utilities
• middleware.go: Middleware for logging in
• internal/config/: Configuration management
• internal/database/: Database access (generated by sqlc)
• sql/queries/: SQL queries for sqlc
• sql/schema/: Database schema migrations

License

MIT License. See LICENSE for details.