PD-278 — Agent Developer Report: dip-rate-limit (C8)¶

Agent: agent-developer Module: dip-rate-limit Date: 2026-03-01 Status: DELIVERED

1. Scope¶

Implementation of DisseminationRateLimitGuard — a NestJS guard enforcing per-actor rate-limiting and daily quota for SEALED -> DIP transitions.

File delivered: src/modules/documents/guards/dissemination-rate-limit.guard.ts

2. Code Contract Compliance¶

Interfaces¶

Invariants¶

Forbidden Rules¶

3. Architectural Decisions¶

AD-1: HttpException instead of DisseminationError¶

• Decision: Use HttpException from @nestjs/common directly instead of importing DisseminationError from ../dto/dissemination-error.dto.ts.
• Rationale: The DTO module (dip-dto) is delivered by another agent and the file does not exist yet at implementation time. Using HttpException directly ensures the guard compiles independently with zero cross-agent dependencies, following the same pattern as LegalRateLimitGuard (PD-81).
• Alternatives considered: (1) Import DisseminationError — would break compilation until DTO agent delivers. (2) Create a minimal stub DTO — violates agent isolation (hors perimetre).
• Trade-offs: Response body uses string literal 'E-429-RATE-LIMIT' instead of typed enum. The controller/filter integration (C10/C11) will use exception.getResponse()['error_code'] for dispatch. When DTO module is delivered, the guard CAN be migrated to DisseminationError — refactoring is mechanical and non-breaking.

AD-2: Redis config from storage.redis (not REDIS_URL)¶

• Decision: Instantiate Redis from storage.redis.host/port/password/db via ConfigService, not from REDIS_URL.
• Rationale: The project's canonical Redis config is in src/config/storage.config.ts under storage.redis.*. The LegalRateLimitGuard uses REDIS_URL which is a different pattern specific to the legal-pre module. Using storage.redis.* is consistent with RateLimitService (PD-23) and the broader project configuration.
• Alternatives considered: REDIS_URL string (LegalRateLimitGuard pattern), @InjectRedis() decorator (if BullMQ module exposes it).
• Trade-offs: Slightly more verbose constructor, but consistent with the majority of Redis consumers in the codebase.

4. Implementation Details¶

4.1 Redis Key Strategy¶

• INCR is atomic — first call creates key with value 1
• EXPIRE set on count === 1 (first request in window)
• Daily key includes date suffix for natural reset at UTC midnight

4.2 Error Response Format¶

Follows PD-279 pattern:

{
  "error_code": "E-429-RATE-LIMIT",
  "message": "Rate limit or daily quota exceeded",
  "details": {
    "limit_type": "per_minute",
    "current": 61,
    "max": 60,
    "retry_after": 45
  }
}

For Redis failure:

{
  "error_code": "E-503-REDIS",
  "message": "Service temporarily unavailable",
  "details": { "reason": "redis_unavailable" }
}

4.3 Actor Identity Extraction¶

The guard extracts actor_id from request.user.sub (JWT claim) or request.user.id (fallback). If neither is present (which should not occur given JwtAuthGuard runs first), the guard fail-closes with 429.

4.4 Compilation Status¶

• npx tsc --noEmit: 0 errors on the guard file
• No errors introduced in the broader project compilation

5. Integration Points¶

5.1 Dependencies (consumed)¶

5.2 Consumers (downstream)¶

5.3 Module Registration (required by consuming agent)¶

The guard must be added to DocumentsModule.providers:

providers: [
  // ... existing providers
  DisseminationRateLimitGuard,
]

6. Test Coverage Mapping¶

Suggested Unit Test Cases for dissemination-rate-limit.guard.spec.ts¶

TC-ERR-13-A: should allow requests within per-minute rate limit
TC-ERR-13-B: should reject with 429 when per-minute rate limit exceeded
TC-ERR-13-C: should allow requests within daily quota
TC-ERR-13-D: should reject with 429 when daily quota exceeded
TC-ERR-13-E: should fail-closed with 503 when Redis unavailable (E-503-REDIS)
TC-ERR-13-F: should set TTL on first request in per-minute window
TC-ERR-13-G: should set TTL on first request in daily quota window
TC-ERR-13-H: should use actor_id (not document_id) for rate-limit key
TC-ERR-13-I: should reject with 429 when no actor identity (fail-closed)
TC-ERR-13-J: should include retry_after in 429 response details (per-minute)
TC-ERR-13-K: should include retry_after in 429 response details (daily quota)
TC-ERR-13-L: should read config from dissemination.rateLimitPerMinute and dissemination.quotaPerDay

7. Hypotheses¶

8. Risks and Debt¶

9. Files Modified¶

10. Verification Checklist¶

• Implements CanActivate interface (NestJS guard)
• Per-minute rate limit: Redis INCR + EXPIRE, key dip:rate:{actorId}
• Daily quota: Redis INCR + EXPIRE, key dip:quota:{actorId}:{YYYY-MM-DD}
• Config from DisseminationConfig via ConfigService (not hardcoded)
• Fail-closed on Redis unavailability (503 E-503-REDIS)
• No fail-open path
• Rate-limit by actorId, not document_id
• Not registered as APP_GUARD (scoped to controller via @UseGuards)
• Error response follows PD-279 format (error_code, message, details)
• TypeScript compilation: 0 errors
• No cross-agent file dependencies (self-contained)