Queues

Introduction

Queues defer work (emails, exports, webhooks) to background workers. JCC Express supports memory, database, and Redis-style drivers (per app/Config/.ts). Dispatch with **app.resolve("Queue") or the global dispatch(...) helper, then run bun artisanNode :work. A web dashboard under /** is registered by default (see _Queue dashboard_).

Configuration

The configuration file is stored in app/Config/.ts.

Driver Prerequisites

Database

In order to use the database driver, you will need a database table to hold the jobs. To generate a migration that creates this table, run the make:-table Artisan command:

Queue dashboard (built-in web UI)

The framework ships with a small management UI, wired in **jcc-express-mvc/lib/Queue and registered by RouteServiceProvider: routes are mounted under the /** prefix (see lib/Providers/RouteServiceProvider.ts and lib/Queue/Route/web.ts).

| Method & path | Purpose | | ------------------------------------ | ---------------------------------------------------------------------------- | | GET //dashboard | Dashboard (jsBlade view **/dashboard**) | | GET //jobs | JSON list of queues (intended for API consumers) | | GET //jobs/{status} | Jobs for a given status (e.g. pending, failed) — view **/jobs** | | PUT / PATCH //jobs/{id}/{status} | Retry a failed job or run a pending / processing job from the UI | | DELETE //jobs/{id} | Remove a job from the store | | POST //jobs | Hook for running jobs (body handled by controller) |

Views: the starter app includes **resources/views//dashboard.blade.html and resources/views//jobs.blade.html. If you publish only jcc-express-mvc**, copy or recreate those views under your app’s resources/views// (or override the controller).

Guards: All //* routes use **queueDashboardGuard** (lib/Queue/middleware/queueDashboardGuard.ts), applied in **lib/Queue/Route/web.ts. When APP_ENV is local, the guard does nothing (open access for development). Otherwise it runs the same JWT cookie auth as AuthMiddleware.auth, then GateFacade.can(user, "viewJobs"). Define viewJobs** in a service provider (e.g. Gate.define("viewJobs", (user) => …)). Unauthenticated users are redirected to **/login; authenticated users without the ability get 403. The guard is re-exported from jcc-express-mvc/lib/Queue as queueDashboardGuard** if you need to reuse it.

Creating Jobs

Generating Job Classes

To generate a new job class, use the make:job Artisan command or create a class extending Job.

Dispatching Jobs

Once you have written your job class, you may dispatch it using the service or the global dispatch(...) helper.

Using the global helper:

Running The Queue Worker

JCC Express includes a worker that will process new jobs as they are pushed onto the . You may run the worker using the :work Artisan command:

Handling Failed Jobs

Retries & Backoff

If an exception is thrown while the job is being processed, the job will automatically be released back onto the to be retried. The job will be retried until it has reached the maximum number of attempts defined by your maxAttempts property.

By default, jobs use an exponential backoff. You may customize this by overriding the backoff method in your job class.

The Failed Jobs Table

When a job exceeds its maximum attempts, it will be moved into the failed_jobs database table. This table contains the job's payload, exception information, and the time it failed.

To create the failed_jobs table, ensure you have run the table migration:

Viewing Failed Jobs

Use the dashboard (**//jobs/failed**) when the database driver is in use, or inspect the failed_jobs table directly: