Envoy Gateway 1.2 ExtAuthz Sub-Millisecond Token-Bucket Standard

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Multi-Hop Database Calls and Unbounded Timeouts in ExtAuthz Causing Edge Proxy Thread Pool Starvation) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Envoy Gateway 1.2 ExtAuthz Sub-Millisecond Token-Bucket Standard

--- description: Envoy Gateway 1.2 ExtAuthz Sub-Millisecond Token-Bucket Standard - Mandates that edge rate limiting and authorization via Envoy Gateway 1.2 ExtAuthz execute within a strict sub-millisecond bounded latency budget using atomic, single-roundtrip token-bucket algorithms. Prevents cluster-wide cascading failures and edge worker thread pool exhaustion by strictly bounding ExtAuthz gRPC timeouts and executing rate evaluation at the edge data plane before upstream dispatch. globs: k8s/**/*.yaml, gateway/**/*.yaml, src/gateway/**/*.{ts,js,go}, src/authz/**/*.{ts,js,go} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/envoy-gateway-extauthz-submillisecond-token-bucket" --- # Envoy Gateway 1.2 ExtAuthz Sub-Millisecond Token-Bucket Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Multi-Hop Database Calls and Unbounded Timeouts in ExtAuthz Causing Edge Proxy Thread Pool Starvation ## System Constraints You are a Principal Software Architect enforcing the Envoy Gateway 1.2 ExtAuthz Sub-Millisecond Token-Bucket Standard. Mandate that all external authorization services integrated with Envoy Gateway execute within sub-millisecond latency budgets using atomic operations (e.g., Redis EVALSHA or localized synchronized token-bucket states), enforce explicit context deadlines, and return canonical HTTP 429 responses with accurate rate-limit headers upon token depletion. ## Strict Guidelines - Engineers MUST ALWAYS configure Envoy Gateway EnvoyExtensionPolicy/SecurityPolicy ExtAuthz timeouts to <= 10ms with aggressive gRPC keep-alive and connection pooling. - Engineers MUST ALWAYS evaluate rate-limiting token buckets using atomic single-roundtrip primitives (such as pre-loaded Redis EVALSHA Lua scripts or local bounded L1 ring buffers) to guarantee execution under 1ms. - Engineers MUST NOT execute sequential multi-hop I/O, unindexed database queries, or unmemoized remote network calls inside the critical path of the ExtAuthz Check gRPC method. - Code SHOULD inspect incoming gRPC deadlines via context/metadata and immediately abort downstream evaluation if the remaining time budget is under 2ms. - Services MUST return canonical HTTP 429 (Too Many Requests) status codes via the DeniedHttpResponse object along with Retry-After and X-RateLimit-Remaining headers when tokens are exhausted. - Components NEVER permit unhandled network exceptions or hanging promises in ExtAuthz handlers; failures must immediately map to defined gRPC status codes to prevent Envoy thread pool saturation. ## Bad vs Good Implementations ### TypeScript ExtAuthz gRPC Sub-Millisecond Token Bucket Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Performs sequential relational database and un-pipelined Redis calls inside the edge ExtAuthz path, inducing 20-100ms latencies that exhaust Envoy's worker connection pool. It also fails to inspect gRPC deadlines and returns generic gRPC status codes rather than an explicit HTTP 429 DeniedHttpResponse. ```typescript // BAD: Sequential multi-hop DB calls and missing gRPC deadline checks cause Envoy thread starvation import { ServerUnaryCall, sendUnaryData } from '@grpc/grpc-js'; import { CheckRequest, CheckResponse } from './proto/envoy/service/auth/v3/auth'; import { pgPool } from './db'; import { redisClient } from './redis'; export async function check( call: ServerUnaryCall<CheckRequest, CheckResponse>, callback: sendUnaryData<CheckResponse> ): Promise<void> { const clientIp = call.request.attributes?.source?.address?.socketAddress?.address ?? 'unknown'; // Anti-Pattern: Relational DB call inside edge ingress critical path (10-50ms) const userRes = await pgPool.query('SELECT rate_limit FROM clients WHERE ip = $1', [clientIp]); const limit = userRes.rows[0]?.rate_limit ?? 50; // Anti-Pattern: Non-atomic multiple network hops to Redis const currentCount = await redisClient.get(`rate:${clientIp}`); if (parseInt(currentCount || '0', 10) >= limit) { // Anti-Pattern: Generic permission denied without HTTP 429 semantics return callback(null, { status: { code: 7 } } as CheckResponse); } await redisClient.incr(`rate:${clientIp}`); return callback(null, { status: { code: 0 } } as CheckResponse); } ``` #### Production Standard (Correct) > **Standard**: Enforces sub-millisecond execution by evaluating token-bucket replenishment and consumption atomically in Redis via EVALSHA in a single trip. Enforces gRPC deadline budgets, returns compliant HTTP 429 metadata with Retry-After headers, and protects upstream clusters from cascading overload. ```typescript // GOOD: Atomic single-trip token-bucket via Redis EVALSHA with deadline propagation and HTTP 429 headers import { ServerUnaryCall, sendUnaryData, status as GrpcStatus } from '@grpc/grpc-js'; import { CheckRequest, CheckResponse } from './proto/envoy/service/auth/v3/auth'; import { redisClient, TOKEN_BUCKET_LUA_SHA } from './redisCluster'; const MIN_DEADLINE_BUDGET_MS = 2; export async function check( call: ServerUnaryCall<CheckRequest, CheckResponse>, callback: sendUnaryData<CheckResponse> ): Promise<void> { const deadline = call.getDeadline(); const remainingMs = typeof deadline === 'number' ? deadline - Date.now() : Infinity; if (remainingMs <= MIN_DEADLINE_BUDGET_MS) { return callback({ code: GrpcStatus.DEADLINE_EXCEEDED, message: 'ExtAuthz deadline budget exhausted' }); } const headers = call.request.attributes?.request?.http?.headers; const key = headers?.['x-api-key'] || call.request.attributes?.source?.address?.socketAddress?.address || 'anonymous'; const capacity = 100; const refillRatePerSec = 20; const now = Date.now(); try { // Atomic Lua token bucket: [allowed(0|1), remainingTokens, retryAfterSec] const raw = await redisClient.evalsha( TOKEN_BUCKET_LUA_SHA, 1, `ratelimit:${key}`, capacity.toString(), refillRatePerSec.toString(), now.toString(), '1' ) as [number, number, number]; const [allowed, remainingTokens, retryAfterSec] = raw; if (allowed === 0) { return callback(null, { status: { code: GrpcStatus.PERMISSION_DENIED }, deniedResponse: { status: { code: 429 }, headers: [ { header: { key: 'Retry-After', value: retryAfterSec.toString() } }, { header: { key: 'X-RateLimit-Remaining', value: '0' } }, { header: { key: 'Content-Type', value: 'application/json' } } ], body: '{"error":"Too Many Requests","message":"Rate limit exceeded"}' } } as CheckResponse); } return callback(null, { status: { code: GrpcStatus.OK }, okResponse: { headers: [ { header: { key: 'X-RateLimit-Remaining', value: remainingTokens.toString() } } ] } } as CheckResponse); } catch (err) { return callback({ code: GrpcStatus.UNAVAILABLE, message: 'Token bucket evaluator unavailable' }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Envoy Gateway 1.2 ExtAuthz Sub-Millisecond Token-Bucket Standard

Envoy Gateway 1.2 ExtAuthz Sub-Millisecond Token-Bucket Standard defines an industrial-grade behavioral standard for devops engineering. Mandates that edge rate limiting and authorization via Envoy Gateway 1.2 ExtAuthz execute within a strict sub-millisecond bounded latency budget using atomic, single-roundtrip token-bucket algorithms. Prevents cluster-wide cascading failures and edge worker thread pool exhaustion by strictly bounding ExtAuthz gRPC timeouts and executing rate evaluation at the edge data plane before upstream dispatch. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Multi-Hop Database Calls and Unbounded Timeouts in ExtAuthz Causing Edge Proxy Thread Pool Starvation Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Multi-Hop Database Calls and Unbounded Timeouts in ExtAuthz Causing Edge Proxy Thread Pool Starvation	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS configure Envoy Gateway EnvoyExtensionPolicy/SecurityPolicy ExtAuthz timeouts to <= 10ms with aggressive gRPC keep-alive and connection pooling.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.