2026-08-05 06:59:14 -05:00
|
|
|
# Chirpy
|
|
|
|
|
|
2026-08-15 22:07:31 -05:00
|
|
|
A Twitter-style microblogging API built in Go as part of the [boot.dev](https://boot.dev) back-end course.
|
|
|
|
|
|
|
|
|
|
## Features
|
|
|
|
|
|
|
|
|
|
- Create, list, sort, and delete chirps (140-char limit, profanity-filtered)
|
|
|
|
|
- User registration and login with password hashing (argon2id)
|
|
|
|
|
- JWT access tokens and revocable refresh tokens
|
|
|
|
|
- Chirpy Red subscription upgrades via Polka webhooks
|
|
|
|
|
- Graceful shutdown and a lightweight admin metrics/reset surface
|
|
|
|
|
|
|
|
|
|
## Tech stack
|
|
|
|
|
|
|
|
|
|
- Go 1.26 (standard `net/http` with `http.ServeMux` routing)
|
|
|
|
|
- PostgreSQL
|
|
|
|
|
- [sqlc](https://sqlc.dev) for type-safe query generation
|
|
|
|
|
- [goose](https://pressly.github.io/goose/) for migrations
|
|
|
|
|
- [golang-jwt/jwt](https://github.com/golang-jwt/jwt) and [argon2id](https://github.com/alexedwards/argon2id)
|
|
|
|
|
|
|
|
|
|
## Getting started
|
|
|
|
|
|
|
|
|
|
### Prerequisites
|
|
|
|
|
|
|
|
|
|
- Go 1.26+
|
|
|
|
|
- PostgreSQL running locally
|
|
|
|
|
- `sqlc`, `goose`, and `make` (run `make install-tools` to install the first two)
|
|
|
|
|
|
|
|
|
|
### Setup
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
# 1. Configure environment variables
|
|
|
|
|
cp .env.example .env
|
|
|
|
|
|
|
|
|
|
# fill in DB_URL, PLATFORM, JWT_SECRET, and POLKA_KEY
|
|
|
|
|
|
|
|
|
|
# 2. Apply database migrations
|
|
|
|
|
make migrate-up
|
|
|
|
|
|
|
|
|
|
# 3. Run the server
|
|
|
|
|
make run
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The server listens on `http://localhost:8080`.
|
|
|
|
|
|
|
|
|
|
### Development
|
|
|
|
|
|
|
|
|
|
Run `make help` to see the full list of targets. Highlights:
|
|
|
|
|
|
2026-08-15 22:10:58 -05:00
|
|
|
| Target | Description |
|
|
|
|
|
| ----------------------------------------------------------------------- | -------------------------------------- |
|
|
|
|
|
| `make run` | Build and run the server |
|
|
|
|
|
| `make dev` | Run with the race detector enabled |
|
|
|
|
|
| `make test` | Run all tests |
|
|
|
|
|
| `make test-race` | Run all tests with the race detector |
|
|
|
|
|
| `make check` | Run formatting, vet, and test checks |
|
|
|
|
|
| `make fmt` | Format all Go source files |
|
|
|
|
|
| `make lint` | Run golangci-lint (if installed) |
|
|
|
|
|
| `make build` | Compile the binary into `bin/` |
|
|
|
|
|
| `make generate` | Regenerate sqlc query code |
|
|
|
|
|
| `make migrate-up` / `migrate-down` / `migrate-status` / `migrate-reset` | Database migrations |
|
|
|
|
|
| `make install-tools` | Install goose, sqlc, and golangci-lint |
|
|
|
|
|
| `make clean` | Remove build artifacts |
|
2026-08-15 22:07:31 -05:00
|
|
|
|
|
|
|
|
## API reference
|
|
|
|
|
|
|
|
|
|
| Method | Path | Description |
|
|
|
|
|
| ------ | --------------------- | ----------------------------------------------- |
|
|
|
|
|
| POST | `/api/users` | Register a user |
|
|
|
|
|
| PUT | `/api/users` | Update email/password (Bearer access token) |
|
|
|
|
|
| POST | `/api/login` | Log in, receive access + refresh tokens |
|
|
|
|
|
| POST | `/api/refresh` | Exchange a refresh token for a new access token |
|
|
|
|
|
| POST | `/api/revoke` | Revoke a refresh token |
|
|
|
|
|
| GET | `/api/chirps` | List chirps (`?author_id=`, `?sort=asc\|desc`) |
|
|
|
|
|
| GET | `/api/chirps/{id}` | Get a single chirp |
|
|
|
|
|
| POST | `/api/chirps` | Create a chirp (Bearer access token) |
|
|
|
|
|
| DELETE | `/api/chirps/{id}` | Delete a chirp you authored |
|
|
|
|
|
| POST | `/api/polka/webhooks` | Polka webhook (`user.upgraded` -> Chirpy Red) |
|
|
|
|
|
| GET | `/api/healthz` | Health check |
|
|
|
|
|
| GET | `/app/` | Static index page |
|
|
|
|
|
| GET | `/admin/metrics` | File server hit counter (dev only) |
|
|
|
|
|
| POST | `/admin/reset` | Reset the database (dev only) |
|
|
|
|
|
|
|
|
|
|
## Regenerating sqlc code
|
|
|
|
|
|
|
|
|
|
After changing `sql/queries/`, run:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
make generate
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## License
|
|
|
|
|
|
|
|
|
|
MIT — see [LICENSE.md](LICENSE.md).
|
