Cuotas de token-bucket con alcance por llamante con clases distintas 429 y 503, Retry-After en limitación, ventanas de ráfaga versus sostenidas, y compartición justa entre inquilinos que nunca revela la identidad de un vecino.
Estado del paquete: contexto de referencia listo para revisión humana. El contrato y los escenarios de prueba están completos, pero no se afirma que una implementación adoptante los haya aprobado.
Decisión
Las API HTTP públicas y de socios admiten una solicitud solo después de que un token-bucket con alcance por llamante concede un token. El tráfico autenticado se indexa por principal e inquilino. Las rutas públicas no autenticadas usan una clase anónima documentada a partir de rango de red hasheado más clase de ruta, nunca un id de inquilino vecino. El relleno de ráfaga y sostenido son valores de perfil independientes. El agotamiento de cuota personal es una limitación para el cliente; el agotamiento de admisión compartida o fallo del almacén del limitador es una clase de servicio. La identidad del vecino y el presupuesto restante nunca aparecen en encabezados, cuerpos o registros visibles para el llamante.
Alcance
- Admisión para clases de ruta public-apis y partner-apis en el perfil de adopción.
- Identidad de cuota, relleno de token-bucket, Retry-After, equidad de fragmentos y claves del limitador que podrían filtrar otro inquilino.
Fuera de este bloque
- Apertura de circuito para una dependencia fallida (paquete relacionado de circuit-breaker).
- Aritmética de plazo restante (paquete relacionado de deadline-propagation).
Contrato
- La identidad del limitador es el principal autenticado y el inquilino, o una clase anónima documentada, nunca un identificador bruto de inquilino vecino.
- Los tokens de ráfaga y el relleno sostenido se evalúan independientemente; la ráfaga solo se permite mientras esa identidad aún tenga crédito de relleno.
- El agotamiento de cuota personal devuelve HTTP 429 con un código de catálogo y Retry-After calculado desde el bucket de este llamante.
- El agotamiento de capacidad compartida o fallo del almacén del limitador devuelve HTTP 503 con un código de catálogo diferente.
- En un fragmento compartido, ningún inquilino puede ocupar más que la cuota del perfil de los espacios de admisión compartida en una ventana.
- Las respuestas y registros visibles para el llamante omiten identificadores de otros inquilinos, cuotas restantes y estadísticas de rutas vecinas.
Guía de implementación
- Indexar buckets por principal y clase de ruta; no indexar tráfico autenticado solo por IP. Decrementar atómicamente para que las actualizaciones perdidas no concedan ráfaga extra.
- Cuando el almacén del limitador no sea accesible, fallar cerrado a la clase de error de capacidad en lugar de admitir tráfico ilimitado.
Manejo de fallos y salvaguardas
- Los clientes deben distinguir limitación personal de capacidad del proveedor. Si no se puede calcular Retry-After para este llamante, omitir el encabezado en lugar de copiar la demora de un vecino.
- El relleno del bucket usa el tiempo del almacén del limitador, no el encabezado Date del cliente.
Verificación y operaciones
- Ejecutar dos inquilinos en un fragmento y demostrar que uno no puede dejar sin recursos al otro más allá de la cuota del perfil, y que los cuerpos 429 nunca incluyen el id del otro inquilino.
- Alertar cuando los rechazos de clase de capacidad excedan el presupuesto de error del perfil.
Los ejemplos con apariencia ejecutable en este paquete son fixtures y contratos de aceptación. Ejecute
python tools/validate.py desde la raíz de la colección para verificar la estructura y metadatos del paquete; luego
implemente y ejecute los escenarios en el repositorio objetivo.
Suposiciones de adopción
- Nombres y valores numéricos en
example.yamlson un perfil de adopción, no valores predeterminados universales. - El equipo adoptante debe mapear actores, clases de datos, vocabulario de errores y propiedad a su sistema.