apalis-skills

A comprehensive skill that enables LLM-based coding assistants to accurately use and build solutions with the Apalis Rust library — a robust, tower-native background job processing and message queue framework.

Overview

Apalis is a Rust-first framework for building reliable, scalable background job processors and message-driven systems. It provides durable job queues, real-time message consumption, retry logic, observability, and graceful shutdown — all built on the tower::Service trait, giving access to the entire tower middleware ecosystem.

• Website: apalis.dev
• GitHub: github.com/apalis-dev/apalis
• Target version: v1.0.0-rc.7
• License: MIT OR Apache-2.0

Installation

npx skills add melonask/apalis-skills

What This Skill Covers

Core Concepts

• Backend, TaskSink, Metrics, Expose traits and when to use each
• Task<Args, Ctx, IdType> job wrapper with Parts metadata
• Job lifecycle states (Pending, Scheduled, Running, Done, Failed, Retry, Killed)
• Monitor orchestration and graceful shutdown
• WorkerBuilder API and FromRequest extractors (Data<T>, TaskId<RandomId>, Attempt, WorkerContext)
• TaskBuilder fluent API for constructing tasks with scheduling and metadata

9 Backends

• Storage (durable): Redis, PostgreSQL, SQLite, MySQL, in-Memory
• MessageQueue (fire-and-forget): AMQP/RabbitMQ, NATS, PGMQ, RSMQ
• Each with Cargo.toml dependencies, connection setup, and push/consume examples

Middleware Layers

• Tracing (default), Retry with configurable policy, Timeout, Catch-panic, Rate limiting, Filtering
• Custom tower layer creation
• Recommended layer composition order for production

Advanced Patterns

• Multiple job types with separate workers and storages
• Axum integration with shared storage
• Scheduled tasks via TaskBuilder + push_task()
• Stream-as-backend (any Stream can be a job source)
• MakeShared for sharing backends across workers
• Expose traits for programmatic observability
• Polling strategies (Interval, Backoff, Multi, Stream)
• Graceful shutdown coordination with custom signals

Error Handling

• AbortError — permanently fail (no retry)
• RetryAfterError — retry after specified delay
• DeferredError — instant retry
• BoxDynError — treated as transient (retryable)

File Structure

apalis/
├── SKILL.md                          # Main skill file (core concepts, patterns, error handling)
├── README.md                         # This file
├── known-issues.md                   # Verified bugs, limitations, and workarounds for v1.0.0-rc.7
└── references/
    ├── backends.md                   # All 9 backends: setup, config, and usage examples
    ├── middleware-layers.md          # Built-in layers, custom layers, Data<T> extraction
    └── patterns-advanced.md          # Web integration, scheduling, observability, shutdown

File	Purpose
SKILL.md	Core architecture, traits, quick start, 6 essential patterns, error handling, feature flags
known-issues.md	12 verified issues with workarounds for v1.0.0-rc.7
references/backends.md	Detailed setup for Memory, Redis, PostgreSQL, SQLite, MySQL, AMQP, NATS, PGMQ, RSMQ
references/middleware-layers.md	TraceLayer, RetryLayer, TimeoutLayer, CatchPanicLayer, FilterLayer, custom layers, Data pattern
references/patterns-advanced.md	Multiple job types, Axum integration, TaskBuilder, polling strategies, observability, shutdown

Quick Example

use apalis::prelude::*;

#[derive(Debug, Clone)]
struct Email { to: String, subject: String }

async fn send_email(email: Email) {
    println!("Sending email to: {}", email.to);
}

#[tokio::main]
async fn main() -> Result<(), BoxDynError> {
    let mut storage = MemoryStorage::new();
    storage.push(Email { to: "user@example.com".into(), subject: "Hi".into() }).await?;

    Monitor::new()
        .register(|_| {
            WorkerBuilder::new("emailer")
                .backend(MemoryStorage::new())
                .build(send_email)
        })
        .run()
        .await?;

    Ok(())
}

Trigger Phrases

This skill activates when the user's request involves any of the following:

• Background workers or job processors in Rust
• Task queues or message queues (Redis, PostgreSQL, SQLite, MySQL, AMQP, NATS, PGMQ, RSMQ)
• Asynchronous job processing (emails, file processing, reports, webhooks)
• Retry logic, timeouts, rate limiting, or job scheduling in Rust
• Monitoring workers and job queues
• Integrating background processing into web frameworks (Axum, Actix-Web)
• Building message consumers or event-driven systems
• Graceful shutdown of worker processes
• Tower middleware with job processing
• The apalis crate or any of its backend crates

Key Design Decisions

• SKILL.md under 500 lines — follows progressive disclosure; detailed docs live in references/
• Trigger-optimized description — uses a "pushy" description that lists many trigger phrases to maximize accurate activation
• Code verified against v1.0.0-rc.7 — all examples tested with 20 binaries in a real project using Redis, PostgreSQL, and SQLite backends
• Known issues documented — 12 verified issues with workarounds, including a custom FromRequest limitation

License

This skill is provided as-is for educational and development purposes. Apalis is licensed under MIT OR Apache-2.0.