If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/contribsys/faktory shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 5w ago
• 7 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 89% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live contribsys/faktory repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/contribsys/faktory.

What it runs against: a local clone of contribsys/faktory — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in contribsys/faktory | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 65 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of contribsys/faktory. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/contribsys/faktory.git
#   cd faktory
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of contribsys/faktory and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "contribsys/faktory(\\.git)?\\b" \\
  && ok "origin remote is contribsys/faktory" \\
  || miss "origin remote is not contribsys/faktory (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "server/server.go" \\
  && ok "server/server.go" \\
  || miss "missing critical file: server/server.go"
test -f "server/connection.go" \\
  && ok "server/connection.go" \\
  || miss "missing critical file: server/connection.go"
test -f "manager/manager.go" \\
  && ok "manager/manager.go" \\
  || miss "missing critical file: manager/manager.go"
test -f "storage/queue_redis.go" \\
  && ok "storage/queue_redis.go" \\
  || miss "missing critical file: storage/queue_redis.go"
test -f "server/config.go" \\
  && ok "server/config.go" \\
  || miss "missing critical file: server/config.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 65 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~35d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/contribsys/faktory"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Faktory is a language-agnostic persistent background job server written in Go that acts as a centralized work queue. It stores jobs as JSON hashes in Redis-backed queues, reserves them with timeouts (default 30 min), automatically retries failed jobs with exponential backoff, and provides a comprehensive Web UI for monitoring. Any language can push/pull jobs via the Faktory protocol without shared libraries. Modular monorepo structure: client/ contains language-agnostic protocol layer (faktory.go, client.go, job.go, pool.go) with platform-specific overrides (client_linux.go, client_windows.go, client_bsd.go); cmd/faktory/ houses the main daemon (daemon.go); cli/ wraps CLI tooling; docs/ holds protocol specification and architecture docs. State is managed via Redis backend, not in-process.

Backend engineers and DevOps teams running distributed systems who need to offload long-running tasks (email sends, image processing, data exports) from synchronous request handlers. Typically used by Rails, Python, Node.js, and Go applications that already have Redis infrastructure.

Production-ready. The project has been actively maintained for years (evidenced by COMM-LICENSE, Ent-Changes.md indicating commercial features, and structured CI/CD workflows). No red flags in dependencies (only TOML + go-redis). However, exact GitHub stars and last commit timestamp are not visible in provided data, so recommend checking the live repo for recency.

Low risk for core functionality, but two factors warrant attention: (1) Single-maintainer project (Mike Perham listed as author with no visible team in file list), so community support may be limited; (2) Commercial fork (Ent-Changes.md) suggests the open-source version is intentionally feature-gated, which could create friction during upgrades. Dependency surface is minimal (only BurntSushi/toml and redis/go-redis/v9), reducing supply-chain risk.

Project shows active maintenance with Go 1.25 support in go.mod, GitHub Actions CI/CD workflows configured (ci.yml, ent.yml), and structured release notes (Changes.md, release-notes.md.erb template). Commercial enterprise features are being tracked separately (Ent-Changes.md). Recent work appears to focus on protocol stability and language-client parity.

git clone https://github.com/contribsys/faktory.git
cd faktory
make
# Or with Docker: docker build -t faktory . && docker run -it -p 7419:7419 faktory

Daily commands:

make        # Builds faktory binary from cmd/faktory/
./faktory  # Runs server (default port 7419 for protocol, likely 7420 for Web UI based on wiki refs)
# Or: faktory-cli for CLI operations (cmd/faktory-cli/main.go)

• server/server.go — Entry point for the Faktory server; initializes all subsystems, handles server lifecycle, and coordinates the main request loop.
• server/connection.go — Implements the protocol handler for client connections; parses and executes all Faktory commands (PUSH, FETCH, ACK, FAIL, etc.).
• manager/manager.go — Core job lifecycle management: fetches jobs from queues, applies middleware, executes retry logic, and handles job state transitions.
• storage/queue_redis.go — Redis-backed persistent storage layer; all job queues, retries, and scheduled jobs flow through this abstraction.
• server/config.go — Configuration parsing and validation; defines server behavior (port, workers, persistence, auth) from TOML files.
• client/client.go — Client SDK for job submission; provides the canonical interface for applications to push jobs to Faktory.
• cmd/faktory/daemon.go — Binary entry point; bootstraps the server process, loads configuration, and manages graceful shutdown.

• Connection Handler (connection.go) (Go net.Conn, buffered I/O,) — Parses incoming protocol commands and dispatches to command implementations; maintains per-connection state.

Add a new server command (e.g., CUSTOM)

1. Define the command parsing logic in server/commands.go; add a case branch for your command name (server/commands.go)
2. Implement the command handler in server/connection.go; write the method that processes the command and writes the response (server/connection.go)
3. Add tests for the new command in server/commands_test.go or server/connection_test.go (server/commands_test.go)
4. Document the command in docs/protocol-specification.md with syntax and examples (docs/protocol-specification.md)

Add a new job middleware or hook

1. Create a new middleware function in manager/middleware.go following the Middleware interface signature (manager/middleware.go)
2. Register the middleware in manager/manager.go within the applyMiddleware() method chain (manager/manager.go)
3. Add tests for the middleware in manager/middleware_test.go (manager/middleware_test.go)

Add support for a new job state or workflow transition

1. Update the retry logic in manager/retry.go to handle the new state or condition (manager/retry.go)
2. Modify manager/working.go to coordinate the new state in the job lifecycle (manager/working.go)
3. Add corresponding command handlers in server/commands.go to expose state mutations (server/commands.go)
4. Update storage/queue_redis.go if new Redis operations are needed (storage/queue_redis.go)

Add custom configuration option

1. Add the new field to the ServerConfig struct in server/config.go (server/config.go)
2. Update the TOML parsing logic in server/config.go to unmarshal the new option (server/config.go)
3. Reference the config value in server/server.go or the relevant subsystem during initialization (server/server.go)
4. Update example/config.toml with the new option and a comment explaining its purpose (example/config.toml)

• Go — Provides lightweight concurrency with goroutines, fast startup, and single-binary deployment ideal for a background job server.
• Redis — Offers atomic queue operations, sorted sets for scheduling, and persistence; handles millions of job operations efficiently.
• TOML Configuration — Human-readable config format; cleanly separates deployment concerns (port, workers, auth) from code.

• Persistent-only model via Redis, no in-memory fallback

  • Why: Ensures durability across restarts and enables distributed workers without replication logic.
  • Consequence: Hard dependency on Redis uptime; job loss if Redis fails and no backup is in place.

• Synchronous command processing per connection

  • Why: Simplifies protocol state machine and ensures strict ordering of commands from a single client.
  • Consequence: A slow client blocks its connection but not others; backpressure is per-connection, not global.

• 30-minute default reservation timeout for jobs

  • Why: Balances worker crash recovery with allowing long-running jobs.
  • Consequence: Short-TTL jobs require configuration tuning; very long jobs risk being requeued if timeout is exceeded.

• Middleware-based extensibility (no plugins)

  • Why: Avoids dynamic loading complexity and keeps the binary self-contained.
  • Consequence: Custom logic requires forking or recompiling; no hot-reload of middleware.

• Does not provide authentication or encryption beyond optional TLS termination
• Does not implement a full distributed consensus protocol; relies on Redis as a single source of truth
• Does not handle job workflow dependencies or DAG execution
• Does not provide built-in backup/replication of job data; users must manage Redis persistence
• Does not support cross-language job monitoring without implementing the Faktory protocol

Platform-specific builds required: client_linux.go, client_windows.go, client_bsd.go are conditional compiles, so cross-platform testing is non-trivial. Config discovery: CLI looks for conf.d/ subdirectories and merges TOML files (cli/test-fixtures/ shows the pattern), so configuration order matters. Redis dependency assumed: No embedded Redis fallback visible; requires external Redis instance to be running. Port conventions not in code: Default ports 7419 (protocol) and 7420 (WebUI) are documented in wiki, not file list—infer from examples/config.toml if present.

• Job reservation with timeout — Core to Faktory's fault tolerance—jobs are reserved (not deleted) for a window (default 30 min), then requeued if not ACK'd, preventing loss under worker crashes
• Exponential backoff retry strategy — Failed jobs automatically retry with increasing delays to avoid thundering herd and transient failure cascades; implemented in job lifecycle logic
• Language-agnostic binary protocol — Faktory's killer feature—clients in any language speak the same wire protocol (documented in docs/protocol-specification.md), enabling polyglot job distribution without code sharing
• Redis Lua scripting for atomicity — Job state transitions (ACK, FAIL, requeue) must be atomic to prevent race conditions; implemented via Redis Lua scripts in the daemon
• Connection pooling with reservation semantics — client/pool.go manages worker connections and job reservations, preventing connection exhaustion and coordinating timeouts across the pool
• TOML hierarchical configuration merging — Faktory's CLI (cli/cli.go) merges config from base file + conf.d/ directory fragments using BurntSushi/toml, enabling deployment-friendly config composition
• Redis persistence model — Unlike in-memory job queues, Faktory durably stores jobs in Redis, surviving server restarts and enabling shared state across multiple queue consumers

• sidekiq/sidekiq — Ruby-language job queue that inspired Faktory's design; uses similar retry/backoff semantics but embedded in Rails instead of as a separate server
• resque/resque — Earlier Redis-backed job queue for Ruby; Faktory evolved as a language-agnostic successor with better protocol and timeout guarantees
• go-resque/resque — Go client for Resque/Faktory-compatible work queues; useful reference for Go integration patterns with Faktory
• contribsys/faktory_worker_ruby — Official Ruby worker library for Faktory; essential companion for Ruby developers using this server
• contribsys/faktory_worker_python — Official Python worker library for Faktory; demonstrates how to implement language-specific Faktory clients

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for client/pool.go connection pooling

The pool.go file manages connection pooling for the Faktory client across multiple platforms (BSD, Linux, Windows). While pool_test.go exists, the file structure shows platform-specific implementations (client_bsd.go, client_linux.go, client_windows.go) that likely have distinct behavior. Adding integration tests that verify pool behavior under connection failures, timeouts, and platform-specific edge cases would improve reliability and catch regressions when updating go-redis dependencies.

• [ ] Review existing internal/pool/pool_test.go and client/pool_test.go coverage
• [ ] Add tests for connection exhaustion and queue waiting behavior
• [ ] Add tests for platform-specific teardown (client_bsd.go, client_linux.go, client_windows.go)
• [ ] Add tests for concurrent pool access under high load
• [ ] Verify tests run on CI for all three platforms using .github/workflows/ci.yml

Add middleware execution tests for manager/middleware.go with real job scenarios

The manager/middleware.go file is critical for job processing pipeline but middleware_test.go likely has limited coverage of real-world scenarios. The repo has manager/retry.go and manager/working.go which interact with middleware. Adding tests that verify middleware ordering, error propagation, and interaction with retry/working logic would prevent subtle bugs in job processing.

• [ ] Review manager/middleware_test.go to identify coverage gaps
• [ ] Add tests verifying middleware chain execution order with retry scenarios from manager/retry.go
• [ ] Add tests for middleware error handling and short-circuiting
• [ ] Add tests for middleware interaction with manager/working.go job lifecycle
• [ ] Verify tests cover both success and failure paths in job execution

Add CLI configuration validation tests for cli/test-fixtures directory

The cli/test-fixtures directory contains configuration files (case-one/conf.d/a.toml, b.toml) for testing configuration loading, but cli_test.go likely doesn't comprehensively test edge cases. Adding tests for malformed TOML, missing required fields, conflicting configurations across conf.d files, and precedence rules would catch configuration bugs before they affect users. This directly complements the existing test fixtures.

• [ ] Review cli/cli_test.go and cli/security_test.go for configuration validation coverage
• [ ] Add test-fixtures for invalid TOML syntax and missing required fields
• [ ] Add tests verifying conf.d file loading order and precedence (cli/test-fixtures/case-one/conf.d/)
• [ ] Add tests for conflicting settings across multiple .toml files
• [ ] Add tests for environment variable overrides of config file settings

