From 41026f665bc974c70202eb2d16473c8a48e81ab3 Mon Sep 17 00:00:00 2001 From: Durable Workflow Date: Fri, 23 Oct 2026 22:32:54 +0000 Subject: [PATCH] docs: explain published Python failure-report limits in every locale --- docs/failures-and-recovery.md | 4 ++++ docs/polyglot/python.md | 21 +++++++++++++++++++ .../current/failures-and-recovery.md | 4 ++++ .../current/polyglot/python.md | 21 +++++++++++++++++++ i18n/de/source-hashes.json | 4 ++-- .../current/failures-and-recovery.md | 4 ++++ .../current/polyglot/python.md | 21 +++++++++++++++++++ i18n/es/source-hashes.json | 4 ++-- .../current/failures-and-recovery.md | 4 ++++ .../current/polyglot/python.md | 21 +++++++++++++++++++ i18n/fr/source-hashes.json | 4 ++-- .../current/failures-and-recovery.md | 4 ++++ .../current/polyglot/python.md | 21 +++++++++++++++++++ i18n/ja/source-hashes.json | 4 ++-- .../current/failures-and-recovery.md | 4 ++++ .../current/polyglot/python.md | 21 +++++++++++++++++++ i18n/pt-BR/source-hashes.json | 4 ++-- .../current/failures-and-recovery.md | 4 ++++ .../current/polyglot/python.md | 21 +++++++++++++++++++ i18n/uk/source-hashes.json | 4 ++-- .../current/failures-and-recovery.md | 4 ++++ .../current/polyglot/python.md | 21 +++++++++++++++++++ i18n/zh-Hans/source-hashes.json | 4 ++-- 23 files changed, 214 insertions(+), 14 deletions(-) diff --git a/docs/failures-and-recovery.md b/docs/failures-and-recovery.md index bec8e1eed4f..b9767fa1e80 100644 --- a/docs/failures-and-recovery.md +++ b/docs/failures-and-recovery.md @@ -270,6 +270,10 @@ class RetryableWorkflow extends Workflow } ``` +## Python service-mode failure report limits {#python-failure-report-limits} + +Python SDK **2.11.0 or newer** bounds outgoing service-mode failure reports to 62 KiB UTF-8 messages, 128 KiB stacks, 64 KiB combined optional metadata and a 1 MiB complete encoded body, including markers. Lower known transport limits apply. The [Python reporting guide](./polyglot/python.md#bounded-failure-reports) explains configuration, omission diagnostics, preserved retry semantics and the same local observation during first execution and cold replay. These limits apply to SDK reporting. Embedded recording and Core summary storage retain their separate contracts. + ## Rust service-mode failure report limits {#rust-failure-report-limits} For service-mode workers actually running Rust SDK **4.10.1 or newer**, outgoing failure messages are at most 62 KiB UTF-8 including marker, stacks 128 KiB where supported, combined serialized optional metadata 64 KiB, and the full encoded body 1 MiB or a lower known transport cap. Original type, retry decision and claim identity stay intact; impossible mandatory envelopes refuse explicitly. The [Rust reporting guide](./polyglot/rust.md#bounded-failure-reports) explains omission markers, whole Avro details and local-result boundaries. These limits do not qualify old SDKs, embedded mode or the separate Core summary-storage correction. diff --git a/docs/polyglot/python.md b/docs/polyglot/python.md index f5e6c4133bd..dd3a1bfe2b5 100644 --- a/docs/polyglot/python.md +++ b/docs/polyglot/python.md @@ -206,11 +206,32 @@ async with Client( | `payload_size_limit_bytes` | `int` | SDK default | Match the server's max payload-byte contract. | | `payload_size_warning_threshold_percent` | `int` | SDK default | Warn before a payload reaches the configured limit. | | `payload_size_warnings` | `bool` | `True` | Disable local payload-size warnings in tests or controlled scripts. | +| `failure_report_limit_bytes` | `int` | `1048576` | Lower the complete encoded failure-report budget. See [bounded failure reports](#bounded-failure-reports). | `token` is the simplest option. If both `control_token` and `worker_token` are set, control-plane methods use `control_token` and worker-plane methods use `worker_token`. +### Bounded failure reports {#bounded-failure-reports} + +Python SDK **2.11.0** introduced bounded outgoing failure reports. Defaults are **62 KiB UTF-8 for the message**, **128 KiB for the stack**, **64 KiB for combined serialized optional details and diagnostics**, and **1 MiB for the complete HTTPX-encoded body**. Markers, JSON escaping, claim identity and other commands in the batch count toward that body limit. A lower configured or discovered transport limit takes precedence. Failure type, class, code, retry policy and claim identity are preserved. + +Set a smaller body budget when needed. Payload-size warning settings remain advisory. + +```python +from durable_workflow import Client + +async with Client( + "https://workflow.example.com", + worker_token="worker-token", + control_token="operator-token", + failure_report_limit_bytes=512 * 1024, +) as client: + info = await client.get_cluster_info() +``` + +A visible truncation marker and original byte counts identify shortened fields. Avro details remain intact or are omitted whole. An unrepresentable required envelope raises `FailureReportTooLarge` before HTTP submission. Local failures are normalized before workflow code observes them, so first execution and cold replay see the persisted message. An already observed local message remains immutable during final batch fitting. + ### External Payload Storage Normal `Client` and `Worker` operations use Server's authenticated runtime diff --git a/i18n/de/docusaurus-plugin-content-docs/current/failures-and-recovery.md b/i18n/de/docusaurus-plugin-content-docs/current/failures-and-recovery.md index 765ac156e07..3c6e5b1ae8c 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/failures-and-recovery.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/failures-and-recovery.md @@ -263,6 +263,10 @@ class RetryableWorkflow extends Workflow } ``` +## Limits für Python-Fehlerberichte im Service-Modus {#python-failure-report-limits} + +Das Python SDK **ab 2.11.0** begrenzt ausgehende Fehlerberichte im Service-Modus auf 62 KiB UTF-8 für Meldungen, 128 KiB für Stacks, 64 KiB für optionale Metadaten zusammen und 1 MiB für den vollständigen codierten Body einschließlich Markierungen. Niedrigere bekannte Transportlimits gelten weiterhin. Der [Python-Leitfaden für Fehlerberichte](./polyglot/python.md#bounded-failure-reports) erläutert Konfiguration, Auslassungsdiagnosen, unveränderte Retry-Semantik und identische Beobachtungen bei erster Ausführung und kaltem Replay. Diese Grenzen gelten für SDK-Berichte. Eingebettete Fehleraufzeichnung und Core-Summary-Speicherung haben eigene Verträge. + ## Grenzen für Rust-Fehlerberichte im Service-Modus {#rust-failure-report-limits} Bei Service-Workern mit tatsächlich laufendem Rust SDK **4.10.1 oder neuer** hat die ausgehende UTF-8-Nachricht höchstens 62 KiB einschließlich Markierung, ein unterstützter Stack 128 KiB, gemeinsam serialisierte optionale Metadaten 64 KiB und der vollständige kodierte Body 1 MiB oder eine bekannte niedrigere Transportgrenze. Typ, Retry-Entscheidung und Identität bleiben erhalten; unmögliche Pflichthüllen werden ausdrücklich abgelehnt. Der [Rust-Leitfaden](./polyglot/rust.md#bounded-failure-reports) erklärt Markierungen, vollständige Avro-Details und lokale Ergebnisse. Ältere SDKs, Embedded-Modus und die separate Core-Speicherkorrektur sind damit nicht qualifiziert. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/polyglot/python.md b/i18n/de/docusaurus-plugin-content-docs/current/polyglot/python.md index 067217fb63f..021624cf81c 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/polyglot/python.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/polyglot/python.md @@ -207,11 +207,32 @@ async with Client( | `payload_size_limit_bytes` | `int` | SDK-Standard | Vertrag des Servers zur maximalen Nutzlastgröße abbilden. | | `payload_size_warning_threshold_percent` | `int` | SDK-Standard | Vor Erreichen der konfigurierten Nutzlastgrenze warnen. | | `payload_size_warnings` | `bool` | `True` | Lokale Nutzlastgrößenwarnungen in Tests oder kontrollierten Skripten deaktivieren. | +| `failure_report_limit_bytes` | `int` | `1048576` | Das Budget für den vollständig codierten Fehlerbericht verringern. Siehe [begrenzte Fehlerberichte](#bounded-failure-reports). | `token` ist die einfachste Option. Sind `control_token` und `worker_token` gesetzt, verwenden Control-Plane-Methoden `control_token` und Worker-Plane-Methoden `worker_token`. +### Begrenzte Fehlerberichte {#bounded-failure-reports} + +Das Python SDK **2.11.0** führte begrenzte ausgehende Fehlerberichte ein. Standardmäßig gelten **62 KiB UTF-8 für die Meldung**, **128 KiB für den Stack**, **64 KiB für gemeinsam serialisierte optionale Details und Diagnosen** und **1 MiB für den vollständigen HTTPX-codierten Body**. Markierungen, JSON-Escaping, die Claim-Identität und weitere Befehle im Batch zählen zum Body-Limit. Ein niedrigeres konfiguriertes oder erkanntes Transportlimit hat Vorrang. Fehlertyp, Klasse, Code, Retry-Regeln und Claim-Identität bleiben erhalten. + +Bei Bedarf lässt sich das Body-Budget verkleinern. Einstellungen für Warnungen zur Payload-Größe bleiben reine Hinweise. + +```python +from durable_workflow import Client + +async with Client( + "https://workflow.example.com", + worker_token="worker-token", + control_token="operator-token", + failure_report_limit_bytes=512 * 1024, +) as client: + info = await client.get_cluster_info() +``` + +Eine sichtbare Kürzungsmarkierung und die ursprünglichen Byte-Anzahlen kennzeichnen gekürzte Felder. Avro-Details bleiben vollständig erhalten oder werden als Ganzes weggelassen. Ein nicht darstellbarer erforderlicher Umschlag löst vor der HTTP-Übertragung `FailureReportTooLarge` aus. Lokale Fehler werden normalisiert, bevor der Workflow-Code sie beobachtet. Dadurch sehen die erste Ausführung und ein kalter Replay dieselbe gespeicherte Meldung. Eine bereits beobachtete lokale Meldung bleibt bei der abschließenden Größenanpassung des Batches unveränderlich. + ### Externer Nutzlastspeicher {#external-payload-storage} Normale `Client`- und `Worker`-Operationen verwenden automatisch den authentifizierten Runtime-Transport von Server. Das SDK ermittelt Richtlinie und Limits über `GET /api/cluster/info`, lädt codierte Werte über dem Schwellenwert oder bei Bedarf zum Einhalten des Anfragelimits hoch und lädt Referenzwerte vor dem Decodieren. Workflow- und Aktivitätscode erhalten den decodierten Wert. Anbieter-Zugangsdaten bleiben auf dem Server. Entfernte Worker benötigen weder boto3 noch Anbieter-Clients oder Zugriff auf das lokale Server-Verzeichnis. diff --git a/i18n/de/source-hashes.json b/i18n/de/source-hashes.json index c305d7b1bca..8b3f392daed 100644 --- a/i18n/de/source-hashes.json +++ b/i18n/de/source-hashes.json @@ -28,7 +28,7 @@ "defining-workflows/workflow-status.md": "8e8cb27ff44c890d489d89bf166375acfdfaecabd990a2235e106fab1592d529", "defining-workflows/workflows.md": "f467bc73de32aa5d722c61ce085065460382ae7dd44cea4625847d9fcdc4c97c", "deployment.md": "dd0b6bd184eda12e67922121a09c7f3c98346bde01be1d4c3217f168db5fd7ca", - "failures-and-recovery.md": "7df0b7ce4139b789d8988ce2bf640c388225daa28731b88719e4777f61e40a4c", + "failures-and-recovery.md": "809a86ec38b63d7f8591d1fbee970b0f34bcc5cb508a72060fa78a441cbcdb60", "features/activity-execution-model.md": "e8c37520ae46a7efb30438f4fc06bf893c1df430cb1f92c48963697adaf09082", "features/cancel-and-terminate.md": "c678fc7a0c9b11f0e1bee295aff259de9803219c0aa6769fb801622799e7deb1", "features/child-workflows.md": "57016591fb8816aed7b077e204f1c80f9c6a8dff7501bc00a141c41a4607306b", @@ -82,7 +82,7 @@ "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989", "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959", "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c", - "polyglot/python.md": "d55056ca7638df07b7267bc6d62e635b954957b99620478e861df90558860df3", + "polyglot/python.md": "ac9cd626b7ac3d444509d933f2fec3af015f4c4c171abb0bfcf32642282d7536", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "af91b22c93a7fe6833df156371d99bb105740684915bc73af4576f6de2897e10", "polyglot/server-api-reference.md": "b0a7bfa17ccaec0507ee97dfc1badac49fa5ff96f8178fa4ce5963bc8c6fe7d1", diff --git a/i18n/es/docusaurus-plugin-content-docs/current/failures-and-recovery.md b/i18n/es/docusaurus-plugin-content-docs/current/failures-and-recovery.md index da324f3757a..2ee49af00f6 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/failures-and-recovery.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/failures-and-recovery.md @@ -320,6 +320,10 @@ class RetryableWorkflow extends Workflow } ``` +## Límites de los informes de error de Python en modo servicio {#python-failure-report-limits} + +El SDK de Python **2.11.0 o posterior** limita los informes de error salientes en modo servicio a mensajes UTF-8 de 62 KiB, pilas de 128 KiB, 64 KiB de metadatos opcionales combinados y un cuerpo completo codificado de 1 MiB, incluidos los marcadores. Se aplican los límites de transporte conocidos que sean menores. La [guía de informes de Python](./polyglot/python.md#bounded-failure-reports) explica la configuración, los diagnósticos de omisión, la semántica de reintentos conservada y la igualdad entre la primera ejecución local y la reproducción en frío. Estos límites corresponden a los informes del SDK. El registro integrado y el almacenamiento de resúmenes del Core mantienen sus propios contratos. + ## Límites de informes de fallo Rust en modo servicio {#rust-failure-report-limits} En workers de servicio que realmente ejecutan Rust SDK **4.10.1 o posterior**, el mensaje saliente admite hasta 62 KiB UTF-8 con marcador, stack 128 KiB si existe, metadata opcional serializada combinada 64 KiB y cuerpo completo codificado 1 MiB o un límite de transporte conocido menor. Se conservan tipo, retry e identidad; un envelope obligatorio imposible se rechaza. La [guía Rust](./polyglot/rust.md#bounded-failure-reports) explica marcadores, details Avro íntegros y resultados locales. No cualifica SDK antiguos, modo embedded ni la corrección separada del almacenamiento de resúmenes Core. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/polyglot/python.md b/i18n/es/docusaurus-plugin-content-docs/current/polyglot/python.md index 75a71906abe..1d5bd1af954 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/polyglot/python.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/polyglot/python.md @@ -209,10 +209,31 @@ async with Client( | `payload_size_limit_bytes` | `int` | predeterminado del SDK | Ajustar al contrato máximo de bytes de carga del servidor. | | `payload_size_warning_threshold_percent` | `int` | predeterminado del SDK | Avisar antes de alcanzar el límite. | | `payload_size_warnings` | `bool` | `True` | Desactivar avisos locales de tamaño en pruebas o scripts controlados. | +| `failure_report_limit_bytes` | `int` | `1048576` | Reducir el presupuesto del informe de error completamente codificado. Consulta [informes de error acotados](#bounded-failure-reports). | `token` es lo más sencillo. Si estableces `control_token` y `worker_token`, los métodos usan el correspondiente a su plano. +### Informes de error acotados {#bounded-failure-reports} + +El SDK de Python **2.11.0** incorporó informes de error salientes acotados. Los valores predeterminados son **62 KiB UTF-8 para el mensaje**, **128 KiB para la pila**, **64 KiB para los detalles y diagnósticos opcionales serializados en conjunto** y **1 MiB para el cuerpo completo codificado por HTTPX**. Los marcadores, el escape JSON, la identidad de la concesión y los demás comandos del lote cuentan para ese límite del cuerpo. Tiene prioridad cualquier límite de transporte configurado o descubierto que sea menor. Se conservan el tipo, la clase y el código del error, la política de reintentos y la identidad de la concesión. + +Configura un presupuesto menor para el cuerpo cuando sea necesario. Los ajustes de advertencia sobre el tamaño de la carga siguen siendo informativos. + +```python +from durable_workflow import Client + +async with Client( + "https://workflow.example.com", + worker_token="worker-token", + control_token="operator-token", + failure_report_limit_bytes=512 * 1024, +) as client: + info = await client.get_cluster_info() +``` + +Un marcador visible de truncamiento y los recuentos originales de bytes identifican los campos recortados. Los detalles Avro se conservan íntegros o se omiten por completo. Si una envoltura obligatoria no puede representarse, se lanza `FailureReportTooLarge` antes del envío HTTP. Los errores locales se normalizan antes de que el código del workflow los observe, por lo que la primera ejecución y la reproducción en frío ven el mensaje persistido. Un mensaje local ya observado permanece inmutable durante el ajuste final del lote. + ### Almacenamiento externo de cargas {#external-payload-storage} Las operaciones normales de `Client` y `Worker` usan automáticamente el transporte autenticado del runtime de Server. El SDK descubre la política y los límites mediante `GET /api/cluster/info`, sube valores codificados superiores al umbral o necesarios para que quepa la solicitud y recupera los valores referenciados antes de decodificar. El código del workflow y de la actividad recibe el valor decodificado. Las credenciales permanecen en Server. Los workers remotos no necesitan boto3, clientes del proveedor ni acceso al directorio local de Server. diff --git a/i18n/es/source-hashes.json b/i18n/es/source-hashes.json index c305d7b1bca..8b3f392daed 100644 --- a/i18n/es/source-hashes.json +++ b/i18n/es/source-hashes.json @@ -28,7 +28,7 @@ "defining-workflows/workflow-status.md": "8e8cb27ff44c890d489d89bf166375acfdfaecabd990a2235e106fab1592d529", "defining-workflows/workflows.md": "f467bc73de32aa5d722c61ce085065460382ae7dd44cea4625847d9fcdc4c97c", "deployment.md": "dd0b6bd184eda12e67922121a09c7f3c98346bde01be1d4c3217f168db5fd7ca", - "failures-and-recovery.md": "7df0b7ce4139b789d8988ce2bf640c388225daa28731b88719e4777f61e40a4c", + "failures-and-recovery.md": "809a86ec38b63d7f8591d1fbee970b0f34bcc5cb508a72060fa78a441cbcdb60", "features/activity-execution-model.md": "e8c37520ae46a7efb30438f4fc06bf893c1df430cb1f92c48963697adaf09082", "features/cancel-and-terminate.md": "c678fc7a0c9b11f0e1bee295aff259de9803219c0aa6769fb801622799e7deb1", "features/child-workflows.md": "57016591fb8816aed7b077e204f1c80f9c6a8dff7501bc00a141c41a4607306b", @@ -82,7 +82,7 @@ "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989", "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959", "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c", - "polyglot/python.md": "d55056ca7638df07b7267bc6d62e635b954957b99620478e861df90558860df3", + "polyglot/python.md": "ac9cd626b7ac3d444509d933f2fec3af015f4c4c171abb0bfcf32642282d7536", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "af91b22c93a7fe6833df156371d99bb105740684915bc73af4576f6de2897e10", "polyglot/server-api-reference.md": "b0a7bfa17ccaec0507ee97dfc1badac49fa5ff96f8178fa4ce5963bc8c6fe7d1", diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/failures-and-recovery.md b/i18n/fr/docusaurus-plugin-content-docs/current/failures-and-recovery.md index 4c1ed8b891a..6e7e175c1f4 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/failures-and-recovery.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/failures-and-recovery.md @@ -353,6 +353,10 @@ class RetryableWorkflow extends Workflow } ``` +## Limites des rapports d’échec Python en mode service {#python-failure-report-limits} + +Le SDK Python **2.11.0 ou ultérieur** borne les rapports d’échec sortants en mode service à des messages UTF-8 de 62 KiB, des piles de 128 KiB, 64 KiB de métadonnées facultatives combinées et un corps complet encodé de 1 MiB, marqueurs compris. Les limites de transport connues plus basses s’appliquent. Le [guide des rapports Python](./polyglot/python.md#bounded-failure-reports) explique la configuration, les diagnostics d’omission, la sémantique de nouvelle tentative conservée et l’égalité entre première exécution locale et relecture à froid. Ces limites concernent les rapports du SDK. L’enregistrement embarqué et le stockage des résumés du Core gardent leurs contrats distincts. + ## Limites des rapports d’échec Rust en mode service {#rust-failure-report-limits} Pour les workers de service exécutant réellement Rust SDK **4.10.1 ou ultérieur**, le message sortant atteint au plus 62 KiB UTF-8 avec marqueur, le stack 128 KiB si pris en charge, les métadonnées facultatives sérialisées combinées 64 KiB et le corps encodé complet 1 MiB ou une limite de transport connue plus basse. Type, retry et identité restent intacts ; une enveloppe obligatoire impossible est refusée. Le [guide Rust](./polyglot/rust.md#bounded-failure-reports) explique marqueurs, details Avro entiers et résultats locaux. Cela ne qualifie pas anciens SDK, mode embedded ou correction séparée du stockage des résumés Core. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/python.md b/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/python.md index 7dbc1918d24..7f74cbcbec8 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/python.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/python.md @@ -213,11 +213,32 @@ async with Client( | `payload_size_limit_bytes` | `int` | défaut SDK | Respecter le contrat maximal d'octets du serveur. | | `payload_size_warning_threshold_percent` | `int` | défaut SDK | Avertir avant d'atteindre la limite configurée. | | `payload_size_warnings` | `bool` | `True` | Désactiver les avertissements locaux de taille dans les tests ou scripts contrôlés. | +| `failure_report_limit_bytes` | `int` | `1048576` | Réduire la taille maximale du rapport d’échec entièrement encodé. Voir les [rapports d’échec bornés](#bounded-failure-reports). | `token` est l'option la plus simple. Si `control_token` et `worker_token` sont tous deux définis, les méthodes du plan de contrôle utilisent `control_token` et celles du plan worker utilisent `worker_token`. +### Rapports d’échec bornés {#bounded-failure-reports} + +Le SDK Python **2.11.0** a introduit des rapports d’échec sortants bornés. Les limites par défaut sont de **62 KiB UTF-8 pour le message**, **128 KiB pour la pile**, **64 KiB pour l’ensemble des détails et diagnostics facultatifs sérialisés** et **1 MiB pour le corps complet encodé par HTTPX**. Les marqueurs, l’échappement JSON, l’identité du bail et les autres commandes du lot comptent dans cette limite du corps. Une limite de transport configurée ou découverte plus basse est prioritaire. Le type, la classe et le code de l’échec, la politique de nouvelle tentative et l’identité du bail sont conservés. + +Configurez un budget plus faible pour le corps si nécessaire. Les paramètres d’avertissement sur la taille des données restent indicatifs. + +```python +from durable_workflow import Client + +async with Client( + "https://workflow.example.com", + worker_token="worker-token", + control_token="operator-token", + failure_report_limit_bytes=512 * 1024, +) as client: + info = await client.get_cluster_info() +``` + +Un marqueur de troncature visible et les tailles originales en octets identifient les champs raccourcis. Les détails Avro sont conservés intégralement ou omis en entier. Une enveloppe obligatoire impossible à représenter déclenche `FailureReportTooLarge` avant l’envoi HTTP. Les échecs locaux sont normalisés avant que le code du workflow les observe. La première exécution et la relecture à froid voient donc le même message persistant. Un message local déjà observé reste immuable lors de l’ajustement final du lot. + ### Stockage externe des charges utiles {#external-payload-storage} Les opérations ordinaires de `Client` et `Worker` utilisent automatiquement le transport authentifié du runtime Server. Le SDK découvre politique et limites via `GET /api/cluster/info`, téléverse les valeurs encodées supérieures au seuil ou nécessaires pour respecter la limite de requête, puis récupère les références avant décodage. Le code du workflow et de l’activité reçoit la valeur décodée. Les identifiants fournisseur restent sur Server. Les workers distants n’ont besoin ni de boto3, ni de clients fournisseur, ni d’accès au répertoire local de Server. diff --git a/i18n/fr/source-hashes.json b/i18n/fr/source-hashes.json index c305d7b1bca..8b3f392daed 100644 --- a/i18n/fr/source-hashes.json +++ b/i18n/fr/source-hashes.json @@ -28,7 +28,7 @@ "defining-workflows/workflow-status.md": "8e8cb27ff44c890d489d89bf166375acfdfaecabd990a2235e106fab1592d529", "defining-workflows/workflows.md": "f467bc73de32aa5d722c61ce085065460382ae7dd44cea4625847d9fcdc4c97c", "deployment.md": "dd0b6bd184eda12e67922121a09c7f3c98346bde01be1d4c3217f168db5fd7ca", - "failures-and-recovery.md": "7df0b7ce4139b789d8988ce2bf640c388225daa28731b88719e4777f61e40a4c", + "failures-and-recovery.md": "809a86ec38b63d7f8591d1fbee970b0f34bcc5cb508a72060fa78a441cbcdb60", "features/activity-execution-model.md": "e8c37520ae46a7efb30438f4fc06bf893c1df430cb1f92c48963697adaf09082", "features/cancel-and-terminate.md": "c678fc7a0c9b11f0e1bee295aff259de9803219c0aa6769fb801622799e7deb1", "features/child-workflows.md": "57016591fb8816aed7b077e204f1c80f9c6a8dff7501bc00a141c41a4607306b", @@ -82,7 +82,7 @@ "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989", "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959", "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c", - "polyglot/python.md": "d55056ca7638df07b7267bc6d62e635b954957b99620478e861df90558860df3", + "polyglot/python.md": "ac9cd626b7ac3d444509d933f2fec3af015f4c4c171abb0bfcf32642282d7536", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "af91b22c93a7fe6833df156371d99bb105740684915bc73af4576f6de2897e10", "polyglot/server-api-reference.md": "b0a7bfa17ccaec0507ee97dfc1badac49fa5ff96f8178fa4ce5963bc8c6fe7d1", diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/failures-and-recovery.md b/i18n/ja/docusaurus-plugin-content-docs/current/failures-and-recovery.md index a0ea9277eb7..e1f61bc6561 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/failures-and-recovery.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/failures-and-recovery.md @@ -261,6 +261,10 @@ class RetryableWorkflow extends Workflow } ``` +## サービスモードの Python 障害レポートの上限 {#python-failure-report-limits} + +Python SDK **2.11.0 以降**では、サービスモードで送信する障害レポートの上限は、UTF-8 メッセージが 62 KiB、スタックが 128 KiB、任意のメタデータの合計が 64 KiB、マーカーを含むエンコード済み本文全体が 1 MiB です。既知の転送上限がより小さい場合は、その値が適用されます。[Python のレポートガイド](./polyglot/python.md#bounded-failure-reports)では、設定、省略の診断情報、維持されるリトライの意味、ローカルの初回実行とコールドリプレイの一致を説明しています。これは SDK のレポート上限です。組み込み実行での記録と Core の要約保存には、それぞれ別の契約があります。 + ## サービスモード Rust の失敗レポート上限 {#rust-failure-report-limits} 実際に Rust SDK **4.10.1 以降**を動かすサービス worker では、送信 UTF-8 message はマーカー込み62 KiB、対応する stack は128 KiB、任意 metadata の合計シリアライズ結果は64 KiB、完全なエンコード済み body は1 MiBまたはそれより低い既知の輸送上限です。type、retry 判断、claim 識別情報を保ち、必須 envelope が入らなければ明示的に拒否します。[Rust ガイド](./polyglot/rust.md#bounded-failure-reports)に省略マーカー、完全な Avro details、ローカル結果の境界を説明しています。旧 SDK、embedded mode、別の Core summary 保存修正を検証したものではありません。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/python.md b/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/python.md index 99da896e1ff..f81fd5bb773 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/python.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/python.md @@ -172,9 +172,30 @@ async with Client( | `payload_size_limit_bytes` | `int` | SDK 既定値 | Server の最大ペイロードバイト数契約に合わせる。 | | `payload_size_warning_threshold_percent` | `int` | SDK 既定値 | 設定した上限に達する前に警告する。 | | `payload_size_warnings` | `bool` | `True` | テストや管理されたスクリプトでローカルのサイズ警告を無効にする。 | +| `failure_report_limit_bytes` | `int` | `1048576` | エンコード済みの障害レポート全体の上限を引き下げます。[障害レポートのサイズ制限](#bounded-failure-reports)を参照してください。 | `token` が最も単純な選択肢です。`control_token` と `worker_token` の両方を設定すると、コントロールプレーンのメソッドは `control_token`、Worker プレーンのメソッドは `worker_token` を使います。 +### 障害レポートのサイズ制限 {#bounded-failure-reports} + +Python SDK **2.11.0** から、送信する障害レポートにサイズ制限が加わりました。既定値は、**メッセージが UTF-8 で 62 KiB**、**スタックが 128 KiB**、**シリアライズ後の任意の詳細と診断情報が合計 64 KiB**、**HTTPX でエンコードした本文全体が 1 MiB** です。本文の上限には、マーカー、JSON エスケープ、リースの識別情報、バッチ内のほかのコマンドも含まれます。設定または検出された転送上限がより小さい場合は、その値が優先されます。障害の型、クラス、コード、リトライポリシー、リースの識別情報は保持されます。 + +必要に応じて本文の上限を引き下げます。ペイロードサイズの警告設定は引き続き助言として扱われます。 + +```python +from durable_workflow import Client + +async with Client( + "https://workflow.example.com", + worker_token="worker-token", + control_token="operator-token", + failure_report_limit_bytes=512 * 1024, +) as client: + info = await client.get_cluster_info() +``` + +短縮されたフィールドには、見える切り詰めマーカーと元のバイト数が付けられます。Avro の詳細は全体を保持するか、全体を省略します。必須のエンベロープを表現できない場合は、HTTP 送信前に `FailureReportTooLarge` が発生します。ローカル障害はワークフローコードが参照する前に正規化されるため、初回実行とコールドリプレイは保存された同じメッセージを参照します。一度参照したローカルメッセージは、最終的なバッチサイズ調整でも変更されません。 + ### 外部ペイロードストレージ {#external-payload-storage} 通常の `Client` と `Worker` 操作は、Server の認証付きランタイム転送を自動で使います。SDK は `GET /api/cluster/info` で名前空間ポリシーと転送上限を検出し、しきい値を超える値やリクエストを収めるために必要な値をアップロードし、参照値を取得してからデコードします。ワークフローとアクティビティのコードはデコード済み値を受け取ります。プロバイダー認証情報は Server に残ります。リモート Worker に boto3、プロバイダークライアント、Server のローカルディレクトリへのアクセスは不要です。 diff --git a/i18n/ja/source-hashes.json b/i18n/ja/source-hashes.json index c305d7b1bca..8b3f392daed 100644 --- a/i18n/ja/source-hashes.json +++ b/i18n/ja/source-hashes.json @@ -28,7 +28,7 @@ "defining-workflows/workflow-status.md": "8e8cb27ff44c890d489d89bf166375acfdfaecabd990a2235e106fab1592d529", "defining-workflows/workflows.md": "f467bc73de32aa5d722c61ce085065460382ae7dd44cea4625847d9fcdc4c97c", "deployment.md": "dd0b6bd184eda12e67922121a09c7f3c98346bde01be1d4c3217f168db5fd7ca", - "failures-and-recovery.md": "7df0b7ce4139b789d8988ce2bf640c388225daa28731b88719e4777f61e40a4c", + "failures-and-recovery.md": "809a86ec38b63d7f8591d1fbee970b0f34bcc5cb508a72060fa78a441cbcdb60", "features/activity-execution-model.md": "e8c37520ae46a7efb30438f4fc06bf893c1df430cb1f92c48963697adaf09082", "features/cancel-and-terminate.md": "c678fc7a0c9b11f0e1bee295aff259de9803219c0aa6769fb801622799e7deb1", "features/child-workflows.md": "57016591fb8816aed7b077e204f1c80f9c6a8dff7501bc00a141c41a4607306b", @@ -82,7 +82,7 @@ "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989", "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959", "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c", - "polyglot/python.md": "d55056ca7638df07b7267bc6d62e635b954957b99620478e861df90558860df3", + "polyglot/python.md": "ac9cd626b7ac3d444509d933f2fec3af015f4c4c171abb0bfcf32642282d7536", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "af91b22c93a7fe6833df156371d99bb105740684915bc73af4576f6de2897e10", "polyglot/server-api-reference.md": "b0a7bfa17ccaec0507ee97dfc1badac49fa5ff96f8178fa4ce5963bc8c6fe7d1", diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/failures-and-recovery.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/failures-and-recovery.md index 2802a46f38e..357573ed8de 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/failures-and-recovery.md +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/failures-and-recovery.md @@ -338,6 +338,10 @@ class RetryableWorkflow extends Workflow } ``` +## Limites de relatórios de falha Python no modo de serviço {#python-failure-report-limits} + +O SDK Python **2.11.0 ou posterior** limita os relatórios de falha enviados no modo de serviço a mensagens UTF-8 de 62 KiB, pilhas de 128 KiB, 64 KiB de metadados opcionais combinados e um corpo completo codificado de 1 MiB, incluindo os marcadores. Limites de transporte conhecidos menores são respeitados. O [guia de relatórios Python](./polyglot/python.md#bounded-failure-reports) explica a configuração, os diagnósticos de omissão, a semântica de novas tentativas preservada e a igualdade entre a primeira execução local e o replay a frio. Esses limites se aplicam aos relatórios do SDK. O registro embarcado e o armazenamento de resumos do Core mantêm contratos separados. + ## Limites de relatos de falha Rust no modo serviço {#rust-failure-report-limits} Em workers de serviço realmente executando Rust SDK **4.10.1 ou posterior**, mensagem enviada tem até 62 KiB UTF-8 com marcador, stack 128 KiB quando suportado, metadata opcional serializada combinada 64 KiB e corpo codificado completo 1 MiB ou limite de transporte conhecido menor. Tipo, retry e identidade permanecem; envelope obrigatório impossível é recusado. A [guia Rust](./polyglot/rust.md#bounded-failure-reports) explica marcadores, details Avro inteiros e resultados locais. Não qualifica SDKs antigos, modo embedded nem a correção separada do armazenamento de resumo Core. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/python.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/python.md index 83bc5ea5c9d..39176ba1aff 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/python.md +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/python.md @@ -212,11 +212,32 @@ async with Client( | `payload_size_limit_bytes` | `int` | padrão do SDK | Corresponder ao contrato de bytes máximos de payload do servidor. | | `payload_size_warning_threshold_percent` | `int` | padrão do SDK | Avisar antes de um payload atingir o limite configurado. | | `payload_size_warnings` | `bool` | `True` | Desabilitar avisos locais de tamanho de payload em testes ou scripts controlados. | +| `failure_report_limit_bytes` | `int` | `1048576` | Reduzir o limite do relatório de falha totalmente codificado. Veja [relatórios de falha com limites](#bounded-failure-reports). | `token` é a opção mais simples. Se `control_token` e `worker_token` estiverem definidos, métodos do plano de controle usam `control_token`, e métodos do plano de workers usam `worker_token`. +### Relatórios de falha com limites {#bounded-failure-reports} + +O SDK Python **2.11.0** introduziu limites para os relatórios de falha enviados. Os padrões são **62 KiB UTF-8 para a mensagem**, **128 KiB para a pilha**, **64 KiB para os detalhes e diagnósticos opcionais serializados em conjunto** e **1 MiB para o corpo completo codificado pelo HTTPX**. Marcadores, escapes JSON, identidade da concessão e outros comandos do lote contam para esse limite do corpo. Um limite de transporte configurado ou descoberto menor tem precedência. Tipo, classe e código da falha, política de novas tentativas e identidade da concessão são preservados. + +Defina um limite menor para o corpo quando necessário. As configurações de aviso sobre o tamanho da carga continuam sendo apenas informativas. + +```python +from durable_workflow import Client + +async with Client( + "https://workflow.example.com", + worker_token="worker-token", + control_token="operator-token", + failure_report_limit_bytes=512 * 1024, +) as client: + info = await client.get_cluster_info() +``` + +Um marcador visível de truncamento e as contagens originais de bytes identificam os campos reduzidos. Os detalhes Avro permanecem inteiros ou são omitidos por completo. Um envelope obrigatório que não possa ser representado gera `FailureReportTooLarge` antes do envio HTTP. As falhas locais são normalizadas antes que o código do workflow as observe. Assim, a primeira execução e o replay a frio veem a mensagem persistida. Uma mensagem local já observada permanece imutável durante o ajuste final do lote. + ### Armazenamento externo de payloads {#external-payload-storage} Operações normais de `Client` e `Worker` usam automaticamente o transporte autenticado do runtime do Server. O SDK descobre a política e os limites por `GET /api/cluster/info`, envia valores codificados acima do limite ou necessários para que a solicitação caiba e busca os valores referenciados antes de decodificar. O código do workflow e da atividade recebe o valor decodificado. As credenciais ficam no Server. Workers remotos não precisam de boto3, clientes do provedor nem acesso ao diretório local do Server. diff --git a/i18n/pt-BR/source-hashes.json b/i18n/pt-BR/source-hashes.json index c305d7b1bca..8b3f392daed 100644 --- a/i18n/pt-BR/source-hashes.json +++ b/i18n/pt-BR/source-hashes.json @@ -28,7 +28,7 @@ "defining-workflows/workflow-status.md": "8e8cb27ff44c890d489d89bf166375acfdfaecabd990a2235e106fab1592d529", "defining-workflows/workflows.md": "f467bc73de32aa5d722c61ce085065460382ae7dd44cea4625847d9fcdc4c97c", "deployment.md": "dd0b6bd184eda12e67922121a09c7f3c98346bde01be1d4c3217f168db5fd7ca", - "failures-and-recovery.md": "7df0b7ce4139b789d8988ce2bf640c388225daa28731b88719e4777f61e40a4c", + "failures-and-recovery.md": "809a86ec38b63d7f8591d1fbee970b0f34bcc5cb508a72060fa78a441cbcdb60", "features/activity-execution-model.md": "e8c37520ae46a7efb30438f4fc06bf893c1df430cb1f92c48963697adaf09082", "features/cancel-and-terminate.md": "c678fc7a0c9b11f0e1bee295aff259de9803219c0aa6769fb801622799e7deb1", "features/child-workflows.md": "57016591fb8816aed7b077e204f1c80f9c6a8dff7501bc00a141c41a4607306b", @@ -82,7 +82,7 @@ "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989", "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959", "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c", - "polyglot/python.md": "d55056ca7638df07b7267bc6d62e635b954957b99620478e861df90558860df3", + "polyglot/python.md": "ac9cd626b7ac3d444509d933f2fec3af015f4c4c171abb0bfcf32642282d7536", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "af91b22c93a7fe6833df156371d99bb105740684915bc73af4576f6de2897e10", "polyglot/server-api-reference.md": "b0a7bfa17ccaec0507ee97dfc1badac49fa5ff96f8178fa4ce5963bc8c6fe7d1", diff --git a/i18n/uk/docusaurus-plugin-content-docs/current/failures-and-recovery.md b/i18n/uk/docusaurus-plugin-content-docs/current/failures-and-recovery.md index 64fa21d305e..d43295b511b 100644 --- a/i18n/uk/docusaurus-plugin-content-docs/current/failures-and-recovery.md +++ b/i18n/uk/docusaurus-plugin-content-docs/current/failures-and-recovery.md @@ -335,6 +335,10 @@ class RetryableWorkflow extends Workflow } ``` +## Ліміти звітів про помилки Python у сервісному режимі {#python-failure-report-limits} + +Python SDK **2.11.0 або новіший** обмежує вихідні звіти про помилки в сервісному режимі: повідомлення UTF-8 до 62 KiB, стеки до 128 KiB, необов’язкові метадані разом до 64 KiB і все закодоване тіло до 1 MiB, включно з маркерами. Застосовуються нижчі відомі транспортні ліміти. [Посібник зі звітів Python](./polyglot/python.md#bounded-failure-reports) пояснює налаштування, діагностику пропущених полів, збереження семантики повторних спроб і рівність першого локального виконання та холодного відтворення. Це межі звітів SDK. Вбудований запис і зберігання зведень Core мають окремі контракти. + ## Межі звітів про помилки Rust у service mode {#rust-failure-report-limits} Для service-mode worker, які фактично запускають Rust SDK **4.10.1 або новіший**, вихідний message має до62 KiB UTF-8 разом із маркером, stack —128 KiB за підтримки, сумарні серіалізовані необов’язкові metadata —64 KiB, повне закодоване тіло —1 MiB або нижчу відому транспортну межу. Тип, рішення retry та ідентичність claim зберігаються; неможливий обов’язковий envelope явно відхиляється. [Довідник Rust](./polyglot/rust.md#bounded-failure-reports) пояснює маркери пропусків, цілі Avro details та межі локальних результатів. Це не кваліфікує старі SDK, embedded mode чи окреме виправлення summary-сховища Core. diff --git a/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/python.md b/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/python.md index 2e97f250c51..ac323d1004b 100644 --- a/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/python.md +++ b/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/python.md @@ -210,10 +210,31 @@ async with Client( | `payload_size_limit_bytes` | `int` | типове SDK | Відповідність максимальному розміру payload Server. | | `payload_size_warning_threshold_percent` | `int` | типове SDK | Попередження до досягнення межі payload. | | `payload_size_warnings` | `bool` | `True` | Вимкнення локальних попереджень розміру в тестах чи контрольованих скриптах. | +| `failure_report_limit_bytes` | `int` | `1048576` | Зменшити ліміт повністю закодованого звіту про помилку. Див. [обмежені звіти про помилки](#bounded-failure-reports). | `token` є найпростішим варіантом. Якщо задані `control_token` і `worker_token`, методи control-plane використовують перший, а worker другий. +### Обмежені звіти про помилки {#bounded-failure-reports} + +У Python SDK **2.11.0** з’явилися обмеження вихідних звітів про помилки. Типові межі: **62 KiB UTF-8 для повідомлення**, **128 KiB для стека**, **64 KiB для разом серіалізованих необов’язкових деталей і діагностики** та **1 MiB для всього тіла, закодованого HTTPX**. До ліміту тіла входять маркери, екранування JSON, ідентичність оренди та інші команди пакета. Нижчий налаштований або виявлений транспортний ліміт має пріоритет. Тип, клас і код помилки, політика повторних спроб та ідентичність оренди зберігаються. + +За потреби задайте менший ліміт тіла. Налаштування попереджень про розмір даних залишаються лише інформаційними. + +```python +from durable_workflow import Client + +async with Client( + "https://workflow.example.com", + worker_token="worker-token", + control_token="operator-token", + failure_report_limit_bytes=512 * 1024, +) as client: + info = await client.get_cluster_info() +``` + +Видимий маркер скорочення та початкові кількості байтів позначають скорочені поля. Деталі Avro зберігаються цілими або пропускаються повністю. Якщо обов’язковий конверт неможливо подати, до надсилання HTTP виникає `FailureReportTooLarge`. Локальні помилки нормалізуються до того, як код workflow їх спостерігає. Тому перше виконання й холодне відтворення бачать збережене повідомлення. Уже спостережене локальне повідомлення залишається незмінним під час остаточного підлаштування пакета до ліміту. + ### Зовнішнє сховище payload {#external-payload-storage} Звичайні операції `Client` і `Worker` автоматично використовують автентифікований транспорт runtime Server. SDK виявляє політику namespace й ліміти через `GET /api/cluster/info`, завантажує закодовані значення понад поріг або потрібні для вміщення запиту й отримує байти посилань перед декодуванням. Код workflow та activity отримує декодоване значення. Облікові дані провайдера залишаються на Server. Віддаленим worker не потрібні boto3, клієнти провайдерів або доступ до локального каталогу Server. diff --git a/i18n/uk/source-hashes.json b/i18n/uk/source-hashes.json index c305d7b1bca..8b3f392daed 100644 --- a/i18n/uk/source-hashes.json +++ b/i18n/uk/source-hashes.json @@ -28,7 +28,7 @@ "defining-workflows/workflow-status.md": "8e8cb27ff44c890d489d89bf166375acfdfaecabd990a2235e106fab1592d529", "defining-workflows/workflows.md": "f467bc73de32aa5d722c61ce085065460382ae7dd44cea4625847d9fcdc4c97c", "deployment.md": "dd0b6bd184eda12e67922121a09c7f3c98346bde01be1d4c3217f168db5fd7ca", - "failures-and-recovery.md": "7df0b7ce4139b789d8988ce2bf640c388225daa28731b88719e4777f61e40a4c", + "failures-and-recovery.md": "809a86ec38b63d7f8591d1fbee970b0f34bcc5cb508a72060fa78a441cbcdb60", "features/activity-execution-model.md": "e8c37520ae46a7efb30438f4fc06bf893c1df430cb1f92c48963697adaf09082", "features/cancel-and-terminate.md": "c678fc7a0c9b11f0e1bee295aff259de9803219c0aa6769fb801622799e7deb1", "features/child-workflows.md": "57016591fb8816aed7b077e204f1c80f9c6a8dff7501bc00a141c41a4607306b", @@ -82,7 +82,7 @@ "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989", "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959", "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c", - "polyglot/python.md": "d55056ca7638df07b7267bc6d62e635b954957b99620478e861df90558860df3", + "polyglot/python.md": "ac9cd626b7ac3d444509d933f2fec3af015f4c4c171abb0bfcf32642282d7536", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "af91b22c93a7fe6833df156371d99bb105740684915bc73af4576f6de2897e10", "polyglot/server-api-reference.md": "b0a7bfa17ccaec0507ee97dfc1badac49fa5ff96f8178fa4ce5963bc8c6fe7d1", diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/failures-and-recovery.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/failures-and-recovery.md index f293bc92546..a4684f15f93 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/failures-and-recovery.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/failures-and-recovery.md @@ -259,6 +259,10 @@ class RetryableWorkflow extends Workflow } ``` +## Python 服务模式失败报告上限 {#python-failure-report-limits} + +Python SDK **2.11.0 或更新版本**将服务模式下发出的失败报告限制为：UTF-8 消息 62 KiB、堆栈 128 KiB、可选元数据合计 64 KiB，以及包含标记的完整编码请求体 1 MiB。已知传输上限更低时，以较低值为准。[Python 报告指南](./polyglot/python.md#bounded-failure-reports)说明了配置、省略诊断信息、保留的重试语义，以及本地首次执行与冷重放的一致性。这些是 SDK 报告的边界。嵌入式记录和 Core 摘要存储遵循各自独立的契约。 + ## Rust 服务模式失败报告上限 {#rust-failure-report-limits} 实际运行 Rust SDK **4.10.1 或更新版本**的服务 worker，其发出 UTF-8 message 含标记最多62 KiB，受支持 stack 为128 KiB，可选 metadata 合计序列化结果为64 KiB，完整编码 body 为1 MiB或已知更低传输上限。type、retry 决定和 claim 标识保持不变；必需 envelope 无法容纳时显式拒绝。[Rust 报告指南](./polyglot/rust.md#bounded-failure-reports)说明省略标记、完整 Avro details 和本地结果边界。这不构成对旧 SDK、embedded mode 或独立 Core summary 存储修复的验证。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/python.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/python.md index 430992979d7..e065cee3d02 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/python.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/python.md @@ -172,9 +172,30 @@ async with Client( | `payload_size_limit_bytes` | `int` | SDK 默认值 | 匹配 Server 最大负载字节契约。 | | `payload_size_warning_threshold_percent` | `int` | SDK 默认值 | 在负载达到配置上限前警告。 | | `payload_size_warnings` | `bool` | `True` | 在测试或受控脚本中禁用本地负载大小警告。 | +| `failure_report_limit_bytes` | `int` | `1048576` | 降低完整编码后失败报告的大小上限。请参阅[有界失败报告](#bounded-failure-reports)。 | `token` 是最简单的选项。如果同时设置 `control_token` 和 `worker_token`，控制平面方法使用 `control_token`，Worker 平面方法使用 `worker_token`。 +### 有界失败报告 {#bounded-failure-reports} + +Python SDK **2.11.0** 为发出的失败报告引入了大小限制。默认上限为：**消息使用 UTF-8 编码后 62 KiB**、**堆栈 128 KiB**、**可选详情和诊断信息序列化后合计 64 KiB**，以及 **HTTPX 编码后的完整请求体 1 MiB**。标记、JSON 转义、租约身份和批次中的其他命令都计入请求体上限。配置或发现的传输上限更低时，以较低值为准。失败类型、类、代码、重试策略和租约身份会保留。 + +需要时可降低请求体上限。载荷大小警告设置仍然只提供提示。 + +```python +from durable_workflow import Client + +async with Client( + "https://workflow.example.com", + worker_token="worker-token", + control_token="operator-token", + failure_report_limit_bytes=512 * 1024, +) as client: + info = await client.get_cluster_info() +``` + +被缩短的字段带有可见的截断标记和原始字节数。Avro 详情要么完整保留，要么整体省略。无法表示必需的信封时，会在发送 HTTP 请求前抛出 `FailureReportTooLarge`。本地失败会在工作流代码读取前规范化，因此首次执行和冷重放读取的是同一条已持久化消息。已经读取的本地消息在最终调整批次大小时保持不变。 + ### 外部负载存储 {#external-payload-storage} 普通 `Client` 和 `Worker` 操作会自动使用 Server 的认证运行时传输。SDK 通过 `GET /api/cluster/info` 发现命名空间策略和传输上限，上传大于阈值或为满足请求限制而必须外置的编码值，并在解码前获取引用值。工作流和活动代码收到的是解码后的值。提供商凭据保留在 Server 上。远程 Worker 不需要 boto3、提供商客户端或 Server 本地目录的访问权。 diff --git a/i18n/zh-Hans/source-hashes.json b/i18n/zh-Hans/source-hashes.json index c305d7b1bca..8b3f392daed 100644 --- a/i18n/zh-Hans/source-hashes.json +++ b/i18n/zh-Hans/source-hashes.json @@ -28,7 +28,7 @@ "defining-workflows/workflow-status.md": "8e8cb27ff44c890d489d89bf166375acfdfaecabd990a2235e106fab1592d529", "defining-workflows/workflows.md": "f467bc73de32aa5d722c61ce085065460382ae7dd44cea4625847d9fcdc4c97c", "deployment.md": "dd0b6bd184eda12e67922121a09c7f3c98346bde01be1d4c3217f168db5fd7ca", - "failures-and-recovery.md": "7df0b7ce4139b789d8988ce2bf640c388225daa28731b88719e4777f61e40a4c", + "failures-and-recovery.md": "809a86ec38b63d7f8591d1fbee970b0f34bcc5cb508a72060fa78a441cbcdb60", "features/activity-execution-model.md": "e8c37520ae46a7efb30438f4fc06bf893c1df430cb1f92c48963697adaf09082", "features/cancel-and-terminate.md": "c678fc7a0c9b11f0e1bee295aff259de9803219c0aa6769fb801622799e7deb1", "features/child-workflows.md": "57016591fb8816aed7b077e204f1c80f9c6a8dff7501bc00a141c41a4607306b", @@ -82,7 +82,7 @@ "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989", "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959", "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c", - "polyglot/python.md": "d55056ca7638df07b7267bc6d62e635b954957b99620478e861df90558860df3", + "polyglot/python.md": "ac9cd626b7ac3d444509d933f2fec3af015f4c4c171abb0bfcf32642282d7536", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "af91b22c93a7fe6833df156371d99bb105740684915bc73af4576f6de2897e10", "polyglot/server-api-reference.md": "b0a7bfa17ccaec0507ee97dfc1badac49fa5ff96f8178fa4ce5963bc8c6fe7d1",