Stevan Freeborn
9eca3c71e2
Add godoc comments to the exported auth package helpers. Expand the README with feature and tech stack overviews, setup instructions, an API reference, and make targets for development workflows.
95 lines
3.7 KiB
Markdown
95 lines
3.7 KiB
Markdown
# Chirpy
|
|
|
|
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:
|
|
|
|
| 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 |
|
|
|
|
## 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).
|