DOCSEARCHbyAlgolia
Submit Docs

bunqueue

repository·main·Indexed 19 days ago

https://github.com/egeominotti/bunqueue

A high-performance, zero-infrastructure job queue for Bun and AI agents featuring SQLite persistence, cron scheduling, and a native MCP server. It supports embedded and standalone server modes (TCP/HTTP), a Saga workflow engine for complex orchestration, and multi-language SDKs. Key capabilities include sharded in-memory priority queues, dead letter queues (DLQ), rate limiting, and an MQTT bridge for edge telemetry.

Tokens
363.4K
Snippets
882
Records
1.4K
Agent score
61%

What's inside bunqueue

  1. Overview of Official Bunqueue Polyglot SDKs

    main

    Bunqueue provides official network clients (SDKs) for multiple languages. While language APIs are designed to be idiomatic, all official clients must adhere to a strict production contract regarding transport, delivery, safety, and observability as defined in the protocol.

    Supported SDKs and Capabilities:

    SDKProducerWorker ModelAtomic FlowsTLSTelemetry
    TypeScriptYesConcurrentYesYesCallback + Lifecycle
    PythonYesConcurrentYesYesCallback
    PHPYesSequentialYesYesCallback
    GoYesConcurrentYesYesCallback
    RustYesBounded ThreadsYesYesCallback
    ElixirYesTask.async_streamYesYesCallback

    Note on Worker Models: PHP is intentionally designed for sequential processing as a worker model choice, whereas other SDKs support concurrency.

  2. Overview of bunqueue core capabilities

    main

    bunqueue is a high-performance, zero-external-dependency job queue designed for the Bun runtime. Its core architecture includes:

    • Sharded in-memory priority queues: High-speed job management.
    • SQLite Backend: Uses a write-behind SQLite store for persistence.
    • Transports: Supports both binary-TCP and HTTP transports.
    • Embedded SDK: Provides Queue and Worker abstractions for direct integration.
    • Saga Workflow Engine: For complex orchestration.
    • Native MCP Server: Built-in support for AI agents via the Model Context Protocol.

  3. Overview of the bunqueue CLI

    main

    The bunqueue CLI is a dual-purpose executable. It can be used to boot the server or act as a thin TCP client to interact with a running server.

    As a client, it allows operators to manage queues without writing code. You can use it to:

    • Push, pull, ack, or fail jobs.
    • Inspect job states, results, and logs.
    • Manage queues (pause, resume, drain, or obliterate).
    • Control Dead Letter Queues (DLQ), cron jobs, workers, and webhooks.
    • Manage rate limits and concurrency.
    • Run diagnostics (doctor) and trigger S3 backups.

    The CLI communicates with the server using a TCP wire protocol with msgpack encoding. It supports human-readable colorized output by default, but can also output results in JSON format using the --json flag.

  4. Explore bunqueue Feature Reference

    main

    The bunqueue documentation is organized into functional modules. You can find detailed information on the following areas:

    Engine & Jobs

    • Core Queue Engine: Central coordinator for sharding and job orchestration.
    • Job Lifecycle: Details on the push/pull/ack/fail state machine.
    • Dead Letter Queue (DLQ): Terminal sink for failed/stalled jobs with retry/purge capabilities.
    • Deduplication: Mechanisms for job-ID idempotency and unique keys.
    • Rate Limiting & Concurrency: Per-queue limits enforced server-side.

    Scheduling & Orchestration

    • Scheduler & Cron: Event-driven engine for recurring jobs.
    • Workflow Engine: Multi-step saga orchestration using a typed DSL.
    • FlowProducer: Atomic multi-queue graph creation and dependency management.

    Transport & SDKs

    • TCP Wire Protocol: Binary length-prefixed MessagePack transport.
    • HTTP/REST/SSE/WebSocket API: Control surface via port 6790.
    • Client SDKs: Official support for Rust, Elixir, and polyglot TCP clients.
    • Simple Mode: A thin all-in-one wrapper for pairing a Queue and Worker with built-in middleware and retries.

    Persistence & Observability

    • Persistence: Durable SQLite-backed storage with WAL and msgpack.
    • S3 Backup: Periodic compressed SQLite snapshots to S3.
    • Stats & Monitoring: Global and per-queue metrics, including latency histograms and throughput rates.

  5. Understand the bunqueue architecture and module map

    main

    bunqueue is a multi-mode queueing system that can operate in Embedded mode (in-process QueueManager) or Server (TCP) mode. The architecture is divided into several functional layers:

    Core Engine & Data

    • QueueManager & Shards: The central coordinator for all job operations.
    • Data Structures: Uses high-performance in-memory structures like 4-ary priority heaps and skip-lists for job indexing and temporal cleanup.
    • Persistence: Uses a durable SQLite-backed store with WAL and MessagePack for job, DLQ, and cron state.

    Job Operations & Orchestration

    • Job Lifecycle: Implements the primitive push, pull, ack, and fail operations.
    • Orchestration: Supports complex job trees via FlowProducer (BullMQ v5 compatible) and multi-step saga orchestration via the Workflow Engine.
    • Control Features: Includes Dead Letter Queues (DLQ), job deduplication, and rate limiting/concurrency control.

    Transports & SDKs

    • Protocols: Uses a binary length-prefixed MessagePack over TCP for high-performance client/server communication. It also provides an HTTP/REST/SSE/WebSocket API (port 6790).
    • Polyglot SDKs: Provides client libraries for TypeScript, Go, Python, Rust, and Elixir.
    • Simple Mode: An all-in-one wrapper that pairs a Queue and Worker with built-in middleware, retries, and circuit breakers.

    Observability & Management

    • Monitoring: Provides metrics via Prometheus, HTTP endpoints (/stats, /metrics, /health), and a web dashboard.
    • Management: Includes a CLI for server management and a Native MCP Server for AI agent integration.

  6. Supported Client SDKs and Platforms

    main

    Bunqueue provides official, production-grade SDKs for multiple runtimes. These SDKs communicate via a formal, versioned TCP protocol and MessagePack, allowing cross-language interoperability (e.g., a TypeScript producer can feed a Python consumer).

    PlatformPackageDistribution
    Node.js ≥ 20, Bun, Deno ≥ 2, Cloudflare Workersbunqueue-clientnpm
    Python ≥ 3.9bunqueue-clientPyPI
    PHP ≥ 8.1bunqueue/clientPackagist
    Go ≥ 1.26.5github.com/egeominotti/bunqueue/sdk/gogo get
    Rust ≥ 1.85bunqueue-clientcrates.io
    Elixir ≥ 1.15bunqueue_clientHex (upcoming)

  7. Understand the core capabilities of Bunqueue

    main

    Bunqueue provides a robust job queueing system with several key functional areas. Developers can rely on the following verified behaviors across both Embedded and Server (TCP) modes:

    Queue Management

    • Job Operations: Single/bulk adds, custom IDs, priority, delays, and retry strategies (fixed/exponential backoff).
    • Deduplication: TTL-based deduplication, extend, replace, and broker-wide custom-ID idempotency.
    • Queries: Generic/per-state queries, deterministic pagination, and job counts.
    • Control: Pause/resume, drain, obliterate, clean, promote, and retry failed/completed jobs.
    • Concurrency & Limits: Global concurrency, token-bucket rate limits, and QueueGroup isolation.
    • Namespacing: Support for namespaces/prefixes across jobs, workers, control, DLQ, and schedulers.

    Worker Behavior

    • Processing: Autorun/manual modes, runtime concurrency adjustments, and batching.
    • Reliability: Retry/backoff, graceful/forced shutdown, heartbeats, lock extension, and stall recovery.
    • Execution: Support for SandboxedWorker threads and CPU-yield expectations.

    Schedulers (Cron)

    • Management: Create, replace, move, list, get, count, and remove schedulers.
    • Scheduling: Support for five/six-field expressions, timezone support, and overlap prevention.
    • Recovery: SQLite restart recovery and fixed-rate anchoring.

    Dead Letter Queue (DLQ)

    • Inspection: Terminal attempt history, retention/eviction, and filtering by reason, time, retriability, or expiration.
    • Recovery: Retry all, retry one, or retry by filter; manual-chain resets.

    Flows (Atomic Graphs)

    • Execution: Atomic creation/rollback, chain/fan-in/tree ordering, and cross-queue dependencies.
    • Constraints: Bounded graph traversal and parent result reads.

  8. Overview of the Elixir client SDK components

    main

    The sdk/elixir/ directory contains the official OTP-native client for bunqueue in server mode. It utilizes the version 3 TCP protocol with MessagePack framing and supports the job-name capability. The core components are:

    • Bunqueue.Connection: A GenServer that manages an authenticated TCP or TLS socket. It handles lazy reconnections and manages stream closure.
    • Bunqueue.Queue: Provides access to query, control, and admin modules for commands like produce, bulk, lookup, queue control, DLQ (Dead Letter Queue), scheduler, rate-limit, and concurrency management.
    • Bunqueue.Worker: Manages job processing by bounding PULLB (pull jobs) via free concurrency. It uses Task.async_stream to process jobs, renews leases via an independent connection, and ensures exactly-once reporting of ACK or FAIL. It supports graceful shutdown by draining active handlers.
    • Bunqueue.FlowProducer: Used for creating child-first dependency trees and chains. It provides best-effort rollback for multi-job operations that fail.
    • Bunqueue.Telemetry: Provides optional structured connection and command events delivered via isolated lightweight processes.

  9. What is Bunqueue Simple Mode?

    main

    Bunqueue is an all-in-one wrapper that simplifies queue management by constructing both a Queue (for producing jobs) and a Worker (for consuming jobs) for the same queue name within a single object.

    It provides a unified processing pipeline that includes several opt-in features not available in the bare Queue or Worker SDKs, such as:

    • Middleware: An onion-style middleware chain.
    • Resilience: In-process retries with backoff and a circuit breaker.
    • Lifecycle Management: TTL expiry, priority aging, and graceful cancellation.
    • Advanced Processing: Batch accumulation, event triggers, and deduplication/debounce defaults.
    • Error Handling: Dead Letter Queue (DLQ) and rate-limiting passthrough.

    Note that Bunqueue does not implement its own transport; it delegates all core operations (enqueue, dequeue, persistence) to the underlying Queue/Worker (either via TCP or embedded SQLite).

  10. What is the Dead Letter Queue (DLQ)?

    main

    The Dead Letter Queue (DLQ) is a terminal sink for jobs that can no longer progress. Jobs enter the DLQ when they:

    • Exhaust their retry attempts.
    • Timeout during processing.
    • Are explicitly discarded.
    • Stall past maxStalls.
    • Lose their lock.
    • Have a parent job fail because a child job failed.

    Each DLQ entry preserves the original Job along with failure metadata (reason, error, attempt history, and timestamps) to allow operators to inspect, filter, retry, or purge dead jobs. The DLQ also supports optional time-based auto-retry with exponential backoff and age-based auto-purge.

  11. Overview of bunqueue Architecture and Modules

    main

    bunqueue is a distributed queueing system with a layered architecture. The system is organized into several functional domains:

    • Domain: Pure business logic and types (e.g., Shard, PriorityQueue, DlqShard).
    • Application: Use cases and managers (e.g., QueueManager, background tasks).
    • Infrastructure: External integrations like SQLite persistence, TCP/HTTP servers, schedulers, and S3 backups.
    • Client: SDKs for embedded use or TCP-based remote connections (Queue, Worker, Workflow, and Simple Mode).
    • Shared: Core utilities like locks, semaphores, LRU/TTL maps, and data structures (skipList, minHeap).
    • CLI & MCP: Command-line interface and Model Context Protocol server for AI agents.
    • Config: Configuration resolution and process entrypoints.

  12. Overview of bunqueue Data Structures

    main

    bunqueue utilizes several specialized data structures to optimize job queue operations, including priority scheduling, temporal indexing, and result caching. The core structures and their complexities are:

    StructureUse CaseComplexity
    4-ary MinHeapPriority queue, cron scheduling, delayed-job trackingO(log₄ n)
    Skip ListQueue-local temporal indexing, cleanup range queriesO(log q)
    LRU CacheJob results, custom IDsO(1)
    Hash (FNV-1a)Sharding, distributionO(len)