By name: qstash-analyze description: | Analyze and understand qstash-stress codebase behavior, trace data flow, and explain design decisions. Use when user asks to: (1) trace how messages flow through the system, (2) understand why code is structured a certain way, (3) find where a QStash feature is implemented, (4) explain a design decision, (5) map QStash headers to code, (6) understand the architecture, or (7) debug why something isn't working as expected. Triggers: "how does X work", "where is X implemented", "trace the flow", "explain the design", "why does it do X".
qstash-analyze
Analyze qstash-stress codebase structure, trace execution flow, and explain design decisions.
Quick Reference
Read CLAUDE.md in the project root for comprehensive architecture documentation.
Analysis Workflows
Trace Message Flow
- Publish path:
cmd/publish.go→publisher/client.go:Publish()→ QStash API - Receive path: QStash →
receiver/handlers.go:handleMessage()→verify/signature.go→tracker/tracker.go:RecordDelivery() - Test path:
runner/runner.go:RunTest()→ publish →tracker.WaitForDelivery()→ validate expectations
Find Feature Implementation
| QStash Feature | Primary Location |
|---|---|
| Publish | internal/publisher/client.go:112-272 |
| Batch | internal/publisher/client.go:289-329 |
| Queues | internal/publisher/queue.go |
| Schedules | internal/publisher/schedule.go |
| URL Groups | internal/publisher/urlgroup.go |
| DLQ | internal/publisher/dlq.go |
| Callbacks | publisher/client.go:180-210 (headers), receiver/handlers.go (receive) |
| Retries | publisher/client.go:165-170 (Upstash-Retries, Upstash-Retry-Delay) |
| Delays | publisher/client.go:155-160 (Upstash-Delay, Upstash-Not-Before) |
| Deduplication | publisher/client.go:220-225 |
| Flow Control | publisher/client.go:230-235 |
| Signature Verify | internal/verify/signature.go:14-64 |
Explain Design Decisions
| Decision | Rationale | Location |
|---|---|---|
--serve mode |
Share tracker between runner and receiver in same process | cmd/run.go:82-105 |
sync.Map |
Lock-free reads for high-concurrency tracking | tracker/tracker.go:40-52 |
Per-message RWMutex |
Fine-grained locking without global contention | tracker/tracker.go:23-37 |
| Reservoir sampling | Memory-bounded metrics (10K samples max) | tracker/metrics.go:65-107 |
| Dual signing keys | Support QStash key rotation | verify/signature.go:14-19 |
| YAML test suites | Declarative, version-controlled test definitions | runner/config.go |
Debug Common Issues
Message not delivered:
- Check
RECEIVER_BASE_URLmatches ngrok URL - Verify signing keys match QStash console
- Check
/metricsendpoint for tracker state - Run with
-vfor debug logs
Test timeout:
- Confirm
--serveflag is used (shared tracker) - Check QStash console for message status
- Verify receiver is accessible from internet
Signature verification failed:
- Check
QSTASH_CURRENT_SIGNING_KEYandQSTASH_NEXT_SIGNING_KEY - Keys are in QStash console under "Signing Keys"
- Both current and next are required
Code Navigation Patterns
To find implementation of a specific header:
grep -r "Upstash-HeaderName" internal/publisher/
To find where a type is used:
grep -r "TypeName" --include="*.go"
To trace a function call chain:
- Start at entry point (cmd/*.go)
- Follow function calls to internal packages
- Note the tracker/metrics recording points
QStash Documentation Reference
Official docs at ../qstash/ for:
features/*.mdx- Feature detailsapi/- API referencesdks/- SDK patterns