feat: 0.0.1
This commit is contained in:
146 files changed
+10444
No files matched your search
@@ -0,0 +1,171 @@
|
||||
# simple_bank
|
||||
|
||||
simple_bank is a small example backend service in Go that demonstrates a banking-style API with:
|
||||
- HTTP gateway (grpc-gateway) and gRPC server
|
||||
- PostgreSQL for persistent storage (SQLC generated queries)
|
||||
- Redis + Asynq for background task queue / worker processing
|
||||
- Migrations via golang-migrate
|
||||
- Email verification task example
|
||||
|
||||
This repository is intended as a reference/demo for building a production-ish Go service with background jobs.
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
- RESTful HTTP gateway (default `:8080`) backed by gRPC (default `:9090`)
|
||||
- gRPC API and generated protobufs (uses grpc-gateway)
|
||||
- Database operations generated with `sqlc`
|
||||
- Background job dispatching and processing with `asynq` (Redis)
|
||||
- Config-driven via environment variables
|
||||
- Example Send Verification Email background task
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Go 1.20+ (or compatible)
|
||||
- PostgreSQL
|
||||
- Redis
|
||||
- make/migrate/other CLIs (optional for migrations)
|
||||
- Docker & Docker Compose (recommended for local dev)
|
||||
|
||||
---
|
||||
|
||||
## Quickstart (development)
|
||||
|
||||
1. Copy environment example (or use `api.env`):
|
||||
- Main variables you will want to set:
|
||||
- `DB_ADDR` (Postgres connection string)
|
||||
- `REDIS_ADDR` (Redis host:port)
|
||||
- `HTTP_SERVER_ADDR` (default `:8080`)
|
||||
- `GRPC_SERVER_ADDR` (default `:9090`)
|
||||
- `ENVIRONMENT` (e.g. `development` to enable console logs)
|
||||
|
||||
2. Start local infra with Docker Compose (if you want local Postgres + Redis):
|
||||
- (This repo includes a `docker-compose.yml` with Postgres and Redis)
|
||||
- Example:
|
||||
- docker-compose up -d
|
||||
- Confirm Postgres and Redis are reachable at the addresses in your env.
|
||||
|
||||
3. Run DB migrations:
|
||||
- Using golang-migrate CLI (example):
|
||||
- migrate -path db/migrations -database "postgres://postgres:postgres@localhost:5432/simple_bank?sslmode=disable" up
|
||||
- Adjust the `database` URL to match your `DB_ADDR` environment variable.
|
||||
|
||||
4. Download dependencies and build:
|
||||
- go mod download
|
||||
- go build -o simple_bank ./...
|
||||
|
||||
5. Run the service:
|
||||
- With the environment loaded (example):
|
||||
- export $(cat api.env | xargs) # or use your preferred env loader
|
||||
- ./simple_bank
|
||||
- Running the binary will:
|
||||
- start the task processor (asynq server) that consumes background jobs
|
||||
- start gRPC server (on `GRPC_SERVER_ADDR`)
|
||||
- start the HTTP gateway (on `HTTP_SERVER_ADDR`) in a goroutine/handler
|
||||
|
||||
- Alternatively, run directly with `go run`:
|
||||
- go run ./main.go
|
||||
|
||||
6. Verify:
|
||||
- HTTP gateway: http://localhost:8080 (or whatever `HTTP_SERVER_ADDR` you configure)
|
||||
- gRPC: connect at the configured `GRPC_SERVER_ADDR`
|
||||
- Redis dashboard / Redis Commander: if using docker-compose, a redis-commander service may be available
|
||||
|
||||
---
|
||||
|
||||
## Background Worker (Asynq)
|
||||
|
||||
- Tasks are enqueued by the app and processed by an asynq server embedded in the application.
|
||||
- The worker configuration (queues and handlers) lives under `worker/`:
|
||||
- `worker.NewRedisTaskProcessor` creates the asynq server (`asynq.Server`) with queue weights and error handler.
|
||||
- `worker.NewRedisTaskDistributor` creates a client to enqueue tasks.
|
||||
- Example queue names: `CriticalQueue`, `DefaultQueue`.
|
||||
|
||||
Customizing logs and formatting for asynq:
|
||||
- The asynq server can be given a custom logger via `asynq.Config.Logger`. This project includes `worker/logger.go` which adapts logs to `zerolog`. Edit `worker/logger.go` if you want to change asynq log formatting/fields.
|
||||
- If you also want to capture/format other libraries' logs (for example libraries that use the standard `log` package), redirect stdlib logs to your `zerolog` instance at startup.
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Important variables (see `api.env` for full list):
|
||||
|
||||
- Server:
|
||||
- `HTTP_SERVER_ADDR` (default `:8080`)
|
||||
- `GRPC_SERVER_ADDR` (default `:9090`)
|
||||
- `ENVIRONMENT` (`development` for console logs)
|
||||
- Database:
|
||||
- `DB_DRIVER` (e.g. `pgx`)
|
||||
- `DB_ADDR` (postgres connection string)
|
||||
- `MIGRATIONS_URL` (e.g. `file://db/migrations`)
|
||||
- Redis:
|
||||
- `REDIS_ADDR` (e.g. `localhost:6379`)
|
||||
- `REDIS_PASSWORD`
|
||||
- `REDIS_DB`
|
||||
- Auth / Tokens:
|
||||
- `AUTH_TOKEN_SECRET`, `AUTH_TOKEN_EXP`, `REFRESH_TOKEN_EXP`
|
||||
- Email:
|
||||
- `EMAIL_FROM`, `EMAIL_SMTP_PASSWORD` (used by the worker email task)
|
||||
- Rate limiter:
|
||||
- `RATE_LIMITER_REQS_COUNT`, `RATE_LIMITER_TIME_FRAME`, `RATE_LIMITER_ENABLED`
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
- Unit tests:
|
||||
- go test ./...
|
||||
- Integration tests:
|
||||
- Ensure Postgres and Redis are running and configured as in `api.env` before running tests that depend on external services.
|
||||
|
||||
---
|
||||
|
||||
## Development tips
|
||||
|
||||
- To change queue weights, error handling or task handlers, edit `worker/processor.go`.
|
||||
- To change how tasks are enqueued, review `worker/distributer.go`.
|
||||
- To adjust logging format globally, modify `main.go` startup logger configuration and `worker/logger.go`.
|
||||
- Protobuf / gRPC: regenerate stubs if you change proto files (this project uses `pb/` and generated code).
|
||||
|
||||
---
|
||||
|
||||
## Project layout (high level)
|
||||
|
||||
- `main.go` — application entrypoint
|
||||
- `api/` — Gin HTTP handlers (HTTP server)
|
||||
- `gapi/` — gRPC server, grpc-gateway wiring
|
||||
- `worker/` — asynq task distributor & processor, custom logger
|
||||
- `db/` — SQLC generated code and migrations
|
||||
- `pb/` — generated protobuf/gRPC code
|
||||
- `docs/statik` — static files (swagger UI) bundled with the binary
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- If migrations fail:
|
||||
- Confirm `DB_ADDR` is correct and database is reachable.
|
||||
- Check that `db/migrations` contains the migration files and paths are correct.
|
||||
- If Redis jobs don't process:
|
||||
- Confirm the app can reach Redis (`REDIS_ADDR`).
|
||||
- Ensure the process that runs the asynq server is running (the app starts it by default).
|
||||
- If logs appear in different formats:
|
||||
- Redirect stdlib logs into `zerolog` or update `worker/logger.go` to include more structured context.
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
- Fork and open pull requests.
|
||||
- Keep changes small and focused; add/update unit tests where appropriate.
|
||||
|
||||
---
|
||||
|
||||
If you'd like, I can:
|
||||
- Add a short example curl snippet for the HTTP API endpoints.
|
||||
- Add a sample `docker-compose` snippet and explicit commands for local development.
|
||||
- Add a "Deploy" section with production tips (env secrets, TLS, metrics, etc.).
|
||||
Reference in new issue
Block a user