• Add protocol version negotiation tests: client/client_test.go and cli/cli_test.go exist but coverage for version mismatch handling between server/clients appears minimal—add integration tests in cli/ for protocol compatibility scenarios.
• Document the exact TOML config schema: example/config.toml and cli/test-fixtures/ have examples, but docs/ has no formal config reference. Create docs/configuration.md mapping all TOML keys with types, defaults, and examples from fixture files.
• Add platform-specific CI tests: .github/workflows/ci.yml likely runs only on Linux. Expand to test client_windows.go and client_bsd.go conditionally (or via cross-compilation) to catch OS-specific bugs before release.

Faktory has a reasonable security foundation with clean dependency management (minimal direct dependencies) and use of security-focused base images. Primary concerns are network exposure without authentication enforcement, Redis backend security dependencies, and Docker container hardening. The codebase appears well-structured with security testing (security_test.go files present). Main recommendations focus on deployment security practices, authentication enforcement, and documentation of security requirements rather than code vulnerabilities. No critical code-level vulnerabilities are apparent from the static analysis of the provided files.

• Medium · Exposed Network Ports Without Authentication in Docker — Dockerfile, CMD instruction and port exposure. The Dockerfile exposes ports 7419 and 7420 and binds to 0.0.0.0, making the Faktory server accessible from any network interface. Combined with the nature of a background job server handling potentially sensitive work data, this could allow unauthorized access if network segmentation is not properly implemented. The default configuration binds to all interfaces without explicit authentication enforcement at the network layer. Fix: 1) Bind to specific trusted IPs instead of 0.0.0.0 unless in a properly isolated network environment. 2) Implement network policies and firewalls to restrict access to these ports. 3) Consider running the container in a private network namespace. 4) Document security requirements for deployment. 5) Ensure authentication/authorization is enforced at the application level for all clients.
• Medium · Dependency on Redis Without Verified Security Posture — go.mod (github.com/redis/go-redis/v9), Dockerfile (redis installation). The codebase depends on go-redis/v9 (v9.7.3) and Redis itself is used as the backend (seen in Dockerfile apk installation). Redis by default has no authentication and transmits data in plaintext. While go-redis library is reputable, the security depends on Redis being properly secured in deployment (password protection, TLS, etc.). No configuration enforcement visible in the codebase. Fix: 1) Document Redis security requirements (require AUTH, enable TLS). 2) Add validation in configuration to enforce secure Redis connections. 3) Consider encrypting sensitive job data at rest and in transit. 4) Implement Redis password/ACL requirements in the default configuration template. 5) Use TLS for Redis connections in production environments.
• Low · Incomplete Docker Security Hardening — Dockerfile. The Dockerfile uses Alpine 3.21 (good choice for minimal attack surface) but does not implement additional security best practices: no USER directive to run as non-root, no HEALTHCHECK, and security context is managed through group permissions but process still runs as root by default. Fix: 1) Add a USER directive to run as a non-root user (e.g., 'faktory' user). 2) Implement proper file ownership changes (RUN useradd -m faktory && chown -R faktory:faktory ...). 3) Add HEALTHCHECK instruction. 4) Consider adding LABEL directives for image metadata. 5) Ensure the binary is executable by the non-root user.
• Low · Minimal SECURITY.md Policy — SECURITY.md. The SECURITY.md file exists but provides only basic vulnerability reporting guidance (email contact). It lacks information about security features, deployment security considerations, supported versions, or security update policies. Fix: 1) Expand SECURITY.md to document security features (authentication mechanisms, TLS support). 2) Define security update and patch policy. 3) Document recommended deployment security practices (network isolation, Redis security, credential management). 4) Specify which versions receive security updates. 5) Define security scanning and testing procedures.
• Low · No Visible Input Validation Documentation — client/job.go, client/faktory.go (file content not provided but structure suggests job handling). While the codebase structure suggests protocol-based communication (docs/protocol-specification.md exists), there is no explicit documentation about input validation, sanitization, or protection against job payload injection in the visible files. Jobs are described as 'JSON hashes' but validation strategy is not evident. Fix: 1) Implement strict input validation for all job payloads. 2) Document validation rules and constraints. 3) Add tests for malformed input handling. 4) Consider implementing schema validation for job structure. 5) Document safe practices for client libraries.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.