Skip to content

Latest commit

 

History

History
88 lines (64 loc) · 2.5 KB

AGENTS.md

File metadata and controls

88 lines (64 loc) · 2.5 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

OpenQueue is a simple HTTP message queue written in Go. It accepts tasks via a Connect RPC API and executes HTTP requests with configurable retry logic.

Build & Development Commands

# Development with hot reload
just dev       # or: air

# Build
just build     # or: go build -o ./tmp/main ./cmd/root.go

# Run server
./tmp/main server --port 8080 --config openqueue.yaml

# Run tests
go test ./...

# Run a single test
go test -run TestName ./pkg/path/...

# Update dependencies
just update

# Generate protobuf code (requires buf, protoc-gen-go, protoc-gen-connect-go)
buf generate

# Install tooling dependencies
just init

Architecture

Entry Points

  • cmd/root.go - Main CLI entry point using urfave/cli
  • cmd/server/ - Server subcommand that loads config and starts HTTP server

Core Packages

pkg/server/ - HTTP server setup with chi router

  • server.go - Server lifecycle, graceful shutdown handling
  • routes.go - Route registration, health endpoint, logging middleware

pkg/api/apiv1/ - Connect RPC API handlers implementing QueueService

  • create_task.go - Creates task in database and triggers async execution
  • get_task.go - Retrieves task and its latest execution status

pkg/database/ - SQLite database layer using sqlx

  • Stores tasks and task_execution records
  • Uses modernc.org/sqlite (pure Go, no CGO)
  • Database files stored in ./data/

pkg/task_runner/ - Task execution engine

  • Executes HTTP requests with exponential backoff retry (cenkalti/backoff)
  • Tracks execution status (pending/completed/failed)

pkg/config/ - YAML configuration loading using koanf

Protocol Buffers

  • proto/api/v1/api.proto - Service definition for CreateTask and GetTask RPCs
  • proto/gen/ - Generated Go code from buf

Configuration

Queue configuration via YAML file (default: openqueue.yaml):

queues:
  - name: my_queue
    db: my_queue   # SQLite database name in ./data/
    retry: 3       # Max retry attempts

API Usage

# Create a task
curl --header 'Content-Type: application/json' \
  --data '{"queue_name": "my_queue", "task":{"url":"http://example.com", "method":"GET"}}' \
  http://localhost:8080/api.v1.QueueService/CreateTask

# Get task status
curl --header 'Content-Type: application/json' \
  --data '{"queue_name": "my_queue", "taskId":"<task-id>"}' \
  http://localhost:8080/api.v1.QueueService/GetTask