feat(skills): add gateway-debug and gateway-it-tests agent skills#2014
Conversation
renuka-fernando
requested review from
AnuGayan,
Arshardh,
CrowleyRajapakse,
HeshanSudarshana,
HiranyaKavishani,
Krishanx92,
PasanT9,
RakhithaRR,
Tharsanan1,
VirajSalaka,
ashera96,
chamilaadhi,
dushaniw,
hisanhunais,
malinthaprasan,
pubudu538,
senthuran16,
tgtshanika,
tharikaGitHub and
tharindu1st
as code owners
📝 WalkthroughSummaryThis PR introduces two new developer workflow documentation skills and supporting example files to the WSO2 API Platform gateway codebase. New Skills Documentationgateway-it-tests skill (293 lines) — Documents the end-to-end workflow for running BDD integration tests using Godog and Docker Compose. Covers building coverage images, running tests with selected feature files via gateway-debug skill (694 lines) — Documents local debugging of gateway controller and policy-engine components under Delve while Envoy runs in Docker. Specifies component selection, two debugging paths (deployment-only via REST API and request-runtime through Envoy), setup instructions for configuring compose files and generating policy artifacts, step-by-step launch procedures with healthcheck verification, reproduction workflows using the example API, triage approaches via logs and config dumps, debugger attachment techniques with breakpoint discovery, optional non-interactive scripted debugging, and structured cleanup procedures. Includes a failure signatures reference table mapping symptoms to troubleshooting steps. Supporting ChangesExample API configuration — Adds Claude Code integration — Adds a symlink at ValidationDogfooding validation performed on macOS with existing coverage images confirmed both integration test and debug workflows function correctly across multiple feature suites. WalkthroughThis pull request introduces two comprehensive developer skills for the WSO2 API Platform: a source-level gateway debugging workflow and an integration test execution guide. The gateway-debug skill provides an 8-step procedure to identify faulty components, prepare the local environment with Docker and builder artifacts, launch debugger sessions, reproduce issues via REST APIs, and systematically triage and fix problems. The gateway-it-tests skill documents how to build coverage images, select and run Godog feature files, troubleshoot failures with container inspection and log analysis, and optionally escalate to source-level debugging. The changes also configure Claude Code agent skills integration via a .claude/skills pointer, update .gitignore to selectively commit skills references while keeping other agent artifacts local, and add a sample-echo-api.yaml example configuration with API key authentication and header injection for use as a reproducer in debugging workflows. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
.agents/skills/gateway-it-tests/SKILL.md (1)
243-248: ⚡ Quick winSpecify a language for this fenced block.
Add a language tag (for example
textordlv) to keep markdown lint clean and improve rendering consistency.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.agents/skills/gateway-it-tests/SKILL.md around lines 243 - 248, The fenced code block containing dlv debugger commands (lines showing "funcs steps.*AssertSteps", "break steps.(*AssertSteps).<method>", "break steps.(*HTTPSteps).<method>", "continue") needs a language tag to satisfy markdown linting; add an appropriate tag such as ```dlv or ```text to the opening fence so the block becomes e.g. ```dlv and closes with ```, preserving the exact commands and spacing..agents/skills/gateway-debug/SKILL.md (1)
436-458: ⚡ Quick winAdd language identifiers to unlabeled fenced code blocks.
Several fenced blocks are missing a language tag, which can fail markdown linting and reduce readability. Add tags like
text,bash, ordlvconsistently.Also applies to: 496-556
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.agents/skills/gateway-debug/SKILL.md around lines 436 - 458, The markdown contains multiple unlabeled fenced code blocks (log and access-log examples) which fail linting; edit SKILL.md and add appropriate language identifiers to each fenced block shown (for the HTTP request / policy-engine log blocks and the Envoy [rtr] access log block) — e.g. use `text` for plain logs, `bash` for shell snippets, or `dlv` where relevant — and apply the same fixes to the other unlabeled blocks noted at lines 496-556 so all fenced code blocks include a language tag.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.agents/skills/gateway-debug/SKILL.md:
- Around line 283-303: The readiness block that waits for dlv listeners and then
curls controller, policy-engine and Envoy should be made path-aware: detect the
selected path (Path A vs Path B) and only perform the checks relevant to that
path—if Path A (controller-only) only wait for the controller listener/port (the
lsof check for ports 2345/2346 should be narrowed to the controller port) and
only curl the controller REST endpoint
(http://localhost:9090/api/management/v0.9/rest-apis); if Path B, keep the
existing checks for both dlv listeners (ports 2345 and 2346), the policy-engine
config_dump (http://localhost:9002/config_dump) and Envoy readiness
(http://localhost:9901/ready); add a simple conditional (based on the path
selection variable used by the script) around the waiting loop and the three
curl calls so the block does not fail for Path A.
In `@gateway/examples/httpbin-api.yaml`:
- Around line 38-39: Update the X-Gateway-Marker header value to match the
documented reproducer output: change the YAML entry for the header named
X-Gateway-Marker (the value currently set to "ap-gateway") to
"from-gateway-debug" so the sample verification in Step 4 will match the
expected output.
---
Nitpick comments:
In @.agents/skills/gateway-debug/SKILL.md:
- Around line 436-458: The markdown contains multiple unlabeled fenced code
blocks (log and access-log examples) which fail linting; edit SKILL.md and add
appropriate language identifiers to each fenced block shown (for the HTTP
request / policy-engine log blocks and the Envoy [rtr] access log block) — e.g.
use `text` for plain logs, `bash` for shell snippets, or `dlv` where relevant —
and apply the same fixes to the other unlabeled blocks noted at lines 496-556 so
all fenced code blocks include a language tag.
In @.agents/skills/gateway-it-tests/SKILL.md:
- Around line 243-248: The fenced code block containing dlv debugger commands
(lines showing "funcs steps.*AssertSteps", "break
steps.(*AssertSteps).<method>", "break steps.(*HTTPSteps).<method>", "continue")
needs a language tag to satisfy markdown linting; add an appropriate tag such as
```dlv or ```text to the opening fence so the block becomes e.g. ```dlv and
closes with ```, preserving the exact commands and spacing.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 8ce2c2ee-72c4-4ba0-8c1c-8608928f878d
📒 Files selected for processing (5)
.agents/skills/gateway-debug/SKILL.md.agents/skills/gateway-it-tests/SKILL.md.claude/skills.gitignoregateway/examples/httpbin-api.yaml
Two project-local agent skills covering the BDD integration suite and source-level gateway debugging. - gateway-it-tests: run/triage Godog .feature files via IT_FEATURE_PATHS with container-log + config-dump triage; hands off to gateway-debug when source-level inspection is needed. - gateway-debug: run gateway-controller and/or policy-engine locally under Delve while Envoy stays in Docker. Two paths — deployment-only (controller REST) and request-runtime (through Envoy + policy-engine). Supports both dev (docker-compose.yaml) and IT-handoff (docker-compose.test.yaml) compose targets. - gateway/examples/httpbin-api.yaml: debug-friendly echo upstream (httpbin.org/anything) wired with api-key-auth + set-headers — the default reproducer in gateway-debug Step 4. - .claude/skills → ../.agents/skills symlink wires the skills into the harness's expected location; cross-vendor convention is to keep skills under .agents/ (Codex, Gemini CLI, Cursor, OpenCode, GitHub Copilot all read from there). .gitignore tweak keeps the symlink tracked while ignoring the rest of .claude/. Signed-off-by: Renuka Fernando <renukapiyumal@gmail.com>
renuka-fernando
force-pushed
the
agent-skills
branch
from
4c88d54 to
0c12915
Compare
|
@coderabbitai full review |
✅ Actions performedFull review triggered. |
Replace gateway/examples/httpbin-api.yaml (https://httpbin.org/anything) with sample-echo-api.yaml that targets the in-compose sample-backend service. Avoids the external dependency, keeps the reproducer entirely inside the local docker network, and gains a deterministic upstream status via sample-service's ?statusCode=<n> query param. - Add gateway/examples/sample-echo-api.yaml — api-key-auth + set-headers over http://sample-backend:5000 with /anything operations. - Remove gateway/examples/httpbin-api.yaml. - Update gateway-debug SKILL.md: layout entry, deploy table, recommended reproducer section (jq output now matches sample-service's response shape: method/path/headers map[string][]string), scripted-repro and fix-verification snippets, controller/PE log examples, and the [rtr] access-log examples (replaced httpbin.org with sample-backend:5000; 503 example now driven by ?statusCode=503 rather than cold-start). - Note that the IT-handoff compose target uses sample-backend:9080, so the YAML's upstream port needs editing in that mode. Signed-off-by: Renuka Fernando <renukapiyumal@gmail.com>
There was a problem hiding this comment.
🧹 Nitpick comments (1)
.agents/skills/gateway-debug/SKILL.md (1)
463-467: ⚡ Quick winAdd language identifier to code block.
The fenced code block showing log examples should specify a language for proper rendering and tooling support.
📝 Suggested fix
-``` +```text msg="Parsed StoredPolicyConfig" api_name="Sample Echo" routes=1 msg="Policy chain update completed successfully" version=2 total_routes=4 msg="Successfully processed and ACKed discovery response" type_url=...PolicyChainConfig version=2 num_resources=4🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.agents/skills/gateway-debug/SKILL.md around lines 463 - 467, Update the fenced code block containing the log examples so it includes a language identifier (e.g., change the opening ``` to ```text) to ensure proper rendering and tooling support; locate the block that starts with the log lines like "msg=\"Parsed StoredPolicyConfig\" api_name=\"Sample Echo\" routes=1" and modify its opening fence to include the language token.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In @.agents/skills/gateway-debug/SKILL.md:
- Around line 463-467: Update the fenced code block containing the log examples
so it includes a language identifier (e.g., change the opening ``` to ```text)
to ensure proper rendering and tooling support; locate the block that starts
with the log lines like "msg=\"Parsed StoredPolicyConfig\" api_name=\"Sample
Echo\" routes=1" and modify its opening fence to include the language token.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 6392d0b2-7ff6-4bb0-b237-2fa98dc1fcae
📒 Files selected for processing (3)
.agents/skills/gateway-debug/SKILL.md.agents/skills/gateway-it-tests/SKILL.mdgateway/examples/sample-echo-api.yaml
💤 Files with no reviewable changes (1)
- .agents/skills/gateway-it-tests/SKILL.md
2 participants
Purpose
The gateway has two recurring developer workflows that are easy to get wrong without a guide: running a chosen subset of the Godog integration suite and debugging a specific component (controller or policy-engine) under Delve while the rest of the stack runs in Docker. This PR adds two project-local agent skills that capture those workflows end-to-end so any contributor (or an LLM-driven helper) can drive them reliably and clean up afterwards.
Goals
.featurefile and triage failures from container logs / config dumps.Approach
gateway-it-testsskill (.agents/skills/gateway-it-tests/SKILL.md): wraps the existingmake test IT_FEATURE_PATHS=...flow, documents the cold-start caveat, container-log + config-dump triage steps, and the optionaldlv testlast-resort path. New Step 7 cross-referencesgateway-debugfor source-level inspection.gateway-debugskill (.agents/skills/gateway-debug/SKILL.md): runs gateway-controller and/or policy-engine locally under headless Delve while Envoy stays in Docker. Step 2 presents two equal paths — deployment-only (controller REST API, dockerless) and request-runtime (through Envoy + policy-engine) — and supports both compose targets: dev (gateway/docker-compose.yaml) and IT-handoff (gateway/it/docker-compose.test.yaml). Includes function-name breakpoint discovery, a non-interactive scripted-repro pattern, and analways continue before exitwarning for state-inspection commands.gateway/examples/httpbin-api.yaml: small reference API wired withapi-key-auth+set-headersthat targetshttpbin.org/anythingso every request is echoed back as JSON. Default reproducer for gateway-debug Step 4 — lets a contributor verify header injection, host rewrite, and policy execution without running a local backend..claude/skills→../.agents/skillssymlink. The cross-vendor convention is to keep agent skills under.agents/(Codex, Gemini CLI, Cursor, OpenCode, GitHub Copilot read from there); the symlink exposes the same skills under the location Claude Code expects..gitignorekeeps.claude/ignored generally but un-ignores the symlink so it's tracked.Both skills were dogfooded end-to-end before this PR:
api-keys.feature(15/15 PASS) was followed by a controller deployment-path debug session, andcel-conditions.feature(6/6 PASS) was followed by a request-runtime debug session that broke inside CELexecutionConditionevaluation in the policy engine.User stories
N/A — dev-tooling change. No end-user impact.
Documentation
N/A — each skill's
SKILL.mdis its own documentation, structured for both human and LLM consumption.Automation tests
Security checks
Samples
gateway/examples/httpbin-api.yamlis the new sample — a REST API withapi-key-auth+set-headerspolicies targetinghttps://httpbin.org/anything. Doubles as a debug reproducer (gateway-debug Step 4) and a minimal demo of policy chaining without needing a local backend.Related PRs
N/A
Test environment
ghcr.io/wso2/api-platform/gateway-{controller,runtime}-coverage:testimages (frommake build-coverage)