Home

codeQ

codeQ is a task queue server written in Go. It accepts tasks over an HTTP API or a pair of bidirectional gRPC streams, persists them on an embedded LSM tree, and hands them out to workers under a lease-based at-least-once delivery contract. A single binary serves producers, workers, and operators; the same binary forms a three-node raft cluster when high availability matters.

Read by section

The wiki is organized into six sections. Each section has an overview page that explains what the section covers and who it is for, followed by topical pages that go deep on one idea at a time. Start at the overview if you are new to codeQ; jump to a topical page if you already know what you want.

The Get Started section walks through installing codeQ, running it on a laptop, running it in Docker, standing up a three-node raft cluster, and deploying to Kubernetes. Start here if you have never seen codeQ before.

The Concepts and Architecture section explains tasks, queues, sharding, leases, multi-tenancy, authentication, the persistence engine, consensus, cluster failover, and deployment modes. Start here if you want to understand how codeQ works before deciding whether to use it.

The Sous Functions section documents the worker framework that turns a Go function into a codeQ consumer. Read this if you want to ship business logic rather than wire up gRPC stubs by hand.

The CodeQ IO section is the wire-protocol reference: the producer stream, the worker stream, the REST API, the persistence engine, the group-commit coalescer, raft replication, and the mux transport. Read this when you need to know exactly what bytes move where.

The Observability section covers tracing, metrics, profiling, and logging. This is the chapter you want open in another tab when you are debugging a production incident.

The Performance section reports measured throughput, the cost of high availability, multi-shard scaling, tuning knobs, and the bench harness itself. Every number is traced back to the source file that produced it.

Quick paths

If you came here with a specific intent, the table below points to a single page that gets you moving.

Intent	Start here
I want to install codeQ on my laptop	Run Locally
I want to run it in one Docker container	Run In Docker
I want a three-node HA cluster	Run With Docker Compose
I want to deploy on Kubernetes	Run In Kubernetes
I want to understand the architecture	Architecture Overview
I want to wire a Go producer or worker	Sous Functions Get Started
I want to read the HTTP API	REST API
I want to see throughput numbers	Single-Node Throughput
I want to tune for my workload	Tuning Knobs
Production broke and I need help	Observability Overview

Source code and issues

The codeQ source lives at github.com/osvaldoandrade/codeq. Issues, discussions, and pull requests are accepted on GitHub. The wiki is generated from wiki-staging/ in the main repository — edits go via PR there.