AgentSkillsCN

qstash-analyze

分析并理解Qstash-Stress代码库的行为，追踪数据流，解释设计决策。 当用户提出以下需求时使用此功能：(1) 追踪消息在系统中的流动路径；(2) 理解代码为何采用特定的结构；(3) 查找QStash某项功能的实现位置；(4) 解释某项设计决策；(5) 将QStash的头部信息映射到代码中；(6) 了解系统架构；(7) 调试某项功能为何未能按预期运行。 可通过“X是如何工作的？”“X在哪里被实现？”“追踪数据流”“解释设计”“为什么它要执行X？”等指令触发。

SKILL.md
--- frontmatter
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

  1. •Publish path: cmd/publish.go → publisher/client.go:Publish() → QStash API
  2. •Receive path: QStash → receiver/handlers.go:handleMessage() → verify/signature.go → tracker/tracker.go:RecordDelivery()
  3. •Test path: runner/runner.go:RunTest() → publish → tracker.WaitForDelivery() → validate expectations

Find Feature Implementation

QStash FeaturePrimary Location
Publishinternal/publisher/client.go:112-272
Batchinternal/publisher/client.go:289-329
Queuesinternal/publisher/queue.go
Schedulesinternal/publisher/schedule.go
URL Groupsinternal/publisher/urlgroup.go
DLQinternal/publisher/dlq.go
Callbackspublisher/client.go:180-210 (headers), receiver/handlers.go (receive)
Retriespublisher/client.go:165-170 (Upstash-Retries, Upstash-Retry-Delay)
Delayspublisher/client.go:155-160 (Upstash-Delay, Upstash-Not-Before)
Deduplicationpublisher/client.go:220-225
Flow Controlpublisher/client.go:230-235
Signature Verifyinternal/verify/signature.go:14-64

Explain Design Decisions

DecisionRationaleLocation
--serve modeShare tracker between runner and receiver in same processcmd/run.go:82-105
sync.MapLock-free reads for high-concurrency trackingtracker/tracker.go:40-52
Per-message RWMutexFine-grained locking without global contentiontracker/tracker.go:23-37
Reservoir samplingMemory-bounded metrics (10K samples max)tracker/metrics.go:65-107
Dual signing keysSupport QStash key rotationverify/signature.go:14-19
YAML test suitesDeclarative, version-controlled test definitionsrunner/config.go

Debug Common Issues

Message not delivered:

  1. •Check RECEIVER_BASE_URL matches ngrok URL
  2. •Verify signing keys match QStash console
  3. •Check /metrics endpoint for tracker state
  4. •Run with -v for debug logs

Test timeout:

  1. •Confirm --serve flag is used (shared tracker)
  2. •Check QStash console for message status
  3. •Verify receiver is accessible from internet

Signature verification failed:

  1. •Check QSTASH_CURRENT_SIGNING_KEY and QSTASH_NEXT_SIGNING_KEY
  2. •Keys are in QStash console under "Signing Keys"
  3. •Both current and next are required

Code Navigation Patterns

To find implementation of a specific header:

bash
grep -r "Upstash-HeaderName" internal/publisher/

To find where a type is used:

bash
grep -r "TypeName" --include="*.go"

To trace a function call chain:

  1. •Start at entry point (cmd/*.go)
  2. •Follow function calls to internal packages
  3. •Note the tracker/metrics recording points

QStash Documentation Reference

Official docs at ../qstash/ for:

  • •features/*.mdx - Feature details
  • •api/ - API reference
  • •sdks/ - SDK patterns