From ee5d01aa66a833b583b6cffe7ad6d2f36a6b5674 Mon Sep 17 00:00:00 2001 From: Zeni Kim Date: Sun, 13 Sep 2026 01:18:13 -0500 Subject: [PATCH] updated README.md --- README.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 80 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 4ae95df..7a8c574 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,9 @@ Cup is a skeleton project for the Goffee [Go](https://go.dev) framework made fo - JWT tokens - Cache (Redis) - HTTPS (TLS) +- Queues ([asynq](https://github.com/hibiken/asynq)) +- Scheduler (DB-backed task runner) +- Server-side template rendering ## Installation To create a new `cup` project you need to install the `Goffee's cli` first @@ -67,26 +70,97 @@ The first component that receive's the request in `Cup` is the `Router`, then `Goffee` locates the matching [handler](https://git.smarteching.com/goffee/docs/handlers) of the request and it check's if there are any [hooks](https://git.smarteching.com/goffee/docs/hooks) to be executed either before or after the [controller](https://git.smarteching.com/goffee/controllers), if so, it executes them in the right order, then at the final stage it returns the response to the user. `Request -> Router -> Optional Hooks -> Controller -> Optional Hooks -> Response` +## Configuration +The application is configured through the `config/` package. Each file exposes a single +`Get...Config()` function that returns a `core.*Config` struct. The most important toggles are: + +| File | Function | Controls | +| --- | --- | --- | +| `config/dotenvfile.go` | `GetEnvFileConfig()` | Whether to load variables from the `.env` file | +| `config/request.go` | `GetRequestConfig()` | Max upload file size | +| `config/gorm.go` | `GetGormConfig()` | Enables the GORM database layer | +| `config/cache.go` | `GetCacheConfig()` | Enables the cache (Redis) | +| `config/queue.go` | `GetQueueConfig()` | Enables the queue system (asynq) | +| `config/scheduler.go` | `GetSchedulerConfig()` | Enables the DB-backed scheduler | + +The enabled features are wired up in `main.go`. For example, queues are only started when +`GetQueueConfig().EnableQueue` is `true`, and the scheduler only when +`GetSchedulerConfig().EnableScheduler` is `true`. + +## Background jobs + +Cup ships with two independent background processing systems, both disabled by default. + +### Queues (asynq) +The queue system is built on [asynq](https://github.com/hibiken/asynq). Register your task +handlers in `register-queues.go`: + +```go +queque.AddWork(workers.TypeWelcomeEmail, workers.HandleWelcomeEmailTask) +``` + +Task types and handlers live under `workers/`. To enqueue a task from a controller use the +queue client, as shown in `controllers/queuesample.go`: + +```go +client := c.GetQueueClient() +client.Enqueue(asynq.NewTask(workers.TypeWelcomeEmail, payload)) +``` + +### Scheduler +The scheduler is a lightweight, DB-backed task runner. Register handlers in +`register-scheduler.go`: + +```go +sched.AddWork("send_email", handleSendEmail) +``` + +Tasks are enqueued into the `queue_items` table and can run multiple times, with +priorities and concurrency. See `controllers/schedsample.go` for examples of enqueuing +tasks with different `maxRuns` / `thread` / priority values. + +### Managing the scheduler from the CLI +The `goffee` cli provides commands to inspect and manage the scheduler tables. They must be +run from the project directory: + +```bash +goffee scheduler:queue dev # list pending/processing tasks +goffee scheduler:processed dev 20 # list the last 20 processed executions +goffee scheduler:semaphore dev # show the semaphore state +goffee scheduler:semaphore dev red # block execution (after restart) +goffee scheduler:truncate dev # empty the queue and processed logs +``` + ## Folder structure ```bash ├── cup │ ├── config/ --------------------------> main configs -│ ├── events/ --------------------------> contains events -│ │ ├── jobs/ ------------------------> contains the event jobs │ ├── controllers/ ---------------------> route's controllers -│ ├── logs/ ----------------------------> app log files +│ ├── events/ --------------------------> contains events +│ │ ├── event-names.go ---------------> event name constants +│ │ └── eventjobs/ -------------------> contains the event jobs │ ├── hooks/ ---------------------------> app hooks +│ ├── logs/ ----------------------------> app log files │ ├── models/ --------------------------> database models │ ├── storage/ -------------------------> a place to store files +│ │ ├── app/ -------------------------> static files served under /app +│ │ ├── cdn/ -------------------------> static files served under /cdn +│ │ ├── public/ ----------------------> static files served under /public +│ │ ├── sqlite/ ----------------------> sqlite database file +│ │ └── templates/ -------------------> server-side templates │ ├── tls/ -----------------------------> tls certificates -│ ├── .env -----------------------------> environment variables +│ ├── utils/ ---------------------------> shared helpers and seed data +│ ├── workers/ -------------------------> queue task types and handlers +│ ├── .env -----------------------------> environment variables │ ├── .gitignore -----------------------> .gitignore │ ├── go.mod ---------------------------> Go modules │ ├── LICENSE --------------------------> license │ ├── main.go --------------------------> go main file │ ├── README.md ------------------------> readme file │ ├── register-events.go ---------------> register events and jobs -│ ├── register-global-hooks.go ---------> register global middlewares +│ ├── register-global-hooks.go ---------> register global hooks +│ ├── register-queues.go ---------------> register queue workers +│ ├── register-scheduler.go ------------> register scheduler tasks │ ├── routes.go ------------------------> app routes │ ├── run-auto-migrations.go -----------> database migrations -``` \ No newline at end of file +```