Rate Limiting & Throttling — Integration

​

Purpose

​

PF Dependencies

​

Event Contract: pf_rate_limit_violated

​

Purpose

​

Trigger Conditions

• After pf_check_rate_limit() returns allowed = false and a row is inserted into pf_rate_limit_violations.

​

Payload Schema

/** Canonical payload for pf_rate_limit_violated event (PF-42). */
export interface PfRateLimitViolatedPayload {
  organizationId: string;
  userId?: string;
  ipAddress?: string;
  endpoint?: string;
  rateLimitId: string;
  limitType: 'per_minute' | 'per_hour' | 'per_day';
  limitValue: number;
  actualCount: number;
  violatedAt: string; // ISO 8601
}

​

Consumer Actions

​

Database Function API: pf_check_rate_limit

​

Function Signature

​

Security

• SECURITY DEFINER; SET search_path = public. Callers must pass validated IP (see spec FR-3.2 for getValidatedIPAddress and trusted proxy whitelist).

​

Platform Integration Layer (Consumed by Cores)

• Rate limit check (client): useRateLimit hook (see spec API Design). Cores use this for UI-level rate limit checks.
• Rate limit check (server): Edge functions call pf_check_rate_limit() at request entry; return 429 with Retry-After when not allowed.

​

API Contract: Check Rate Limit (Edge)

​

Request / Response

​

Error

• 429 Too Many Requests with Retry-After header when rate limited.

​

References

• PF-42 Spec
• EVENT_CONTRACTS.md — add pf_rate_limit_violated to registry when implemented
• PLATFORM_INTEGRATION_LAYERS.md — rate limiting as platform capability