network-protocol-gateway-usage
Registry Trigger
Use when
- Nginx Envoy HAProxy Cloudflare Fastly CloudFront ALB NLB
- ingress API gateway service mesh WAF CDN reverse proxy load balancer
- TLS DNS SNI ALPN
- HTTP proxy header X-Forwarded-For Forwarded Host CORS
- WebSocket SSE gRPC timeout-chain
- 502 503 504 retry-amplification upstream-status edge origin trace context
- path-rewrite cache-key TTL invalidation purge stale-behavior per-user data health check origin shielding
Do not use when
- no task-local network protocol gateway usage decision is required
Skill Role
Trace client-to-origin behavior across name resolution, transport, proxies, retries, headers, protocol upgrades, caching, and telemetry. Own hop-chain deadline and retry ceilings; degradation-circuit-breaking owns application/dependency resilience and out-of-chain local deadlines, leaving no shared or unowned boundary.
High-Value Rules
- Map only affected client-to-origin hops, excluding those proven irrelevant to the symptom or change.
- Derive the gateway-owned caller, gateway, and upstream deadline and retry ceilings from the end-to-end budget, cancellation behavior, and amplification risk. Degradation consumes those ceilings without redefining them.
- Preserve host, scheme, client identity, request context, trace context, and authorization only across trusted proxies.
- Validate forwarded values before using them as authority.
- When transport security changes, verify certificate chain, endpoint identity, negotiation policy, renewal, and affected client compatibility.
- Select upgrade, idle, buffering, framing, and connection controls from the actual streaming, WebSocket, event-stream, RPC, or protocol behavior.
- Define body, header, compression, buffering, and chunking bounds from accepted payloads, resource limits, and abuse risk.
- Require telemetry that identifies the failing hop and relevant upstream result, duration, retry, and correlation context when diagnosis or operation depends on it.
Anti-Patterns
- A gateway error identifies the reporting hop, not necessarily the slow or failed component.
- Raising a timeout without capacity, cancellation, and backpressure evidence can preserve work after callers have left.
- Accepting forwarded identity from an untrusted peer lets a client spoof origin, scheme, host, or authority.
- Shared caching of authorization-dependent responses can cross user or tenant boundaries.
Stop Conditions
Escalate forwarded identity, authorization, cookies, transport downgrade, edge bypass, or public exposure to security-privacy-gate.
Escalate saturation or failover to reliability-observability-gate.
Route application/dependency fallback, bulkhead, circuit, recovery, and local deadlines outside a gateway chain to degradation-circuit-breaking.
Escalate DNS, certificate, ingress, or load-balancer rollout to delivery-release-gate.
Escalate protocol behavior that changes the client contract to api-contract-design.
Output Contract
- Network Gateway Record: map surfaces, hops, protocol, timeouts, retries, trusted headers, security, and observability; include decisions, validation commands, and residual risk
Targeted References
| Path |
Type |
Load when |
Do not load when |
Required by |
Required output |
| benchmarks and patterns |
benchmark-pattern |
timeout retry header TLS cache or streaming mechanisms remain undecided |
current hop contracts and provider policy select one mechanism |
task-agent, review-agent, analysis-agent |
option-comparison, selected-approach |
| checklist |
decision-checklist |
gateway changes affect hop trust deadlines retries TLS or protocol limits |
no network hop or gateway behavior changes |
task-agent, review-agent, analysis-agent |
checklist-result, residual-risk |
| evidence patterns |
evidence-pattern |
routing timeout TLS or failing-hop claims need representative proof |
fresh config probes and correlated telemetry prove each claim |
task-agent, review-agent, analysis-agent |
evidence-record, proof-limit, residual-risk |
1---2name: network-protocol-gateway-usage3description: `analysis-agent`/`task-agent`/`review-agent`: use when HTTP/TLS/DNS, proxies, ingress, headers, timeout chains, WebSocket, or gateways change; skip without network-edge impact.4---5
6# network-protocol-gateway-usage
7
8## Registry Trigger
9
10**Use when**
11
12- Nginx Envoy HAProxy Cloudflare Fastly CloudFront ALB NLB
13- ingress API gateway service mesh WAF CDN reverse proxy load balancer
14- TLS DNS SNI ALPN
15- HTTP proxy header X-Forwarded-For Forwarded Host CORS
16- WebSocket SSE gRPC timeout-chain
17- 502 503 504 retry-amplification upstream-status edge origin trace context
18- path-rewrite cache-key TTL invalidation purge stale-behavior per-user data health check origin shielding
19
20**Do not use when**
21
22- no task-local network protocol gateway usage decision is required
23
24## Skill Role
25
26Trace client-to-origin behavior across name resolution, transport, proxies, retries, headers, protocol upgrades, caching, and telemetry. Own hop-chain deadline and retry ceilings; `degradation-circuit-breaking` owns application/dependency resilience and out-of-chain local deadlines, leaving no shared or unowned boundary.
27
28## High-Value Rules
29
30- Map only affected client-to-origin hops, excluding those proven irrelevant to the symptom or change.
31- Derive the gateway-owned caller, gateway, and upstream deadline and retry ceilings from the end-to-end budget, cancellation behavior, and amplification risk. Degradation consumes those ceilings without redefining them.
32- Preserve host, scheme, client identity, request context, trace context, and authorization only across trusted proxies.
33- Validate forwarded values before using them as authority.
34- When transport security changes, verify certificate chain, endpoint identity, negotiation policy, renewal, and affected client compatibility.
35- Select upgrade, idle, buffering, framing, and connection controls from the actual streaming, WebSocket, event-stream, RPC, or protocol behavior.
36- Define body, header, compression, buffering, and chunking bounds from accepted payloads, resource limits, and abuse risk.
37- Require telemetry that identifies the failing hop and relevant upstream result, duration, retry, and correlation context when diagnosis or operation depends on it.
38
39## Anti-Patterns
40
41- A gateway error identifies the reporting hop, not necessarily the slow or failed component.
42- Raising a timeout without capacity, cancellation, and backpressure evidence can preserve work after callers have left.
43- Accepting forwarded identity from an untrusted peer lets a client spoof origin, scheme, host, or authority.
44- Shared caching of authorization-dependent responses can cross user or tenant boundaries.
45
46## Stop Conditions
47
48Escalate forwarded identity, authorization, cookies, transport downgrade, edge bypass, or public exposure to `security-privacy-gate`.
49Escalate saturation or failover to `reliability-observability-gate`.
50Route application/dependency fallback, bulkhead, circuit, recovery, and local deadlines outside a gateway chain to `degradation-circuit-breaking`.
51Escalate DNS, certificate, ingress, or load-balancer rollout to `delivery-release-gate`.
52Escalate protocol behavior that changes the client contract to `api-contract-design`.
53
54## Output Contract
55
56- Network Gateway Record: map surfaces, hops, protocol, timeouts, retries, trusted headers, security, and observability; include decisions, validation commands, and residual risk
57
58## Targeted References
59
60| Path | Type | Load when | Do not load when | Required by | Required output |
61|---|---|---|---|---|---|
62| [benchmarks and patterns](references/benchmarks-and-patterns.md) | benchmark-pattern | timeout retry header TLS cache or streaming mechanisms remain undecided | current hop contracts and provider policy select one mechanism | task-agent, review-agent, analysis-agent | option-comparison, selected-approach |
63| [checklist](references/checklist.md) | decision-checklist | gateway changes affect hop trust deadlines retries TLS or protocol limits | no network hop or gateway behavior changes | task-agent, review-agent, analysis-agent | checklist-result, residual-risk |
64| [evidence patterns](references/evidence-patterns.md) | evidence-pattern | routing timeout TLS or failing-hop claims need representative proof | fresh config probes and correlated telemetry prove each claim | task-agent, review-agent, analysis-agent | evidence-record, proof-limit, residual-risk |
machenjie