chore: add Claude Code smoke-test skill#857
Open
a10zn8 wants to merge 3 commits into
Open
Conversation
Adds a project-scoped Claude Code skill at .claude/skills/smoke-test/SKILL.md that captures the workflow for bringing dshackle (or any local service) up with a minimal config and verifying it serves real requests end-to-end: build → minimal config → background start → condition-based readiness wait → route discovery → happy + edge probes → log scan for soft failures → cleanup. The skill is generic but distilled from running dshackle locally with the demo Ethereum config: hitting / returns 404 because the proxy uses routed paths, "Started" appears before async upstream init finishes, etc. Loosens .gitignore so .claude/ stays local except for .claude/skills/, which is the intended place to share project skills with the team. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The skill previously only documented the HTTP JSON-RPC proxy. dshackle's gRPC port (:2449) is a separate code path — a regression can land in one without the other — so HTTP-only smoke testing is incomplete. Adds, validated against demo Ethereum upstream (https://eth.drpc.org): - grpcurl discovery via server reflection (on by default) - emerald.Blockchain/Describe as a health-check (chains, status, labels, supportedMethods) - emerald.Blockchain/NativeCall with eth_blockNumber and eth_getBlockByNumber, decoded round-trip (params and result are base64(JSON), payload is bytes) - "What to check" guidance: succeed=true, upstream_id populated, and the distinction between cache/aggregator id ("!all:ETH") vs real upstream id - gRPC gotchas: bytes-not-string payload, enum chain names, server-stream response, TLS adjustments - 3 new rows in Common Mistakes covering the same pitfalls - Workflow step 6 amended to call out probing both HTTP and gRPC when both ports listen Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per request: make gRPC the primary smoke-test surface (it's dshackle's primary API), and add coverage for the streaming RPCs. Changes: - Drop the HTTP JSON-RPC probe section entirely. HTTP proxy is a thin wrapper on top of gRPC; verifying gRPC implies the HTTP path. - Add an explicit copy-paste config block at /tmp/dshackle-test/dshackle.yaml with line-by-line rationale for each piece (why both rpc+ws, why no proxy block, why eth.drpc.org, why no auth). - Restructure probes as 5 numbered sections, each with explicit pass criteria: 1. reflection (sanity) 2. Describe (config + label-detector + supportedMethods) 3. NativeCall (real upstream hop, not cache aggregator) 4. SubscribeNodeStatus (server stream without upstream traffic) 5. NativeSubscribe newHeads (real WS-backed subscription) - Validated end-to-end against eth.drpc.org: NativeSubscribe newHeads delivered 3 sequential block headers in 15s (heights 25128418-20). - Document the supportedSubscriptions detector caveat: it underreports newHeads even though NativeSubscribe newHeads works fine. - Document streaming idioms: -max-time is required, DeadlineExceeded is the success terminator (not a failure). - Common Mistakes table reworked for gRPC-only surface; HTTP rows removed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
.claude/skills/smoke-test/SKILL.mddocumenting the workflow for running dshackle (or any local service) end-to-end with a minimal config and verifying real requests work..gitignore:.claude/stays local (settings, transcripts) except for.claude/skills/, which is the team-shared slot for project skills.Why
When you ask Claude Code to "run it locally and check it works", the non-obvious parts bite: hitting
/returns 404 because the proxy uses routed paths (/eth), the "Started" log line shows up before async upstream init finishes, and blindsleepis flaky. This skill captures the right pattern — condition-based readiness wait on the LISTEN port, route discovery from the config, happy + edge probes, log scan for soft failures, cleanup — so future runs are consistent.The content is generic to local-service smoke testing; the JSON-RPC probe template happens to match Ethereum endpoints because that's the most common dshackle use case.
Test plan
demo/quick-start-style flow: built withmake build-foundation+./gradlew installDist, ran withhttps://eth.drpc.orgupstream, probed/ethwitheth_chainId,eth_blockNumber, batch, and an invalid method (-32601).git check-ignore .claude/settings.jsonstill ignores it (only.claude/skills/is allowed through).🤖 Generated with Claude Code